diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 5e14f73..dcf6f53 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -4,12 +4,12 @@ ## Checklist -- [ ] **Metadata complete in the registration** (`plugin.RegisterProvider`: provider id, name, category, homepage; each source's id, layer, what it watches, URLs, page), and I read the words. There is no list to update. Not applicable: +- [ ] **Metadata complete in the registration** (`plugin.RegisterProvider`: provider id, name, category, homepage; each source's id, kind, layer, what it watches, URLs, packages, page), and I read the words. There is no list to update. Not applicable: - [ ] Every commit is signed off (`git commit -s`, DCO) -- [ ] Golden test over a real saved copy of the source (`testdata/golden/.json`) +- [ ] Golden test over a real saved copy of the source (`testdata/golden/-.json`) - [ ] `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** +- [ ] `providers/-.md` written or updated from `providers/_template.md`, including **Why this source** - [ ] Fetches only through `env.Get` / `core/kit/` - [ ] `make check` passes locally (`make plugins` prints the source as you expect) - [ ] 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 0ddd5cb..515d953 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 core/event/ and core/migrate/ test +# patch-it owns). This fails when the two drift apart, so core/event/ tests # the same events the patch-it client does. Only top-level "_comment" fields may # differ (scripts/check_contract.py). # diff --git a/AGENTS.md b/AGENTS.md index 24b5996..d23d094 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,7 @@ Rules for AI coding agents (and humans) working in this repo. `CLAUDE.md` import ## Rule 1: every new or changed provider or source has complete metadata in its registration -**A source exists when its kind's package registers it with `plugin.RegisterProvider`, and its metadata lives only there: the provider's id, name, category and homepage, and each source's id, layer, what it watches, the URLs it reads and its page, `providers/.md`.** Adding, changing or removing a source is a change to that registration (and to its page) in the same PR. There is no list to update: nothing in this repo, the docs site or anywhere else keeps one by hand. +**A source exists when its kind's package registers it with `plugin.RegisterProvider`, and its metadata lives only there: the provider's id, name, category and homepage, and each source's id, layer, what it watches, the URLs it reads, the packages it covers (`pypi:stripe`) and its page, `providers/.md`.** Adding, changing or removing a source is a change to that registration (and to its page) in the same PR. There is no list to update: nothing in this repo, the docs site or anywhere else keeps one by hand. `go run ./cmd/list-plugins` prints the list from the registry (JSON), and the Release workflow attaches it to every release as `plugins.json`; the docs site and patch-it's hosted ingestion service read it from there. `RegisterProvider` refuses incomplete metadata and `go test` fails when a source's page is missing, but no check can tell whether the words are right: you are that check. Say in the PR that you read them. @@ -23,12 +23,12 @@ 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. +- **Start a new source with `make new-plugin ARGS='--provider --name --source --kind '`** (`go run ./cmd/new-plugin`; [which kind](docs/which-kind.md)), 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 `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. +- **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. -- **`providers/.md`** for every provider, copied from `providers/_template.md`, including **Why this source**: the link, the date it was checked, why it's the best source, the alternatives not used, and a short quote. +- **`providers/-.md`** for every provider, copied from `providers/_template.md`, including **Why this source**: the link, the date it was checked, why it's the best source, the alternatives not used, and a short quote. - **No source, no event**: every event carries the source URL and a quote. - Don't edit golden files to make a test pass without explaining in the PR why the new output is right. @@ -40,6 +40,7 @@ Refer to the service that runs these plugins as "patch-it's hosted ingestion ser make check # tidy, build, gofmt, vet, the import allowlist, the net/http guard, go test -race, no TODO(new-plugin) left, leak guard make check PATCH_IT=../patch-it # also CI_contract: contract/fixtures/ against a patch-it checkout make plugins # print the list of providers and sources from the registry (what each release attaches as plugins.json) +make new-plugin ARGS='--provider acme --source api --kind openapi' # scaffold a source (asks for what's missing in a terminal) ``` One target at a time: `make tidy`, `make build`, `make fmt`, `make vet`, `make imports`, `make nethttp`, `make test`, `make todos`, `make leak-guard`, `make contract`. Use `make GO=/path/to/go check` for another Go. @@ -52,22 +53,21 @@ Go module `github.com/patch-it-dev/patch-it-plugins`; the only dependency is `go core/plugin/ the Plugin interface (Run; ListVersions, ReadAt, Extract), the registry of providers and sources, Env, Result 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/versions/ every version of a source: GitHub releases, tags and commits, PyPI, npm, the Web Archive at a date -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/versions/ every version of a source: GitHub releases, tags and commits, PyPI, npm, Web Archive captures +core/kit/ core/kit/kittest/ Unchanged, Cite, Wayback, Notices; the test kit (Mem, Pages, Ingest, Golden) +core/extract/ what readers of prose share: RSS/Atom entries, HTML as text, dates, code spans +core/event/ the change event of patch-it's contract: types, fingerprint, validation 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; + per provider), notices (+ retire/, feed/, eol/), migrationguide (+ sdkguide/, + members/), changelog (Markdown, RST or JSON), catalog, apisurface (+ pysurface/); 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/ prints the list from the registry (make plugins); internal/pluginlist/ is its logic -cmd/new-plugin/ scaffolds a provider on a format plugin (go run ./cmd/new-plugin --help) +cmd/new-plugin/ scaffolds a provider's source on a kind (make new-plugin ARGS=...; go run ./cmd/new-plugin --help) contract/fixtures/ a copy of patch-it's change-event fixtures (CI_contract checks it) Makefile make check (what CI_go runs, plus the leak guard), make plugins docs/ contributor docs, including writing-a-plugin.md -providers/.md one page per provider +providers/-.md one page per provider scripts/ leak_guard.py (hashed internal names), check_contract.py .github/ CODEOWNERS, PR template, release-notes categories, workflows (CI_go, CI_dco, CI_leak_guard, CI_contract, Release) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8554f02..f7ede16 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,16 +2,16 @@ Thanks for helping patch-it watch more APIs. This file is the rulebook; [docs/writing-a-plugin.md](docs/writing-a-plugin.md) is the how-to. -**Start a new provider with the starter:** `go run ./cmd/new-plugin --api --provider --format ` writes the definition, its registration, a test over placeholder sources, the testdata rows, the provider page, and the source's metadata in its `RegisterProvider` block; you fill in the `TODO(new-plugin)`s ([how](docs/writing-a-plugin.md#1-scaffold-it-with-new-plugin)). +**Start a new provider with the starter:** `make new-plugin ARGS='--provider --source --kind '` ([which kind?](docs/which-kind.md); in a terminal it asks for the rest) writes the definition, its registration, a test over placeholder sources, the testdata rows, the provider page, and the source's metadata in its `RegisterProvider` block; you fill in the `TODO(new-plugin)`s ([how](docs/writing-a-plugin.md#1-scaffold-it-with-new-plugin)). ## The rules 1. **Give every provider and source complete metadata in its registration.** A source exists when its kind's package registers it with `plugin.RegisterProvider`: the provider's id, name, category and homepage, and the source's id, layer, what it watches, the URLs it reads and its page. That registration is the only list: `make plugins` prints it, each release carries it as `plugins.json`, and docs.patch-it.dev reads it from there. Nothing else to update. 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. +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). -6. **Document the provider** in `providers/.md`, copied from [`providers/_template.md`](providers/_template.md): what it watches, **why you chose that source** (and the alternatives you didn't), how the provider announces changes, what the plugin reads and ignores, and known gaps. +6. **Document the provider** in `providers/-.md`, copied from [`providers/_template.md`](providers/_template.md): what it watches, **why you chose that source** (and the alternatives you didn't), how the provider announces changes, what the plugin reads and ignores, and known gaps. 7. **Nothing private.** This repo is public. No credentials, tokens, internal hostnames or links to private repos or systems, in code, tests, commit messages or PR descriptions. CI scans every PR for secrets and for known internal names. ## Sign your commits (DCO) @@ -46,14 +46,14 @@ That adds `Signed-off-by: Your Name `, matching the commit's au Releases are tags on `main` (`v0.x.y`), made only by the **Release** workflow. Nothing is tagged on push, and agents never tag or release. -**Automatic, twice a week:** every Monday and Thursday at 14:00 UTC the workflow makes a **patch** release, but only if something was merged since the last tag; otherwise it does nothing. If the merges add a **new format plugin** (a new `plugins//` directory), the scheduled run skips with a warning instead: run it by hand with **minor**. So a merged plugin reaches patch-it's hosted ingestion service within a few days. +**Automatic, twice a week:** every Monday and Thursday at 14:00 UTC the workflow makes a **patch** release, but only if something was merged since the last tag; otherwise it does nothing. If the merges add a **new kind** (a new `plugins//` directory), the scheduled run skips with a warning instead: run it by hand with **minor**. So a merged plugin reaches patch-it's hosted ingestion service within a few days. **By hand, any time** (an urgent fix, or a **minor** release): 1. Merge the PRs that should go out. 2. **Actions → Release → Run workflow** (branch `main`), pick the bump: - - **patch** (`v0.4.1` → `v0.4.2`): fixes, a new provider on an existing format plugin, docs; - - **minor** (`v0.4.1` → `v0.5.0`): a new format plugin, new exported API, anything users should read about. + - **patch** (`v0.4.1` → `v0.4.2`): fixes, a new source on an existing kind, docs; + - **minor** (`v0.4.1` → `v0.5.0`): a new kind, new exported API, anything users should read about. 3. The workflow refuses if `main`'s HEAD is already tagged, then runs, on that exact commit, the internal-names check over every file, gitleaks over the whole history, `go build`, `go vet`, `gofmt` and `go test -race`. Any failure stops it before a tag exists. 4. When everything passes it pushes an annotated tag and publishes a GitHub release with generated notes (grouped by the PR's label: `plugin`/`enhancement`, `bug`, `documentation`; see [`.github/release.yml`](.github/release.yml)). The release carries one asset, `plugins.json`: the list of providers and sources printed from the registry at that tag (`go run ./cmd/list-plugins`). It is the only published list; nothing in the repo keeps one, and docs.patch-it.dev reads `https://github.com/patch-it-dev/patch-it-plugins/releases/latest/download/plugins.json`. diff --git a/Makefile b/Makefile index 5aa7bcd..b95da4f 100644 --- a/Makefile +++ b/Makefile @@ -6,6 +6,8 @@ # make check everything below, in CI's order # make check PATCH_IT=../patch-it also compare contract/fixtures/ with patch-it's # make plugins print the providers and sources from the registry (JSON) +# make new-plugin ARGS='--provider acme --source api --kind openapi' +# scaffold a source (cmd/new-plugin; asks for what's missing) # # The `::error` lines are GitHub annotations; locally they're plain messages. @@ -17,7 +19,7 @@ PYTHON ?= python3 MODULE := github.com/patch-it-dev/patch-it-plugins ALLOWED := ^($(MODULE)(/|$$)|gopkg\.in/yaml\.v3$$) -.PHONY: check tidy build fmt vet imports nethttp test todos leak-guard contract plugins +.PHONY: check tidy build fmt vet imports nethttp test todos leak-guard contract plugins new-plugin check: tidy build fmt vet imports nethttp test todos leak-guard contract @echo "make check: all passed" @@ -63,7 +65,7 @@ test: # A provider started with new-plugin is done when nothing it wrote still says # TODO(new-plugin). -TODO_DIRS := plugins core/migrate providers +TODO_DIRS := plugins providers todos: @left=$$(grep -rl 'TODO(new-plugin)' $(TODO_DIRS) || true); \ if [ -n "$$left" ]; then \ @@ -90,3 +92,8 @@ contract: # Release workflow attaches it to each release as plugins.json. plugins: @$(GO) run ./cmd/list-plugins + +# Scaffold a provider's source on a kind: cmd/new-plugin with ARGS. In a +# terminal it asks for whatever ARGS leaves out. +new-plugin: + $(GO) run ./cmd/new-plugin $(ARGS) diff --git a/README.md b/README.md index ab32e15..5df0e49 100644 --- a/README.md +++ b/README.md @@ -15,13 +15,13 @@ You need Go (the version in `go.mod`), `make` and Python 3. -1. **Scaffold it**, on the kind that reads its source ([which kind](docs/writing-a-plugin.md#3-pick-the-kind)): +1. **Scaffold it**, on the kind that reads its source ([which kind?](docs/which-kind.md)); in a terminal, `make new-plugin` asks for what's missing: ```sh - go run ./cmd/new-plugin --api acme --provider Acme --format feed --source https://acme.example/changelog.xml + make new-plugin ARGS='--provider acme --name Acme --source api --kind notices --reader feed --url https://acme.example/changelog.xml' ``` -2. **Fill in every `TODO(new-plugin)`**: the reader, the provider and source metadata in its `plugin.RegisterProvider` block, a saved copy of the source in `testdata/`, and "Why this source" in `providers/acme.md`. Then write the golden file and read it like code: +2. **Fill in every `TODO(new-plugin)`**: the reader, the provider and source metadata in its `plugin.RegisterProvider` block, a saved copy of the source in `testdata/`, and "Why this source" in `providers/acme-api.md`. Then write the golden file and read it like code: ```sh - go test ./plugins/feed -run TestAcme -update + go test ./plugins/notices -run TestAcmeApi -update ``` 3. **Check it the way CI will, and open the PR** (`git commit -s`, one provider per PR): ```sh @@ -30,7 +30,7 @@ You need Go (the version in `go.mod`), `make` and Python 3. ## More -- [How to write a plugin](docs/writing-a-plugin.md): providers, sources, kinds, versions, the test kit, step by step. +- [Which kind fits my provider?](docs/which-kind.md) and [how to write a plugin](docs/writing-a-plugin.md): providers, sources, kinds, versions, the test kit, step by step. - [How it works](docs/how-it-works.md): what a plugin does, the layout, the checks, releases. - What's covered: `make plugins` prints every provider and source from the code; each [release](https://github.com/patch-it-dev/patch-it-plugins/releases) carries it as `plugins.json`, and [docs.patch-it.dev](https://docs.patch-it.dev/supported-apis/plugins/) shows it. - [CONTRIBUTING.md](CONTRIBUTING.md) (the rules), [AGENTS.md](AGENTS.md) (for AI coding agents), [Discussions](https://github.com/patch-it-dev/patch-it-plugins/discussions), [good first issues](https://github.com/patch-it-dev/patch-it-plugins/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22). diff --git a/cmd/list-plugins/main.go b/cmd/list-plugins/main.go index 0718165..1f9c2b9 100644 --- a/cmd/list-plugins/main.go +++ b/cmd/list-plugins/main.go @@ -1,5 +1,5 @@ // Command list-plugins prints what patch-it watches, as JSON: every registered -// provider with its sources (id, old slug, kind, layer, what it watches, the +// provider with its sources (id, kind, layer, what it watches, the // URLs it reads, its page), built from the plugin registry at run time. The // Release workflow attaches its output to each release as plugins.json; it is // never committed. diff --git a/cmd/new-plugin/formats.go b/cmd/new-plugin/formats.go index 7c88291..9e3bd44 100644 --- a/cmd/new-plugin/formats.go +++ b/cmd/new-plugin/formats.go @@ -4,6 +4,7 @@ package main // definition goes, the line that registers it, the placeholder sources its // test reads, and how the test runs it. type formatSpec struct { + kind string // the kind: the plugins/ package that registers and tests it layer string // the source's default layer (plugin.Layers()) defDir string // the package directory the definition goes in def string // the definition file (template) @@ -17,21 +18,22 @@ type formatSpec struct { next string // a format-specific line for the next steps drop string // the drop test, when "no event at all" can't be it (template) dropFile string // the drop test's placeholder, when not a copy of the source's - mapEntry *mapEntry // an entry the format needs in a map elsewhere -} - -// mapEntry is a line added to a map literal in another package: the v1 -> v2 -// conversion in migrate/ knows each model retirement page and SDK guide. -type mapEntry struct { - file, varName, entry string // entry is a template } const todo = "TODO(new-plugin)" +// defaultReaders are the reader --kind picks when --reader is left out. +var defaultReaders = map[string]string{ + "notices": "deprecations", + "migrationguide": "sdk", + "changelog": "markdown", +} + var formats = map[string]formatSpec{ - "feed": { + "notices/feed": { + kind: "notices", layer: "api", - defDir: "plugins/feed", + defDir: "plugins/notices/feed", def: `package feed // {{.Ident}} is {{.Provider}}'s feed of changes. @@ -58,8 +60,8 @@ func read{{.Ident}}(e Entry) []Finding { return nil } `, - register: `plugin.Register(Plugin{Feed: {{.Ident}}, Archiver: kit.Wayback{}})`, - pluginOf: `Plugin{Feed: {{.Ident}}}`, + register: `plugin.Register(Plugin{Page: feed.{{.Ident}}, Archiver: kit.Wayback{}})`, + pluginOf: `Plugin{Page: feed.{{.Ident}}}`, fixtures: map[string]string{"{{.File}}.rss.xml": ` placeholderhttps://example.com/placeholder @@ -69,19 +71,20 @@ func read{{.Ident}}(e Entry) []Finding { source: "{{.File}}.rss.xml", ingest: `// {{.Lower}}Ingest runs the plugin over a saved copy of the feed, cited // through a test archive that serves the same copy. -func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { +func {{.Lower}}Ingest(t *testing.T, file string) []event.Event { t.Helper() - saved := kittest.Pages{ {{.Ident}}.URL: file} + saved := kittest.Pages{feed.{{.Ident}}.URL: file} archive := &kittest.Archive{T: t, Pages: saved} - return kittest.IngestWith(t, kittest.Env(t, saved), Plugin{Feed: {{.Ident}}, Archiver: archive}) + return kittest.IngestWith(t, kittest.Env(t, saved), Plugin{Page: feed.{{.Ident}}, Archiver: archive}) } `, - imports: []string{"github.com/patch-it-dev/patch-it-plugins/core/event"}, + imports: []string{"github.com/patch-it-dev/patch-it-plugins/core/event", "github.com/patch-it-dev/patch-it-plugins/plugins/notices/feed"}, }, - "retirements": { + "notices/deprecations": { + kind: "notices", layer: "ai-models", - defDir: "plugins/retirements/retire", + defDir: "plugins/notices/retire", def: `package retire import "strings" @@ -93,18 +96,16 @@ import "strings" // date" or "Retirement date" column first, then the model and its // replacement), how far back it goes. var {{.Ident}} = Page{ - API: "{{.ID}}", - Vendor: "{{.Provider}}", - URL: "{{.Source}}", - // ` + todo + `: the provider's main call that takes a model name. - Operation: "POST /v1/TODO", - // ` + todo + `: keep the model names the operation above takes (text - // models, not image or embedding ones), as openAIText in providers.go does. + API: "{{.ID}}", + Provider: "{{.ProviderID}}", + Vendor: "{{.Provider}}", + URL: "{{.Source}}", + // ` + todo + `: keep the model names the provider's calls take as text + // models (not image or embedding ones), as openAIText in providers.go does. Keep: func(name string) bool { return strings.HasPrefix(name, "placeholder-text-") }, } `, register: `plugin.Register(Plugin{Page: retire.{{.Ident}}, Archiver: kit.Wayback{}})`, - 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 @@ -142,17 +143,18 @@ func Test{{.Ident}}DropsANonChange(t *testing.T) { source: "{{.File}}-deprecations.md", ingest: `// {{.Lower}}Ingest runs the plugin over a saved copy of the page, cited // through a test archive that serves the same copy. -func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { +func {{.Lower}}Ingest(t *testing.T, file string) []event.Event { t.Helper() saved := kittest.Pages{retire.{{.Ident}}.URL: file} archive := &kittest.Archive{T: t, Pages: saved} 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/core/event", "github.com/patch-it-dev/patch-it-plugins/plugins/retirements/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/notices/retire"}, }, - "migrationguide": { + "migrationguide/sdk": { + kind: "migrationguide", layer: "sdk", defDir: "plugins/migrationguide/sdkguide", def: `package sdkguide @@ -160,20 +162,18 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { // {{.Ident}} is {{.Provider}}'s SDK guide to a major release (MIGRATION.md at // the release tag). // -// ` + todo + `: the repo, the major release, the API operation the removed -// parameters were sent to, and the calls the guide's table names. Say what -// you checked, with the date. +// ` + todo + `: the PyPI name, the repo, the major release and the calls the +// guide's table names. Say what you checked, with the date. var {{.Ident}} = Guide{ - API: "{{.ID}}", - Repo: "TODO-owner/TODO-repo", - Major: 1, - Operation: "POST /v1/TODO", - Methods: "` + "`TODO.create()`" + `", - Symbols: []string{"TODO.create"}, + API: "{{.ID}}", + Package: "{{.PyPI}}", + Repo: "TODO-owner/TODO-repo", + Major: 1, + Methods: "` + "`TODO.create()`" + `", + Symbols: []string{"TODO.create"}, } `, register: `plugin.Register(Plugin{Guide: 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 @@ -210,7 +210,7 @@ func Test{{.Ident}}DropsANonChange(t *testing.T) { `, source: "{{.File}}-MIGRATION.md", ingest: `// {{.Lower}}Ingest runs the plugin over a saved copy of the guide. -func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { +func {{.Lower}}Ingest(t *testing.T, file string) []event.Event { t.Helper() return kittest.Ingest(t, Plugin{Guide: sdkguide.{{.Ident}}}, kittest.Pages{sdkguide.{{.Ident}}.URL(): file}) } @@ -218,10 +218,11 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { 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": { + "migrationguide/members": { + kind: "migrationguide", layer: "package", - defDir: "plugins/removedmembers", - def: `package removedmembers + defDir: "plugins/migrationguide/members", + def: `package members // {{.Ident}} is {{.Provider}}'s migration guide to a release, with its table // of removed members. @@ -230,16 +231,17 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { // the repo, the guide's path at the release tag and the heading the table is // under. Say what you checked, with the date. var {{.Ident}} = Guide{ - Package: "{{.ID}}", - Module: "{{.ID}}", + API: "{{.ID}}", + Package: "{{.PyPI}}", + Module: "{{.Module}}", Release: "1.0.0", Repo: "TODO-owner/TODO-repo", Path: "TODO/migration_guide.rst", Section: "Removed members", } `, - register: `plugin.Register(Plugin{Guide: {{.Ident}}})`, - pluginOf: `Plugin{Guide: {{.Ident}}}`, + register: `plugin.Register(Plugin{Guide: members.{{.Ident}}})`, + pluginOf: `Plugin{Guide: members.{{.Ident}}}`, fixtures: map[string]string{"{{.File}}-migration-guide.rst": `.. ` + todo + `: a placeholder. Replace it with a real copy of the guide at the release tag and list it in README.md. Removed members @@ -248,7 +250,7 @@ Removed members ====================== ========================== Removed member Migration guideline ====================== ========================== -placeholder_member Use ` + "``{{.ID}}.placeholder_new``" + ` instead. +placeholder_member Use ` + "``{{.Module}}.placeholder_new``" + ` instead. ====================== ========================== `}, dropFile: `.. ` + todo + `: a placeholder. Replace it with a real copy of the guide and say in the test why its other table is no removal. @@ -259,7 +261,7 @@ Removed members ====================== ========================== Removed member Migration guideline ====================== ========================== -placeholder_member Use ` + "``{{.ID}}.placeholder_new``" + ` instead. +placeholder_member Use ` + "``{{.Module}}.placeholder_new``" + ` instead. ====================== ========================== Other members @@ -278,22 +280,23 @@ placeholder_elsewhere Not in the main table. func Test{{.Ident}}DropsANonChange(t *testing.T) { for _, e := range {{.Lower}}Ingest(t, {{.Lower}}Drop) { if slices.Contains(e.Subject.Symbols, "placeholder_elsewhere") { - t.Errorf("event for placeholder_elsewhere, which isn't under %q", {{.Ident}}.Section) + t.Errorf("event for placeholder_elsewhere, which isn't under %q", members.{{.Ident}}.Section) } } } `, source: "{{.File}}-migration-guide.rst", ingest: `// {{.Lower}}Ingest runs the plugin over a saved copy of the guide. -func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { +func {{.Lower}}Ingest(t *testing.T, file string) []event.Event { t.Helper() - return kittest.Ingest(t, Plugin{Guide: {{.Ident}}}, kittest.Pages{ {{.Ident}}.URL(): file}) + return kittest.Ingest(t, Plugin{Guide: members.{{.Ident}}}, kittest.Pages{members.{{.Ident}}.URL(): file}) } `, - imports: []string{"slices", "github.com/patch-it-dev/patch-it-plugins/core/event"}, + imports: []string{"slices", "github.com/patch-it-dev/patch-it-plugins/core/event", "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/members"}, }, - "changelog": { + "changelog/markdown": { + kind: "changelog", layer: "package", defDir: "plugins/changelog", def: `package changelog @@ -305,7 +308,7 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { // the changelog's path. Say what you checked, with the date, as changelog.go // does for Textual and urllib3. var {{.Ident}} = File{ - Package: "{{.ID}}", Ecosystem: "pypi", Module: "{{.ID}}", + API: "{{.ID}}", Package: "{{.PyPI}}", Ecosystem: "pypi", Module: "{{.Module}}", Repo: "TODO-owner/TODO-repo", TagPrefix: "v", Path: "CHANGELOG.md", } @@ -326,7 +329,7 @@ var {{.Ident}}Golden = {{.Ident}}.At("1.0.0") `}, source: "{{.File}}-CHANGELOG.md", ingest: `// {{.Lower}}Ingest runs the plugin over a saved copy of the changelog. -func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { +func {{.Lower}}Ingest(t *testing.T, file string) []event.Event { t.Helper() return kittest.Ingest(t, Plugin{File: {{.Ident}}Golden}, kittest.Pages{ {{.Ident}}Golden.URL(): file}) } @@ -334,15 +337,16 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { imports: []string{"github.com/patch-it-dev/patch-it-plugins/core/event"}, }, - "apichangelog": { + "changelog/json": { + kind: "changelog", layer: "api", - defDir: "plugins/apichangelog", - def: `package apichangelog + defDir: "plugins/changelog", + def: `package changelog // {{.Ident}} is {{.Provider}}'s machine-readable API changelog. // // ` + todo + `: the repo and the file's path, and what you checked, with the -// date, as apichangelog.go does for MongoDB Atlas. +// date, as json.go does for MongoDB Atlas. var {{.Ident}} = Log{ API: "{{.ID}}", Vendor: "{{.Provider}}", Name: "TODO: the API's name, for sentences", Repo: "TODO-owner/TODO-repo", Path: "changelog/changelog.json", @@ -360,7 +364,7 @@ var {{.Ident}} = Log{ const {{.Lower}}Commit = "0000000000000000000000000000000000000000" // {{.Lower}}Ingest runs the plugin over a saved copy of the changelog. -func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { +func {{.Lower}}Ingest(t *testing.T, file string) []event.Event { t.Helper() return kittest.Ingest(t, Plugin{Log: {{.Ident}}}, kittest.Pages{ {{.Ident}}.CommitsURL(): "testdata/{{.File}}-commits.json", @@ -372,6 +376,7 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { }, "catalog": { + kind: "catalog", layer: "runtime", defDir: "plugins/catalog", def: `package catalog @@ -383,7 +388,7 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { // the catalog's path and the commits API URL for the newest ref. Say what you // checked, with the date, as catalog.go does for Redis. var {{.Ident}} = Catalog{ - API: "{{.ID}}", Ecosystem: "{{.ID}}", Package: "{{.ID}}", + API: "{{.ID}}", Ecosystem: "{{.ProviderID}}", Package: "{{.ProviderID}}", Repo: "TODO-owner/TODO-repo", Path: "TODO/commands.json", RefsURL: "https://api.github.com/repos/TODO-owner/TODO-repo/commits/main", } @@ -402,8 +407,8 @@ const ( {{.Lower}}NewRef = "1111111111111111111111111111111111111111" ) -// {{.Lower}}Ingest replays the saved old snapshot against file. -func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { +// {{.Lower}}Ingest extracts the change from the saved old snapshot to file. +func {{.Lower}}Ingest(t *testing.T, file string) []event.Event { t.Helper() env := kittest.Env(t, kittest.Pages{ {{.Ident}}.URL({{.Lower}}OldRef): "testdata/{{.File}}-old.json", @@ -411,8 +416,8 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { }) sink := env.Baselines.(kittest.Sink) p := Plugin{Catalog: {{.Ident}}} - if rejected, err := kittest.Replay(context.Background(), env, sink, p, {{.Lower}}OldRef, {{.Lower}}NewRef); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + if rejected, err := kittest.Pair(context.Background(), env, sink, p, {{.Lower}}OldRef, {{.Lower}}NewRef); err != nil || rejected { + t.Fatalf("pair: rejected=%v err=%v", rejected, err) } return kittest.Stored(t, sink) } @@ -421,6 +426,7 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { }, "openapi": { + kind: "openapi", layer: "api", defDir: "plugins/openapi/adapter", def: `package adapter @@ -428,6 +434,8 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { import ( "context" "fmt" + + "github.com/patch-it-dev/patch-it-plugins/core/plugin" ) // {{.Ident}} adapts {{.Provider}}'s OpenAPI spec for the openapi plugin. @@ -451,6 +459,14 @@ func ({{.Ident}}) LatestTag(ctx context.Context) (string, error) { func ({{.Ident}}) Fetch(ctx context.Context, tag string) (Spec, error) { return Spec{}, fmt.Errorf("{{.ID}}: Fetch isn't written yet (plugins/openapi/adapter/{{.File}}.go)") } + +// Versions are every release of the spec, oldest first, each with the Ref +// Fetch takes: what lets every pair of releases be diffed, not only the +// newest. ` + todo + `: list them with core/versions (GitHubReleases, +// GitHubCommits, GitHubTags), as versions.go does for the other adapters. +func ({{.Ident}}) Versions(ctx context.Context) ([]plugin.Version, error) { + return nil, fmt.Errorf("{{.ID}}: Versions isn't written yet (plugins/openapi/adapter/{{.File}}.go)") +} `, register: `plugin.Register(Plugin{Adapter: adapter.{{.Ident}}{}})`, pluginOf: `Plugin{Adapter: adapter.{{.Ident}}{}}`, @@ -479,25 +495,107 @@ func (a {{.Lower}}Adapter) Fetch(_ context.Context, tag string) (adapter.Spec, e return adapter.Spec{Content: body, Version: tag, SourceURL: "{{.Source}}"}, nil } -// {{.Lower}}Ingest replays the saved old spec against file. -func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { +// {{.Lower}}Ingest extracts the change from the saved old spec to file. +func {{.Lower}}Ingest(t *testing.T, file string) []event.Event { t.Helper() env := kittest.Env(t, nil) sink := env.Baselines.(kittest.Sink) p := Plugin{Adapter: {{.Lower}}Adapter{"old": "testdata/{{.File}}-old.json", "new": file}} - if rejected, err := kittest.Replay(context.Background(), env, sink, p, "old", "new"); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + if rejected, err := kittest.Pair(context.Background(), env, sink, p, "old", "new"); err != nil || rejected { + t.Fatalf("pair: rejected=%v err=%v", rejected, err) } return kittest.Stored(t, sink) } `, 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).", + next: "Write LatestTag, Fetch and Versions in plugins/openapi/adapter/{{.File}}.go (fetch.Get only); add Diff/Keep to the Register line if the spec needs them (see vercel.go).", + }, + "apisurface": { + kind: "apisurface", + layer: "sdk", + defDir: "plugins/apisurface", + def: `package apisurface + +// {{.Ident}} is {{.Provider}}'s package on PyPI, its public API read from each +// release's wheel. +// +// ` + todo + `: check the name on PyPI and the top-level module code +// imports (from --package, or guessed). Say +// what you checked, with the date: that the wheel holds the package's .py +// (or .pyi) files. +var {{.Ident}} = Package{ID: "{{.ID}}", Name: "{{.PyPI}}", Ecosystem: "pypi", Module: "{{.Module}}"} +`, + register: `plugin.Register(Plugin{Package: {{.Ident}}})`, + pluginOf: `Plugin{Package: {{.Ident}}}`, + fixtures: map[string]string{ + "{{.File}}-old.py": "# ` + todo + `: a placeholder for the older release's module. Save the real release's wheel instead (see apisurface_test.go).\ndef placeholder(a, b=1):\n pass\n", + "{{.File}}-new.py": "# ` + todo + `: a placeholder for the newer release's module: it drops b, one event.\ndef placeholder(a):\n pass\n", + }, + // The drop test's newer release: the older one again, nothing gone. + dropFile: "# ` + todo + `: a placeholder: a release that only adds or changes private names.\ndef placeholder(a, b=1):\n pass\n\ndef _private(x):\n pass\n", + source: "{{.File}}-new.py", + ingest: `// {{.Lower}}Ingest compares two releases: 1.0.0, a wheel holding +// testdata/{{.File}}-old.py as {{.Module}}/__init__.py, and 1.1.0, one +// holding file. The wheels are built here so the placeholders are text. +// ` + todo + `: save the two real wheels (trimmed if they're large, as +// apisurface_test.go's are) and serve them instead. +func {{.Lower}}Ingest(t *testing.T, file string) []event.Event { + t.Helper() + wheel := func(src string) []byte { + var buf bytes.Buffer + zw := zip.NewWriter(&buf) + w, err := zw.Create("{{.Module}}/__init__.py") + if err != nil { + t.Fatal(err) + } + w.Write(kittest.Read(t, src)) + if err := zw.Close(); err != nil { + t.Fatal(err) + } + return buf.Bytes() + } + files := map[string][]byte{ + "https://pypi.org/pypi/{{.PyPI}}/json": []byte(` + "`" + `{"releases": {"1.0.0": [{"upload_time_iso_8601": "2026-01-01T00:00:00Z"}], "1.1.0": [{"upload_time_iso_8601": "2026-02-01T00:00:00Z"}]}}` + "`" + `), + "https://pypi.org/pypi/{{.PyPI}}/1.0.0/json": []byte(` + "`" + `{"urls": [{"packagetype": "bdist_wheel", "filename": "{{.Module}}-1.0.0-py3-none-any.whl", "url": "https://example.com/{{.Module}}-1.0.0-py3-none-any.whl"}]}` + "`" + `), + "https://pypi.org/pypi/{{.PyPI}}/1.1.0/json": []byte(` + "`" + `{"urls": [{"packagetype": "bdist_wheel", "filename": "{{.Module}}-1.1.0-py3-none-any.whl", "url": "https://example.com/{{.Module}}-1.1.0-py3-none-any.whl"}]}` + "`" + `), + "https://example.com/{{.Module}}-1.0.0-py3-none-any.whl": wheel("testdata/{{.File}}-old.py"), + "https://example.com/{{.Module}}-1.1.0-py3-none-any.whl": wheel(file), + } + env := kittest.Env(t, nil) + env.Get = func(_ context.Context, url string) ([]byte, error) { + if b, ok := files[url]; ok { + return b, nil + } + t.Errorf("fetched %s, which the test didn't save", url) + return nil, fmt.Errorf("no saved copy of %s", url) + } + ctx, p := context.Background(), Plugin{Package: {{.Ident}}} + vs, err := p.ListVersions(ctx, env) + if err != nil || len(vs) != 2 { + t.Fatalf("versions %v: %v", vs, err) + } + from, err := p.ReadAt(ctx, env, vs[0]) + if err != nil { + t.Fatal(err) + } + to, err := p.ReadAt(ctx, env, vs[1]) + if err != nil { + t.Fatal(err) + } + res, err := p.Extract(ctx, env, from, to) + if err != nil || len(res.Rejected) > 0 { + t.Fatalf("%v %v", err, res.Rejected) + } + return res.Events +} +`, + imports: []string{"archive/zip", "bytes", "context", "fmt", "github.com/patch-it-dev/patch-it-plugins/core/event"}, + next: "Save two real wheels of the package and serve them in {{.Lower}}Ingest; the kind reads their .py files, never runs them.", }, } // testFile is the generated test, the same for every format. -const testFile = `package {{.Format}} +const testFile = `package {{.Kind}} import ( {{range .Imports}} "{{.}}" @@ -518,12 +616,12 @@ func Test{{.Ident}}RegistersItself(t *testing.T) { // The golden test: the saved source in, every event out. // ` + todo + `: once the source is real, run // -// go test ./plugins/{{.Format}} -run Test{{.Ident}}Golden -update +// go test ./plugins/{{.Kind}} -run Test{{.Ident}}Golden -update // -// and read testdata/golden/{{.ID}}.json like code: every event in it is a +// and read testdata/golden/{{.Name}}.json like code: every event in it is a // pull request someone may get. func Test{{.Ident}}Golden(t *testing.T) { - kittest.Golden(t, "testdata/golden/{{.ID}}.json", {{.Lower}}Ingest(t, {{.Lower}}Source)) + kittest.Golden(t, "testdata/golden/{{.Name}}.json", {{.Lower}}Ingest(t, {{.Lower}}Source)) } {{if .Drop}}{{.Drop}}{{else}}// The pinned drop test: a realistic input that must not become an event. diff --git a/cmd/new-plugin/main.go b/cmd/new-plugin/main.go index 12e21bc..f508721 100644 --- a/cmd/new-plugin/main.go +++ b/cmd/new-plugin/main.go @@ -1,23 +1,35 @@ -// Command new-plugin scaffolds a provider on one of the format plugins, so a -// contributor only fills in what is specific to the provider. Run it from the -// repo root: +// Command new-plugin scaffolds a source of a provider on one of the kinds, +// so a contributor only fills in what is specific to it. Run it from the +// repo root (or `make new-plugin ARGS='...'`): // -// go run ./cmd/new-plugin --api acme --provider Acme --format openapi +// go run ./cmd/new-plugin --provider acme --name Acme --category devtools \ +// --homepage https://acme.example --source api --kind openapi \ +// --url https://github.com/acme/openapi --package pypi:acme // -// It writes the provider's definition in the format's package (or the reader -// package the format uses: plugins/openapi/adapter/, plugins/retirements/retire/, -// plugins/migrationguide/sdkguide/), adds its -// plugin.RegisterProvider block (the source's metadata) to plugins/'s -// init, a test (registered, golden, drop) over placeholder sources with an -// empty golden file, a row in that testdata/README.md, and providers/.md -// from providers/_template.md. `go test ./...` -// passes right after; every place to fill in says TODO(new-plugin). +// A flag left out is asked for when the command runs in a terminal; a +// second source of a registered provider needs only --provider, --source +// and --kind (the provider's name, category and homepage come from the +// registry). Run it once per source. // -// It changes nothing when the id is taken (registered, or a file it would -// write exists). +// It writes the source's definition in the kind's package (or the reader +// package the kind uses: plugins/openapi/adapter/, plugins/notices/retire/, +// plugins/notices/feed/, plugins/migrationguide/sdkguide/, +// plugins/migrationguide/members/), with the version wiring the kind needs +// from it (an OpenAPI adapter's Versions; every other kind lists, reads and +// extracts versions itself), adds the plugin.RegisterProvider block (the +// provider and the source with their metadata) to the kind'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 the kind's import in plugins/all when it isn't +// there. `go test ./...` passes right after; every place to fill in says +// TODO(new-plugin). +// +// It changes nothing when the provider/source id is taken, or a file it +// would write exists. package main import ( + "bufio" "bytes" "flag" "fmt" @@ -42,31 +54,64 @@ import ( // Options are the command's flags. type Options struct { - Root string // the repo root - API string // the plugin id: --api and every event's api - Provider string // whose API, SDK or package - Format string // the format plugin - Layer string // the source's layer (plugin.Layers()); "" is the format's default - Source string // the provider's source URL; "" is a placeholder - Watches string // what the source watches, in a few words - Page string // the provider page, providers/.md; "" is the id. An existing page is shared, not rewritten - Today time.Time + Root string // the repo root + + // The provider. + ProviderID string // lowercase slug: "acme" + Provider string // its name, as it writes it: "Acme" + Category string // one of plugin.Categories(); a registered provider's is kept + Homepage string // its own site + + // The source. + SourceID string // unique within the provider: "api", "python-sdk" + Kind string // the kind that reads it: plugins/ + Reader string // for a kind with several readers: "feed" for notices; "" is the kind's default + Layer string // the source's layer (plugin.Layers()); "" is the template's default + URLs []string // the provider's pages or files it reads; none is a placeholder + Packages []string // the packages it covers, "pypi:acme" + Watches string // what the source watches, in a few words + Page string // the provider page, providers/.md; "" is -. An existing page is shared, not rewritten + + Today time.Time // Go runs the go command afterwards: the golden file from the placeholders // (go test -update). Go bool + + tmpl string // the template: a kind, or kind/reader + name string // the files' base name: -, or the provider's id when they're the same + url string // the first URL } +// list is a repeatable flag. +type list []string + +func (l *list) String() string { return strings.Join(*l, ",") } +func (l *list) Set(v string) error { *l = append(*l, v); return nil } + func main() { var o Options + var urls, packages list flag.StringVar(&o.Root, "root", ".", "the repo root") - flag.StringVar(&o.API, "api", "", "the plugin id, e.g. acme or acme-models (lowercase letters, digits, hyphens)") - flag.StringVar(&o.Provider, "provider", "", "the provider's name, e.g. Acme") - flag.StringVar(&o.Format, "format", "", "the format plugin: "+strings.Join(formatNames(), ", ")) - flag.StringVar(&o.Layer, "layer", "", "the source's layer: api, sdk, package, runtime, ci, ai-models or infra (default: the format's)") - flag.StringVar(&o.Source, "source", "", "the provider's source URL (default: a placeholder to fill in)") + flag.StringVar(&o.ProviderID, "provider", "", "the provider's id, e.g. acme") + flag.StringVar(&o.Provider, "name", "", "the provider's name as it writes it, e.g. Acme (a registered provider's is kept)") + flag.StringVar(&o.Category, "category", "", "the provider's category: "+strings.Join(categories(), ", ")) + flag.StringVar(&o.Homepage, "homepage", "", "the provider's own site, https://...") + flag.StringVar(&o.SourceID, "source", "", "the source's id within the provider, e.g. api or python-sdk") + flag.StringVar(&o.Kind, "kind", "", "the kind that reads it: "+strings.Join(kindNames(), ", ")) + flag.StringVar(&o.Reader, "reader", "", "the kind's reader, for a kind with several: "+readerHelp()) + flag.StringVar(&o.Layer, "layer", "", "the source's layer: api, sdk, package, runtime, ci, ai-models or infra (default: the kind's)") + flag.Var(&urls, "url", "a page or file the source reads, https://... (repeatable; default: a placeholder to fill in)") + flag.Var(&packages, "package", "a package the source covers, ecosystem:name, e.g. pypi:acme or npm:@acme/sdk (repeatable)") flag.StringVar(&o.Watches, "watches", "", "what it watches, in a few words (default: a placeholder)") - flag.StringVar(&o.Page, "page", "", "the provider page, providers/.md (default: the --api id); one page per provider, so a second plugin of a provider names the existing page") + flag.StringVar(&o.Page, "page", "", "the provider page, providers/.md (default: -); a second source of a provider may share the existing page") flag.Parse() + o.URLs, o.Packages = urls, packages + if term() { + if err := ask(&o, bufio.NewReader(os.Stdin), os.Stdout); err != nil { + fmt.Fprintln(os.Stderr, "new-plugin:", err) + os.Exit(1) + } + } o.Today = time.Now().UTC() o.Go = true if err := Run(o, os.Stdout); err != nil { @@ -75,6 +120,7 @@ func main() { } } +// formatNames are the templates: a kind, or kind/reader. func formatNames() []string { var names []string for n := range formats { @@ -84,6 +130,58 @@ func formatNames() []string { return names } +// kindNames are the kinds a template scaffolds. +func kindNames() []string { + var names []string + for n := range formats { + k, _, _ := strings.Cut(n, "/") + if !slices.Contains(names, k) { + names = append(names, k) + } + } + slices.Sort(names) + return names +} + +func readerHelp() string { + var parts []string + for _, k := range kindNames() { + var rs []string + for _, n := range formatNames() { + if kind, r, ok := strings.Cut(n, "/"); ok && kind == k { + rs = append(rs, r) + } + } + if len(rs) > 0 { + parts = append(parts, k+": "+strings.Join(rs, "|")+" (default "+defaultReaders[k]+")") + } + } + return strings.Join(parts, "; ") +} + +func categories() []string { + var out []string + for _, c := range plugin.Categories() { + out = append(out, string(c)) + } + return out +} + +// template is the template o asks for: from --kind and --reader. +func (o Options) template() (string, error) { + if !slices.Contains(kindNames(), o.Kind) { + return "", fmt.Errorf("--kind %q: want one of %s", o.Kind, strings.Join(kindNames(), ", ")) + } + if _, ok := formats[o.Kind]; ok && o.Reader == "" { + return o.Kind, nil + } + r := cmp(o.Reader, defaultReaders[o.Kind]) + if _, ok := formats[o.Kind+"/"+r]; !ok { + return "", fmt.Errorf("--reader %q: kind %s's readers are %s", o.Reader, o.Kind, readerHelp()) + } + return o.Kind + "/" + r, nil +} + var ( validID = regexp.MustCompile(`^[a-z][a-z0-9]*(-[a-z0-9]+)*$`) validURL = regexp.MustCompile(`^https://[^\s|()]+$`) @@ -94,20 +192,27 @@ var ( // data is what the templates fill in. type data struct { - ID, Ident, Lower, Provider, Source, File, Format string - Slug string // the provider, lowercase: a model subject's provider - SourceFile, DropFile, PluginOf, Ingest, Drop string - Imports []string + ID, Name, Ident, Lower, ProviderID, Provider, Source, File, Format, Kind, Module, PyPI string + Slug string // the provider, lowercase: a model subject's provider + SourceFile, DropFile, PluginOf, Ingest, Drop string + Imports []string } -// Run scaffolds the plugin, or changes nothing and says why. +// Run scaffolds the source, or changes nothing and says why. func Run(o Options, out io.Writer) error { - f, ok := formats[o.Format] - if !ok { - return fmt.Errorf("--format %q: want one of %s", o.Format, strings.Join(formatNames(), ", ")) + tmpl, err := o.template() + if err != nil { + return err + } + o.tmpl = tmpl + f := formats[tmpl] + if err := o.resolve(); err != nil { + return err } - if !validID.MatchString(o.API) || o.API == "all" { - return fmt.Errorf("--api %q: want lowercase letters, digits and single hyphens, starting with a letter (acme, acme-models), and not \"all\"", o.API) + id := o.ProviderID + "/" + o.SourceID + o.name = o.ProviderID + "-" + o.SourceID + if o.SourceID == o.ProviderID { + o.name = o.ProviderID } if o.Provider == "" || !cellSafe.MatchString(o.Provider) { return fmt.Errorf("--provider %q: want the provider's name, without |, quotes, backslashes or backticks", o.Provider) @@ -118,10 +223,23 @@ func Run(o Options, out io.Writer) error { if !slices.Contains(plugin.Layers(), plugin.Layer(o.Layer)) { return fmt.Errorf("--layer %q: want one of %v", o.Layer, plugin.Layers()) } - if o.Source == "" { - o.Source = "https://example.com/TODO-" + o.API + "-source" - } else if !validURL.MatchString(o.Source) { - return fmt.Errorf("--source %q: want an https URL", o.Source) + if len(o.URLs) == 0 { + o.URLs = []string{"https://example.com/TODO-" + o.name + "-source"} + } + o.url = o.URLs[0] + for _, u := range o.URLs { + if !validURL.MatchString(u) { + return fmt.Errorf("--url %q: want an https URL", u) + } + } + if len(o.Packages) == 0 && f.kind == "apisurface" { + o.Packages = []string{"pypi:" + o.ProviderID} + } + for _, p := range o.Packages { + eco, name, ok := strings.Cut(p, ":") + if !ok || !slices.Contains(plugin.Ecosystems(), eco) || name == "" || !cellSafe.MatchString(name) || strings.ContainsAny(name, " \t") { + return fmt.Errorf("--package %q: want ecosystem:name, the ecosystem one of %v", p, plugin.Ecosystems()) + } } if o.Watches == "" { o.Watches = "TODO: what it watches, in a few words" @@ -131,7 +249,7 @@ func Run(o Options, out io.Writer) error { sharedPage := false if o.Page == "" { - o.Page = o.API + o.Page = o.name } else if !validID.MatchString(o.Page) { return fmt.Errorf("--page %q: want the name of a page in providers/, without .md", o.Page) } else if _, err := os.Stat(filepath.Join(o.Root, "providers", o.Page+".md")); err == nil { @@ -139,14 +257,21 @@ func Run(o Options, out io.Writer) error { } // Taken? Check everything before writing anything. - if _, ok := plugin.Lookup(o.API); ok { - return fmt.Errorf("a plugin named %q is already registered: pick another --api", o.API) + if _, ok := plugin.LookupSource(id); ok { + return fmt.Errorf("source %s is already registered: pick another --source", id) } - d := data{ID: o.API, Provider: o.Provider, Source: o.Source, Format: o.Format} - d.Ident = ident(o.API) + d := data{ID: id, Name: o.name, ProviderID: o.ProviderID, Provider: o.Provider, Source: o.url, Format: o.tmpl, Kind: f.kind, PyPI: o.ProviderID} + for _, p := range o.Packages { + if name, ok := strings.CutPrefix(p, "pypi:"); ok { + d.PyPI = name + break + } + } + d.Module = strings.ReplaceAll(strings.ToLower(d.PyPI), "-", "_") + d.Ident = ident(o.name) d.Lower = string(unicode.ToLower(rune(d.Ident[0]))) + d.Ident[1:] - d.File = fileBase(o.API) + d.File = fileBase(o.name) d.Slug = strings.Trim(regexp.MustCompile(`[^a-z0-9]+`).ReplaceAllString(strings.ToLower(o.Provider), "-"), "-") d.SourceFile = fill(f.source, d) d.DropFile = dropName(d.SourceFile) @@ -156,13 +281,13 @@ func Run(o Options, out io.Writer) error { 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 + pkgDir := "plugins/" + f.kind writes := map[string][]byte{} add := func(path string, b []byte) { writes[path] = b } def, err := gofmt(fill(f.def, d)) if err != nil { - return fmt.Errorf("the %s template: %w", o.Format, err) + return fmt.Errorf("the %s template: %w", o.tmpl, err) } add(filepath.Join(f.defDir, d.File+".go"), def) test, err := gofmt(fill(testFile, d)) @@ -180,7 +305,7 @@ func Run(o Options, out io.Writer) error { add(filepath.Join(pkgDir, "testdata", d.DropFile), []byte(fill(drop, d))) // What the placeholders give; rewritten with -update below, and again // once the source is real. - add(filepath.Join(pkgDir, "testdata", "golden", o.API+".json"), []byte("[]\n")) + add(filepath.Join(pkgDir, "testdata", "golden", o.name+".json"), []byte("[]\n")) if !sharedPage { page, err := providerPage(o) @@ -192,7 +317,7 @@ func Run(o Options, out io.Writer) error { for path := range writes { if _, err := os.Stat(filepath.Join(o.Root, path)); err == nil { - return fmt.Errorf("%s already exists: pick another --api, or remove what's left of an earlier run", path) + return fmt.Errorf("%s already exists: pick another --source, or remove what's left of an earlier run", path) } } for _, dir := range []string{f.defDir, pkgDir} { @@ -207,17 +332,17 @@ func Run(o Options, out io.Writer) error { return err } edits := map[string][]byte{mainFile: registered} - if m := f.mapEntry; m != nil { - if edits[m.file], err = addMapEntry(filepath.Join(o.Root, m.file), m.varName, fill(m.entry, d)); err != nil { - return err - } + if all, ok, err := importInAll(o.Root, f.kind); err != nil { + return err + } else if ok { + edits[filepath.Join("plugins", "all", "all.go")] = all } readmePath := filepath.Join(pkgDir, "testdata", "README.md") readme, err := os.ReadFile(filepath.Join(o.Root, readmePath)) if err != nil { return err } - if edits[readmePath], err = readmeRows(readme, []string{d.SourceFile, d.DropFile}, o.Source); err != nil { + if edits[readmePath], err = readmeRows(readme, []string{d.SourceFile, d.DropFile}, o.url); err != nil { return fmt.Errorf("%s: %w", readmePath, err) } @@ -240,7 +365,7 @@ func Run(o Options, out io.Writer) error { paths = append(paths, path) } slices.Sort(paths) - fmt.Fprintf(out, "Scaffolded %s (%s, format %s):\n", o.API, o.Provider, o.Format) + fmt.Fprintf(out, "Scaffolded %s (%s, kind %s):\n", id, o.Provider, o.tmpl) for _, p := range paths { fmt.Fprintln(out, " "+p) } @@ -254,7 +379,7 @@ func Run(o Options, out io.Writer) error { return fmt.Errorf("the files are written, but `go %s` failed: %w\n%s", strings.Join(args, " "), err, b) } } - fmt.Fprintf(out, " %s (from the placeholders)\n", filepath.Join(pkgDir, "testdata", "golden", o.API+".json")) + fmt.Fprintf(out, " %s (from the placeholders)\n", filepath.Join(pkgDir, "testdata", "golden", o.name+".json")) } fmt.Fprint(out, fill(nextSteps, struct { data @@ -267,13 +392,13 @@ func Run(o Options, out io.Writer) error { const nextSteps = ` Next steps (every place to fill in says TODO(new-plugin): grep -rn 'TODO(new-plugin)' .): 1. Save a real copy of the source over the placeholder: - curl -fsSL -o plugins/{{.Format}}/testdata/{{.SourceFile}} '' - and a realistic input that must not become an event as plugins/{{.Format}}/testdata/{{.DropFile}}. - Fill in their rows in plugins/{{.Format}}/testdata/README.md (URL, date fetched, license, quote). + curl -fsSL -o plugins/{{.Kind}}/testdata/{{.SourceFile}} '' + and a realistic input that must not become an event as plugins/{{.Kind}}/testdata/{{.DropFile}}. + Fill in their rows in plugins/{{.Kind}}/testdata/README.md (URL, date fetched, license, quote). 2. Fill in the definition (the TODOs in the file next to the Register line for {{.Ident}}).{{if .Extra}} {{.Extra}}{{end}} 3. Write the golden file, then read it like code: - go test ./plugins/{{.Format}} -run Test{{.Ident}} -update + go test ./plugins/{{.Kind}} -run Test{{.Ident}} -update 4. {{if .Shared}}Add {{.ID}} to providers/{{.Page}}.md (shared with the provider's other plugins){{else}}Fill in providers/{{.Page}}.md{{end}}, above all "Why this source", and the source's metadata in its RegisterProvider block (what it watches, its URLs; a new provider's category and homepage). go run ./cmd/list-plugins prints the list with it; there is no list to edit. @@ -328,7 +453,7 @@ func identsFree(dir string, names ...string) error { for _, decl := range file.Decls { for _, n := range declNames(decl) { if slices.Contains(names, n) { - return fmt.Errorf("%s already declares %s: pick another --api", path, n) + return fmt.Errorf("%s already declares %s: pick another --source", path, n) } } } @@ -360,30 +485,42 @@ func declNames(decl ast.Decl) []string { return nil } -// providerBlock turns a format's "plugin.Register()" line into the -// provider's registration with its metadata: a provider already registered -// (a second source of Algolia) keeps its id, category and homepage; a new one -// gets placeholders that say TODO(new-plugin). +// providerBlock turns a template's "plugin.Register()" line into +// the provider's registration with its metadata: a provider already +// registered (a second source of Algolia) keeps its name, category and +// homepage; a new one gets what the flags say, or placeholders that say +// TODO(new-plugin). func providerBlock(o Options, d data, line string) string { expr := strings.TrimSuffix(strings.TrimPrefix(line, "plugin.Register("), ")") - id, category, homepage := d.Slug, "plugin.CategoryDevTools, // TODO(new-plugin): the provider's category, one of plugin.Categories()\n\t\t", `"https://example.com/TODO-`+d.Slug+`-homepage", // TODO(new-plugin): the provider's own site`+"\n\t\t" - for _, p := range plugin.Providers() { - if strings.EqualFold(p.Name, o.Provider) { - id, category, homepage = p.ID, fmt.Sprintf("%q,", p.Category), fmt.Sprintf("%q,", p.Homepage) - category = "plugin.Category(" + strings.TrimSuffix(category, ",") + ")," - } + category := "plugin.CategoryDevTools, // TODO(new-plugin): the provider's category, one of plugin.Categories()\n\t\t" + if o.Category != "" { + category = fmt.Sprintf("plugin.Category(%q),", o.Category) + } + homepage := `"https://example.com/TODO-` + o.ProviderID + `-homepage", // TODO(new-plugin): the provider's own site` + "\n\t\t" + if o.Homepage != "" { + homepage = fmt.Sprintf("%q,", o.Homepage) + } + var urls, pkgs []string + for _, u := range o.URLs { + urls = append(urls, fmt.Sprintf("%q", u)) + } + for _, p := range o.Packages { + pkgs = append(pkgs, fmt.Sprintf("%q", p)) + } + packages := "" + if len(pkgs) > 0 { + packages = fmt.Sprintf("\n\t\t\tPackages: []string{%s},", strings.Join(pkgs, ", ")) } - source := strings.TrimPrefix(o.API, id+"-") return fmt.Sprintf(`plugin.RegisterProvider(plugin.Provider{ ID: %q, Name: %q, Category: %s Homepage: %s Sources: []plugin.Source{{ ID: %q, Layer: %q, Page: %q, Watches: %q, - URLs: []string{%q}, + URLs: []string{%s},%s Plugin: %s, }}, - })`, id, o.Provider, category, homepage, source, o.Layer, "providers/"+o.Page+".md", o.Watches, o.Source, expr) + })`, o.ProviderID, o.Provider, category, homepage, o.SourceID, o.Layer, "providers/"+o.Page+".md", o.Watches, strings.Join(urls, ", "), packages, expr) } // register adds line at the end of the init func that registers pkgDir's @@ -427,39 +564,6 @@ func register(root, pkgDir, line string) (string, []byte, error) { return "", nil, fmt.Errorf("found no init in %s that calls plugin.RegisterProvider", pkgDir) } -// addMapEntry adds entry to the map literal varName is set to in path. -func addMapEntry(path, varName, entry string) ([]byte, error) { - src, err := os.ReadFile(path) - if err != nil { - return nil, err - } - fset := token.NewFileSet() - file, err := parser.ParseFile(fset, path, src, parser.SkipObjectResolution) - if err != nil { - return nil, err - } - var lit *ast.CompositeLit - ast.Inspect(file, func(n ast.Node) bool { - if v, ok := n.(*ast.ValueSpec); ok && len(v.Names) == 1 && v.Names[0].Name == varName && len(v.Values) == 1 { - lit, _ = v.Values[0].(*ast.CompositeLit) - } - return lit == nil - }) - if lit == nil { - return nil, fmt.Errorf("%s: no map literal %s to add %s to", path, varName, entry) - } - at := fset.Position(lit.Rbrace).Offset - var b bytes.Buffer - b.Write(src[:at]) - if len(lit.Elts) > 0 && fset.Position(lit.Elts[len(lit.Elts)-1].End()).Line == fset.Position(lit.Rbrace).Line { - b.WriteString(", " + entry) - } else { - b.WriteString("\t" + entry + ",\n") - } - b.Write(src[at:]) - return format.Source(b.Bytes()) -} - // readmeRows adds a row per saved file to the first table of a testdata // README whose first column is the file, with a TODO in every other column. func readmeRows(readme []byte, files []string, source string) ([]byte, error) { @@ -511,13 +615,6 @@ func readmeRows(readme []byte, files []string, source string) ([]byte, error) { return []byte(strings.Join(lines, "\n")), nil } -func linkText(url string) string { - if strings.Contains(url, "example.com/TODO") { - return "TODO: the source" - } - return strings.TrimPrefix(url, "https://") -} - // providerPage is providers/_template.md for this provider. func providerPage(o Options) ([]byte, error) { tmpl, err := os.ReadFile(filepath.Join(o.Root, "providers", "_template.md")) @@ -526,10 +623,10 @@ func providerPage(o Options) ([]byte, error) { } s := string(tmpl) s = strings.ReplaceAll(s, "", o.Provider) - s = strings.ReplaceAll(s, "", o.API) - s = strings.ReplaceAll(s, "``", "<"+o.Source+">") + s = strings.ReplaceAll(s, "`/`", "`"+o.ProviderID+"/"+o.SourceID+"`") + s = strings.ReplaceAll(s, "``", "<"+o.url+">") s = strings.ReplaceAll(s, "``", o.Today.Format("2006-01-02")+" (TODO(new-plugin): the date you checked it)") - s = strings.Replace(s, "Copy this file to `providers/"+o.API+".md` and fill every section. Delete these instructions.", + s = strings.Replace(s, "Copy this file to `providers/-.md` and fill every section. Delete these instructions.", "TODO(new-plugin): fill every section, then delete this line. Scaffolded by `go run ./cmd/new-plugin`.", 1) return []byte(s), nil } diff --git a/cmd/new-plugin/main_test.go b/cmd/new-plugin/main_test.go index 3092ef5..1ee9952 100644 --- a/cmd/new-plugin/main_test.go +++ b/cmd/new-plugin/main_test.go @@ -1,6 +1,7 @@ package main import ( + "bufio" "bytes" "crypto/sha256" "io" @@ -16,10 +17,18 @@ import ( var today = time.Date(2026, 11, 19, 0, 0, 0, 0, time.UTC) -// A plugin of every format, scaffolded into a copy of the repo: the copy -// builds, vets and passes its tests, and list-plugins lists them all. -// Then the same command again changes nothing. -func TestScaffoldEveryFormat(t *testing.T) { +// optionsFor is a source of the provider acme on template tmpl ("openapi", +// "notices/feed"). +func optionsFor(root, tmpl string) Options { + kind, reader, _ := strings.Cut(tmpl, "/") + return Options{Root: root, ProviderID: "acme", Provider: "Acme Corp", SourceID: strings.ReplaceAll(tmpl, "/", "-"), + Kind: kind, Reader: reader, Packages: []string{"pypi:acme-" + strings.ReplaceAll(tmpl, "/", "-")}, Today: today, Go: true} +} + +// A source of every kind and reader, scaffolded into a copy of the repo: +// the copy builds, vets and passes its tests, and list-plugins lists them +// all. Then the same command again changes nothing. +func TestScaffoldEveryKind(t *testing.T) { if testing.Short() { t.Skip("runs the go command over a copy of the repo") } @@ -29,7 +38,7 @@ func TestScaffoldEveryFormat(t *testing.T) { } root := copyRepo(t) for _, f := range formatNames() { - o := Options{Root: root, API: "acme-" + f, Provider: "Acme Corp", Format: f, Today: today, Go: true} + o := optionsFor(root, f) var out bytes.Buffer if err := Run(o, &out); err != nil { t.Fatalf("%s: %v\n%s", f, err, out.String()) @@ -38,7 +47,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/...", "./core/migrate/..."}} { + for _, args := range [][]string{{"build", "./..."}, {"vet", "./..."}, {"test", "-count=1", "./plugins/...", "./internal/..."}} { cmd := exec.Command(goCmd, args...) cmd.Dir = root if b, err := cmd.CombinedOutput(); err != nil { @@ -52,13 +61,14 @@ func TestScaffoldEveryFormat(t *testing.T) { t.Fatalf("go run ./cmd/list-plugins: %v", err) } for _, f := range formatNames() { - if !bytes.Contains(listed, []byte(`"alias": "acme-`+f+`"`)) { - t.Errorf("list-plugins doesn't list acme-%s", f) + id := strings.ReplaceAll(f, "/", "-") + if !bytes.Contains(listed, []byte(`"id": "acme/`+id+`"`)) || !bytes.Contains(listed, []byte(`"pypi:acme-`+id+`"`)) { + t.Errorf("list-plugins doesn't list acme/%s with its package", id) } } before := tree(t, root) - err = Run(Options{Root: root, API: "acme-feed", Provider: "Acme Corp", Format: "feed", Today: today, Go: true}, io.Discard) + err = Run(optionsFor(root, "notices/feed"), io.Discard) if err == nil || !strings.Contains(err.Error(), "already exists") { t.Errorf("second run: err = %v, want the id taken", err) } @@ -71,7 +81,7 @@ func TestScaffoldEveryFormat(t *testing.T) { // page, and the registration names the existing ones. func TestScaffoldSharesTheProviderPage(t *testing.T) { root := copyRepo(t) - o := Options{Root: root, API: "algolia-analytics", Provider: "Algolia", Format: "openapi", Page: "algolia", Today: today} + o := Options{Root: root, ProviderID: "algolia", SourceID: "analytics", Kind: "openapi", Page: "algolia", Today: today} if err := Run(o, io.Discard); err != nil { t.Fatal(err) } @@ -90,16 +100,20 @@ func TestRefusesBadInput(t *testing.T) { root := copyRepo(t) before := tree(t, root) for name, o := range map[string]Options{ - "unknown format": {API: "acme", Provider: "Acme", Format: "graphql"}, - "uppercase id": {API: "Acme", Provider: "Acme", Format: "feed"}, - "double hyphen": {API: "acme--x", Provider: "Acme", Format: "feed"}, - "id all": {API: "all", Provider: "Acme", Format: "feed"}, - "registered id": {API: "stripe", Provider: "Stripe", Format: "openapi"}, - "no provider": {API: "acme", Format: "feed"}, - "pipe in name": {API: "acme", Provider: "Ac|me", Format: "feed"}, - "unknown layer": {API: "acme", Provider: "Acme", Format: "feed", Layer: "database"}, - "http source": {API: "acme", Provider: "Acme", Format: "feed", Source: "http://acme.example/feed"}, - "provider exists": {API: "numpy", Provider: "NumPy", Format: "changelog"}, + "unknown kind": {ProviderID: "acme", Provider: "Acme", SourceID: "api", Kind: "graphql"}, + "unknown reader": {ProviderID: "acme", Provider: "Acme", SourceID: "api", Kind: "notices", Reader: "tweets"}, + "no source id": {ProviderID: "acme", Provider: "Acme", Kind: "openapi"}, + "source registered": {ProviderID: "stripe", SourceID: "api", Kind: "openapi"}, + "other name": {ProviderID: "stripe", Provider: "Stripe Inc", SourceID: "sdk", Kind: "apisurface"}, + "bad category": {ProviderID: "acme", Provider: "Acme", SourceID: "api", Kind: "openapi", Category: "toys"}, + "bad package": {ProviderID: "acme", Provider: "Acme", SourceID: "api", Kind: "openapi", Packages: []string{"pip:acme"}}, + "uppercase id": {ProviderID: "Acme", Provider: "Acme", SourceID: "api", Kind: "notices"}, + "double hyphen": {ProviderID: "acme", Provider: "Acme", SourceID: "a--x", Kind: "notices"}, + "no provider name": {ProviderID: "acme", SourceID: "api", Kind: "notices"}, + "pipe in name": {ProviderID: "acme", Provider: "Ac|me", SourceID: "api", Kind: "notices"}, + "unknown layer": {ProviderID: "acme", Provider: "Acme", SourceID: "api", Kind: "notices", Layer: "database"}, + "http source": {ProviderID: "acme", Provider: "Acme", SourceID: "api", Kind: "notices", URLs: []string{"http://acme.example/feed"}}, + "provider exists": {ProviderID: "numpy", Provider: "NumPy Inc", SourceID: "changes", Kind: "changelog"}, } { o.Root, o.Today = root, today if err := Run(o, io.Discard); err == nil { @@ -187,3 +201,20 @@ func hash(b []byte) string { sum := sha256.Sum256(b) return string(sum[:]) } + +// Asked at a terminal: what the flags left out, a registered provider's +// name, category and homepage not asked again. +func TestAsksWhatIsMissing(t *testing.T) { + o := Options{ProviderID: "stripe"} + in := bufio.NewReader(strings.NewReader("python-sdk\napisurface\nsdk\nhttps://pypi.org/project/stripe/\npypi:stripe\nRemoved names\n")) + var out bytes.Buffer + if err := ask(&o, in, &out); err != nil { + t.Fatal(err) + } + if o.SourceID != "python-sdk" || o.Kind != "apisurface" || o.Layer != "sdk" || o.URLs[0] != "https://pypi.org/project/stripe/" || o.Packages[0] != "pypi:stripe" || o.Watches != "Removed names" || o.Provider != "" { + t.Errorf("%+v", o) + } + if strings.Contains(out.String(), "Provider name") { + t.Errorf("asked for a registered provider's name:\n%s", out.String()) + } +} diff --git a/cmd/new-plugin/resolve.go b/cmd/new-plugin/resolve.go new file mode 100644 index 0000000..99612db --- /dev/null +++ b/cmd/new-plugin/resolve.go @@ -0,0 +1,151 @@ +package main + +import ( + "bufio" + "bytes" + "fmt" + "go/format" + "io" + "os" + "path/filepath" + "slices" + "strings" + + "github.com/patch-it-dev/patch-it-plugins/core/plugin" +) + +// resolve fills in the provider from the registry: a registered provider's +// name, category and homepage. +func (o *Options) resolve() error { + if !validID.MatchString(o.ProviderID) { + return fmt.Errorf("--provider %q: want the provider's id, lowercase letters, digits and single hyphens (acme)", o.ProviderID) + } + if !validID.MatchString(o.SourceID) { + return fmt.Errorf("--source %q: want the source's id within the provider, lowercase letters, digits and single hyphens (api, python-sdk)", o.SourceID) + } + if i := slices.IndexFunc(plugin.Providers(), func(p plugin.Provider) bool { return p.ID == o.ProviderID }); i >= 0 { + p := plugin.Providers()[i] + switch { + case o.Provider != "" && !strings.EqualFold(o.Provider, p.Name): + return fmt.Errorf("--name %q: provider %s is registered as %q", o.Provider, p.ID, p.Name) + case o.Category != "" && o.Category != string(p.Category): + return fmt.Errorf("--category %q: provider %s is registered in %q", o.Category, p.ID, p.Category) + case o.Homepage != "" && o.Homepage != p.Homepage: + return fmt.Errorf("--homepage %q: provider %s is registered with %q", o.Homepage, p.ID, p.Homepage) + } + o.Provider, o.Category, o.Homepage = p.Name, string(p.Category), p.Homepage + } else { + if o.Category != "" && !slices.Contains(categories(), o.Category) { + return fmt.Errorf("--category %q: want one of %s", o.Category, strings.Join(categories(), ", ")) + } + if o.Homepage != "" && !validURL.MatchString(o.Homepage) { + return fmt.Errorf("--homepage %q: want an https URL", o.Homepage) + } + } + return nil +} + +// term is true when stdin is a terminal: flags left out are asked for. +func term() bool { + fi, err := os.Stdin.Stat() + return err == nil && fi.Mode()&os.ModeCharDevice != 0 +} + +// ask fills in, from a person at a terminal, what the flags left out: only +// when one of the provider id, the source id or the kind is missing (a full +// command line asks nothing). +func ask(o *Options, in *bufio.Reader, out io.Writer) error { + if o.ProviderID != "" && o.SourceID != "" && o.Kind != "" { + return nil + } + prompt := func(field *string, question, def string) error { + if *field != "" { + return nil + } + if def != "" { + question += " [" + def + "]" + } + fmt.Fprint(out, question+": ") + line, _ := in.ReadString('\n') // no answer (end of input) is the default + *field = cmp(strings.TrimSpace(line), def) + return nil + } + list := func(field *[]string, question string) error { + if len(*field) > 0 { + return nil + } + var answer string + if err := prompt(&answer, question+" (comma-separated, empty for none)", ""); err != nil { + return err + } + for _, v := range strings.Split(answer, ",") { + if v = strings.TrimSpace(v); v != "" { + *field = append(*field, v) + } + } + return nil + } + if err := prompt(&o.ProviderID, "Provider id (acme)", ""); err != nil { + return err + } + if !slices.ContainsFunc(plugin.Providers(), func(p plugin.Provider) bool { return p.ID == o.ProviderID }) { + for _, q := range []struct { + field *string + question string + }{ + {&o.Provider, "Provider name, as it writes it (Acme)"}, + {&o.Category, "Category (" + strings.Join(categories(), ", ") + ")"}, + {&o.Homepage, "Homepage (https://...)"}, + } { + if err := prompt(q.field, q.question, ""); err != nil { + return err + } + } + } + if err := prompt(&o.SourceID, "Source id within the provider (api, python-sdk)", ""); err != nil { + return err + } + if err := prompt(&o.Kind, "Kind ("+strings.Join(kindNames(), ", ")+"; docs/which-kind.md)", ""); err != nil { + return err + } + if def := defaultReaders[o.Kind]; def != "" { + if err := prompt(&o.Reader, "Reader ("+readerHelp()+")", def); err != nil { + return err + } + } + if err := prompt(&o.Layer, "Layer (api, sdk, package, runtime, ci, ai-models, infra; empty for the kind's default)", ""); err != nil { + return err + } + if err := list(&o.URLs, "URLs it reads (https://...)"); err != nil { + return err + } + if err := list(&o.Packages, "Packages it covers (pypi:acme, npm:@acme/sdk)"); err != nil { + return err + } + return prompt(&o.Watches, "What it watches, in a few words", "") +} + +func cmp(a, b string) string { + if a != "" { + return a + } + return b +} + +// importInAll adds plugins/ to plugins/all's imports when it isn't +// there (a new kind), so a program importing all runs it. ok is false when +// it's already there. +func importInAll(root, kind string) ([]byte, bool, error) { + path := filepath.Join(root, "plugins", "all", "all.go") + src, err := os.ReadFile(path) + if err != nil { + return nil, false, err + } + imp := `"github.com/patch-it-dev/patch-it-plugins/plugins/` + kind + `"` + if bytes.Contains(src, []byte(imp)) { + return nil, false, nil + } + out := bytes.Replace(src, []byte("import (\n"), []byte("import (\n\t_ "+imp+"\n"), 1) + b, err := format.Source(out) + return b, err == nil, err +} diff --git a/core/event/event.go b/core/event/event.go index d17f1c9..be8b0b9 100644 --- a/core/event/event.go +++ b/core/event/event.go @@ -1,20 +1,23 @@ +// Package event is the change event of patch-it's contract +// (docs/contract/change-event.md in patch-it): what changed, at which +// version, with the source that says so. A typed subject says what changed. package event import ( + "bytes" "crypto/sha256" "encoding/hex" + "encoding/json" "fmt" "regexp" + "slices" "strings" "time" "unicode/utf8" ) -type ( - ChangeType string - AffectedKind string - Side string -) +// ChangeType is what kind of change it is to the code that calls the source. +type ChangeType string const ( ChangeTypeBreaking ChangeType = "breaking" @@ -23,30 +26,77 @@ const ( ChangeTypeFix ChangeType = "fix" ) +// Kind is what an api_operation subject is about. +type Kind string + const ( - AffectedKindOperation AffectedKind = "operation" - AffectedKindRequestParameter AffectedKind = "request_parameter" - AffectedKindSchema AffectedKind = "schema" - AffectedKindSchemaProperty AffectedKind = "schema_property" + KindOperation Kind = "operation" + KindRequestParameter Kind = "request_parameter" + KindSchema Kind = "schema" + KindSchemaProperty Kind = "schema_property" ) +// Side is which side of a call an api_operation change breaks. +type Side string + 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"` +// SubjectType is what kind of thing changed. +type SubjectType string + +const ( + SubjectAPIOperation SubjectType = "api_operation" + SubjectModel SubjectType = "model" + SubjectPackageRelease SubjectType = "package_release" + SubjectCIRuntime SubjectType = "ci_runtime" +) + +// PackageChange is what a package release did to the code that calls it. +type PackageChange string + +const ( + PackageRemovedParameter PackageChange = "removed_parameter" + PackageRemovedSymbol PackageChange = "removed_symbol" + PackageRenamedSymbol PackageChange = "renamed_symbol" + PackageChangedDefault PackageChange = "changed_default" +) + +// Subject is what changed. Type picks which fields it may have; every other +// field must be empty (the contract's "a field its type doesn't define"). +type Subject struct { + Type SubjectType `json:"type"` + + // api_operation + Kind Kind `json:"kind,omitempty"` + Side Side `json:"side,omitempty"` + Operation string `json:"operation,omitempty"` + Schema string `json:"schema,omitempty"` + Property string `json:"property,omitempty"` + + // model + Provider string `json:"provider,omitempty"` + Name string `json:"name,omitempty"` + + // package_release + Ecosystem string `json:"ecosystem,omitempty"` + Package string `json:"package,omitempty"` + Change PackageChange `json:"change,omitempty"` + Symbols []string `json:"symbols,omitempty"` + Parameter string `json:"parameter,omitempty"` + + // ci_runtime + Platform string `json:"platform,omitempty"` + Runtime string `json:"runtime,omitempty"` + + // model, package_release (renamed_symbol), ci_runtime + Replacement string `json:"replacement,omitempty"` } -type ChangeEvent struct { +// Event is one change event. +type Event struct { ID int64 `json:"id"` Fingerprint string `json:"fingerprint"` API string `json:"api"` @@ -54,7 +104,8 @@ type ChangeEvent struct { PreviousVersion string `json:"previous_version,omitempty"` ChangeType ChangeType `json:"change_type"` Breaking bool `json:"breaking"` - Affected Affected `json:"affected"` + Subject Subject `json:"subject"` + Supersedes string `json:"supersedes,omitempty"` Description string `json:"description"` MigrationHint string `json:"migration_hint,omitempty"` SourceURL string `json:"source_url"` @@ -64,50 +115,186 @@ type ChangeEvent struct { 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[:]) +// Decode reads one event and refuses a field the contract doesn't define, +// at the top level or in subject: the patch-it client's model forbids extra +// fields too, so the hosted service and the client reject the same events. Keys are +// matched exactly ("TYPE" isn't "type", though encoding/json would take it), +// and a subject key belongs to its type even when its value is empty: pydantic +// sees the key, not the value. +func Decode(raw []byte) (Event, error) { + var e Event + dec := json.NewDecoder(bytes.NewReader(raw)) + dec.DisallowUnknownFields() + if err := dec.Decode(&e); err != nil { + return Event{}, err + } + var keys struct { + Top map[string]json.RawMessage + Subject map[string]json.RawMessage `json:"subject"` + } + if err := json.Unmarshal(raw, &keys.Top); err != nil { + return Event{}, err + } + for k := range keys.Top { + if !slices.Contains(eventKeys, k) { + return Event{}, fmt.Errorf("%q isn't a field of a change event", k) + } + } + if sub, ok := keys.Top["subject"]; ok { + if err := json.Unmarshal(sub, &keys.Subject); err != nil { + return Event{}, err + } + } + allowed := slices.Concat(subjectKeys[e.Subject.Type], []string{"type"}) + for k := range keys.Subject { + if !slices.Contains(allowed, k) { + return Event{}, fmt.Errorf("subject.%s isn't a field of type %s", k, e.Subject.Type) + } + } + return e, nil } -// 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}$`) +// eventKeys are the JSON names of Event's fields. +var eventKeys = []string{"id", "fingerprint", "api", "version", "previous_version", "change_type", + "breaking", "subject", "supersedes", "description", "migration_hint", "source_url", + "source_pointer", "source_excerpt", "confidence", "detected_at"} -func (e ChangeEvent) Validate() error { +// subjectKeys are the fields each type may have, besides `type`. +var subjectKeys = map[SubjectType][]string{ + SubjectAPIOperation: {"kind", "side", "operation", "schema", "property"}, + SubjectModel: {"provider", "name", "replacement"}, + SubjectPackageRelease: {"ecosystem", "package", "change", "symbols", "parameter", "replacement"}, + SubjectCIRuntime: {"platform", "runtime", "replacement"}, +} + +// Fingerprint identifies one change, so re-reading the same source stores +// nothing twice. The parts are joined with a separator that can't appear in +// them. For api_operation, the location and detail (what separates two +// changes at one place: the enum value added, "added as required"); for the +// other types, the type and its key fields, detail empty: the key already +// says what changed. Symbols are sorted first, so the same release always +// gets the same fingerprint. +func Fingerprint(api, version string, changeType ChangeType, s Subject, detail string) string { + if s.Type == SubjectAPIOperation { + return hash(api, version, string(changeType), string(s.Kind), string(s.Side), s.Operation, s.Schema, s.Property, detail) + } + parts := []string{api, version, string(changeType), string(s.Type)} + switch s.Type { + case SubjectModel: + parts = append(parts, s.Provider, s.Name) + case SubjectPackageRelease: + symbols := slices.Clone(s.Symbols) + slices.Sort(symbols) + parts = append(parts, s.Ecosystem, s.Package, string(s.Change), strings.Join(symbols, ","), s.Parameter) + case SubjectCIRuntime: + parts = append(parts, s.Platform, s.Runtime) + } + return hash(append(parts, "")...) +} + +func hash(parts ...string) string { + sum := sha256.Sum256([]byte(strings.Join(parts, "|"))) + return "sha256:" + hex.EncodeToString(sum[:]) +} + +// Validate applies the contract: the rules for every field, then subject's own. +func (e Event) 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 e.Supersedes != "" && !fingerprintPattern.MatchString(e.Supersedes) { + return fmt.Errorf("supersedes must look like sha256:<64 lowercase hex>, got %q", e.Supersedes) + } + return e.Subject.validate() +} - if err := e.Affected.validate(); err != nil { +func (s Subject) validate() error { + allowed, err := s.required() + if err != nil { return err } + for name, set := range s.present() { + if set && !slices.Contains(allowed, name) { + return fmt.Errorf("subject.%s isn't a field of type %s", name, s.Type) + } + } + return nil +} - // 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") +// required checks the fields the type must have and returns every field it may. +func (s Subject) required() ([]string, error) { + need := func(name, v string) error { + if v == "" { + return fmt.Errorf("subject.%s is required for type %s", name, s.Type) + } + return nil } + switch s.Type { + case SubjectAPIOperation: + if err := s.validateOperation(); err != nil { + return nil, fmt.Errorf("subject: %w", err) + } + return subjectKeys[SubjectAPIOperation], nil + case SubjectModel: + for _, f := range [][2]string{{"provider", s.Provider}, {"name", s.Name}} { + if err := need(f[0], f[1]); err != nil { + return nil, err + } + } + return subjectKeys[SubjectModel], nil + case SubjectPackageRelease: + for _, f := range [][2]string{{"ecosystem", s.Ecosystem}, {"package", s.Package}} { + if err := need(f[0], f[1]); err != nil { + return nil, err + } + } + switch s.Change { + case PackageRemovedParameter, PackageChangedDefault: + if err := need("parameter", s.Parameter); err != nil { + return nil, err + } + case PackageRenamedSymbol: + if err := need("replacement", s.Replacement); err != nil { + return nil, err + } + case PackageRemovedSymbol: + default: + return nil, fmt.Errorf("subject.change must be a valid enum value, got %q", s.Change) + } + if len(s.Symbols) == 0 || slices.Contains(s.Symbols, "") { + return nil, fmt.Errorf("subject.symbols must name at least one symbol, none empty") + } + return subjectKeys[SubjectPackageRelease], nil + case SubjectCIRuntime: + for _, f := range [][2]string{{"platform", s.Platform}, {"runtime", s.Runtime}} { + if err := need(f[0], f[1]); err != nil { + return nil, err + } + } + return subjectKeys[SubjectCIRuntime], nil + } + return nil, fmt.Errorf("subject.type must be a valid enum value, got %q", s.Type) +} - return nil +// present is which subject fields are set, by their JSON names. +func (s Subject) present() map[string]bool { + return map[string]bool{ + "kind": s.Kind != "", "side": s.Side != "", "operation": s.Operation != "", + "schema": s.Schema != "", "property": s.Property != "", + "provider": s.Provider != "", "name": s.Name != "", + "ecosystem": s.Ecosystem != "", "package": s.Package != "", "change": s.Change != "", + "symbols": len(s.Symbols) > 0, "parameter": s.Parameter != "", + "platform": s.Platform != "", "runtime": s.Runtime != "", + "replacement": s.Replacement != "", + } } -// 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. +// 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}$`) + +// checkCommon is the contract's rules for every field outside subject. 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. @@ -165,50 +352,50 @@ func checkCommon(sourceURL, excerpt, fingerprint, api, version, description stri 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) +// validateOperation is the contract's rules for an api_operation subject: +// kind decides the side and the required fields. +func (a Subject) validateOperation() error { + // Rule 3 (continued): subject.kind and subject.side must be valid too. + if a.Kind != KindOperation && + a.Kind != KindRequestParameter && + a.Kind != KindSchema && + a.Kind != KindSchemaProperty { + return fmt.Errorf("subject.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) + return fmt.Errorf("subject.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. + // Rule 5: subject's required fields, and its side, depend on its kind. // Kind decides side: requests live under paths, responses under schemas. switch a.Kind { - case AffectedKindOperation: + case KindOperation: if a.Operation == "" { - return fmt.Errorf("affected.operation is required when kind is operation") + return fmt.Errorf("subject.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) + return fmt.Errorf("subject.side must be %q when kind is operation, got %q", SideRequest, a.Side) } - case AffectedKindRequestParameter: + case KindRequestParameter: if a.Operation == "" || a.Property == "" { - return fmt.Errorf("affected.operation and affected.property are required when kind is request_parameter") + return fmt.Errorf("subject.operation and subject.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) + return fmt.Errorf("subject.side must be %q when kind is request_parameter, got %q", SideRequest, a.Side) } - case AffectedKindSchema: + case KindSchema: if a.Schema == "" { - return fmt.Errorf("affected.schema is required when kind is schema") + return fmt.Errorf("subject.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) + return fmt.Errorf("subject.side must be %q when kind is schema, got %q", SideResponse, a.Side) } - case AffectedKindSchemaProperty: + case KindSchemaProperty: if a.Schema == "" || a.Property == "" { - return fmt.Errorf("affected.schema and affected.property are required when kind is schema_property") + return fmt.Errorf("subject.schema and subject.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 fmt.Errorf("subject.side must be %q when kind is schema_property, got %q", SideResponse, a.Side) } } return nil diff --git a/core/event/event_test.go b/core/event/event_test.go index 6f0b3f6..a513875 100644 --- a/core/event/event_test.go +++ b/core/event/event_test.go @@ -8,223 +8,77 @@ import ( "time" ) -var fixtureOperationAdded = ChangeEvent{ - ID: 1, - Fingerprint: "sha256:3b1f000000000000000000000000000000000000000000000000000000000000", - API: "stripe", - Version: "2026-08-26.dahlia", - PreviousVersion: "2026-07-29.dahlia", - ChangeType: ChangeTypeNewFeature, - Breaking: false, - Affected: Affected{ - Kind: AffectedKindOperation, - Side: SideRequest, - Operation: "POST /v1/billing/feedback_options", - }, - Description: "New operation POST /v1/billing/feedback_options (PostBillingFeedbackOptions).", - SourceURL: "https://raw.githubusercontent.com/stripe/openapi/v2468/latest/openapi.spec3.json", - SourcePointer: "/paths/~1v1~1billing~1feedback_options/post", - SourceExcerpt: `{"operationId":"PostBillingFeedbackOptions","summary":"Create a feedback option"}`, - Confidence: 1.0, - DetectedAt: time.Date(2026, 9, 13, 15, 0, 0, 0, time.UTC), -} +// fixtures is the copy of patch-it's contract fixtures (CI_contract keeps it +// in sync). +const fixtures = "../../contract/fixtures/" -var fixtureEnumValueAdded = ChangeEvent{ - ID: 2, - Fingerprint: "sha256:9f2c000000000000000000000000000000000000000000000000000000000000", - API: "stripe", +var operationAdded = Event{ + ID: 1, + API: "stripe/api", Version: "2026-08-26.dahlia", PreviousVersion: "2026-07-29.dahlia", ChangeType: ChangeTypeNewFeature, - Breaking: false, - Affected: Affected{ - Kind: AffectedKindSchemaProperty, - Side: SideResponse, - Schema: "invoices_payment_settings", - Property: "payment_method_types[]", - }, - Description: "Enum value 'billie' added to invoices_payment_settings.payment_method_types[].", - SourceURL: "https://raw.githubusercontent.com/stripe/openapi/v2468/latest/openapi.spec3.json", - SourcePointer: "/components/schemas/invoices_payment_settings/properties/payment_method_types/items/enum", - SourceExcerpt: `["ach_credit_transfer","ach_debit","billie"]`, - Confidence: 1.0, - DetectedAt: time.Date(2026, 9, 13, 15, 0, 0, 0, time.UTC), -} - -var fixturePropertyRemoved = ChangeEvent{ - ID: 3, - Fingerprint: "sha256:c07a000000000000000000000000000000000000000000000000000000000000", - API: "stripe", - Version: "2026-08-26.dahlia", - PreviousVersion: "2026-07-29.dahlia", - ChangeType: ChangeTypeBreaking, - Breaking: true, - Affected: Affected{ - Kind: AffectedKindSchemaProperty, - Side: SideResponse, - Schema: "payments_primitives_payment_records_resource_payment_method_card_details_resource_three_d_secure", - Property: "cryptogram", - }, - Description: "Property cryptogram removed from payments_primitives_payment_records_resource_payment_method_card_details_resource_three_d_secure.", - SourceURL: "https://raw.githubusercontent.com/stripe/openapi/v2460/latest/openapi.spec3.json", - SourcePointer: "/components/schemas/payments_primitives_payment_records_resource_payment_method_card_details_resource_three_d_secure/properties/cryptogram", - SourceExcerpt: `{"description":"The 3D Secure cryptogram.","maxLength":5000,"nullable":true,"type":"string"}`, - Confidence: 1.0, - DetectedAt: time.Date(2026, 9, 13, 15, 0, 0, 0, time.UTC), -} - -var fixtureDeprecation = ChangeEvent{ - ID: 4, - Fingerprint: "sha256:a1e5000000000000000000000000000000000000000000000000000000000000", - API: "stripe", - Version: "2026-08-26.dahlia", - PreviousVersion: "2026-07-29.dahlia", - ChangeType: ChangeTypeDeprecation, - Breaking: false, - Affected: Affected{ - Kind: AffectedKindOperation, - Side: SideRequest, - Operation: "POST /v1/charges", - }, - Description: "Operation POST /v1/charges marked deprecated in favor of POST /v1/payment_intents.", - MigrationHint: "Use POST /v1/payment_intents instead.", - SourceURL: "https://raw.githubusercontent.com/stripe/openapi/v2468/latest/openapi.spec3.json", - SourcePointer: "/paths/~1v1~1charges/post/deprecated", - SourceExcerpt: `{"deprecated":true}`, - Confidence: 1.0, - DetectedAt: time.Date(2026, 9, 13, 15, 0, 0, 0, time.UTC), -} - -func TestFixturesAreValid(t *testing.T) { - fixtures := []ChangeEvent{ - fixtureOperationAdded, - fixtureEnumValueAdded, - fixturePropertyRemoved, - fixtureDeprecation, - } - for i, e := range fixtures { - if err := e.Validate(); err != nil { - t.Errorf("fixture %d failed validation: %v", i, err) - } - } -} - -func TestValidateRejectsMissingProvenance(t *testing.T) { - bad := fixtureOperationAdded - bad.SourceURL = "" - if err := bad.Validate(); err == nil { - t.Error("expected validation error for missing source_url, got nil") - } -} - -// Regression: the excerpt cap is 2,000 characters, not bytes. Spec text is full of -// non-ASCII, and a byte count rejected valid events. -func TestExcerptLimitCountsCharacters(t *testing.T) { - ok := fixtureOperationAdded - ok.SourceExcerpt = strings.Repeat("é", 2000) // 2,000 characters, 4,000 bytes - if err := ok.Validate(); err != nil { - t.Errorf("2000-character excerpt rejected: %v", err) - } - tooLong := fixtureOperationAdded - tooLong.SourceExcerpt = strings.Repeat("é", 2001) - if err := tooLong.Validate(); err == nil { - t.Error("2001-character excerpt accepted") - } -} - -func TestValidateRejectsContractViolations(t *testing.T) { - cases := map[string]func(e *ChangeEvent){ - "missing source_excerpt": func(e *ChangeEvent) { e.SourceExcerpt = "" }, - "missing detected_at": func(e *ChangeEvent) { e.DetectedAt = time.Time{} }, - "breaking disagrees with change_type": func(e *ChangeEvent) { e.Breaking = true }, - "unknown change_type": func(e *ChangeEvent) { e.ChangeType = "maybe" }, - "confidence above 1": func(e *ChangeEvent) { e.Confidence = 1.5 }, - "operation kind on the response side": func(e *ChangeEvent) { e.Affected.Side = SideResponse }, - "operation kind without an operation": func(e *ChangeEvent) { e.Affected.Operation = "" }, - } - for name, breakIt := range cases { - e := fixtureOperationAdded - breakIt(&e) - if err := e.Validate(); err == nil { - t.Errorf("%s: accepted", name) - } - } - - schemaOnRequest := fixtureEnumValueAdded - schemaOnRequest.Affected.Side = SideRequest - if err := schemaOnRequest.Validate(); err == nil { - t.Error("schema_property kind on the request side: accepted") - } + Subject: Subject{Type: SubjectAPIOperation, Kind: KindOperation, Side: SideRequest, Operation: "POST /v1/billing/feedback_options"}, + Description: "New operation POST /v1/billing/feedback_options (PostBillingFeedbackOptions).", + SourceURL: "https://raw.githubusercontent.com/stripe/openapi/v2468/latest/openapi.spec3.json", + SourcePointer: "/paths/~1v1~1billing~1feedback_options/post", + SourceExcerpt: `{"operationId":"PostBillingFeedbackOptions","summary":"Create a feedback option"}`, + Confidence: 1.0, + DetectedAt: time.Date(2026, 9, 13, 15, 0, 0, 0, time.UTC), } -func TestAValueNeedsTheProperty(t *testing.T) { - e := fixtureOperationAdded - e.Affected = Affected{Kind: AffectedKindOperation, Side: SideRequest, Operation: "POST /v1/chat/completions", Value: "gpt-4"} - if err := e.Validate(); err == nil { - t.Error("a value with no property it belongs to: accepted") - } - e.Affected = Affected{Kind: AffectedKindRequestParameter, Side: SideRequest, Operation: "POST /v1/chat/completions", Property: "model", Value: "gpt-4"} - if err := e.Validate(); err != nil { - t.Errorf("a model retirement: %v", err) - } +func init() { + operationAdded.Fingerprint = Fingerprint(operationAdded.API, operationAdded.Version, operationAdded.ChangeType, operationAdded.Subject, "") } -// Contract test between the hosted service and the patch-it client. -// contract/fixtures/change-events.json is the file the client builds against -// in place of the real feed. The client's tests check the same file against its -// own model, so if either side's idea of a change event drifts from the -// 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") +func rawEvents(t *testing.T, name string) []json.RawMessage { + t.Helper() + raw, err := os.ReadFile(fixtures + name) if err != nil { - t.Fatalf("reading the shared fixture: %v", err) + t.Fatal(err) } var feed struct { - Changes []ChangeEvent `json:"changes"` + Changes []json.RawMessage `json:"changes"` } if err := json.Unmarshal(raw, &feed); err != nil { - t.Fatalf("the fixture doesn't decode as change events: %v", err) + t.Fatalf("%s: %v", name, err) } if len(feed.Changes) == 0 { - t.Fatal("the fixture has no events") - } - for _, e := range feed.Changes { - if err := e.Validate(); err != nil { - t.Errorf("fixture event %d fails the service's validation: %v", e.ID, err) - } + t.Fatalf("%s has no events", name) } + return feed.Changes } -// 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") - if err != nil { - t.Fatalf("reading the fixture: %v", err) - } - var feed struct { - Changes []ChangeEvent `json:"changes"` - } - if err := json.Unmarshal(raw, &feed); err != nil { - t.Fatalf("decoding: %v", err) - } - if len(feed.Changes) == 0 { - t.Fatal("no events") - } - for _, e := range feed.Changes { - if err := e.Validate(); err != nil || e.Affected.Value == "" { - t.Errorf("event %d: %v (value %q)", e.ID, err, e.Affected.Value) +// The contract's fixtures, the same ones the patch-it client checks, are +// accepted, with the fingerprints the formula gives. +func TestFixturesAreValid(t *testing.T) { + for _, name := range []string{"change-events-v2.json", "change-events-v2-types.json"} { + for _, raw := range rawEvents(t, name) { + e, err := Decode(raw) + if err != nil { + t.Fatalf("%s: %v", name, err) + } + if err := e.Validate(); err != nil { + t.Errorf("%s event %d: %v", name, e.ID, err) + } + // An API event's detail isn't stored, so only the other types are + // recomputed here. + if e.Subject.Type == SubjectAPIOperation && name == "change-events-v2.json" { + continue + } + if want := Fingerprint(e.API, e.Version, e.ChangeType, e.Subject, ""); e.Fingerprint != want { + t.Errorf("%s event %d: fingerprint %s, the formula gives %s", name, e.ID, e.Fingerprint, want) + } } } } -// 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") +// Every case in the contract's invalid fixture breaks one rule, and is +// rejected while decoding or validating. +func TestInvalidFixtureIsRejected(t *testing.T) { + raw, err := os.ReadFile(fixtures + "change-events-v2-invalid.json") if err != nil { - t.Fatalf("reading the shared invalid fixture: %v", err) + t.Fatal(err) } var fixture struct { Cases []struct { @@ -233,15 +87,85 @@ func TestSharedInvalidFixtureIsRejected(t *testing.T) { } `json:"cases"` } if err := json.Unmarshal(raw, &fixture); err != nil { - t.Fatalf("decoding the invalid fixture: %v", err) + t.Fatal(err) + } + if len(fixture.Cases) == 0 { + t.Fatal("no cases") } for _, c := range fixture.Cases { - var e ChangeEvent - if err := json.Unmarshal(c.Event, &e); err != nil { - continue // can't even decode, e.g. a malformed timestamp: rejected + e, err := Decode(c.Event) + if err != nil { + continue // a field the contract doesn't define: rejected while decoding } if err := e.Validate(); err == nil { t.Errorf("accepted an invalid event: %s", c.WhyInvalid) } } } + +func TestValidateRejectsContractViolations(t *testing.T) { + if err := operationAdded.Validate(); err != nil { + t.Fatalf("the valid event: %v", err) + } + cases := map[string]func(e *Event){ + "missing source_url": func(e *Event) { e.SourceURL = "" }, + "missing source_excerpt": func(e *Event) { e.SourceExcerpt = "" }, + "missing detected_at": func(e *Event) { e.DetectedAt = time.Time{} }, + "breaking disagrees with change_type": func(e *Event) { e.Breaking = true }, + "unknown change_type": func(e *Event) { e.ChangeType = "maybe" }, + "confidence above 1": func(e *Event) { e.Confidence = 1.5 }, + "a bad fingerprint": func(e *Event) { e.Fingerprint = "sha256:abc" }, + "operation kind on the response side": func(e *Event) { e.Subject.Side = SideResponse }, + "operation kind without an operation": func(e *Event) { e.Subject.Operation = "" }, + "schema kind on the request side": func(e *Event) { + e.Subject = Subject{Type: SubjectAPIOperation, Kind: KindSchema, Side: SideRequest, Schema: "invoice"} + }, + "a model field on an api_operation": func(e *Event) { e.Subject.Name = "gpt-4" }, + } + for name, breakIt := range cases { + e := operationAdded + breakIt(&e) + if err := e.Validate(); err == nil { + t.Errorf("%s: accepted", name) + } + } +} + +// Regression: the excerpt cap is 2,000 characters, not bytes. Spec text is full of +// non-ASCII, and a byte count rejected valid events. +func TestExcerptLimitCountsCharacters(t *testing.T) { + ok := operationAdded + ok.SourceExcerpt = strings.Repeat("é", 2000) // 2,000 characters, 4,000 bytes + if err := ok.Validate(); err != nil { + t.Errorf("2000-character excerpt rejected: %v", err) + } + tooLong := operationAdded + tooLong.SourceExcerpt = strings.Repeat("é", 2001) + if err := tooLong.Validate(); err == nil { + t.Error("2001-character excerpt accepted") + } +} + +// The same release listed in another order is the same event (found in +// review: otherwise the store keeps it twice). +func TestSymbolOrderDoesntChangeTheFingerprint(t *testing.T) { + s := Subject{Type: SubjectPackageRelease, Ecosystem: "pypi", Package: "anthropic", + Change: PackageRemovedParameter, Parameter: "top_k", Symbols: []string{"messages.stream", "messages.create"}} + r := s + r.Symbols = []string{"messages.create", "messages.stream"} + if Fingerprint("anthropic/python-sdk", "1.0.0", ChangeTypeBreaking, s, "") != Fingerprint("anthropic/python-sdk", "1.0.0", ChangeTypeBreaking, r, "") { + t.Error("symbol order changed the fingerprint") + } + if s.Symbols[0] != "messages.stream" { + t.Error("Fingerprint reordered the caller's symbols") + } +} + +// Two kinds of change that share every other field still get two fingerprints. +func TestTheTypeIsPartOfTheFingerprint(t *testing.T) { + m := Fingerprint("x/y", "1", ChangeTypeBreaking, Subject{Type: SubjectModel, Provider: "p", Name: "n"}, "") + c := Fingerprint("x/y", "1", ChangeTypeBreaking, Subject{Type: SubjectCIRuntime, Platform: "p", Runtime: "n"}, "") + if m == c { + t.Error("a model and a CI runtime with the same values share a fingerprint") + } +} diff --git a/core/event/v2.go b/core/event/v2.go deleted file mode 100644 index cae02b0..0000000 --- a/core/event/v2.go +++ /dev/null @@ -1,262 +0,0 @@ -package event - -import ( - "bytes" - "crypto/sha256" - "encoding/hex" - "encoding/json" - "fmt" - "slices" - "strings" - "time" -) - -// Change event v2 (the change event contract), in force since the -// cut-over: v1's fields with `affected`, which can only describe an OpenAPI -// location, replaced by a typed `subject`. The store holds and serves v2; the -// sources still build v1 events, converted on the way out (migrate/). - -// SubjectType is what kind of thing changed. -type SubjectType string - -const ( - SubjectAPIOperation SubjectType = "api_operation" - SubjectModel SubjectType = "model" - SubjectPackageRelease SubjectType = "package_release" - SubjectCIRuntime SubjectType = "ci_runtime" -) - -// PackageChange is what a package release did to the code that calls it. -type PackageChange string - -const ( - PackageRemovedParameter PackageChange = "removed_parameter" - PackageRemovedSymbol PackageChange = "removed_symbol" - PackageRenamedSymbol PackageChange = "renamed_symbol" - PackageChangedDefault PackageChange = "changed_default" -) - -// Subject is what changed. Type picks which fields it may have; every other -// field must be empty (the contract's "a field its type doesn't define"). -type Subject struct { - Type SubjectType `json:"type"` - - // api_operation: v1's affected, without value (a model has its own type). - Kind AffectedKind `json:"kind,omitempty"` - Side Side `json:"side,omitempty"` - Operation string `json:"operation,omitempty"` - Schema string `json:"schema,omitempty"` - Property string `json:"property,omitempty"` - - // model - Provider string `json:"provider,omitempty"` - Name string `json:"name,omitempty"` - - // package_release - Ecosystem string `json:"ecosystem,omitempty"` - Package string `json:"package,omitempty"` - Change PackageChange `json:"change,omitempty"` - Symbols []string `json:"symbols,omitempty"` - Parameter string `json:"parameter,omitempty"` - - // ci_runtime - Platform string `json:"platform,omitempty"` - Runtime string `json:"runtime,omitempty"` - - // model, package_release (renamed_symbol), ci_runtime - Replacement string `json:"replacement,omitempty"` -} - -// EventV2 is a v2 change event. -type EventV2 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"` - Subject Subject `json:"subject"` - Supersedes string `json:"supersedes,omitempty"` - 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"` -} - -// DecodeV2 reads one v2 event and refuses a field the contract doesn't define, -// at the top level or in subject: the patch-it client's model forbids extra -// fields too, so the hosted service and the client reject the same events. Keys are -// matched exactly ("TYPE" isn't "type", though encoding/json would take it), -// and a subject key belongs to its type even when its value is empty: pydantic -// sees the key, not the value. -func DecodeV2(raw []byte) (EventV2, error) { - var e EventV2 - dec := json.NewDecoder(bytes.NewReader(raw)) - dec.DisallowUnknownFields() - if err := dec.Decode(&e); err != nil { - return EventV2{}, err - } - var keys struct { - Top map[string]json.RawMessage - Subject map[string]json.RawMessage `json:"subject"` - } - if err := json.Unmarshal(raw, &keys.Top); err != nil { - return EventV2{}, err - } - for k := range keys.Top { - if !slices.Contains(eventKeys, k) { - return EventV2{}, fmt.Errorf("%q isn't a field of a change event", k) - } - } - if sub, ok := keys.Top["subject"]; ok { - if err := json.Unmarshal(sub, &keys.Subject); err != nil { - return EventV2{}, err - } - } - allowed := slices.Concat(subjectKeys[e.Subject.Type], []string{"type"}) - for k := range keys.Subject { - if !slices.Contains(allowed, k) { - return EventV2{}, fmt.Errorf("subject.%s isn't a field of type %s", k, e.Subject.Type) - } - } - return e, nil -} - -// eventKeys are the JSON names of EventV2's fields. -var eventKeys = []string{"id", "fingerprint", "api", "version", "previous_version", "change_type", - "breaking", "subject", "supersedes", "description", "migration_hint", "source_url", - "source_pointer", "source_excerpt", "confidence", "detected_at"} - -// subjectKeys are the fields each type may have, besides `type`. -var subjectKeys = map[SubjectType][]string{ - SubjectAPIOperation: {"kind", "side", "operation", "schema", "property"}, - SubjectModel: {"provider", "name", "replacement"}, - SubjectPackageRelease: {"ecosystem", "package", "change", "symbols", "parameter", "replacement"}, - SubjectCIRuntime: {"platform", "runtime", "replacement"}, -} - -// FingerprintV2 identifies one change. For api_operation it is v1's formula -// byte for byte, so every stored Stripe event keeps its fingerprint. For the -// other types, the type's key fields stand where v1's location was and detail -// is empty: the key already says what changed. Symbols are sorted first, so -// the same release always gets the same fingerprint. -func FingerprintV2(api, version string, changeType ChangeType, s Subject, detail string) string { - if s.Type == SubjectAPIOperation { - return Fingerprint(api, version, changeType, Affected{ - Kind: s.Kind, Side: s.Side, Operation: s.Operation, Schema: s.Schema, Property: s.Property, - }, detail) - } - parts := []string{api, version, string(changeType), string(s.Type)} - switch s.Type { - case SubjectModel: - parts = append(parts, s.Provider, s.Name) - case SubjectPackageRelease: - symbols := slices.Clone(s.Symbols) - slices.Sort(symbols) - parts = append(parts, s.Ecosystem, s.Package, string(s.Change), strings.Join(symbols, ","), s.Parameter) - case SubjectCIRuntime: - parts = append(parts, s.Platform, s.Runtime) - } - sum := sha256.Sum256([]byte(strings.Join(append(parts, ""), "|"))) - return "sha256:" + hex.EncodeToString(sum[:]) -} - -// Validate applies the v2 contract: v1's rules for everything outside subject, -// then subject's own. -func (e EventV2) 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 e.Supersedes != "" && !fingerprintPattern.MatchString(e.Supersedes) { - return fmt.Errorf("supersedes must look like sha256:<64 lowercase hex>, got %q", e.Supersedes) - } - return e.Subject.validate() -} - -func (s Subject) validate() error { - allowed, err := s.required() - if err != nil { - return err - } - for name, set := range s.present() { - if set && !slices.Contains(allowed, name) { - return fmt.Errorf("subject.%s isn't a field of type %s", name, s.Type) - } - } - return nil -} - -// required checks the fields the type must have and returns every field it may. -func (s Subject) required() ([]string, error) { - need := func(name, v string) error { - if v == "" { - return fmt.Errorf("subject.%s is required for type %s", name, s.Type) - } - return nil - } - switch s.Type { - case SubjectAPIOperation: - // v1's kind and side rules, unchanged. - a := Affected{Kind: s.Kind, Side: s.Side, Operation: s.Operation, Schema: s.Schema, Property: s.Property} - if err := a.validate(); err != nil { - return nil, fmt.Errorf("subject: %w", err) - } - return subjectKeys[SubjectAPIOperation], nil - case SubjectModel: - for _, f := range [][2]string{{"provider", s.Provider}, {"name", s.Name}} { - if err := need(f[0], f[1]); err != nil { - return nil, err - } - } - return subjectKeys[SubjectModel], nil - case SubjectPackageRelease: - for _, f := range [][2]string{{"ecosystem", s.Ecosystem}, {"package", s.Package}} { - if err := need(f[0], f[1]); err != nil { - return nil, err - } - } - switch s.Change { - case PackageRemovedParameter, PackageChangedDefault: - if err := need("parameter", s.Parameter); err != nil { - return nil, err - } - case PackageRenamedSymbol: - if err := need("replacement", s.Replacement); err != nil { - return nil, err - } - case PackageRemovedSymbol: - default: - return nil, fmt.Errorf("subject.change must be a valid enum value, got %q", s.Change) - } - if len(s.Symbols) == 0 || slices.Contains(s.Symbols, "") { - return nil, fmt.Errorf("subject.symbols must name at least one symbol, none empty") - } - return subjectKeys[SubjectPackageRelease], nil - case SubjectCIRuntime: - for _, f := range [][2]string{{"platform", s.Platform}, {"runtime", s.Runtime}} { - if err := need(f[0], f[1]); err != nil { - return nil, err - } - } - return subjectKeys[SubjectCIRuntime], nil - } - return nil, fmt.Errorf("subject.type must be a valid enum value, got %q", s.Type) -} - -// present is which subject fields are set, by their JSON names. -func (s Subject) present() map[string]bool { - return map[string]bool{ - "kind": s.Kind != "", "side": s.Side != "", "operation": s.Operation != "", - "schema": s.Schema != "", "property": s.Property != "", - "provider": s.Provider != "", "name": s.Name != "", - "ecosystem": s.Ecosystem != "", "package": s.Package != "", "change": s.Change != "", - "symbols": len(s.Symbols) > 0, "parameter": s.Parameter != "", - "platform": s.Platform != "", "runtime": s.Runtime != "", - "replacement": s.Replacement != "", - } -} diff --git a/core/event/v2_test.go b/core/event/v2_test.go deleted file mode 100644 index 0d2dab3..0000000 --- a/core/event/v2_test.go +++ /dev/null @@ -1,147 +0,0 @@ -package event - -import ( - "bytes" - "encoding/json" - "flag" - "os" - "testing" -) - -// -update writes the computed fingerprints into the hand-written v2 fixture: -// go test ./event -update -var update = flag.Bool("update", false, "rewrite fingerprints in change-events-v2-types.json") - -const v2Fixtures = "../../contract/fixtures/" - -func rawEvents(t *testing.T, name string) []json.RawMessage { - t.Helper() - raw, err := os.ReadFile(v2Fixtures + name) - if err != nil { - t.Fatal(err) - } - var feed struct { - Changes []json.RawMessage `json:"changes"` - } - if err := json.Unmarshal(raw, &feed); err != nil { - t.Fatalf("%s: %v", name, err) - } - if len(feed.Changes) == 0 { - t.Fatalf("%s has no events", name) - } - return feed.Changes -} - -// Contract test for v2, the same fixtures the patch-it client checks -// (patch-it's tests/test_contract_v2.py): the converted events and one example per -// type are accepted, with fingerprints the formula gives. -func TestV2FixturesAreValid(t *testing.T) { - for _, name := range []string{"change-events-v2.json", "change-events-v2-types.json"} { - for _, raw := range rawEvents(t, name) { - e, err := DecodeV2(raw) - if err != nil { - t.Fatalf("%s: %v", name, err) - } - if err := e.Validate(); err != nil { - t.Errorf("%s event %d: %v", name, e.ID, err) - } - // An API event's detail isn't stored, so only the other types are - // recomputed here; TestAPIOperationKeepsV1Fingerprint covers it. - if e.Subject.Type == SubjectAPIOperation && name == "change-events-v2.json" { - continue - } - if want := FingerprintV2(e.API, e.Version, e.ChangeType, e.Subject, ""); e.Fingerprint != want && !*update { - t.Errorf("%s event %d: fingerprint %s, the formula gives %s", name, e.ID, e.Fingerprint, want) - } - } - } -} - -func TestUpdateV2TypeFingerprints(t *testing.T) { - if !*update { - t.Skip("only with -update") - } - var out []EventV2 - for _, raw := range rawEvents(t, "change-events-v2-types.json") { - e, err := DecodeV2(raw) - if err != nil { - t.Fatal(err) - } - e.Fingerprint = FingerprintV2(e.API, e.Version, e.ChangeType, e.Subject, "") - out = append(out, e) - } - var buf bytes.Buffer - enc := json.NewEncoder(&buf) - enc.SetEscapeHTML(false) - enc.SetIndent("", " ") - if err := enc.Encode(map[string]any{"changes": out}); err != nil { - t.Fatal(err) - } - if err := os.WriteFile(v2Fixtures+"change-events-v2-types.json", buf.Bytes(), 0o644); err != nil { - t.Fatal(err) - } -} - -// Every case breaks one rule, and both loops must reject all of them. -func TestV2InvalidFixtureIsRejected(t *testing.T) { - raw, err := os.ReadFile(v2Fixtures + "change-events-v2-invalid.json") - if err != nil { - t.Fatal(err) - } - var fixture struct { - Cases []struct { - WhyInvalid string `json:"why_invalid"` - Event json.RawMessage `json:"event"` - } `json:"cases"` - } - if err := json.Unmarshal(raw, &fixture); err != nil { - t.Fatal(err) - } - if len(fixture.Cases) == 0 { - t.Fatal("no cases") - } - for _, c := range fixture.Cases { - e, err := DecodeV2(c.Event) - if err != nil { - continue // a field v2 doesn't define: rejected while decoding - } - if err := e.Validate(); err == nil { - t.Errorf("accepted an invalid v2 event: %s", c.WhyInvalid) - } - } -} - -// Stripe's stored events keep their fingerprints: v2's api_operation formula -// is v1's, byte for byte. -func TestAPIOperationKeepsV1Fingerprint(t *testing.T) { - a := Affected{Kind: AffectedKindSchemaProperty, Side: SideResponse, Schema: "invoice", Property: "subscription"} - s := Subject{Type: SubjectAPIOperation, Kind: a.Kind, Side: a.Side, Schema: a.Schema, Property: a.Property} - v1 := Fingerprint("stripe", "2026-09-30.endive", ChangeTypeBreaking, a, "removed") - if v2 := FingerprintV2("stripe", "2026-09-30.endive", ChangeTypeBreaking, s, "removed"); v2 != v1 { - t.Errorf("v2 %s, v1 %s", v2, v1) - } -} - -// The same release listed in another order is the same event (found in -// review: otherwise the store keeps it twice). -func TestSymbolOrderDoesntChangeTheFingerprint(t *testing.T) { - s := Subject{Type: SubjectPackageRelease, Ecosystem: "pypi", Package: "anthropic", - Change: PackageRemovedParameter, Parameter: "top_k", Symbols: []string{"messages.stream", "messages.create"}} - r := s - r.Symbols = []string{"messages.create", "messages.stream"} - if FingerprintV2("anthropic", "1.0.0", ChangeTypeBreaking, s, "") != FingerprintV2("anthropic", "1.0.0", ChangeTypeBreaking, r, "") { - t.Error("symbol order changed the fingerprint") - } - if s.Symbols[0] != "messages.stream" { - t.Error("FingerprintV2 reordered the caller's symbols") - } -} - -// Two kinds of change that share every other field still get two fingerprints. -func TestTheTypeIsPartOfTheFingerprint(t *testing.T) { - m := FingerprintV2("x", "1", ChangeTypeBreaking, Subject{Type: SubjectModel, Provider: "p", Name: "n"}, "") - c := FingerprintV2("x", "1", ChangeTypeBreaking, Subject{Type: SubjectCIRuntime, Platform: "p", Runtime: "n"}, "") - if m == c { - t.Error("a model and a CI runtime with the same values share a fingerprint") - } -} diff --git a/plugins/feed/parse.go b/core/extract/feed.go similarity index 93% rename from plugins/feed/parse.go rename to core/extract/feed.go index f49d035..22b0d02 100644 --- a/plugins/feed/parse.go +++ b/core/extract/feed.go @@ -1,4 +1,8 @@ -package feed +// Package extract is what readers of prose share: an RSS or Atom feed's +// entries, an HTML fragment as plain text or lines, its sections by +// heading, a "Month D, YYYY" date, the code spans in it. A reader of any +// kind uses it; it knows no vendor. +package extract import ( "bytes" @@ -53,10 +57,10 @@ type atom struct { } `xml:"entry"` } -// Parse reads an RSS 2.0 or Atom feed, whichever the root element says. A +// ParseFeed reads an RSS 2.0 or Atom feed, whichever the root element says. A // feed with no entries is an error: a feed that moved or changed shape must // not read as a quiet week. -func Parse(b []byte) ([]Entry, error) { +func ParseFeed(b []byte) ([]Entry, error) { var root struct{ XMLName xml.Name } if err := xml.NewDecoder(bytes.NewReader(b)).Decode(&root); err != nil { return nil, fmt.Errorf("not a feed: %w", err) diff --git a/core/hint/hint.go b/core/hint/hint.go index 7039941..02c6957 100644 --- a/core/hint/hint.go +++ b/core/hint/hint.go @@ -100,8 +100,8 @@ func NewIndex(entries []Entry) *Index { // ("[]" dropped on both sides), and a change kind that fits the event (a row // that *adds* a parameter never explains a breaking change to it). When // several entries name the same key, the first on the release page wins. -func (ix *Index) Lookup(e event.ChangeEvent) (Entry, bool) { - a := e.Affected +func (ix *Index) Lookup(e event.Event) (Entry, bool) { + a := e.Subject if ix == nil || a.Property == "" { return Entry{}, false } @@ -137,7 +137,7 @@ func compatible(rowChange string, ct event.ChangeType) bool { // sending V"), is the precise sentence and stays first; the vendor's prose // follows it. A match only ever adds information. An event nothing matches is // left as it was. -func (ix *Index) Attach(events []event.ChangeEvent) int { +func (ix *Index) Attach(events []event.Event) int { n := 0 for i := range events { e, ok := ix.Lookup(events[i]) diff --git a/core/hint/hint_test.go b/core/hint/hint_test.go index 00ba8f0..1231519 100644 --- a/core/hint/hint_test.go +++ b/core/hint/hint_test.go @@ -30,10 +30,10 @@ func fakeDocs(t *testing.T) *httptest.Server { return srv } -func request(op, property string, ct event.ChangeType, hint string) event.ChangeEvent { - return event.ChangeEvent{ +func request(op, property string, ct event.ChangeType, hint string) event.Event { + return event.Event{ ChangeType: ct, - Affected: event.Affected{Kind: event.AffectedKindRequestParameter, Side: event.SideRequest, + Subject: event.Subject{Type: event.SubjectAPIOperation, Kind: event.KindRequestParameter, Side: event.SideRequest, Operation: op, Property: property}, MigrationHint: hint, } @@ -175,13 +175,13 @@ func TestIndexFetchesAVersionsEntriesAndAttachesHints(t *testing.T) { } breaking := event.ChangeTypeBreaking - events := []event.ChangeEvent{ + events := []event.Event{ request("POST /v1/checkout/sessions", "payment_method_types", breaking, "Stop sending payment_method_types."), request("POST /v1/payment_intents/{intent}/confirm", "payment_method_types", breaking, ""), request("POST /v1/payment_methods/{payment_method}", "payto", breaking, ""), // Same parameter name, an operation no entry names: keeps its placeholder. request("POST /v1/invoices", "payment_settings.payment_method_types[]", breaking, "placeholder"), - {ChangeType: breaking, Affected: event.Affected{Kind: event.AffectedKindSchemaProperty, Side: event.SideResponse, + {ChangeType: breaking, Subject: event.Subject{Type: event.SubjectAPIOperation, Kind: event.KindSchemaProperty, Side: event.SideResponse, Schema: "payment_intent", Property: "charges"}}, // A collision found in review: the top-level billing_cycle_anchor type // change on Subscription#update, and the nested one trial offers added. @@ -233,7 +233,7 @@ func TestIndexFetchesAVersionsEntriesAndAttachesHints(t *testing.T) { func TestAnAddedRowNeverExplainsABreakingChange(t *testing.T) { ix := NewIndex([]Entry{{URL: "https://x/added", WhatsNew: "Adds p.", Rows: []Row{{Parameter: "p", Change: "Added", Targets: []Target{{Operation: "POST /v1/x", Path: "p"}}}}}}) - events := []event.ChangeEvent{ + events := []event.Event{ request("POST /v1/x", "p", event.ChangeTypeBreaking, "Stop sending p."), request("POST /v1/x", "p", event.ChangeTypeNewFeature, ""), } @@ -250,7 +250,7 @@ func TestAnAddedRowNeverExplainsABreakingChange(t *testing.T) { func TestARemovedRowNeverExplainsAnAddition(t *testing.T) { ix := NewIndex([]Entry{{URL: "https://x/removed", WhatsNew: "Removes p.", Rows: []Row{{Parameter: "p", Change: "Removed", Targets: []Target{{Operation: "POST /v1/x", Path: "p"}}}}}}) - events := []event.ChangeEvent{ + events := []event.Event{ request("POST /v1/x", "p", event.ChangeTypeBreaking, ""), request("POST /v1/x", "p", event.ChangeTypeNewFeature, ""), } @@ -281,7 +281,7 @@ func TestReleaseOf(t *testing.T) { func TestAHintIsCappedFromTheFrontAndKeepsItsSource(t *testing.T) { ix := NewIndex([]Entry{{URL: "https://x", WhatsNew: strings.Repeat("a", 5000), Rows: []Row{{Parameter: "p", Change: "Changed", Targets: []Target{{Operation: "POST /v1/x", Path: "p"}}}}}}) - events := []event.ChangeEvent{request("POST /v1/x", "p", event.ChangeTypeBreaking, "Handle p as q.")} + events := []event.Event{request("POST /v1/x", "p", event.ChangeTypeBreaking, "Handle p as q.")} ix.Attach(events) got := events[0].MigrationHint if n := len([]rune(got)); n > hintLimit { diff --git a/core/kit/kit_test.go b/core/kit/kit_test.go index a27881e..ea7b9a6 100644 --- a/core/kit/kit_test.go +++ b/core/kit/kit_test.go @@ -54,7 +54,7 @@ func TestUnchangedComparesWithTheLastBaseline(t *testing.T) { if last, same, err := Unchanged(env, "x", []byte("page")); err != nil || same || last != nil { t.Fatalf("first run: %v %v %v", last, same, err) } - if err := env.Baselines.(kittest.Sink).SaveSpec(plugin.Baseline("x", "1", "t", "https://x.test", []byte("page"), false, time.Now())); err != nil { + if err := env.Baselines.(kittest.Sink).SaveSpec(plugin.Baseline("x", "1", "t", "https://x.test", []byte("page"), time.Now())); err != nil { t.Fatal(err) } if _, same, _ := Unchanged(env, "x", []byte("page")); !same { diff --git a/core/kit/kittest/checksink.go b/core/kit/kittest/checksink.go index 548881d..6ea4002 100644 --- a/core/kit/kittest/checksink.go +++ b/core/kit/kittest/checksink.go @@ -27,8 +27,8 @@ func CheckSink(t *testing.T, open func(t *testing.T) Sink) { } return last.Tag } - spec := func(tag, content string, fetched time.Time, replay bool) plugin.Spec { - return plugin.Baseline("x", tag, tag, "https://example.test/"+tag, []byte(content), replay, fetched) + spec := func(tag, content string, fetched time.Time) plugin.Spec { + return plugin.Baseline("x", tag, tag, "https://example.test/"+tag, []byte(content), fetched) } saveSpecs := func(t *testing.T, s Sink, specs ...plugin.Spec) { t.Helper() @@ -41,11 +41,11 @@ func CheckSink(t *testing.T, open func(t *testing.T) Sink) { t.Run("dedupe and ids", func(t *testing.T) { s := open(t) - first := []event.EventV2{sinkEvent(1), sinkEvent(2), sinkEvent(1)} + first := []event.Event{sinkEvent(1), sinkEvent(2), sinkEvent(1)} if n, err := s.SaveEvents(first); err != nil || n != 2 { t.Fatalf("first save: %d new, %v; want 2 (the repeat in the batch is skipped)", n, err) } - if n, err := s.SaveEvents([]event.EventV2{sinkEvent(2), sinkEvent(3)}); err != nil || n != 1 { + if n, err := s.SaveEvents([]event.Event{sinkEvent(2), sinkEvent(3)}); err != nil || n != 1 { t.Fatalf("second save: %d new, %v; want 1", n, err) } all, err := s.All() @@ -67,7 +67,7 @@ func CheckSink(t *testing.T, open func(t *testing.T) Sink) { s := open(t) bad := sinkEvent(2) bad.SourceExcerpt = "" - if _, err := s.SaveEvents([]event.EventV2{sinkEvent(1), bad}); err == nil { + if _, err := s.SaveEvents([]event.Event{sinkEvent(1), bad}); err == nil { t.Fatal("saved an event without provenance") } if all, _ := s.All(); len(all) != 0 { @@ -81,42 +81,28 @@ func CheckSink(t *testing.T, open func(t *testing.T) Sink) { }) t.Run("latest instant across offsets", func(t *testing.T) { s := open(t) - saveSpecs(t, s, spec("older", "1", at.Add(-time.Hour), false), spec("newer", "2", at.In(time.FixedZone("UTC-11", -11*3600)), false)) + saveSpecs(t, s, spec("older", "1", at.Add(-time.Hour)), spec("newer", "2", at.In(time.FixedZone("UTC-11", -11*3600)))) if got := lastTag(t, s, "x"); got != "newer" { t.Errorf("baseline %s, want newer", got) } }) t.Run("equal times go to the newest save", func(t *testing.T) { s := open(t) - saveSpecs(t, s, spec("first", "1", at, false), spec("second", "2", at, false)) + saveSpecs(t, s, spec("first", "1", at), spec("second", "2", at)) if got := lastTag(t, s, "x"); got != "second" { t.Errorf("baseline %s, want second", got) } }) t.Run("same content is one baseline", func(t *testing.T) { s := open(t) - saveSpecs(t, s, spec("a", "same", at, false), spec("b", "other", at.Add(time.Hour), false), spec("c", "same", at.Add(2*time.Hour), false)) + saveSpecs(t, s, spec("a", "same", at), spec("b", "other", at.Add(time.Hour)), spec("c", "same", at.Add(2*time.Hour))) if got := lastTag(t, s, "x"); got != "b" { t.Errorf("baseline %s, want b: the same bytes again aren't a new baseline", got) } }) - t.Run("replays never move the baseline", func(t *testing.T) { - s := open(t) - saveSpecs(t, s, spec("real", "1", at, false), spec("replayed", "2", at.Add(time.Hour), true)) - if got := lastTag(t, s, "x"); got != "real" { - t.Errorf("baseline %s, want real", got) - } - }) - t.Run("a normal fetch claims what a replay stored", func(t *testing.T) { - s := open(t) - saveSpecs(t, s, spec("old", "1", at, false), spec("replayed", "same", at.Add(-time.Hour), true), spec("fetched", "same", at.Add(time.Hour), false)) - if got := lastTag(t, s, "x"); got != "fetched" { - t.Errorf("baseline %s, want fetched", got) - } - }) t.Run("a baseline keeps every field", func(t *testing.T) { s := open(t) - want := spec("v7", "body", at.Add(123456789), false) + want := spec("v7", "body", at.Add(123456789)) saveSpecs(t, s, want) got, err := s.LastSpec("x") if err != nil || got == nil { @@ -124,19 +110,19 @@ func CheckSink(t *testing.T, open func(t *testing.T) Sink) { } want.FetchedAt = want.FetchedAt.Truncate(time.Microsecond) if got.API != want.API || got.Version != want.Version || got.Tag != want.Tag || got.SHA256 != want.SHA256 || got.SourceURL != want.SourceURL || - !got.FetchedAt.Equal(want.FetchedAt) || got.FetchedAt.Location() != time.UTC || got.Replay || string(got.Content) != "body" { + !got.FetchedAt.Equal(want.FetchedAt) || got.FetchedAt.Location() != time.UTC || string(got.Content) != "body" { t.Errorf("got %+v, want %+v", got, want) } }) } -func sinkEvent(n int) event.EventV2 { +func sinkEvent(n int) event.Event { subject := event.Subject{ - Type: event.SubjectAPIOperation, Kind: event.AffectedKindSchemaProperty, Side: event.SideResponse, + Type: event.SubjectAPIOperation, Kind: event.KindSchemaProperty, Side: event.SideResponse, Schema: "thing", Property: fmt.Sprintf("field_%d", n), } - return event.EventV2{ - Fingerprint: event.FingerprintV2("x", "2", event.ChangeTypeBreaking, subject, ""), + return event.Event{ + Fingerprint: event.Fingerprint("x", "2", event.ChangeTypeBreaking, subject, ""), API: "x", Version: "2", ChangeType: event.ChangeTypeBreaking, diff --git a/core/kit/kittest/kittest.go b/core/kit/kittest/kittest.go index d134f14..8437690 100644 --- a/core/kit/kittest/kittest.go +++ b/core/kit/kittest/kittest.go @@ -70,7 +70,7 @@ func Env(t testing.TB, pages Pages) plugin.Env { // 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 { +func Ingest(t testing.TB, p plugin.Plugin, pages Pages) []event.Event { t.Helper() env := Env(t, pages) return IngestWith(t, env, p) @@ -79,7 +79,7 @@ func Ingest(t testing.TB, p plugin.Plugin, pages Pages) []event.EventV2 { // 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 { +func IngestWith(t testing.TB, env plugin.Env, p plugin.Plugin) []event.Event { t.Helper() sink, ok := env.Baselines.(Sink) if !ok { @@ -99,7 +99,7 @@ func IngestWith(t testing.TB, env plugin.Env, p plugin.Plugin) []event.EventV2 { } // Stored is every event in s, in feed order, or the test fails. -func Stored(t testing.TB, s Sink) []event.EventV2 { +func Stored(t testing.TB, s Sink) []event.Event { t.Helper() all, err := s.All() if err != nil { @@ -109,20 +109,20 @@ func Stored(t testing.TB, s Sink) []event.EventV2 { } // 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) { +// -update. Every event must also be valid, or the golden would pin a bug. +func Golden(t testing.TB, path string, events []event.Event) { 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) { +func CompareGolden(t testing.TB, path string, events []event.Event) { t.Helper() golden(t, path, events, false) } -func golden(t testing.TB, path string, events []event.EventV2, rewrite bool) { +func golden(t testing.TB, path string, events []event.Event, rewrite bool) { t.Helper() for _, e := range events { if err := e.Validate(); err != nil { @@ -130,7 +130,7 @@ func golden(t testing.TB, path string, events []event.EventV2, rewrite bool) { } } if events == nil { - events = []event.EventV2{} + events = []event.Event{} } var buf bytes.Buffer enc := json.NewEncoder(&buf) diff --git a/core/kit/kittest/mem.go b/core/kit/kittest/mem.go index 8a04593..1ef098a 100644 --- a/core/kit/kittest/mem.go +++ b/core/kit/kittest/mem.go @@ -20,22 +20,22 @@ type Sink interface { plugin.BaselineReader // SaveEvents stores events, skipping any whose fingerprint is already // stored, and returns how many were new. An invalid event stores nothing. - SaveEvents(events []event.EventV2) (int, error) + SaveEvents(events []event.Event) (int, error) // SaveSpec stores a baseline, once per (api, sha256). SaveSpec(spec plugin.Spec) error // All is every stored event in feed order, each with its id. - All() ([]event.EventV2, error) + All() ([]event.Event, error) } // Mem is a Sink in memory that stores like the hosted service's database does, so a // golden file is the same whichever stored the events: events are deduped by // fingerprint and get ids 1, 2, 3... in the order they were saved, each is // stored as its JSON (what the feed serves), and a baseline is the latest -// non-replay one, by fetch time, then by save order. Ingest's conformance test -// replays every plugin's golden through the real store to keep the two equal. +// one, by fetch time, then by save order. Ingest's conformance test stores +// every plugin's golden through the real store to keep the two equal. type Mem struct { mu sync.Mutex - events []event.EventV2 + events []event.Event seen map[string]bool specs []plugin.Spec // in save order } @@ -45,9 +45,9 @@ var _ Sink = (*Mem)(nil) // NewMem is an empty store. func NewMem() *Mem { return &Mem{seen: map[string]bool{}} } -func (m *Mem) SaveEvents(events []event.EventV2) (int, error) { +func (m *Mem) SaveEvents(events []event.Event) (int, error) { // Like the store's transaction: one invalid event and none are stored. - stored := make([]event.EventV2, 0, len(events)) + stored := make([]event.Event, 0, len(events)) for _, e := range events { if err := e.Validate(); err != nil { return 0, fmt.Errorf("invalid event %s: %w", e.Fingerprint, err) @@ -56,7 +56,7 @@ func (m *Mem) SaveEvents(events []event.EventV2) (int, error) { if err != nil { return 0, fmt.Errorf("marshaling event %s: %w", e.Fingerprint, err) } - var back event.EventV2 + var back event.Event if err := json.Unmarshal(data, &back); err != nil { return 0, fmt.Errorf("unmarshaling event %s: %w", e.Fingerprint, err) } @@ -80,43 +80,36 @@ func (m *Mem) SaveEvents(events []event.EventV2) (int, error) { return saved, nil } -func (m *Mem) All() ([]event.EventV2, error) { +func (m *Mem) All() ([]event.Event, error) { m.mu.Lock() defer m.mu.Unlock() return slices.Clone(m.events), nil } -// SaveSpec stores spec once per (api, sha256). The same content saved again -// is not a new baseline, with one exception kept from the store: a replay saved -// it first and a normal run now has, so the row stops being a replay and takes -// the normal run's time and tag (else LastSpec, which skips replays, would -// never find it). +// SaveSpec stores spec once per (api, sha256): the same content saved again +// is not a new baseline. func (m *Mem) SaveSpec(spec plugin.Spec) error { spec.FetchedAt = spec.FetchedAt.UTC().Truncate(time.Microsecond) // what Postgres keeps: UTC, to the microsecond spec.Content = bytes.Clone(spec.Content) m.mu.Lock() defer m.mu.Unlock() - for i, s := range m.specs { - if s.API != spec.API || s.SHA256 != spec.SHA256 { - continue - } - if s.Replay && !spec.Replay { - m.specs[i].Replay, m.specs[i].FetchedAt, m.specs[i].Tag = false, spec.FetchedAt, spec.Tag + for _, s := range m.specs { + if s.API == spec.API && s.SHA256 == spec.SHA256 { + return nil } - return nil } m.specs = append(m.specs, spec) return nil } -// LastSpec is api's latest non-replay baseline, or nil on a first run. +// LastSpec is api's latest baseline, or nil on a first run. func (m *Mem) LastSpec(api string) (*plugin.Spec, error) { m.mu.Lock() defer m.mu.Unlock() var last *plugin.Spec for i := range m.specs { s := &m.specs[i] - if s.API != api || s.Replay { + if s.API != api { continue } if last == nil || !s.FetchedAt.Before(last.FetchedAt) { // a later save wins a tie @@ -144,13 +137,23 @@ func Run(ctx context.Context, env plugin.Env, sink Sink, p plugin.Plugin) (rejec return save(sink, p.Name(), r) } -// Replay is Run over two releases of a plugin that can replay them. -func Replay(ctx context.Context, env plugin.Env, sink Sink, p plugin.Plugin, from, to string) (rejected bool, err error) { - rp, ok := p.(plugin.Replayer) +// Pair reads two versions of a versioned plugin (by id, read at the same +// ref), extracts the change between them and stores its events in sink: a +// version pair as patch-it's ingestion service does it. +func Pair(ctx context.Context, env plugin.Env, sink Sink, p plugin.Plugin, from, to string) (rejected bool, err error) { + vp, ok := p.(plugin.Versioned) if !ok { - return false, fmt.Errorf("%s has no releases to replay", p.Name()) + return false, fmt.Errorf("%s isn't read version by version", p.Name()) + } + a, err := vp.ReadAt(ctx, env, plugin.Version{ID: from, Ref: from}) + if err != nil { + return false, fmt.Errorf("%s: %w", p.Name(), err) + } + b, err := vp.ReadAt(ctx, env, plugin.Version{ID: to, Ref: to}) + if err != nil { + return false, fmt.Errorf("%s: %w", p.Name(), err) } - r, err := rp.Replay(ctx, env, from, to) + r, err := vp.Extract(ctx, env, a, b) if err != nil { return false, fmt.Errorf("%s: %w", p.Name(), err) } diff --git a/core/kit/kittest/mem_test.go b/core/kit/kittest/mem_test.go index c673613..f7bb357 100644 --- a/core/kit/kittest/mem_test.go +++ b/core/kit/kittest/mem_test.go @@ -15,10 +15,10 @@ func TestMemStoresAsIngestDoes(t *testing.T) { // golden file's ids then depend only on the events it holds. func TestMemIdsHaveNoGaps(t *testing.T) { m := NewMem() - if _, err := m.SaveEvents([]event.EventV2{sinkEvent(1), sinkEvent(1), sinkEvent(2)}); err != nil { + if _, err := m.SaveEvents([]event.Event{sinkEvent(1), sinkEvent(1), sinkEvent(2)}); err != nil { t.Fatal(err) } - if _, err := m.SaveEvents([]event.EventV2{sinkEvent(2), sinkEvent(3)}); err != nil { + if _, err := m.SaveEvents([]event.Event{sinkEvent(2), sinkEvent(3)}); err != nil { t.Fatal(err) } all, _ := m.All() @@ -43,5 +43,5 @@ func TestMemLastSpecIsACopy(t *testing.T) { } func sinkSpec(content string) plugin.Spec { - return plugin.Baseline("x", "1", "v1", "https://example.test/1", []byte(content), false, Clock) + return plugin.Baseline("x", "1", "v1", "https://example.test/1", []byte(content), Clock) } diff --git a/core/kit/notices.go b/core/kit/notices.go new file mode 100644 index 0000000..a2c3a2b --- /dev/null +++ b/core/kit/notices.go @@ -0,0 +1,11 @@ +package kit + +// Notices is what a reader of a live page of dated notices (a deprecations +// table, an end-of-life table, a feed: plugins/notices) found on one read +// of it. The kind compares what the live page and its snapshot give with +// reflect.DeepEqual (Cite), so a Notices holds plain values, never a func. +type Notices interface { + // Count is how many notices were read: what the shape guard compares + // with the last read. + Count() int +} diff --git a/core/migrate/migrate.go b/core/migrate/migrate.go deleted file mode 100644 index 3ffa523..0000000 --- a/core/migrate/migrate.go +++ /dev/null @@ -1,120 +0,0 @@ -// 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/core/migrate/migrate_test.go b/core/migrate/migrate_test.go deleted file mode 100644 index c6fccb3..0000000 --- a/core/migrate/migrate_test.go +++ /dev/null @@ -1,137 +0,0 @@ -package migrate - -import ( - "bytes" - "encoding/json" - "flag" - "os" - "strings" - "testing" - - "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/" - -// 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. -var v1Files = []string{ - "change-events.json", - "change-events-model-retirements-2026-10-13.json", - "change-events-anthropic-sdk-1.0.0.json", -} - -func read(t *testing.T, name string) []event.ChangeEvent { - t.Helper() - raw, err := os.ReadFile(fixtures + name) - if err != nil { - t.Fatal(err) - } - var feed struct { - Changes []event.ChangeEvent `json:"changes"` - } - if err := json.Unmarshal(raw, &feed); err != nil { - t.Fatalf("%s: %v", name, err) - } - return feed.Changes -} - -// The golden file is what the cut-over will store: both loops check it -// (event's v2 tests, patch-it's tests/test_contract_v2.py). -func TestV2FixtureIsTheConversionOfV1(t *testing.T) { - var out []event.EventV2 - for _, name := range v1Files { - for _, e := range read(t, name) { - v2, err := ToV2(e) - if err != nil { - t.Fatalf("%s: %v", name, err) - } - if err := v2.Validate(); err != nil { - t.Fatalf("%s event %d converts to an invalid v2 event: %v", name, e.ID, err) - } - out = append(out, v2) - } - } - var buf bytes.Buffer - enc := json.NewEncoder(&buf) - enc.SetEscapeHTML(false) - enc.SetIndent("", " ") - if err := enc.Encode(map[string]any{"changes": out}); err != nil { - t.Fatal(err) - } - golden := fixtures + "change-events-v2.json" - if *update { - if err := os.WriteFile(golden, buf.Bytes(), 0o644); err != nil { - t.Fatal(err) - } - } - want, err := os.ReadFile(golden) - if err != nil { - t.Fatalf("%v (run with -update to create it)", err) - } - if !bytes.Equal(buf.Bytes(), want) { - t.Errorf("%s isn't the conversion of the v1 fixtures: run go test ./migrate -update", golden) - } -} - -// A Stripe event keeps its fingerprint, so the 901 stored events of a release -// aren't re-keyed. Checked on the whole endive release, not only the samples. -func TestAStripeEventKeepsItsFingerprint(t *testing.T) { - for _, name := range []string{"change-events.json", "change-events-stripe-2026-09-30.json"} { - for _, e := range read(t, name) { - v2, err := ToV2(e) - if err != nil { - t.Fatalf("%s: %v", name, err) - } - if v2.Fingerprint != e.Fingerprint || v2.Supersedes != "" { - t.Errorf("%s event %d: fingerprint %s → %s, supersedes %q", name, e.ID, e.Fingerprint, v2.Fingerprint, v2.Supersedes) - } - if err := v2.Validate(); err != nil { - t.Errorf("%s event %d: %v", name, e.ID, err) - } - } - } -} - -// A re-keyed event names the fingerprint it replaces: the patch-it client -// finds its open issue or pull request by that one, and opens nothing twice (found in -// review: without it, every repo with an open retirement PR gets a second). -func TestARekeyedEventSupersedesItsV1Fingerprint(t *testing.T) { - for _, name := range v1Files[1:] { - for _, e := range read(t, name) { - v2, err := ToV2(e) - if err != nil { - t.Fatal(err) - } - if v2.Fingerprint == e.Fingerprint || v2.Supersedes != e.Fingerprint { - t.Errorf("%s event %d: fingerprint %s, supersedes %q, v1 %s", name, e.ID, v2.Fingerprint, v2.Supersedes, e.Fingerprint) - } - } - } -} - -func TestReplacementIsOnlyOnePlainModel(t *testing.T) { - for hint, want := range map[string]string{ - "Use `gpt-5.6-sol` instead: OpenAI's recommended replacement.": "gpt-5.6-sol", - "Use `gpt-5.6-terra` instead: OpenAI's recommended replacement. (OpenAI first named `gpt-3.5-turbo`, which is itself retired.)": "gpt-5.6-terra", - "Use `gpt-5.6-sol` (`reasoning.mode: pro`) instead: OpenAI's recommended replacement.": "", - "OpenAI names no replacement model: The most capable cyber model available to you.": "", - "Use `a` or `b` instead: OpenAI's recommended replacement.": "", - } { - if got := replacement(hint); got != want { - t.Errorf("replacement(%q) = %q, want %q", hint, got, want) - } - } -} - -func TestAnEventItCantPlaceIsRefused(t *testing.T) { - e := read(t, "change-events.json")[0] - e.Affected.Value = "gpt-4" - e.Affected.Property = "model" - if _, err := ToV2(e); err == nil || !strings.Contains(err.Error(), "isn't a model retirement") { - t.Errorf("a value on a Stripe event converted: %v", err) - } -} diff --git a/core/normalize/golden_test.go b/core/normalize/golden_test.go index 6fb92a1..9f5dd76 100644 --- a/core/normalize/golden_test.go +++ b/core/normalize/golden_test.go @@ -29,7 +29,7 @@ var update = flag.Bool("update", false, "rewrite the golden events.json files fr // Everything that isn't part of the spec pair is fixed, so the output is exactly // reproducible. var goldenSource = Source{ - API: "stripe", + API: "stripe/api", NewSpecURL: "https://raw.githubusercontent.com/stripe/openapi/v2468/latest/openapi.spec3.json", OldSpecURL: "https://raw.githubusercontent.com/stripe/openapi/v2460/latest/openapi.spec3.json", DetectedAt: time.Date(2026, 9, 27, 12, 0, 0, 0, time.UTC), diff --git a/core/normalize/normalize.go b/core/normalize/normalize.go index 9279fc9..9f8b1ab 100644 --- a/core/normalize/normalize.go +++ b/core/normalize/normalize.go @@ -24,7 +24,7 @@ const excerptLimit = 2000 // Source describes where a pair of specs came from, so each event can point // back at the exact document that proves it. type Source struct { - API string // "stripe" + API string // the source id: "stripe/api" Version string // info.version of the new spec PreviousVersion string // info.version of the old spec NewSpecURL string // pinned URL of the new spec, e.g. .../v2468/... @@ -40,17 +40,17 @@ type Source struct { // is structural, so there is nothing to be unsure about: the change did happen // exactly as described. Whether it matters to a given repository is the // patch-it client's question, not this one's. -func Events(changes []diff.Change, src Source) ([]event.ChangeEvent, []error) { +func Events(changes []diff.Change, src Source) ([]event.Event, []error) { detectedAt := src.DetectedAt if detectedAt.IsZero() { detectedAt = time.Now().UTC() } - events := make([]event.ChangeEvent, 0, len(changes)) + events := make([]event.Event, 0, len(changes)) var errs []error for _, c := range changes { - affected := affectedFor(c) + subject := subjectFor(c) sourceURL := src.NewSpecURL if c.InOld { sourceURL = src.OldSpecURL @@ -62,14 +62,14 @@ func Events(changes []diff.Change, src Source) ([]event.ChangeEvent, []error) { continue } - e := event.ChangeEvent{ - Fingerprint: event.Fingerprint(src.API, src.Version, c.ChangeType, affected, c.Detail), + e := event.Event{ + Fingerprint: event.Fingerprint(src.API, src.Version, c.ChangeType, subject, c.Detail), API: src.API, Version: src.Version, PreviousVersion: src.PreviousVersion, ChangeType: c.ChangeType, Breaking: c.Breaking, - Affected: affected, + Subject: subject, Description: describe(c), MigrationHint: migrationHint(c), SourceURL: sourceURL, @@ -89,11 +89,12 @@ func Events(changes []diff.Change, src Source) ([]event.ChangeEvent, []error) { return events, errs } -// affectedFor maps a change's location onto the contract's four kinds. The +// subjectFor maps a change's location onto the contract's four kinds. The // side already decides the pair: requests are addressed by operation, responses // by schema, and naming a property narrows either one. -func affectedFor(c diff.Change) event.Affected { - a := event.Affected{ +func subjectFor(c diff.Change) event.Subject { + a := event.Subject{ + Type: event.SubjectAPIOperation, Side: c.Side, Operation: c.Operation, Schema: c.Schema, @@ -102,15 +103,15 @@ func affectedFor(c diff.Change) event.Affected { switch { case c.Side == event.SideRequest && c.Property != "": - a.Kind = event.AffectedKindRequestParameter + a.Kind = event.KindRequestParameter case c.Side == event.SideRequest: // A change to the request body's root schema has no property to name, // so it is reported against the operation itself. - a.Kind = event.AffectedKindOperation + a.Kind = event.KindOperation case c.Property != "": - a.Kind = event.AffectedKindSchemaProperty + a.Kind = event.KindSchemaProperty default: - a.Kind = event.AffectedKindSchema + a.Kind = event.KindSchema } return a } diff --git a/core/normalize/normalize_test.go b/core/normalize/normalize_test.go index 89d8025..4e7845f 100644 --- a/core/normalize/normalize_test.go +++ b/core/normalize/normalize_test.go @@ -16,7 +16,7 @@ const ( ) var source = Source{ - API: "stripe", + API: "stripe/api", Version: "2022-11-15", PreviousVersion: "2022-08-01", NewSpecURL: newURL, @@ -61,8 +61,8 @@ func TestEventsAreValidWithFullProvenance(t *testing.T) { } removed, added := events[0], events[1] - if removed.Affected.Kind != event.AffectedKindSchemaProperty || removed.Affected.Schema != "payment_intent" || - removed.Affected.Property != "charges" || !removed.Breaking { + if removed.Subject.Kind != event.KindSchemaProperty || removed.Subject.Schema != "payment_intent" || + removed.Subject.Property != "charges" || !removed.Breaking { t.Errorf("charges removal mapped wrong: %+v", removed) } // Removals cite the old spec: the evidence is gone from the new one. @@ -71,13 +71,13 @@ func TestEventsAreValidWithFullProvenance(t *testing.T) { } for _, e := range events { if e.Confidence != 1.0 { - t.Errorf("%s: confidence %v, want 1.0 for a spec diff", e.Affected.Property, e.Confidence) + t.Errorf("%s: confidence %v, want 1.0 for a spec diff", e.Subject.Property, e.Confidence) } if e.Version != "2022-11-15" || e.PreviousVersion != "2022-08-01" || !e.DetectedAt.Equal(source.DetectedAt) { - t.Errorf("%s: version/time not carried over: %+v", e.Affected.Property, e) + t.Errorf("%s: version/time not carried over: %+v", e.Subject.Property, e) } if e.SourcePointer == "" || e.SourceExcerpt == "" { - t.Errorf("%s: missing pointer or excerpt", e.Affected.Property) + t.Errorf("%s: missing pointer or excerpt", e.Subject.Property) } } } diff --git a/core/normalize/testdata/golden/breaking-property-removed/events.json b/core/normalize/testdata/golden/breaking-property-removed/events.json index 13ab3a5..90c6f77 100644 --- a/core/normalize/testdata/golden/breaking-property-removed/events.json +++ b/core/normalize/testdata/golden/breaking-property-removed/events.json @@ -1,13 +1,14 @@ [ { "id": 0, - "fingerprint": "sha256:ff7dd3f4198ccc46ce89ac4c82249fe9e442478d8c3da6b713596249017f96fb", - "api": "stripe", + "fingerprint": "sha256:77d0d93b830cba06d786c98a2fc3d22c550a775d5ce5df87c43e042083dda138", + "api": "stripe/api", "version": "2026-08-26.dahlia", "previous_version": "2026-07-29.dahlia", "change_type": "breaking", "breaking": true, - "affected": { + "subject": { + "type": "api_operation", "kind": "schema_property", "side": "response", "schema": "payments_primitives_payment_records_resource_payment_method_card_details_resource_three_d_secure", diff --git a/core/normalize/testdata/golden/deprecation/events.json b/core/normalize/testdata/golden/deprecation/events.json index aad6939..c308aed 100644 --- a/core/normalize/testdata/golden/deprecation/events.json +++ b/core/normalize/testdata/golden/deprecation/events.json @@ -1,13 +1,14 @@ [ { "id": 0, - "fingerprint": "sha256:5e6a726296bc4c319b8605eb7e3f67d641ae3d63c9d5038b75bb691d5ac5b6be", - "api": "stripe", + "fingerprint": "sha256:0563cf609d49fe03301efb63f3b071d05ffa98392a443dbccec31b867a4446b9", + "api": "stripe/api", "version": "2026-08-26.dahlia", "previous_version": "2026-07-29.dahlia", "change_type": "deprecation", "breaking": false, - "affected": { + "subject": { + "type": "api_operation", "kind": "operation", "side": "request", "operation": "POST /v1/charges" diff --git a/core/normalize/testdata/golden/new-endpoint/events.json b/core/normalize/testdata/golden/new-endpoint/events.json index d921674..bfa160b 100644 --- a/core/normalize/testdata/golden/new-endpoint/events.json +++ b/core/normalize/testdata/golden/new-endpoint/events.json @@ -1,13 +1,14 @@ [ { "id": 0, - "fingerprint": "sha256:c945f5c4c228e6a9a7fa10537b4f931c4dfdae7ee8688520dc3229b9860862bc", - "api": "stripe", + "fingerprint": "sha256:480b352be42e611c5b6806177349bb7230190f2ee9ccfe8d16c27ade354b6dfb", + "api": "stripe/api", "version": "2026-08-26.dahlia", "previous_version": "2026-07-29.dahlia", "change_type": "new_feature", "breaking": false, - "affected": { + "subject": { + "type": "api_operation", "kind": "operation", "side": "request", "operation": "POST /v1/billing/feedback_options" diff --git a/core/plugin/plugin.go b/core/plugin/plugin.go index 203f092..f5a623b 100644 --- a/core/plugin/plugin.go +++ b/core/plugin/plugin.go @@ -2,7 +2,7 @@ // 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 +// Adding a source is a RegisterProvider call in its kind's package; nothing // here changes. package plugin @@ -10,7 +10,6 @@ import ( "context" "crypto/sha256" "encoding/hex" - "fmt" "slices" "sync" "time" @@ -20,20 +19,14 @@ import ( // 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 is the source's id, "/", which its events + // carry in `api`: "stripe/api", "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 @@ -67,16 +60,15 @@ type Spec struct { 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 + Label string // what was read, for the summary: a tag, a snapshot, a URL + Events []event.Event // valid events, to store + Rejected []error // changes that failed to become valid events + Baselines []Spec // what the run read, saved after the events } var ( @@ -84,37 +76,16 @@ var ( 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: its old slug ("algolia-search") -// or its source's full id ("algolia/search-api"). -func Lookup(name string) (Plugin, bool) { +// Lookup finds a registered plugin by its source's id ("algolia/search-api"). +func Lookup(id string) (Plugin, bool) { mu.Lock() defer mu.Unlock() - if p, ok := registry[name]; ok { - return p, true - } - if s, ok := sources[name]; ok { - return s.Source.Plugin, true - } - return nil, false + p, ok := registry[id] + return p, ok } -// Names are the registered plugins' old slugs, sorted: what `--api all` runs. -// Sources lists them with their full ids and metadata. +// Names are the registered sources' ids, sorted. Sources lists them with +// their metadata. func Names() []string { mu.Lock() defer mu.Unlock() @@ -128,7 +99,7 @@ func Names() []string { // 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 { +func Baseline(api, version, tag, sourceURL string, content []byte, at time.Time) Spec { return Spec{ API: api, Version: version, @@ -136,7 +107,6 @@ func Baseline(api, version, tag, sourceURL string, content []byte, replay bool, SHA256: SHA256(content), SourceURL: sourceURL, FetchedAt: at, - Replay: replay, Content: content, } } diff --git a/core/plugin/plugin_test.go b/core/plugin/plugin_test.go index 34f3b12..05453f2 100644 --- a/core/plugin/plugin_test.go +++ b/core/plugin/plugin_test.go @@ -21,9 +21,9 @@ func (p testPlugin) Run(_ context.Context, env Env) (Result, error) { if p.err != nil { return Result{}, p.err } - subject := event.Subject{Type: event.SubjectAPIOperation, Kind: event.AffectedKindOperation, Side: event.SideRequest, Operation: "POST /v1/things"} - e := event.EventV2{ - Fingerprint: event.FingerprintV2(p.name, "2", event.ChangeTypeNewFeature, subject, ""), + subject := event.Subject{Type: event.SubjectAPIOperation, Kind: event.KindOperation, Side: event.SideRequest, Operation: "POST /v1/things"} + e := event.Event{ + Fingerprint: event.Fingerprint(p.name, "2", event.ChangeTypeNewFeature, subject, ""), API: p.name, Version: "2", ChangeType: event.ChangeTypeNewFeature, @@ -37,53 +37,47 @@ func (p testPlugin) Run(_ context.Context, env Env) (Result, error) { content := []byte(`{"version":"2"}`) return Result{ Label: "v2", - Events: []event.EventV2{e}, - Baselines: []Spec{Baseline(p.name, "2", "v2", "https://example.test/spec/2.json", content, false, env.Now())}, + Events: []event.Event{e}, + Baselines: []Spec{Baseline(p.name, "2", "v2", "https://example.test/spec/2.json", content, env.Now())}, }, nil } -func TestAPluginRegisteredInATestIsFound(t *testing.T) { - register(t, testPlugin{name: "test-registered"}) - if p, ok := Lookup("test-registered"); !ok || p.Name() != "test-registered" || !slices.Contains(Names(), "test-registered") { +func TestASourceRegisteredInATestIsFound(t *testing.T) { + register(t, "test-registered") + if p, ok := Lookup("test-registered/api"); !ok || p.Name() != "test-registered/api" || !slices.Contains(Names(), "test-registered/api") { t.Fatal("not registered") } } func TestNamesAreSorted(t *testing.T) { - register(t, testPlugin{name: "test-b"}) - register(t, testPlugin{name: "test-a"}) + register(t, "test-b") + register(t, "test-a") if !slices.IsSorted(Names()) { t.Errorf("Names() = %v, want sorted", Names()) } } -// register registers a test plugin for the rest of the test only, so the test -// can run again (-count). -func register(t *testing.T, p Plugin) { +// register registers a test provider with one source, api, for the rest of +// the test only, so the test can run again (-count). +func register(t *testing.T, provider string) { t.Helper() - Register(p) + RegisterProvider(Provider{ID: provider, Name: provider, Category: CategoryDevTools, Homepage: "https://example.test", + Sources: []Source{{ID: "api", Layer: LayerAPI, Watches: "w", URLs: []string{"https://example.test/spec"}, Page: "providers/test.md", Plugin: testPlugin{name: provider + "/api"}}}}) t.Cleanup(func() { mu.Lock() defer mu.Unlock() - delete(registry, p.Name()) + delete(registry, provider+"/api") + delete(sources, provider+"/api") + delete(providers, provider) }) } -func TestTwoPluginsCantShareAName(t *testing.T) { - register(t, testPlugin{name: "test-dup"}) +func TestTwoSourcesCantShareAnID(t *testing.T) { + register(t, "test-dup") defer func() { if recover() == nil { - t.Error("a second plugin named test-dup was registered") + t.Error("a second source test-dup/api was registered") } }() - Register(testPlugin{name: "test-dup"}) -} - -func TestAPluginCantBeNamedAll(t *testing.T) { - defer func() { - if recover() == nil { - t.Error(`a plugin named "all" was registered: --api all would hide it`) - } - }() - Register(testPlugin{name: "all"}) + register(t, "test-dup") } diff --git a/core/plugin/provider.go b/core/plugin/provider.go index 4546d40..f0a4644 100644 --- a/core/plugin/provider.go +++ b/core/plugin/provider.go @@ -67,6 +67,11 @@ const ( LayerInfra Layer = "infra" ) +// Ecosystems are the package registries a Source's Packages name. +func Ecosystems() []string { + return []string{"pypi", "npm", "go", "maven", "nuget", "rubygems", "cargo", "packagist"} +} + // Layers are every layer. func Layers() []Layer { return []Layer{LayerAPI, LayerSDK, LayerPackage, LayerRuntime, LayerCI, LayerAIModels, LayerInfra} @@ -103,9 +108,15 @@ type Source struct { // Page is the source's page in this repo: "providers/algolia.md" (why // this source, what it reads and ignores, its known gaps). Page string - // Plugin runs it. Its Name is the source's old slug ("algolia-search"): - // what `--api` selects and every event's `api` carries until patch-it's - // change-event contract switches to source ids. + // Packages are the published packages whose changes this source + // covers, as ":" ("pypi:stripe", "npm:@vercel/sdk"): + // the package itself for a package or SDK source, the provider's + // official SDKs for an API source. What lets a lockfile entry find its + // sources without a table kept elsewhere. Only names checked by hand; + // none is fine when no package maps to the source. + Packages []string + // Plugin runs it. Its Name is the source's id ("algolia/search-api"), + // which every event's `api` carries. Plugin Plugin } @@ -118,19 +129,14 @@ type SourceInfo struct { // FullID is "/". func (s SourceInfo) FullID() string { return s.Provider.ID + "/" + s.Source.ID } -// Alias is the source's old slug, its Plugin's Name: "algolia-search". -func (s SourceInfo) Alias() string { return s.Source.Plugin.Name() } - var ( providers = map[string]Provider{} // by provider ID, Sources merged sources = map[string]SourceInfo{} // by full ID - aliases = map[string]string{} // old slug to full ID slug = regexp.MustCompile(`^[a-z0-9][a-z0-9-]*$`) ) -// RegisterProvider registers p's sources, each under its full id, and each -// source's Plugin under its old slug (Register), so Lookup finds it by -// either. Incomplete metadata is a programming error, as a duplicate is. +// RegisterProvider registers p's sources, each under its id, with its Plugin +// (Lookup). Incomplete metadata is a programming error, as a duplicate is. func RegisterProvider(p Provider) { if err := p.check(); err != nil { panic("plugin: " + err.Error()) @@ -139,27 +145,17 @@ func RegisterProvider(p Provider) { p.Sources[i].Kind = KindOf(p.Sources[i].Plugin) } mu.Lock() + defer mu.Unlock() if have, ok := providers[p.ID]; ok { if have.Name != p.Name || have.Category != p.Category || have.Homepage != p.Homepage { - mu.Unlock() panic(fmt.Sprintf("plugin: provider %q registered twice with different metadata", p.ID)) } } for _, s := range p.Sources { - id := p.ID + "/" + s.ID - if _, dup := sources[id]; dup { - mu.Unlock() - panic(fmt.Sprintf("plugin: source %q is already registered", id)) + if _, dup := sources[p.ID+"/"+s.ID]; dup { + panic(fmt.Sprintf("plugin: source %q is already registered", p.ID+"/"+s.ID)) } } - mu.Unlock() - - for _, s := range p.Sources { - Register(s.Plugin) // panics on a duplicate old slug - } - - mu.Lock() - defer mu.Unlock() have := providers[p.ID] merged := Provider{ID: p.ID, Name: p.Name, Category: p.Category, Homepage: p.Homepage, Sources: append(have.Sources, p.Sources...)} providers[p.ID] = merged @@ -168,7 +164,7 @@ func RegisterProvider(p Provider) { for _, s := range p.Sources { id := p.ID + "/" + s.ID sources[id] = SourceInfo{Provider: bare, Source: s} - aliases[s.Plugin.Name()] = id + registry[id] = s.Plugin } } @@ -196,6 +192,8 @@ func (p Provider) check() error { return fmt.Errorf("source %q is listed twice", id) case s.Plugin == nil: return fmt.Errorf("source %q has no Plugin", id) + case s.Plugin.Name() != id: + return fmt.Errorf("source %q: its plugin's Name is %q; a plugin is named by its source's id", id, s.Plugin.Name()) case !slices.Contains(Layers(), s.Layer): return fmt.Errorf("source %q: layer %q isn't one of plugin.Layers()", id, s.Layer) case strings.TrimSpace(s.Watches) == "": @@ -212,6 +210,12 @@ func (p Provider) check() error { return fmt.Errorf("source %q: URL %q isn't absolute", id, u) } } + for _, pkg := range s.Packages { + eco, name, ok := strings.Cut(pkg, ":") + if !ok || !slices.Contains(Ecosystems(), eco) || name == "" || strings.ContainsAny(name, " \t\n") { + return fmt.Errorf("source %q: package %q isn't :, the ecosystem one of plugin.Ecosystems()", id, pkg) + } + } seen[s.ID] = true } return nil @@ -259,14 +263,23 @@ func Sources() []SourceInfo { return out } -// LookupSource finds a source by its full id ("algolia/search-api") or its -// old slug ("algolia-search"). +// ForPackage are the sources that cover a published package +// ("pypi:stripe"), sorted by full id: how a lockfile entry finds what to +// ask the feed for. +func ForPackage(pkg string) []SourceInfo { + var out []SourceInfo + for _, s := range Sources() { + if slices.Contains(s.Source.Packages, pkg) { + out = append(out, s) + } + } + return out +} + +// LookupSource finds a source by its id ("algolia/search-api"). func LookupSource(id string) (SourceInfo, bool) { mu.Lock() defer mu.Unlock() - if full, ok := aliases[id]; ok { - id = full - } s, ok := sources[id] return s, ok } diff --git a/core/plugin/provider_test.go b/core/plugin/provider_test.go index e890f1d..9bd2927 100644 --- a/core/plugin/provider_test.go +++ b/core/plugin/provider_test.go @@ -11,25 +11,27 @@ type fake struct{ name string } func (f fake) Name() string { return f.name } func (fake) Run(context.Context, Env) (Result, error) { return Result{}, nil } -func src(id, slug string) Source { - return Source{ID: id, Layer: LayerAPI, Watches: "w", URLs: []string{"https://example.com/spec"}, Page: "providers/acme.md", Plugin: fake{slug}} +// src is a source of the provider whose id is provider, named by its id. +func src(id, provider string) Source { + return Source{ID: id, Layer: LayerAPI, Watches: "w", URLs: []string{"https://example.com/spec"}, Page: "providers/acme.md", Plugin: fake{provider + "/" + id}} } func acme(sources ...Source) Provider { return Provider{ID: "acme-test", Name: "Acme", Category: CategoryPayments, Homepage: "https://example.com", Sources: sources} } -func TestRegisterProviderResolvesBothIDs(t *testing.T) { - RegisterProvider(acme(src("api", "acme-test-api"))) - RegisterProvider(acme(src("sdk", "acme-test-sdk"))) // a second kind adds a source - for _, id := range []string{"acme-test/api", "acme-test-api"} { - s, ok := LookupSource(id) - if !ok || s.FullID() != "acme-test/api" || s.Alias() != "acme-test-api" || s.Source.Kind != "plugin" { - t.Errorf("LookupSource(%q) = %+v, %v", id, s, ok) - } - if p, ok := Lookup(id); !ok || p.Name() != "acme-test-api" { - t.Errorf("Lookup(%q) = %v, %v", id, p, ok) - } +func TestRegisterProviderRegistersEachSourceByItsID(t *testing.T) { + RegisterProvider(acme(src("api", "acme-test"))) + RegisterProvider(acme(src("sdk", "acme-test"))) // a second kind adds a source + s, ok := LookupSource("acme-test/api") + if !ok || s.FullID() != "acme-test/api" || s.Source.Kind != "plugin" { + t.Errorf("LookupSource = %+v, %v", s, ok) + } + if p, ok := Lookup("acme-test/api"); !ok || p.Name() != "acme-test/api" { + t.Errorf("Lookup = %v, %v", p, ok) + } + if _, ok := Lookup("acme-test-api"); ok { + t.Error("found a source by a name that isn't its id") } var got []string for _, p := range Providers() { @@ -46,6 +48,11 @@ func TestRegisterProviderResolvesBothIDs(t *testing.T) { func TestRegisterProviderRefusesIncompleteMetadata(t *testing.T) { for name, p := range map[string]Provider{ + "named by another id": acme(func() Source { + s := src("named", "acme-test") + s.Plugin = fake{"acme-test-named"} + return s + }()), "no category": {ID: "x1", Name: "X", Homepage: "https://x.example", Sources: []Source{src("api", "x1")}}, "no sources": {ID: "x2", Name: "X", Category: CategoryAI, Homepage: "https://x.example"}, "bad homepage": {ID: "x3", Name: "X", Category: CategoryAI, Homepage: "x.example", Sources: []Source{src("api", "x3")}}, @@ -59,6 +66,11 @@ func TestRegisterProviderRefusesIncompleteMetadata(t *testing.T) { s.Layer = "API" return s }()}}, + "bad package": {ID: "x7", Name: "X", Category: CategoryAI, Homepage: "https://x.example", Sources: []Source{func() Source { + s := src("api", "x7") + s.Packages = []string{"pip:x"} + return s + }()}}, "wrong kind": {ID: "x6", Name: "X", Category: CategoryAI, Homepage: "https://x.example", Sources: []Source{func() Source { s := src("api", "x6") s.Kind = "openapi" @@ -72,13 +84,27 @@ func TestRegisterProviderRefusesIncompleteMetadata(t *testing.T) { } func TestRegisterProviderRefusesConflictingProvider(t *testing.T) { - RegisterProvider(acme(src("one", "acme-test-one"))) + RegisterProvider(acme(src("one", "acme-test"))) defer func() { if recover() == nil { t.Error("a provider registered again with another name didn't panic") } }() - p := acme(src("two", "acme-test-two")) + p := acme(src("two", "acme-test")) p.Name = "Acme Corp" RegisterProvider(p) } + +// A package names its sources. +func TestForPackage(t *testing.T) { + s := src("pkg", "acme-test") + s.Packages = []string{"pypi:acme-test", "npm:@acme/test"} + RegisterProvider(acme(s)) + got := ForPackage("npm:@acme/test") + if len(got) != 1 || got[0].FullID() != "acme-test/pkg" { + t.Errorf("ForPackage = %+v", got) + } + if got := ForPackage("pypi:nobody"); len(got) != 0 { + t.Errorf("ForPackage(pypi:nobody) = %+v", got) + } +} diff --git a/core/plugin/versions.go b/core/plugin/versions.go index 5971490..8daec0e 100644 --- a/core/plugin/versions.go +++ b/core/plugin/versions.go @@ -15,11 +15,12 @@ import ( // result, _ := s.Extract(ctx, env, a, b) // what changed from a to b // // Every consecutive pair is one Extract; a released version never changes, so -// a pair is done once. Run keeps working: it reads the newest version and -// extracts against the last baseline, as before. +// a pair is done once. // -// A source with no versions of its own (a deprecations page, a feed) has only -// Run: patch-it's hosted ingestion service reads it as a living page. +// A living page (a deprecations page, a feed: the notices kind) is also read +// as it is now by Run, which compares it with the last baseline and cites a +// fresh Web Archive snapshot of it; its history is its Web Archive captures, +// listed as versions. // Version is one version of a source. type Version struct { diff --git a/core/versions/versions.go b/core/versions/versions.go index 77ebddf..5cccd3c 100644 --- a/core/versions/versions.go +++ b/core/versions/versions.go @@ -1,7 +1,7 @@ // Package versions lists a source's versions from where they're published: // a GitHub repo's releases, tags or the commits that changed a file, a -// package's releases on PyPI or npm, and the Web Archive's capture of a page -// at a date. Every list comes back oldest first, as plugin.Version. +// package's releases on PyPI or npm, and a living page's captures in the Web +// Archive (every distinct one, or the one closest to a date). Every list comes back oldest first, as plugin.Version. // // Each function takes how to fetch (a plugin's env.Get, or github.Get for the // GitHub API with its token), so tests serve saved responses. @@ -36,6 +36,13 @@ var ( // MaxPages caps how many pages of 100 a GitHub list reads (1,000 entries). const MaxPages = 10 +// GitHubPages reads a GitHub list endpoint (base, with or without a query) +// page by page, 100 at a time, until a short page or MaxPages: for a list +// the functions here don't cover (a release's assets, another host's base). +func GitHubPages[T any](ctx context.Context, get Getter, base string) ([]T, error) { + return pages[T](ctx, get, base) +} + // pages reads a GitHub list endpoint page by page until a short page. func pages[T any](ctx context.Context, get Getter, base string) ([]T, error) { sep := "?" @@ -238,6 +245,63 @@ func WaybackAt(ctx context.Context, get Getter, page string, at time.Time) (plug return plugin.Version{ID: taken.Format(time.DateOnly), Released: taken, Ref: c.URL, URL: c.URL}, nil } +// WaybackCaptures are the versions of a living page (one that only shows its +// newest state: a deprecations page, a feed) as the Web Archive captured it +// between from and to (zero: no bound), oldest first, from its CDX API: one +// version per distinct content, so captures of an unchanged page collapse +// into the first of them, and a page that changes back is a new version. +// Two distinct captures on one day keep the later one: a version's ID is +// its day (YYYY-MM-DD). The Ref is the capture's original bytes +// (web.archive.org/web/id_/), the URL the capture a person +// sees and an event cites. +// +// One request, made with get: the caller's fetch is what spaces requests +// out and names the client (patch-it's hosted ingestion service fetches one +// at a time per host, with its own User-Agent). +func WaybackCaptures(ctx context.Context, get Getter, page string, from, to time.Time) ([]plugin.Version, error) { + q := url.Values{"url": {page}, "output": {"json"}, "fl": {"timestamp,original,digest"}, "filter": {"statuscode:200"}, "collapse": {"digest"}} + if !from.IsZero() { + q.Set("from", from.UTC().Format("20060102150405")) + } + if !to.IsZero() { + q.Set("to", to.UTC().Format("20060102150405")) + } + body, err := get(ctx, Wayback+"/cdx/search/cdx?"+q.Encode()) + if err != nil { + return nil, fmt.Errorf("listing the Web Archive's captures of %s: %w", page, err) + } + var rows [][]string + if len(strings.TrimSpace(string(body))) > 0 { + if err := json.Unmarshal(body, &rows); err != nil { + return nil, fmt.Errorf("parsing the Web Archive's captures of %s: %w", page, err) + } + } + var out []plugin.Version + lastDigest := "" + for i, r := range rows { + if i == 0 || len(r) < 3 { // the header row: ["timestamp","original","digest"] + continue + } + taken, err := time.Parse("20060102150405", r[0]) + if err != nil || r[2] == lastDigest { + continue + } + lastDigest = r[2] + v := plugin.Version{ + ID: taken.Format(time.DateOnly), Released: taken, + Ref: "https://web.archive.org/web/" + r[0] + "id_/" + r[1], + URL: "https://web.archive.org/web/" + r[0] + "/" + r[1], + } + if n := len(out); n > 0 && out[n-1].ID == v.ID { + out[n-1] = v + continue + } + out = append(out, v) + } + slices.SortStableFunc(out, func(a, b plugin.Version) int { return a.Released.Compare(b.Released) }) + return out, nil +} + var ( final = regexp.MustCompile(`^v?\d+(\.\d+)*$`) number = regexp.MustCompile(`\d+`) diff --git a/core/versions/versions_test.go b/core/versions/versions_test.go index ba1981a..5fd20f8 100644 --- a/core/versions/versions_test.go +++ b/core/versions/versions_test.go @@ -168,3 +168,52 @@ func TestCompareFinalMajorPairs(t *testing.T) { t.Errorf("Pairs = %v", ps) } } + +// The CDX API's answer: a header row, then captures oldest first. The same +// content captured again (same digest) is one version; a change back is a +// new one; two distinct captures on one day keep the later. +func TestWaybackCapturesCollapseDuplicates(t *testing.T) { + const page = "https://example.com/deprecations" + cdx := `[["timestamp","original","digest"], +["20250103120000","https://example.com/deprecations","AAA"], +["20250210080000","https://example.com/deprecations","AAA"], +["20250301090000","https://example.com/deprecations","BBB"], +["20250301170000","https://example.com/deprecations","CCC"], +["20250601000000","https://example.com/deprecations","CCC"], +["20251120000000","https://example.com/deprecations","AAA"]]` + var asked string + get := func(_ context.Context, u string) ([]byte, error) { asked = u; return []byte(cdx), nil } + from, to := time.Date(2025, 1, 1, 0, 0, 0, 0, time.UTC), time.Date(2025, 12, 31, 0, 0, 0, 0, time.UTC) + vs, err := WaybackCaptures(context.Background(), get, page, from, to) + if err != nil { + t.Fatal(err) + } + var got []string + for _, v := range vs { + got = append(got, v.ID+" "+v.Ref) + } + want := []string{ + "2025-01-03 https://web.archive.org/web/20250103120000id_/https://example.com/deprecations", + "2025-03-01 https://web.archive.org/web/20250301170000id_/https://example.com/deprecations", + "2025-11-20 https://web.archive.org/web/20251120000000id_/https://example.com/deprecations", + } + if strings.Join(got, "\n") != strings.Join(want, "\n") { + t.Errorf("got\n%s\nwant\n%s", strings.Join(got, "\n"), strings.Join(want, "\n")) + } + for _, p := range []string{"from=20250101000000", "to=20251231000000", "collapse=digest", "filter=statuscode%3A200", "url=https%3A%2F%2Fexample.com%2Fdeprecations"} { + if !strings.Contains(asked, p) { + t.Errorf("asked %s, without %s", asked, p) + } + } + if vs[0].URL != "https://web.archive.org/web/20250103120000/https://example.com/deprecations" { + t.Errorf("URL %s", vs[0].URL) + } +} + +// A page the archive never captured has no versions, and no error. +func TestWaybackCapturesOfAnUncapturedPage(t *testing.T) { + get := func(context.Context, string) ([]byte, error) { return []byte("[]"), nil } + if vs, err := WaybackCaptures(context.Background(), get, "https://example.com/x", time.Time{}, time.Time{}); err != nil || len(vs) != 0 { + t.Errorf("%v %v", vs, err) + } +} diff --git a/docs/how-it-works.md b/docs/how-it-works.md index 9a30707..139265d 100644 --- a/docs/how-it-works.md +++ b/docs/how-it-works.md @@ -1,10 +1,10 @@ # How it works -A **provider** (Stripe, OpenAI, GitHub…) has one category and one or more **sources**: each one place it announces changes (an OpenAPI spec repo, a changelog, a deprecations page, a feed), read by one **kind** of plugin (`plugins//`), at one **layer** of a customer's stack. A source's id is `provider/source` (`stripe/api`, `openai/models`); its old slug (`stripe`, `openai-models`) is what events carry in `api` until patch-it's change-event contract switches to source ids. Every provider and source is registered in code with its metadata (`plugin.RegisterProvider`): that registration is the only list. +A **provider** (Stripe, OpenAI, GitHub…) has one category and one or more **sources**: each one place it announces changes (an OpenAPI spec repo, a changelog, a deprecations page, a feed), read by one **kind** of plugin (`plugins//`), at one **layer** of a customer's stack. A source's id is `provider/source` (`stripe/api`, `openai/models`): what its events carry in `api`. Every provider and source is registered in code with its metadata (`plugin.RegisterProvider`): that registration is the only list. ## What a plugin does -0. **List the versions.** A source with versions (a spec's releases, a package on PyPI or npm, a guide per major) lists every one, oldest first (`ListVersions`, from `core/versions`: GitHub releases, tags and commits, PyPI, npm, the Web Archive at a date). Each consecutive pair is read and compared once (`ReadAt`, `Extract`), so a customer several versions behind gets every step of the upgrade. A living page with no versions (a deprecations page, a feed) is read as it is now; each change to it is a dated version. +0. **List the versions.** A source with versions (a spec's releases, a package on PyPI or npm, a guide per major) lists every one, oldest first (`ListVersions`, from `core/versions`: GitHub releases, tags and commits, PyPI, npm, a living page's Web Archive captures). Each consecutive pair is read and compared once (`ReadAt`, `Extract`), so a customer several versions behind gets every step of the upgrade. A living page with no versions (a deprecations page, a feed) is read as it is now; each change to it is a dated version, and its past ones are its Web Archive captures. 1. **Fetch.** The plugin asks its environment for the source (`env.Get`); it never opens connections itself. Pages that change in place are also cited through a Web Archive snapshot, so the link in an event keeps showing what the plugin read. 2. **Compare.** It compares two versions of the source: two OpenAPI specs, two versions of a deprecations page, a release's changelog section against the release before. `Run` does the newest version against the last one it saw (the baseline); `Extract` does any pair. 3. **Emit events.** Each change becomes one event in [patch-it's change-event format](https://github.com/patch-it-dev/patch-it/tree/main/docs/contract): what changed, how bad it is (breaking, deprecation, behavior change, non-breaking), the date it takes effect, and the source URL with a quote. **No source, no event.** When unsure, a plugin emits nothing: a wrong event would become a wrong pull request. @@ -20,15 +20,14 @@ There's no list in this repo: `make plugins` prints every provider and source fr | Path | What's there | |---|---| | [`core/plugin/`](../core/plugin/) | The `Plugin` interface (`Run`; `ListVersions`, `ReadAt`, `Extract`), the registry of providers and sources (`RegisterProvider`, `Lookup`, `LookupSource`, `Providers`), `Env`, `Result` | -| [`core/versions/`](../core/versions/) | Every version of a source: GitHub releases, tags and commits, PyPI, npm, the Web Archive at a date | -| [`plugins/`](../plugins/) | One package per kind, with its providers; `plugins/all` imports every one | +| [`core/versions/`](../core/versions/) | Every version of a source: GitHub releases, tags and commits, PyPI, npm, a page's Web Archive captures (all, or the one at a date) | +| [`plugins/`](../plugins/) | One package per kind, with its providers (openapi, changelog, notices, migrationguide, catalog, apisurface); `plugins/all` imports every one | | [`cmd/new-plugin/`](../cmd/new-plugin/), [`cmd/list-plugins/`](../cmd/list-plugins/) | The starter for a new provider; the list of providers and sources, printed from the registry | -| [`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/kit/`](../core/kit/), [`core/kit/kittest/`](../core/kit/kittest/), [`core/github/`](../core/github/), [`core/extract/`](../core/extract/) | What plugins share (the unchanged-page check, Wayback citing, the newest release or commit on GitHub, RSS/Atom and HTML text helpers) and the test kit (in-memory store, saved pages, golden files) | +| [`core/event/`](../core/event/) | The change event of [patch-it's contract](https://github.com/patch-it-dev/patch-it/tree/main/docs/contract): its types, fingerprint and validation | | [`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 | +| [`plugins/notices/retire/`](../plugins/notices/retire/), [`plugins/notices/feed/`](../plugins/notices/feed/), [`plugins/notices/eol/`](../plugins/notices/eol/), [`plugins/migrationguide/sdkguide/`](../plugins/migrationguide/sdkguide/), [`plugins/migrationguide/members/`](../plugins/migrationguide/members/), [`core/fetch/`](../core/fetch/) | The notices readers (deprecations pages, feeds, end-of-life tables) and the migration-guide readers (removed parameters, removed members); 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/`](./) | [How to write a plugin](writing-a-plugin.md), the [README template](README-template.md) patch-it's public repos share | diff --git a/docs/plugins.schema.json b/docs/plugins.schema.json index 2033d81..7b1ab8d 100644 --- a/docs/plugins.schema.json +++ b/docs/plugins.schema.json @@ -32,12 +32,12 @@ "type": "array", "items": { "type": "object", - "required": ["id", "alias", "kind", "layer", "watches", "urls", "page"], + "required": ["id", "kind", "layer", "watches", "urls", "packages", "page"], "additionalProperties": false, "properties": { - "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*/[a-z0-9][a-z0-9-]*$", "description": "provider/source" }, - "alias": { "type": "string", "pattern": "^[a-z0-9][a-z0-9.-]*$", "description": "The old slug: --api and every event's api field until patch-it's change-event contract switches to source ids." }, - "kind": { "type": "string", "enum": ["openapi", "retirements", "migrationguide", "removedmembers", "changelog", "feed", "apichangelog", "catalog", "eol"] }, + "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*/[a-z0-9][a-z0-9-]*$", "description": "provider/source: every event's api field." }, + "packages": { "type": "array", "items": { "type": "string", "pattern": "^(pypi|npm|go|maven|nuget|rubygems|cargo|packagist):[^\\s]+$" }, "description": "The published packages this source covers, as ecosystem:name, so a lockfile entry finds its sources." }, + "kind": { "type": "string", "enum": ["openapi", "changelog", "notices", "migrationguide", "catalog", "apisurface"] }, "layer": { "type": "string", "enum": ["api", "sdk", "package", "runtime", "ci", "ai-models", "infra"] }, "watches": { "type": "string", "minLength": 1 }, "urls": { "type": "array", "items": { "type": "string", "pattern": "^https://" } }, diff --git a/docs/which-kind.md b/docs/which-kind.md new file mode 100644 index 0000000..59374d3 --- /dev/null +++ b/docs/which-kind.md @@ -0,0 +1,24 @@ +# Which kind fits my provider? + +A provider has one or more sources: each place it publishes changes. Each source is read by one **kind**. Answer the questions below for one source, top to bottom; the first "yes" is its kind. A provider with several sources (an API spec and an SDK, say) asks them once per source. + +The list of what's already covered isn't here: `make plugins` prints it from the code. + +| Ask | If yes, the kind | It reads | Examples of the shape | +|---|---|---|---| +| Does the provider publish an **OpenAPI spec** of its API, per release or per commit? | `openapi` | Two specs, diffed: removed and renamed operations, parameters, fields; deprecations | A spec repo with release tags; a spec file a repo commits on every change | +| Is there a **guide that lists what a release removed**, one per major or per release, in a table? | `migrationguide` | The guide at the release's tag: removed request parameters (reader `sdk`) or removed members of a module (reader `members`, RST or Markdown tables) | `MIGRATION.md` per major; "removed members" tables in a 2.0 migration guide; an API version removal guide | +| Is there a **changelog**: a file per release (`CHANGELOG.md`, `CHANGES.rst`, `HISTORY.rst`), or a machine-readable JSON changelog? | `changelog` | The release's section at its tag (reader `markdown`), or the life-cycle entries a JSON changelog adds commit by commit (reader `json`) | Keep a Changelog files; reStructuredText release notes; an API changelog JSON in a repo; a Terraform provider's changelog | +| Is there a **live page of dated notices**: a deprecations or shutdown table, an end-of-life table, or an **RSS/Atom feed** of announcements? | `notices` | The page as it is now, cited through a Web Archive snapshot; its past versions are its Web Archive captures (reader `deprecations`, `feed`, or an end-of-life table) | A model deprecations page; an API end-of-life policy table; a changelog feed with a "deprecation" label; a Kubernetes API removals page | +| Is there a **flat catalog**, one JSON entry per name (a command, an endpoint), with no release tags? | `catalog` | Two snapshots, compared for names that disappeared entirely | A list of commands a server accepts, kept in a repo | +| Is it a **published package** with no changelog worth reading? | `apisurface` | Each release's files from the registry (PyPI first), compared: removed or renamed classes, functions, methods, and parameters removed or newly required | An SDK generated from a spec, released often, whose changelog says "chore: update types" | + +Still no "yes"? Open a [discussion](https://github.com/patch-it-dev/patch-it-plugins/discussions) with the source's link: a new kind is a new package under `plugins/`, and the questions above get one more row. + +## Two sources, not one kind + +- **An API and its SDKs are separate sources.** The API's changes come from its spec or its notices; an SDK's from its migration guide, its changelog, or its published files. Register each on its kind, under the same provider. +- **There is no kind per vendor or per tool.** Kubernetes API removals are a `migrationguide` or `notices` source; a Kubernetes client is a package source (`changelog` or `apisurface`); a Terraform provider is a `changelog` source. +- **Prefer the most machine-readable source** (a spec beats a changelog, a changelog beats a feed, a feed beats a blog post): [writing-a-plugin.md, step 2](writing-a-plugin.md#2-pick-the-source). + +Then scaffold it: `make new-plugin ARGS='--provider --source --kind '` ([step 1](writing-a-plugin.md#1-scaffold-it-with-new-plugin)). diff --git a/docs/writing-a-plugin.md b/docs/writing-a-plugin.md index 58aab2b..4a59766 100644 --- a/docs/writing-a-plugin.md +++ b/docs/writing-a-plugin.md @@ -1,28 +1,34 @@ # Writing a plugin -A **provider** (Stripe, OpenAI, Kubernetes…) has a **category** and one or more **sources**. A source is one place the provider announces changes; it is read by one **kind** of plugin (the `plugins/` package: `openapi`, `changelog`, `feed`, …), covers one **layer** (`api`, `sdk`, `package`, `runtime`, `ci`, `ai-models`, `infra`), and has **versions**. Its id is `provider/source` (`stripe/api`, `algolia/search-api`). This guide walks through adding a source, from picking it to the PR. The rules are in [CONTRIBUTING.md](../CONTRIBUTING.md); this is the how-to. How the pieces fit: [how-it-works.md](how-it-works.md). +A **provider** (Stripe, OpenAI, Kubernetes…) has a **category** and one or more **sources**. A source is one place the provider announces changes; it is read by one **kind** of plugin (the `plugins/` package: `openapi`, `changelog`, `notices`, `migrationguide`, `catalog`, `apisurface`), covers one **layer** (`api`, `sdk`, `package`, `runtime`, `ci`, `ai-models`, `infra`), and has **versions**. Its id is `provider/source` (`stripe/api`, `algolia/search-api`). This guide walks through adding a source, from picking it to the PR. The rules are in [CONTRIBUTING.md](../CONTRIBUTING.md); this is the how-to. How the pieces fit: [how-it-works.md](how-it-works.md). -**Most new sources don't need new code.** They are a new entry for an existing kind: a new `changelog.File`, a new `retire.Page`, a new `feed.Feed` reader, a new OpenAPI adapter. Write a new kind only when none of them reads your source. There is no "Kubernetes kind" or "Terraform kind": Kubernetes API removals are a migration-guide or notices source, a client SDK is a package source, a Terraform provider is a changelog source. +**Most new sources don't need new code.** They are a new entry for an existing kind: a new `changelog.File`, a new `retire.Page`, a new `feed.Feed` reader, a new OpenAPI adapter, a new `apisurface.Package`. Write a new kind only when none of them reads your source. There is no "Kubernetes kind" or "Terraform kind": Kubernetes API removals are a migration-guide or notices source, a client SDK is a package source, a Terraform provider is a changelog source. ## 1. Scaffold it with `new-plugin` -Pick the source and the kind that reads it (steps 2 and 3), then let the starter write everything around the provider: +Pick the source and the kind that reads it (steps 2 and 3, and [which kind fits my provider?](which-kind.md)), then let the starter write everything around it: ```sh -go run ./cmd/new-plugin --api acme --provider Acme --format openapi -# --format: openapi, retirements, migrationguide, removedmembers, changelog, feed, apichangelog, catalog -# optional: --source https://... (the provider's source), --watches "...", --layer api|sdk|package|runtime|ci|ai-models|infra, -# --page acme (a second source of a provider shares its page in providers/) +make new-plugin ARGS='--provider acme --name Acme --category devtools --homepage https://acme.example \ + --source api --kind openapi --url https://github.com/acme/openapi --package pypi:acme --package npm:acme' +# the same: go run ./cmd/new-plugin --provider acme ... +# --kind: openapi, changelog, notices, migrationguide, catalog, apisurface +# --reader, for a kind with several: changelog markdown|json, notices deprecations|feed, migrationguide sdk|members +# optional: --layer api|sdk|package|runtime|ci|ai-models|infra (default: the kind's), --watches "...", +# --page acme (share an existing providers/ page; default -) ``` +Run in a terminal without the flags, it asks for them: the provider's id, then (for a new provider) its name, category and homepage, then the source's id, kind, reader, layer, URLs, packages and what it watches. A second source of a registered provider needs only `--provider`, `--source` and `--kind`: the name, category and homepage come from the registry. One run adds one source; run it again for the next. + It writes, and lists: -- 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.RegisterProvider` block (the provider and the source with their metadata) 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; +- the source's definition in the package its kind reads it from (`plugins/openapi/adapter/`, `plugins/notices/retire/`, `plugins/notices/feed/`, `plugins/migrationguide/sdkguide/`, `plugins/migrationguide/members/` or `plugins//`), with the version wiring the kind needs from it: an OpenAPI adapter's `LatestTag`, `Fetch` and `Versions` to write; every other kind lists, reads and extracts versions itself; +- its `plugin.RegisterProvider` block (the provider and the source with every metadata field, packages included) in the kind's `init`, and the kind's import in `plugins/all` if it's a new kind; +- `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); +- `providers/-.md` from the template (or nothing, with `--page`, when the provider already has one); -`go test ./...` passes right after; every place to fill in says `TODO(new-plugin)` (`grep -rn 'TODO(new-plugin)' .`), and `make check` (its `todos` step, also in CI_go) fails until none is left. It refuses an id that's taken (registered, or a file it would write exists) and then changes nothing. The steps below are what you fill in. +`go test ./...` passes right after; every place to fill in says `TODO(new-plugin)` (`grep -rn 'TODO(new-plugin)' .`), and `make check` (its `todos` step, also in CI_go) fails until none is left. It refuses a `provider/source` id that's taken, or a file it would write that exists, and then changes nothing. ## 2. Pick the source @@ -72,17 +78,16 @@ Write the numbers on the provider page, as `providers/vercel.md` does for its sp ## 3. Pick the kind +[Which kind fits my provider?](which-kind.md) asks the questions; the table says what each kind reads. + | Kind | Reads | Add a source by | |---|---|---| | `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; `Versions` to list every release) and a `plugin.RegisterProvider` block | -| `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 the tag of each new major (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`, each release's section at its tag (releases from PyPI or npm) | A `changelog.File` with its `TagPrefix` | -| `plugins/feed` | An RSS or Atom feed | A `feed.Feed` with a reader for that vendor's entries | +| `plugins/notices` | A live page of dated notices: a model provider's deprecations page (a table of date, model, replacement), a vendor's RSS or Atom feed, a vendor's table of whole API version ranges and their support status | A `retire.Page` in `plugins/notices/retire/providers.go`, a `feed.Feed` with a reader for that vendor's entries in `plugins/notices/feed/`, or an `eol.Page` in `plugins/notices/eol/` (`new-plugin` doesn't scaffold this reader yet) | +| `plugins/migrationguide` | A guide that lists what a release removed, at the release's tag: an SDK's migration guide per new major (removed request parameters), or a package's table of removed members (an RST simple table or a Markdown pipe table) | A `sdkguide.Guide` in `plugins/migrationguide/sdkguide/`, or a `members.Guide` in `plugins/migrationguide/members/` | +| `plugins/changelog` | A changelog: a `CHANGELOG.md` / `CHANGES.rst` / `HISTORY.rst`, each release's section at its tag (releases from PyPI or npm), or a vendor's machine-readable API changelog in JSON (per day, endpoint and API version, oasdiff change codes), commit by commit | A `changelog.File` with its `TagPrefix`, or a `changelog.Log` | | `plugins/catalog` | A flat JSON catalog, one entry per name, with no release tags to pin — a commit SHA stands in | A `catalog.Catalog`, diffed between two snapshots for names that disappeared entirely | -| `plugins/apichangelog` | A vendor's machine-readable API changelog in JSON (per day, endpoint and API version, oasdiff change codes), at the commit that last changed it | An `apichangelog.Log` | -| `plugins/eol` | A vendor's own table of whole API version ranges and their support status (supported, deprecated, retired) | An `eol.Page`; `--format` doesn't scaffold this one yet, write it by hand | +| `plugins/apisurface` | A published package's public API, compared between two releases: the classes, functions, methods and parameters in each release's files (Python first: the wheel or sdist from PyPI) | A `apisurface.Package` (registry name, ecosystem, top-level module) and its `plugin.RegisterProvider` block | ## 4. The interface @@ -90,7 +95,7 @@ A plugin implements `plugin.Plugin` (package [`core/plugin/`](../core/plugin/plu ```go type Plugin interface { - Name() string // the source's old slug: --api and every event's `api` + Name() string // the source's id, provider/source: every event's `api` Run(ctx context.Context, env Env) (Result, error) // the newest version against the baseline it saved last } @@ -102,7 +107,7 @@ type Env struct { type Result struct { Label string // what was read, for the run summary - Events []event.EventV2 // valid events + Events []event.Event // valid events Rejected []error // changes that failed to become valid events Baselines []Spec // what was read, saved after the events } @@ -120,12 +125,19 @@ ReadAt(ctx, env, v Version) (Snapshot, error) // the source at o Extract(ctx, env, from, to Snapshot) (Result, error) // the changes from one to the next ``` -- **List** with [`core/versions`](../core/versions/versions.go): `GitHubReleases`, `GitHubTags`, `GitHubCommits` (the commits that changed a file), `PyPIReleases`, `NPMReleases`, `WaybackAt` (a page as it was on a date). Never pin a tag in code: a version you need for a golden test is a pinned *case* in the test (`changelog.Urllib3.At("2.0.0")`), not the registered source. +- **List** with [`core/versions`](../core/versions/versions.go): `GitHubReleases`, `GitHubTags`, `GitHubCommits` (the commits that changed a file), `PyPIReleases`, `NPMReleases`, `WaybackCaptures` (every distinct Web Archive capture of a living page, dated), `WaybackAt` (a page as it was on a date), `GitHubPages` (any other GitHub list, page by page). An OpenAPI adapter lists its own versions (`adapter.Lister`): every adapter does. Never pin a tag in code: a version you need for a golden test is a pinned *case* in the test (`changelog.Urllib3.At("2.0.0")`), not the registered source. - **Read at** a version's `Ref` (a tag, a commit SHA, an archive URL) and return the exact URL read as the snapshot's `SourceURL`: it's the events' citation. - **Extract** sets `previous_version` to `from`'s version; `from` may be zero (nothing before). It returns no baselines. - `Run` is built from the same parts: the newest version, extracted against the last baseline. +- Test a version pair with `kittest.Pair(ctx, env, sink, plugin, from, to)`: both versions read, the change extracted, its events stored. + +A living page with no versions of its own (a deprecations page, a feed: a `notices` source) is read as it is now by `Run`, and each change to it is a dated version. Its history comes from the Web Archive: the `notices` kind lists every distinct capture (`WaybackCaptures`), reads each, and extracts what each one added, citing that capture, so a year of it can be backfilled by date with no stored copies. -A living page with no versions of its own (a deprecations page, a feed) only has `Run`: it's read as it is now, and each change to it is a dated version. +### The `apisurface` kind: reading a package's API without running it + +`plugins/apisurface` downloads a release's wheel (or sdist) through `env.Get`, opens it in memory (`archive/zip`, `archive/tar`: nothing is written to disk) and hands the `.py` and `.pyi` files to `plugins/apisurface/pysurface`, which reads them as text: logical lines, indentation, and the headers of `def`, `class`, `__all__` and `from … import`. Nothing in the package is imported, compiled or run. That's the safest way to read code someone else publishes, and it needs no dependency: a Python interpreter (the `ast` module) would mean running a second runtime next to the plugins, and the pure-Go Python parsers available follow old grammars and pull in a large module for what is a few hundred lines here. The cost is that only signatures are read, never what a body does, and anything the reader can't be sure of is left out (see `providers/openai-python-sdk.md`). Archive and file sizes are capped (`MaxFileBytes`, `MaxSourceBytes`), so a crafted release can't exhaust the runner. + +An event cites the newer release's file, and its excerpt quotes the definition's path and line in both releases. npm packages (`.d.ts` files) are next. ### Register the provider and its source @@ -139,30 +151,32 @@ func init() { ID: "urllib3", Layer: plugin.LayerPackage, Page: "providers/urllib3.md", Watches: "Names removed or deprecated in each release, …", URLs: []string{"https://github.com/urllib3/urllib3/blob/main/CHANGES.rst"}, + Packages: []string{"pypi:urllib3"}, Plugin: Plugin{File: Urllib3}, }}, }) } ``` -`RegisterProvider` panics on missing metadata, a duplicate id, or a provider registered twice with a different name, category or homepage (a provider with sources in two kinds repeats the same ones). `plugin.Lookup` and `plugin.LookupSource` find a source by `provider/source` or by its old slug. +`RegisterProvider` panics on missing metadata, a duplicate id, or a provider registered twice with a different name, category or homepage (a provider with sources in two kinds repeats the same ones). `plugin.Lookup` and `plugin.LookupSource` find a source by its id, `provider/source`. The plugin's `Name` is that id: what every event carries in `api`, and what the fingerprint hashes. + +`Packages` are the published packages the source covers, `:` (`pypi:stripe`, `npm:@vercel/sdk`): the package itself for a package or SDK source, the provider's official SDKs for an API source. `plugin.ForPackage` finds a package's sources, so a customer's lockfile maps to sources with no table kept anywhere else. List only names you checked; none is fine. ### 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 `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 `Run` returns. +- `plugin.Baseline(api, version, tag, sourceURL, content, now)`: the baseline `Run` returns. - `github.LatestRelease`, `github.LatestCommit`, `github.Commit`, `github.Head` ([`core/github`](../core/github/github.go)): the newest release or commit on GitHub, one place; don't decode GitHub's responses yourself. -- Older kinds build v1 `event.ChangeEvent`s and convert them with `migrate.Fresh`; new code builds `event.EventV2` directly. ### Events -The event format is [patch-it's change-event contract](https://github.com/patch-it-dev/patch-it/tree/main/docs/contract); `core/event/` is its Go binding. Every event has a typed `subject` (`api_operation`, `model`, `package_release`, `ci_runtime`), a `change_type` (`breaking`, `deprecation`, …), a `version`, a `fingerprint` (`event.FingerprintV2`), and **a `source_url` and `source_excerpt`: no source, no event**. Call `Validate()`; an invalid event goes in `Result.Rejected`, not `Events`. +The event format is [patch-it's change-event contract](https://github.com/patch-it-dev/patch-it/tree/main/docs/contract); `core/event/` is its Go binding. Every event has a typed `subject` (`api_operation`, `model`, `package_release`, `ci_runtime`), a `change_type` (`breaking`, `deprecation`, …), a `version`, a `fingerprint` (`event.Fingerprint`), and **a `source_url` and `source_excerpt`: no source, no event**. Call `Validate()`; an invalid event goes in `Result.Rejected`, not `Events`. ## 5. Save the source -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. +Save a real copy of what the plugin reads under your package's `testdata/` (or the reader package's, like `plugins/notices/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. diff --git a/event/event.go b/event/event.go deleted file mode 100644 index 02bec52..0000000 --- a/event/event.go +++ /dev/null @@ -1,50 +0,0 @@ -// 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 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 ( - 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 = 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 -) - -// 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 -) diff --git a/fetch/fetch.go b/fetch/fetch.go deleted file mode 100644 index 8d79a32..0000000 --- a/fetch/fetch.go +++ /dev/null @@ -1,19 +0,0 @@ -// 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 moved "github.com/patch-it-dev/patch-it-plugins/core/fetch" - -// Deprecated: the types live in github.com/patch-it-dev/patch-it-plugins/core/fetch. -type ( - Cache = moved.Cache - StatusError = moved.StatusError -) - -// 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 e9a9aa8..bde7fda 100644 --- a/internal/pluginlist/pluginlist.go +++ b/internal/pluginlist/pluginlist.go @@ -38,13 +38,13 @@ type Provider struct { // Source is one source. type Source struct { - ID string `json:"id"` // provider/source - Alias string `json:"alias"` // the old slug: --api and every event's api until the contract switches to source ids - Kind string `json:"kind"` - Layer string `json:"layer"` - Watches string `json:"watches"` - URLs []string `json:"urls"` - Page string `json:"page"` // absolute, at Version + ID string `json:"id"` // provider/source: every event's api + Kind string `json:"kind"` + Layer string `json:"layer"` + Watches string `json:"watches"` + URLs []string `json:"urls"` + Packages []string `json:"packages"` // ":"; [] when none + Page string `json:"page"` // absolute, at Version } // Build is the list of everything registered, with pages linked at ref (a @@ -64,9 +64,11 @@ func Build(ref string) File { for _, p := range plugin.Providers() { out := Provider{ID: p.ID, Name: p.Name, Category: string(p.Category), Homepage: p.Homepage} for _, s := range p.Sources { + info := plugin.SourceInfo{Provider: p, Source: s} out.Sources = append(out.Sources, Source{ - ID: p.ID + "/" + s.ID, Alias: s.Plugin.Name(), Kind: s.Kind, Layer: string(s.Layer), - Watches: s.Watches, URLs: s.URLs, Page: Repo + "/blob/" + ref + "/" + s.Page, + ID: info.FullID(), + Kind: s.Kind, Layer: string(s.Layer), Watches: s.Watches, URLs: s.URLs, + Packages: append([]string{}, s.Packages...), Page: Repo + "/blob/" + ref + "/" + s.Page, }) } f.Sources += len(out.Sources) diff --git a/internal/pluginlist/pluginlist_test.go b/internal/pluginlist/pluginlist_test.go index 21dfb84..6138134 100644 --- a/internal/pluginlist/pluginlist_test.go +++ b/internal/pluginlist/pluginlist_test.go @@ -12,7 +12,7 @@ import ( const root = "../.." // The list is the registry: every registered source once, under its provider, -// with its old slug, and the counts agree. +// once, and the counts agree. func TestBuildListsEveryRegisteredSource(t *testing.T) { f := Build("") if f.Version != "main" { @@ -29,7 +29,7 @@ func TestBuildListsEveryRegisteredSource(t *testing.T) { if !strings.HasPrefix(s.Page, Repo+"/blob/main/providers/") { t.Errorf("%s: page %s", s.ID, s.Page) } - seen[s.Alias] = true + seen[s.ID] = true } } if n != f.Sources || len(f.List) != f.Providers || n != len(plugin.Sources()) { @@ -58,12 +58,12 @@ func TestAlgoliaIsOneProviderWithThreeSources(t *testing.T) { } var ids []string for _, s := range p.Sources { - ids = append(ids, s.ID+"="+s.Alias) + ids = append(ids, s.ID) if !strings.Contains(s.Page, "/blob/v1.2.3/") { t.Errorf("%s: page %s isn't at the release", s.ID, s.Page) } } - if got := strings.Join(ids, " "); got != "algolia/ingestion-api=algolia-ingestion algolia/recommend-api=algolia-recommend algolia/search-api=algolia-search" { + if got := strings.Join(ids, " "); got != "algolia/ingestion-api algolia/recommend-api algolia/search-api" { t.Errorf("algolia's sources: %s", got) } return diff --git a/kit/kit.go b/kit/kit.go deleted file mode 100644 index 5575062..0000000 --- a/kit/kit.go +++ /dev/null @@ -1,30 +0,0 @@ -// Package kit is the old import path of github.com/patch-it-dev/patch-it-plugins/core/kit. -// -// 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" - - moved "github.com/patch-it-dev/patch-it-plugins/core/kit" -) - -// Deprecated: the types live in github.com/patch-it-dev/patch-it-plugins/core/kit. -type ( - Archiver = moved.Archiver - Wayback = moved.Wayback -) - -// 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) { - return moved.Cite(ctx, a, pageURL, read, want) -} diff --git a/kit/kittest/kittest.go b/kit/kittest/kittest.go deleted file mode 100644 index 39f0e4e..0000000 --- a/kit/kittest/kittest.go +++ /dev/null @@ -1,33 +0,0 @@ -// Package kittest is the old import path of github.com/patch-it-dev/patch-it-plugins/core/kit/kittest. -// -// 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 moved "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" - -// 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 -) - -// 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 deleted file mode 100644 index cf6865d..0000000 --- a/migrate/migrate.go +++ /dev/null @@ -1,14 +0,0 @@ -// Package migrate is the old import path of github.com/patch-it-dev/patch-it-plugins/core/migrate. -// -// 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 moved "github.com/patch-it-dev/patch-it-plugins/core/migrate" - -// Deprecated: the functions and values live in github.com/patch-it-dev/patch-it-plugins/core/migrate. -var ( - Fresh = moved.Fresh - ToV2 = moved.ToV2 -) diff --git a/plugin/plugin.go b/plugin/plugin.go deleted file mode 100644 index 4b0fb6e..0000000 --- a/plugin/plugin.go +++ /dev/null @@ -1,27 +0,0 @@ -// 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 moved "github.com/patch-it-dev/patch-it-plugins/core/plugin" - -// 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 -) - -// Deprecated: the functions and values live in github.com/patch-it-dev/patch-it-plugins/core/plugin. -var ( - Baseline = moved.Baseline - Lookup = moved.Lookup - Names = moved.Names - Register = moved.Register - SHA256 = moved.SHA256 -) diff --git a/plugins/all/all.go b/plugins/all/all.go index 7ca6527..051a892 100644 --- a/plugins/all/all.go +++ b/plugins/all/all.go @@ -4,13 +4,10 @@ package all import ( - _ "github.com/patch-it-dev/patch-it-plugins/plugins/apichangelog" + _ "github.com/patch-it-dev/patch-it-plugins/plugins/apisurface" _ "github.com/patch-it-dev/patch-it-plugins/plugins/catalog" _ "github.com/patch-it-dev/patch-it-plugins/plugins/changelog" - _ "github.com/patch-it-dev/patch-it-plugins/plugins/eol" - _ "github.com/patch-it-dev/patch-it-plugins/plugins/feed" _ "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide" + _ "github.com/patch-it-dev/patch-it-plugins/plugins/notices" _ "github.com/patch-it-dev/patch-it-plugins/plugins/openapi" - _ "github.com/patch-it-dev/patch-it-plugins/plugins/removedmembers" - _ "github.com/patch-it-dev/patch-it-plugins/plugins/retirements" ) diff --git a/plugins/all/all_test.go b/plugins/all/all_test.go index e4402a0..27cbde5 100644 --- a/plugins/all/all_test.go +++ b/plugins/all/all_test.go @@ -1,8 +1,10 @@ package all import ( + "go/ast" "go/parser" "go/token" + "io/fs" "os" "path/filepath" "slices" @@ -78,29 +80,107 @@ func TestImportingAllRegistersThePlugins(t *testing.T) { } } -// Every registered plugin is a source with complete metadata (RegisterProvider -// checks the fields), reachable by its full id and its old slug, and its page -// exists. -func TestEveryPluginIsASourceWithMetadata(t *testing.T) { - covered := map[string]bool{} +// Every registered source has complete metadata (RegisterProvider checks the +// fields), is found by its id, and its page exists. +func TestEverySourceHasMetadata(t *testing.T) { for _, s := range plugin.Sources() { - covered[s.Alias()] = true if _, err := os.Stat(filepath.Join("..", "..", s.Source.Page)); err != nil { t.Errorf("%s: its page %s doesn't exist (copy providers/_template.md)", s.FullID(), s.Source.Page) } - for _, id := range []string{s.FullID(), s.Alias()} { - got, ok := plugin.LookupSource(id) - if !ok || got.FullID() != s.FullID() { - t.Errorf("LookupSource(%q) = %q, %v; want %s", id, got.FullID(), ok, s.FullID()) - } - if p, ok := plugin.Lookup(id); !ok || p.Name() != s.Alias() { - t.Errorf("Lookup(%q) didn't find %s", id, s.Alias()) + if p, ok := plugin.Lookup(s.FullID()); !ok || p.Name() != s.FullID() { + t.Errorf("Lookup(%q) didn't find it", s.FullID()) + } + } + if len(plugin.Names()) != len(plugin.Sources()) { + t.Errorf("%d plugins, %d sources", len(plugin.Names()), len(plugin.Sources())) + } +} + +// Every registered source's kind is an answer of docs/which-kind.md, so the +// guide sends every source somewhere. +func TestWhichKindNamesEveryKind(t *testing.T) { + guide, err := os.ReadFile("../../docs/which-kind.md") + if err != nil { + t.Fatal(err) + } + for _, s := range plugin.Sources() { + if !strings.Contains(string(guide), "| `"+s.Source.Kind+"` |") { + t.Errorf("%s's kind, %s, isn't an answer in docs/which-kind.md", s.FullID(), s.Source.Kind) + } + } +} + +// Every package under plugins/ is a kind that registers its sources, or a +// reader package inside one (plugins///); and none only +// forwards to another package (type aliases and re-exported values, no code +// of its own). +func TestEveryPackageIsAKindOrPartOfOne(t *testing.T) { + dirs, err := os.ReadDir("..") + if err != nil { + t.Fatal(err) + } + for _, d := range dirs { + if d.IsDir() && d.Name() != "all" && !registers(t, filepath.Join("..", d.Name())) { + t.Errorf("plugins/%s registers no source: a kind registers its sources, a reader lives inside its kind", d.Name()) + } + } + err = filepath.WalkDir("..", func(p string, d fs.DirEntry, err error) error { + if err != nil || !d.IsDir() || d.Name() == "testdata" { + if d != nil && d.IsDir() && d.Name() == "testdata" { + return filepath.SkipDir } + return err + } + if forwardsOnly(t, p) { + t.Errorf("%s only forwards to another package: import that package instead", p) } + return nil + }) + if err != nil { + t.Fatal(err) + } +} + +// forwardsOnly reports whether a package's non-test code is nothing but type +// aliases and values copied from other packages. +func forwardsOnly(t *testing.T, dir string) bool { + t.Helper() + files, err := filepath.Glob(filepath.Join(dir, "*.go")) + if err != nil { + t.Fatal(err) } - for _, name := range plugin.Names() { - if !covered[name] { - t.Errorf("%s is registered with plugin.Register only: register it as a source of its provider (plugin.RegisterProvider) with its metadata", name) + decls := 0 + for _, f := range files { + if strings.HasSuffix(f, "_test.go") { + continue + } + file, err := parser.ParseFile(token.NewFileSet(), f, nil, 0) + if err != nil { + t.Fatal(err) + } + for _, decl := range file.Decls { + g, ok := decl.(*ast.GenDecl) + if !ok { + return false // a func: code of its own + } + for _, spec := range g.Specs { + switch s := spec.(type) { + case *ast.ImportSpec: + continue + case *ast.TypeSpec: + if !s.Assign.IsValid() { + return false + } + case *ast.ValueSpec: + for _, v := range s.Values { + if _, sel := v.(*ast.SelectorExpr); !sel { + return false + } + } + } + decls++ + } } } + return decls > 0 } diff --git a/plugins/apichangelog/testdata/README.md b/plugins/apichangelog/testdata/README.md deleted file mode 100644 index 30f2a0a..0000000 --- a/plugins/apichangelog/testdata/README.md +++ /dev/null @@ -1,9 +0,0 @@ -# Saved changelogs - -| File | URL | Saved | License | Quote | -|---|---|---|---|---| -| `mongodb-atlas-changelog-c0f99ca9.json` | https://raw.githubusercontent.com/mongodb/openapi/c0f99ca9145e5aa74d08ae4451020857e93b5f28/changelog/changelog.json (the "Release API Changelog" commit of 2026-11-18 20:15 UTC; the same file as `main` on 2026-11-19) | 2026-11-19 | Apache-2.0 (mongodb/openapi) | "endpoint with API Version '2023-01-01' was removed as it has reached its sunset date '2026-01-22'" | -| `mongodb-atlas-changelog-2026-11-18-day.json` | The same file's newest day (`2026-11-18`), kept whole and unchanged: the drop test | 2026-11-19 | Apache-2.0 (mongodb/openapi) | `"changeCode": "request-property-one-of-removed"`, `"backwardCompatible": false` | -| `commits-c0f99ca9.json`, `commits-day.json` | Stand-ins for `https://api.github.com/repos/mongodb/openapi/commits?path=changelog/changelog.json&per_page=1`, keeping only the field the plugin reads (`sha`) | 2026-11-19 | n/a (test fixtures) | | - -**Trimmed, positions kept:** the real file is 10 MB. `mongodb-atlas-changelog-c0f99ca9.json` keeps every day, endpoint, API version and change in place. Every change the plugin doesn't read is replaced by `{}`: all but the three life-cycle codes and `endpoint-reactivated`. So is every endpoint or version left with none. So every JSON pointer in `golden/mongodb-atlas.json` names the same change in the real file. The 105 kept changes are copied unchanged. The plugin reads exactly the same 81 findings from this copy as from the real file (checked when the copy was made). The copy is re-indented. diff --git a/plugins/apisurface/apisurface.go b/plugins/apisurface/apisurface.go new file mode 100644 index 0000000..1894165 --- /dev/null +++ b/plugins/apisurface/apisurface.go @@ -0,0 +1,421 @@ +// Package apisurface is the kind for a published package with no changelog +// worth reading: its public API is compared between two releases, read from +// the released files themselves. A class, function or method that is gone, +// or renamed, a parameter that is gone, or one that lost its default (callers +// must now pass it), is an event. +// +// Python first: every release on PyPI (ListVersions), the release's wheel +// (or sdist) read without running any of it (ReadAt: pysurface/ reads the +// .py and .pyi files as text), and the two surfaces compared (Extract). Each +// event cites the release file and quotes the definition's file and line in +// both releases. npm (.d.ts) is a follow-up. +// +// What isn't read, on purpose (precision over recall): private names (a +// leading underscore, a private module, a name left out of __all__), +// classes nested in classes, overloaded functions' parameters, a removed +// parameter when the function now takes **kwargs (passing it still works), +// and a parameter newly added without a default (patch-it's change-event +// contract has no subject for it yet: logged). +package apisurface + +import ( + "context" + "encoding/json" + "fmt" + "log" + "slices" + "strings" + "time" + + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" + "github.com/patch-it-dev/patch-it-plugins/core/versions" + "github.com/patch-it-dev/patch-it-plugins/plugins/apisurface/pysurface" +) + +func init() { + plugin.RegisterProvider(plugin.Provider{ + ID: "openai", Name: "OpenAI", Category: plugin.CategoryAI, Homepage: "https://openai.com", + Sources: []plugin.Source{{ + ID: "python-sdk", Layer: plugin.LayerSDK, Page: "providers/openai-python-sdk.md", + Watches: "Classes, functions, methods and parameters removed or renamed in the public API of the openai Python package, release by release, read from each release's wheel", + URLs: []string{"https://pypi.org/project/openai/", "https://github.com/openai/openai-python"}, + Packages: []string{"pypi:openai"}, + Plugin: Plugin{Package: OpenAIPython}, + }}, + }) +} + +// Package is one published package. +type Package struct { + ID string // the source id the events carry: "openai/python-sdk" + Name string // on the registry: "openai" + Ecosystem string // "pypi" + Module string // the top-level import name: "openai" +} + +// OpenAIPython is the openai package on PyPI. +var OpenAIPython = Package{ID: "openai/python-sdk", Name: "openai", Ecosystem: "pypi", Module: "openai"} + +// Plugin reads one package's releases. +type Plugin struct { + Package Package +} + +func (p Plugin) Name() string { return p.Package.ID } + +// Run reads the newest release and extracts it against the last one read +// (the baseline), or against nothing on a first run: the surface it stores +// as the baseline. +func (p Plugin) Run(ctx context.Context, env plugin.Env) (plugin.Result, error) { + vs, err := p.ListVersions(ctx, env) + if err != nil { + return plugin.Result{}, err + } + if len(vs) == 0 { + return plugin.Result{}, fmt.Errorf("%s: no release listed", p.Package.Name) + } + v := vs[len(vs)-1] + last, err := env.Baselines.LastSpec(p.Package.ID) + if err != nil { + return plugin.Result{}, fmt.Errorf("loading the last baseline of %s: %w", p.Package.Name, err) + } + if last != nil && last.Version == v.ID { + log.Printf("%s: no new release since %s", p.Package.Name, v.ID) + return plugin.Result{}, nil + } + to, err := p.ReadAt(ctx, env, v) + if err != nil { + return plugin.Result{}, err + } + var from plugin.Snapshot + if last != nil { + from = plugin.Snapshot{Version: plugin.Version{ID: last.Version, Ref: last.Tag}, Content: last.Content, SourceURL: last.SourceURL} + } + res, err := p.Extract(ctx, env, from, to) + if err != nil { + return plugin.Result{}, err + } + res.Baselines = []plugin.Spec{plugin.Baseline(p.Package.ID, v.ID, v.Ref, to.SourceURL, to.Content, env.Now().UTC())} + return res, nil +} + +// ListVersions is every final release on the registry, oldest first. +func (p Plugin) ListVersions(ctx context.Context, env plugin.Env) ([]plugin.Version, error) { + switch p.Package.Ecosystem { + case "pypi": + return versions.PyPIReleases(ctx, env.Get, p.Package.Name) + default: + return nil, fmt.Errorf("%s: reading a %q package's API isn't supported yet", p.Package.Name, p.Package.Ecosystem) + } +} + +// Release is what ReadAt keeps of a release: its public surface, the +// classes a method could move to, and what couldn't be read. +type Release struct { + Artifact string `json:"artifact"` + Surface pysurface.Surface `json:"surface"` + Classes pysurface.Classes `json:"classes,omitempty"` + Skipped []string `json:"skipped,omitempty"` // files over the size limit +} + +// ReadAt downloads the release's wheel (or sdist) and reads its public +// surface. The snapshot's content is the surface as JSON, its SourceURL the +// file read. +func (p Plugin) ReadAt(ctx context.Context, env plugin.Env, v plugin.Version) (plugin.Snapshot, error) { + pkg := p.Package + a, err := pickArtifact(ctx, env, pkg.Name, v.ID) + if err != nil { + return plugin.Snapshot{}, err + } + body, err := env.Get(ctx, a.URL) + if err != nil { + return plugin.Snapshot{}, fmt.Errorf("fetching %s: %w", a.URL, err) + } + files, skipped, err := sourceFiles(a, body, pkg.Module) + if err != nil { + return plugin.Snapshot{}, err + } + if len(files) == 0 { + return plugin.Snapshot{}, fmt.Errorf("%s has no %s/ source files", a.Filename, pkg.Module) + } + for _, s := range skipped { + log.Printf("%s %s: %s skipped: over %d bytes", pkg.Name, v.ID, s, MaxFileBytes) + } + content, err := json.Marshal(Release{Artifact: a.Filename, Surface: pysurface.Read(files), Classes: pysurface.ReadClasses(files), Skipped: skipped}) + if err != nil { + return plugin.Snapshot{}, err + } + return plugin.Snapshot{Version: v, Content: content, SourceURL: a.URL}, nil +} + +// Extract compares from's surface with to's: an event per class, function or +// method gone or renamed, and per parameter gone or now required, with to's +// version and from's as previous_version. A zero from has nothing to compare: +// no events. +func (p Plugin) Extract(_ context.Context, env plugin.Env, from, to plugin.Snapshot) (plugin.Result, error) { + if from.IsZero() { + return plugin.Result{Label: to.Version.ID}, nil + } + var a, b Release + if err := json.Unmarshal(from.Content, &a); err != nil { + return plugin.Result{}, fmt.Errorf("reading the %s %s surface: %w", p.Package.Name, from.Version.ID, err) + } + if err := json.Unmarshal(to.Content, &b); err != nil { + return plugin.Result{}, fmt.Errorf("reading the %s %s surface: %w", p.Package.Name, to.Version.ID, err) + } + now := env.Now().UTC() + var events []event.Event + var rejected []error + for _, c := range Compare(a, b) { + if c.Change == "" { + log.Printf("%s %s: not an event: %s", p.Package.Name, to.Version.ID, c.Note) + continue + } + e := p.event(c, from, to, a.Artifact, b.Artifact, now) + e.Fingerprint = event.Fingerprint(e.API, e.Version, e.ChangeType, e.Subject, "") + if err := e.Validate(); err != nil { + rejected = append(rejected, fmt.Errorf("%s %s %s: %w", p.Package.Name, to.Version.ID, c.Symbol, err)) + continue + } + events = append(events, e) + } + return plugin.Result{Label: to.SourceURL, Events: events, Rejected: rejected}, nil +} + +var _ plugin.Versioned = Plugin{} + +// event is one change as a change event. +func (p Plugin) event(c Change, from, to plugin.Snapshot, fromFile, toFile string, now time.Time) event.Event { + pkg := p.Package + sym := p.local(c.Symbol) + subject := event.Subject{Type: event.SubjectPackageRelease, Ecosystem: pkg.Ecosystem, Package: pkg.Name, Change: c.Change, Symbols: []string{sym}} + var desc, hint string + switch c.Change { + case event.PackageRenamedSymbol: + subject.Replacement = p.local(c.Replacement) + desc = fmt.Sprintf("`%s` was renamed to `%s` in %s %s: code using the old name fails.", sym, subject.Replacement, pkg.Name, to.Version.ID) + hint = fmt.Sprintf("Use `%s`, with the same parameters.", subject.Replacement) + case event.PackageRemovedSymbol: + desc = fmt.Sprintf("The %s `%s` was removed in %s %s: code using it fails.", c.Kind, sym, pkg.Name, to.Version.ID) + hint = fmt.Sprintf("%s %s has no `%s`: see the package's release notes for what replaces it.", pkg.Name, to.Version.ID, sym) + case event.PackageRemovedParameter: + subject.Parameter = c.Parameter + desc = fmt.Sprintf("`%s` no longer takes the parameter `%s` in %s %s: passing it raises a TypeError.", sym, c.Parameter, pkg.Name, to.Version.ID) + hint = fmt.Sprintf("Stop passing `%s` to `%s`; its signature in %s is quoted in the source excerpt.", c.Parameter, sym, to.Version.ID) + case event.PackageChangedDefault: + subject.Parameter = c.Parameter + desc = fmt.Sprintf("`%s`'s parameter `%s` has no default in %s %s (it was `%s`): a call that leaves it out raises a TypeError.", sym, c.Parameter, pkg.Name, to.Version.ID, c.OldDefault) + hint = fmt.Sprintf("Pass `%s=%s` to `%s` to keep the old behavior.", c.Parameter, c.OldDefault, sym) + } + return event.Event{ + API: pkg.ID, + Version: to.Version.ID, + PreviousVersion: from.Version.ID, + ChangeType: event.ChangeTypeBreaking, + Breaking: true, + Subject: subject, + Description: desc, + MigrationHint: hint, + SourceURL: to.SourceURL, + SourceExcerpt: cap2000(excerpt(pkg.Name, from.Version.ID, fromFile, c.Before) + "\n" + excerpt(pkg.Name, to.Version.ID, toFile, c.After)), + Confidence: 1.0, + DetectedAt: now, + } +} + +// local is a symbol as code writes it after importing the package: +// "openai.OpenAI.with_options" is "OpenAI.with_options". +func (p Plugin) local(sym string) string { return strings.TrimPrefix(sym, p.Package.Module+".") } + +// excerpt quotes one release's definition: "openai 1.0.0, openai/_client.py +// line 12: def create(...)", or that the release has none. +func excerpt(pkg, version, file string, s *pysurface.Symbol) string { + if s == nil { + return fmt.Sprintf("%s %s (%s): not defined", pkg, version, file) + } + return fmt.Sprintf("%s %s (%s), %s line %d: %s", pkg, version, file, s.File, s.Line, s.Signature) +} + +func cap2000(s string) string { + if r := []rune(s); len(r) > 2000 { + return string(r[:1999]) + "…" + } + return s +} + +// Change is one difference between two surfaces: an event (Change set) or +// a difference that isn't one (Note says why). +type Change struct { + Change event.PackageChange + Kind string // the symbol's kind, for sentences + Symbol string // its full path: "openai.OpenAI.create" + Replacement string // renamed_symbol: the new path + Parameter string + OldDefault string + Before *pysurface.Symbol // its definition in the older release + After *pysurface.Symbol // in the newer one; nil when gone + Note string +} + +// Compare lists what changed from a to b, sorted by symbol: removed and +// renamed symbols (a member of a removed class isn't listed again), then +// for every symbol in both, removed parameters and parameters that lost +// their default. A rename is one removed and one added symbol of the same +// kind under the same parent with the same parameters, at least one of +// them besides self or cls; anything less sure is a removal. +// +// What looks removed but may not be is a note, not an event: a symbol +// defined in a file b couldn't read (over the size limit), and a method +// whose class is still there but whose bases changed, which one of its +// bases (or theirs) now defines, or which the class now defines as an +// attribute (create = _create, a property made a plain attribute). +func Compare(ra, rb Release) []Change { + a, b := ra.Surface, rb.Surface + var out []Change + removed := map[string]bool{} + byParent := map[string][2][]string{} // parent+kind -> removed, added + for k, s := range a { + if _, ok := b[k]; !ok { + removed[k] = true + key := parentOf(k) + " " + s.Kind + g := byParent[key] + g[0] = append(g[0], k) + byParent[key] = g + } + } + for k, s := range b { + if _, ok := a[k]; !ok { + key := parentOf(k) + " " + s.Kind + g := byParent[key] + g[1] = append(g[1], k) + byParent[key] = g + } + } + renamed := map[string]string{} + for _, g := range byParent { + if len(g[0]) == 1 && len(g[1]) == 1 { + old, now := a[g[0][0]], b[g[1][0]] + if old.Params != nil && !old.Overloaded && !now.Overloaded && slices.Equal(old.Params, now.Params) && len(callerParams(old.Params)) > 0 { + renamed[g[0][0]] = g[1][0] + } + } + } + for k := range removed { + if removed[parentOf(k)] { + continue // its class is reported + } + before := a[k] + if why := notGone(k, before, ra, rb); why != "" { + out = append(out, Change{Symbol: k, Note: fmt.Sprintf("%s: not in the newer release, but %s", k, why)}) + continue + } + c := Change{Change: event.PackageRemovedSymbol, Kind: before.Kind, Symbol: k, Before: &before} + if r, ok := renamed[k]; ok { + after := b[r] + c.Change, c.Replacement, c.After = event.PackageRenamedSymbol, r, &after + } + out = append(out, c) + } + for k, old := range a { + now, ok := b[k] + if !ok || old.Overloaded || now.Overloaded || old.Params == nil || now.Params == nil { + continue + } + before, after := old, now + kwargs := slices.ContainsFunc(now.Params, func(p pysurface.Param) bool { return p.Kind == "kwargs" }) + for _, op := range old.Params { + if op.Kind == "args" || op.Kind == "kwargs" { + continue + } + i := slices.IndexFunc(now.Params, func(p pysurface.Param) bool { return p.Name == op.Name }) + switch { + case i < 0 && kwargs: + out = append(out, Change{Symbol: k, Note: fmt.Sprintf("%s: parameter %s gone, but **kwargs still takes it", k, op.Name)}) + case i < 0: + out = append(out, Change{Change: event.PackageRemovedParameter, Kind: old.Kind, Symbol: k, Parameter: op.Name, Before: &before, After: &after}) + case op.HasDef && !now.Params[i].HasDef && now.Params[i].Kind != "args" && now.Params[i].Kind != "kwargs": + out = append(out, Change{Change: event.PackageChangedDefault, Kind: old.Kind, Symbol: k, Parameter: op.Name, OldDefault: op.Default, Before: &before, After: &after}) + } + } + for _, np := range now.Params { + if np.HasDef || np.Kind == "args" || np.Kind == "kwargs" { + continue + } + if !slices.ContainsFunc(old.Params, func(p pysurface.Param) bool { return p.Name == np.Name }) { + out = append(out, Change{Symbol: k, Note: fmt.Sprintf("%s: new required parameter %s (no subject for it in the contract yet)", k, np.Name)}) + } + } + } + slices.SortFunc(out, func(x, y Change) int { + return strings.Compare(x.Symbol+" "+x.Parameter+" "+x.Note, y.Symbol+" "+y.Parameter+" "+y.Note) + }) + return out +} + +// callerParams are the parameters a caller passes: a leading self or cls +// left out. +func callerParams(ps []pysurface.Param) []pysurface.Param { + if len(ps) > 0 && (ps[0].Name == "self" || ps[0].Name == "cls") { + return ps[1:] + } + return ps +} + +// notGone says why symbol k, defined as before in a and missing from b's +// surface, may still be there in b; "" when it's gone. +func notGone(k string, before pysurface.Symbol, a, b Release) string { + if slices.Contains(b.Skipped, before.File) { + return fmt.Sprintf("%s, where it was defined, was too big to read", before.File) + } + if before.Kind != "method" { + return "" + } + cls, ok := b.Surface[parentOf(k)] + if !ok || cls.Kind != "class" { + return "" + } + name := k[strings.LastIndexByte(k, '.')+1:] + oldBases, bases := pysurface.Bases(a.Surface[parentOf(k)].Signature), pysurface.Bases(cls.Signature) + if !slices.Equal(oldBases, bases) { + return fmt.Sprintf("its class's bases changed (%s to %s)", strings.Join(oldBases, ", "), strings.Join(bases, ", ")) + } + if own, ok := b.Classes[className(cls.Signature)]; ok && slices.Contains(own.Members, name) { + return "its class still defines the name (now an attribute)" + } + seen := map[string]bool{} + for len(bases) > 0 { + base := bases[0] + bases = bases[1:] + if seen[base] { + continue + } + seen[base] = true + c, ok := b.Classes[base] + if !ok { + continue // not the package's: unchanged, as the bases are + } + if slices.Contains(c.Members, name) { + return fmt.Sprintf("its base class %s defines it", base) + } + bases = append(bases, c.Bases...) + } + return "" +} + +// className is "Completions" for "class Completions(SyncAPIResource): ...". +func className(signature string) string { + n := strings.TrimPrefix(signature, "class ") + if i := strings.IndexAny(n, "(: "); i >= 0 { + n = n[:i] + } + return n +} + +// parentOf is "openai.OpenAI" for "openai.OpenAI.create". +func parentOf(sym string) string { + if i := strings.LastIndexByte(sym, '.'); i >= 0 { + return sym[:i] + } + return "" +} diff --git a/plugins/apisurface/apisurface_test.go b/plugins/apisurface/apisurface_test.go new file mode 100644 index 0000000..efd4bfc --- /dev/null +++ b/plugins/apisurface/apisurface_test.go @@ -0,0 +1,271 @@ +package apisurface + +import ( + "archive/zip" + "bytes" + "context" + "strings" + "testing" + + "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/core/versions" + "github.com/patch-it-dev/patch-it-plugins/plugins/apisurface/pysurface" +) + +const ( + wheel111 = "https://files.pythonhosted.org/packages/f7/86/ea99e3f966a639a3256e2f79d78cd63d45d5eb651a5457ccbdcfd9eed24a/openai-1.1.1-py3-none-any.whl" + wheel112 = "https://files.pythonhosted.org/packages/dd/82/b92f73453ea318c0d46f31aeb56e9d94a42606c010fb72a513f4a3cd4bac/openai-1.1.2-py3-none-any.whl" +) + +// The saved releases (testdata/README.md): PyPI's answers and the two +// wheels, trimmed to the openai.types.beta package. +var saved = kittest.Pages{ + "https://pypi.org/pypi/openai/json": "testdata/pypi-openai-excerpt.json", + "https://pypi.org/pypi/openai/1.1.1/json": "testdata/pypi-openai-1.1.1.json", + "https://pypi.org/pypi/openai/1.1.2/json": "testdata/pypi-openai-1.1.2.json", + wheel111: "testdata/openai-1.1.1-py3-none-any.trimmed.whl", + wheel112: "testdata/openai-1.1.2-py3-none-any.trimmed.whl", +} + +// pair lists the releases, reads 1.1.1 and 1.1.2 and extracts the pair. +func pair(t *testing.T) []event.Event { + t.Helper() + ctx, env := context.Background(), kittest.Env(t, saved) + p := Plugin{Package: OpenAIPython} + vs, err := p.ListVersions(ctx, env) + if err != nil { + t.Fatal(err) + } + var ids []string + for _, v := range vs { + ids = append(ids, v.ID) + } + if got := strings.Join(ids, " "); got != "1.1.0 1.1.1 1.1.2" { + t.Fatalf("versions %s", got) + } + last := versions.Pairs(vs)[1] + from, err := p.ReadAt(ctx, env, last[0]) + if err != nil { + t.Fatal(err) + } + to, err := p.ReadAt(ctx, env, last[1]) + if err != nil { + t.Fatal(err) + } + if to.SourceURL != wheel112 { + t.Errorf("source %s", to.SourceURL) + } + res, err := p.Extract(ctx, env, from, to) + if err != nil || len(res.Rejected) > 0 { + t.Fatalf("%v %v", err, res.Rejected) + } + return res.Events +} + +// openai 1.1.2 renamed the misspelled AsssitantDeleted to AssistantDeleted, +// module and all: the old name is gone from both places code could import +// it. (Not read as a rename: the class has no parameters to tell it's the +// same class.) +func TestGolden(t *testing.T) { + got := pair(t) + kittest.Golden(t, "testdata/golden/openai-1.1.2.json", got) + for _, e := range got { + if e.PreviousVersion != "1.1.1" || e.Version != "1.1.2" || !strings.Contains(e.SourceExcerpt, "openai/types/beta/asssitant_deleted.py line ") { + t.Errorf("%v: %s<-%s, excerpt %q", e.Subject.Symbols, e.Version, e.PreviousVersion, e.SourceExcerpt) + } + } +} + +// The pinned drop test: 1.1.2 adds AssistantDeleted and its module. A name +// that appears is no breaking change: no event names it. +func TestAnAddedNameIsNoEvent(t *testing.T) { + for _, e := range pair(t) { + for _, s := range e.Subject.Symbols { + if strings.Contains(s, "AssistantDeleted") || strings.Contains(s, "assistant_deleted") { + t.Errorf("event for %s, which 1.1.2 added", s) + } + } + } +} + +func TestRegistersItself(t *testing.T) { + kittest.Registered(t, Plugin{Package: OpenAIPython}) +} + +func sym(kind string, params ...pysurface.Param) pysurface.Symbol { + if params == nil { + params = []pysurface.Param{} + } + return pysurface.Symbol{Kind: kind, File: "acme/x.py", Line: 1, Signature: "def f()", Params: params} +} + +func prm(name, kind, def string) pysurface.Param { + return pysurface.Param{Name: name, Kind: kind, Default: def, HasDef: def != ""} +} + +// Each kind of change, and what isn't one. +func TestCompare(t *testing.T) { + a := pysurface.Surface{ + "acme.Gone": sym("class"), + "acme.Gone.method": sym("method"), + "acme.old_name": sym("function", prm("x", "either", "")), + "acme.f": sym("function", prm("a", "either", ""), prm("b", "keyword", "1"), prm("c", "keyword", "2")), + "acme.g": sym("function", prm("a", "either", "")), + "acme.h": sym("function", prm("a", "either", "")), + "acme.overloaded": {Kind: "function", Overloaded: true}, + "acme.Kept": sym("class", prm("self", "either", ""), prm("timeout", "either", "600")), + "acme.Kept.with_kwargs": sym("method", prm("self", "either", ""), prm("opt", "keyword", "None")), + } + b := pysurface.Surface{ + "acme.new_name": sym("function", prm("x", "either", "")), + "acme.f": sym("function", prm("a", "either", ""), prm("b", "keyword", "")), + "acme.g": sym("function", prm("a", "either", ""), prm("z", "keyword", "")), + "acme.h": sym("function", prm("a", "positional", "")), + "acme.overloaded": {Kind: "function", Overloaded: true}, + "acme.Kept": sym("class", prm("self", "either", ""), prm("timeout", "either", "600")), + "acme.Kept.with_kwargs": sym("method", prm("self", "either", ""), prm("kw", "kwargs", "")), + } + var got []string + for _, c := range Compare(Release{Surface: a}, Release{Surface: b}) { + if c.Change == "" { + got = append(got, "note "+c.Symbol) + continue + } + got = append(got, string(c.Change)+" "+c.Symbol+" "+c.Parameter+c.Replacement) + } + want := []string{ + "removed_symbol acme.Gone ", + "note acme.Kept.with_kwargs", + "changed_default acme.f b", + "removed_parameter acme.f c", + "note acme.g", + "renamed_symbol acme.old_name acme.new_name", + } + if strings.Join(got, "\n") != strings.Join(want, "\n") { + t.Errorf("got\n%s\nwant\n%s", strings.Join(got, "\n"), strings.Join(want, "\n")) + } +} + +// changes is Compare's output as lines, as TestCompare writes them. +func changes(a, b Release) []string { + var got []string + for _, c := range Compare(a, b) { + if c.Change == "" { + got = append(got, "note "+c.Symbol) + continue + } + got = append(got, string(c.Change)+" "+c.Symbol+" "+c.Parameter+c.Replacement) + } + return got +} + +func cls(sig string, params ...pysurface.Param) pysurface.Symbol { + s := sym("class", params...) + s.Signature = sig + return s +} + +// A method that keeps only self in common with the one added beside it +// isn't a rename: close(self) gone and aclose(self) added is a removal. +func TestSelfAloneIsNoRename(t *testing.T) { + self := prm("self", "either", "") + a := Release{Surface: pysurface.Surface{ + "acme.C": cls("class C:"), + "acme.C.close": sym("method", self), + "acme.C.send": sym("method", self, prm("body", "either", "")), + }} + b := Release{Surface: pysurface.Surface{ + "acme.C": cls("class C:"), + "acme.C.aclose": sym("method", self), + "acme.C.send_v2": sym("method", self, prm("body", "either", "")), + }} + // Two removed, two added: neither pairs one to one, so both are + // removals; then one of each, with a real parameter in common, is a + // rename. + want := "removed_symbol acme.C.close \nremoved_symbol acme.C.send " + if got := strings.Join(changes(a, b), "\n"); got != want { + t.Errorf("got\n%s\nwant\n%s", got, want) + } + delete(a.Surface, "acme.C.close") + delete(b.Surface, "acme.C.aclose") + if got := strings.Join(changes(a, b), "\n"); got != "renamed_symbol acme.C.send acme.C.send_v2" { + t.Errorf("with a real parameter: %s", got) + } + a.Surface = pysurface.Surface{"acme.C": cls("class C:"), "acme.C.close": sym("method", self)} + b.Surface = pysurface.Surface{"acme.C": cls("class C:"), "acme.C.aclose": sym("method", self)} + if got := strings.Join(changes(a, b), "\n"); got != "removed_symbol acme.C.close " { + t.Errorf("self only: %s", got) + } +} + +// A file the newer release couldn't read (over the size limit) is a gap, +// not a removal of everything in it. +func TestASkippedFileRemovesNothing(t *testing.T) { + big := sym("class") + big.File = "acme/big.py" + gone := sym("function") + a := Release{Surface: pysurface.Surface{"acme.Big": big, "acme.big.Big": big, "acme.gone": gone}} + b := Release{Surface: pysurface.Surface{}, Skipped: []string{"acme/big.py"}} + want := "note acme.Big\nnote acme.big.Big\nremoved_symbol acme.gone " + if got := strings.Join(changes(a, b), "\n"); got != want { + t.Errorf("got\n%s\nwant\n%s", got, want) + } +} + +// A method that left its class for a base class, or became an attribute, +// or whose class's bases changed, is still there: a note. One its class +// and bases don't define is gone. The two releases are read by the real +// reader, the leaf class included. +func TestAMethodMovedUpIsNotRemoved(t *testing.T) { + read := func(files map[string]string) Release { + var fs []pysurface.File + for p, text := range files { + fs = append(fs, pysurface.File{Path: p, Text: text}) + } + return Release{Surface: pysurface.Read(fs), Classes: pysurface.ReadClasses(fs)} + } + a := read(map[string]string{ + "acme/_base.py": "class _Base:\n pass\n\nclass SyncAPIResource(_Base):\n pass\n", + "acme/__init__.py": "from ._base import SyncAPIResource\n\nclass Completions(SyncAPIResource):\n def create(self, a):\n pass\n def list(self):\n pass\n def models(self):\n pass\n def gone(self):\n pass\n\nclass Files(SyncAPIResource):\n def upload(self, f):\n pass\n", + }) + b := read(map[string]string{ + "acme/_base.py": "class _Base:\n def list(self):\n pass\n\nclass SyncAPIResource(_Base):\n def create(self, a):\n pass\n", + "acme/__init__.py": "from ._base import SyncAPIResource\n\nclass Completions(SyncAPIResource):\n models = _models\n\nclass Files(SyncAPIResource, _Uploads):\n pass\n", + }) + want := "note acme.Completions.create\nremoved_symbol acme.Completions.gone \nnote acme.Completions.list\nnote acme.Completions.models\nnote acme.Files.upload" + if got := strings.Join(changes(a, b), "\n"); got != want { + t.Errorf("got\n%s\nwant\n%s", got, want) + } +} + +// An archive is read, never unpacked or run: paths outside the package, a +// path climbing out, and an oversized file are left out. +func TestSourceFilesStayInThePackage(t *testing.T) { + var buf bytes.Buffer + zw := zip.NewWriter(&buf) + for name, body := range map[string]string{ + "acme/__init__.py": "def ok(): pass\n", + "acme/big.py": strings.Repeat("#", 64) + "\n", + "../acme/evil.py": "def evil(): pass\n", + "tests/test_acme.py": "def test(): pass\n", + "acme-1.0.dist-info/RECORD": "", + } { + w, _ := zw.Create(name) + w.Write([]byte(body)) + } + zw.Close() + old := MaxFileBytes + MaxFileBytes = 32 + t.Cleanup(func() { MaxFileBytes = old }) + files, skipped, err := sourceFiles(artifact{Filename: "acme-1.0-py3-none-any.whl", Kind: "bdist_wheel"}, buf.Bytes(), "acme") + if err != nil { + t.Fatal(err) + } + if len(files) != 1 || files[0].Path != "acme/__init__.py" || len(skipped) != 1 || skipped[0] != "acme/big.py" { + t.Errorf("files %v, skipped %v", files, skipped) + } +} + +var _ plugin.Versioned = Plugin{} diff --git a/plugins/apisurface/artifact.go b/plugins/apisurface/artifact.go new file mode 100644 index 0000000..010edc3 --- /dev/null +++ b/plugins/apisurface/artifact.go @@ -0,0 +1,187 @@ +package apisurface + +import ( + "archive/tar" + "archive/zip" + "bytes" + "compress/gzip" + "context" + "encoding/json" + "fmt" + "io" + "net/url" + "path" + "slices" + "strings" + + "github.com/patch-it-dev/patch-it-plugins/core/plugin" + "github.com/patch-it-dev/patch-it-plugins/core/versions" + "github.com/patch-it-dev/patch-it-plugins/plugins/apisurface/pysurface" +) + +// The limits on what is read out of an archive: a release is data, and a +// crafted one (a zip bomb, a huge generated file) must not exhaust the +// runner. A file over MaxFileBytes is skipped (logged as a gap in the +// surface, never guessed at); an archive whose source files add up to more +// than MaxSourceBytes is refused. Variables only so a test can lower them. +var ( + MaxFileBytes int64 = 4 << 20 + MaxSourceBytes int64 = 128 << 20 +) + +// artifact is the file of a release that's read: a wheel if there is one +// (the files as installed), else the sdist. +type artifact struct { + URL string + Filename string + Kind string // "bdist_wheel", "sdist" +} + +// pickArtifact chooses the release file to read from PyPI's JSON for one +// release: a pure-Python wheel ("py3-none-any"), else any wheel (its .py +// files are the same), else the sdist (.tar.gz or .zip). +func pickArtifact(ctx context.Context, env plugin.Env, pkg, version string) (artifact, error) { + u := versions.PyPI + "/pypi/" + url.PathEscape(pkg) + "/" + url.PathEscape(version) + "/json" + body, err := env.Get(ctx, u) + if err != nil { + return artifact{}, fmt.Errorf("listing %s %s's files on PyPI: %w", pkg, version, err) + } + var doc struct { + URLs []struct { + URL string `json:"url"` + Filename string `json:"filename"` + PackageType string `json:"packagetype"` + Yanked bool `json:"yanked"` + } `json:"urls"` + } + if err := json.Unmarshal(body, &doc); err != nil { + return artifact{}, fmt.Errorf("parsing PyPI's %s %s: %w", pkg, version, err) + } + var wheels, sdists []artifact + for _, f := range doc.URLs { + a := artifact{URL: f.URL, Filename: f.Filename, Kind: f.PackageType} + switch { + case f.PackageType == "bdist_wheel" && strings.HasSuffix(f.Filename, ".whl"): + wheels = append(wheels, a) + case f.PackageType == "sdist" && (strings.HasSuffix(f.Filename, ".tar.gz") || strings.HasSuffix(f.Filename, ".zip")): + sdists = append(sdists, a) + } + } + byName := func(a, b artifact) int { return strings.Compare(a.Filename, b.Filename) } + slices.SortFunc(wheels, byName) + slices.SortFunc(sdists, byName) + for _, w := range wheels { + if strings.Contains(w.Filename, "-none-any.whl") { + return w, nil + } + } + if len(wheels) > 0 { + return wheels[0], nil + } + if len(sdists) > 0 { + return sdists[0], nil + } + return artifact{}, fmt.Errorf("%s %s has no wheel or sdist on PyPI", pkg, version) +} + +// sourceFiles are the .py and .pyi files of an archive, each with its path +// from the package's top directory ("openai/_client.py"): a wheel's paths +// as they are, an sdist's without its "-/" and "src/" +// prefixes. Nothing is written to disk and nothing in it is run. +func sourceFiles(a artifact, body []byte, module string) ([]pysurface.File, []string, error) { + var files []pysurface.File + var skipped []string + var total int64 + add := func(name string, size int64, open func() (io.Reader, error)) error { + if !strings.HasSuffix(name, ".py") && !strings.HasSuffix(name, ".pyi") { + return nil + } + rel, ok := packagePath(name, module, a.Kind == "sdist") + if !ok { + return nil + } + if size > MaxFileBytes { + skipped = append(skipped, rel) + return nil + } + total += size + if total > MaxSourceBytes { + return fmt.Errorf("%s: over %d bytes of source", a.Filename, MaxSourceBytes) + } + r, err := open() + if err != nil { + return err + } + b, err := io.ReadAll(io.LimitReader(r, MaxFileBytes+1)) + if err != nil { + return err + } + if int64(len(b)) > MaxFileBytes { + skipped = append(skipped, rel) + return nil + } + files = append(files, pysurface.File{Path: rel, Text: string(b)}) + return nil + } + switch { + case strings.HasSuffix(a.Filename, ".whl") || strings.HasSuffix(a.Filename, ".zip"): + zr, err := zip.NewReader(bytes.NewReader(body), int64(len(body))) + if err != nil { + return nil, nil, fmt.Errorf("reading %s: %w", a.Filename, err) + } + for _, f := range zr.File { + if f.FileInfo().IsDir() { + continue + } + if err := add(f.Name, int64(f.UncompressedSize64), func() (io.Reader, error) { return f.Open() }); err != nil { + return nil, nil, err + } + } + case strings.HasSuffix(a.Filename, ".tar.gz"): + gz, err := gzip.NewReader(bytes.NewReader(body)) + if err != nil { + return nil, nil, fmt.Errorf("reading %s: %w", a.Filename, err) + } + tr := tar.NewReader(gz) + for { + h, err := tr.Next() + if err == io.EOF { + break + } + if err != nil { + return nil, nil, fmt.Errorf("reading %s: %w", a.Filename, err) + } + if h.Typeflag != tar.TypeReg { + continue // links and devices are never followed + } + if err := add(h.Name, h.Size, func() (io.Reader, error) { return tr, nil }); err != nil { + return nil, nil, err + } + } + default: + return nil, nil, fmt.Errorf("%s: not a wheel, .tar.gz or .zip", a.Filename) + } + slices.SortFunc(files, func(x, y pysurface.File) int { return strings.Compare(x.Path, y.Path) }) + return files, skipped, nil +} + +// packagePath is name's path from the top module's directory, and false for +// a file outside it (tests, docs, setup.py, another top-level package, a +// path that climbs out with ".."). +func packagePath(name, module string, sdist bool) (string, bool) { + name = path.Clean(strings.TrimPrefix(name, "./")) + if strings.HasPrefix(name, "../") || path.IsAbs(name) { + return "", false + } + parts := strings.Split(name, "/") + if sdist && len(parts) > 1 { + parts = parts[1:] // "-/" + if len(parts) > 1 && parts[0] == "src" { + parts = parts[1:] + } + } + if len(parts) == 0 || (parts[0] != module && parts[0] != module+".py" && parts[0] != module+".pyi") { + return "", false + } + return strings.Join(parts, "/"), true +} diff --git a/plugins/apisurface/pysurface/lines.go b/plugins/apisurface/pysurface/lines.go new file mode 100644 index 0000000..1171994 --- /dev/null +++ b/plugins/apisurface/pysurface/lines.go @@ -0,0 +1,170 @@ +// Package pysurface reads the public API of a Python package from its source +// files, statically: the modules, classes, functions and methods code can +// import, with each one's parameters and their defaults. It never imports, +// compiles or runs the package's code: it reads the text, the way a person +// reading the files would. +// +// It is not a Python parser. It reads only what a signature needs: logical +// lines (comments dropped, strings kept whole, brackets and backslashes +// joining physical lines), their indentation, and the headers of `def`, +// `async def` and `class` statements, `__all__ = [...]` and +// `from ... import ...`. Function bodies are skipped. Whatever it can't read +// for sure (a dynamic `__all__`, a star import it can't resolve, an +// overloaded function's parameters) it leaves out: precision over recall. +package pysurface + +import ( + "strings" +) + +// line is one logical line of Python: its text with comments dropped and +// physical lines joined, its indentation, and the physical line it starts on. +type line struct { + text string + indent int + num int // 1-based +} + +// logicalLines splits a Python source file into logical lines. Strings +// (single, double, triple quoted, with any prefix) are kept verbatim, so a +// default value reads as written; a `#` inside one is not a comment. +func logicalLines(src string) []line { + src = strings.ReplaceAll(src, "\r\n", "\n") + var out []line + var cur strings.Builder + depth := 0 + startNum, num := 0, 1 + indent := -1 + atLineStart := true + col := 0 + flush := func() { + t := strings.TrimSpace(cur.String()) + if t != "" { + out = append(out, line{text: t, indent: indent, num: startNum}) + } + cur.Reset() + indent = -1 + depth = 0 + } + for i := 0; i < len(src); i++ { + c := src[i] + if atLineStart { + // Measure the indentation of a new logical line. + if c == ' ' || c == '\t' { + if c == '\t' { + col += 8 - col%8 + } else { + col++ + } + continue + } + atLineStart = false + if indent < 0 && c != '\n' && c != '#' { + indent, startNum = col, num + } + } + switch { + case c == '#': + for i < len(src) && src[i] != '\n' { + i++ + } + i-- // let the newline be handled + case c == '\'' || c == '"': + end := stringEnd(src, i) + lit := src[i:end] + num += strings.Count(lit, "\n") + cur.WriteString(lit) + i = end - 1 + case c == '\\' && i+1 < len(src) && src[i+1] == '\n': + cur.WriteByte(' ') + i++ + num++ + case c == '(' || c == '[' || c == '{': + depth++ + cur.WriteByte(c) + case c == ')' || c == ']' || c == '}': + if depth > 0 { + depth-- + } + cur.WriteByte(c) + case c == '\n': + num++ + if depth > 0 { + cur.WriteByte(' ') + continue + } + flush() + atLineStart, col = true, 0 + default: + cur.WriteByte(c) + } + } + flush() + return out +} + +// stringEnd is the index just past the string literal that starts at i (a +// quote): triple or single quoted, with backslash escapes. An unterminated +// one ends at the end of its line (single) or the file (triple). +func stringEnd(src string, i int) int { + q := src[i] + triple := strings.HasPrefix(src[i:], strings.Repeat(string(q), 3)) + j := i + 1 + if triple { + j = i + 3 + } + for j < len(src) { + switch { + case src[j] == '\\': + j += 2 + continue + case triple && strings.HasPrefix(src[j:], strings.Repeat(string(q), 3)): + return j + 3 + case !triple && src[j] == q: + return j + 1 + case !triple && src[j] == '\n': + return j + } + j++ + } + return len(src) +} + +// splitTop splits s on sep where it isn't inside brackets or a string. +func splitTop(s string, sep byte) []string { + var out []string + depth, start := 0, 0 + for i := 0; i < len(s); i++ { + switch c := s[i]; { + case c == '\'' || c == '"': + i = stringEnd(s, i) - 1 + case c == '(' || c == '[' || c == '{': + depth++ + case c == ')' || c == ']' || c == '}': + depth-- + case c == sep && depth == 0: + out = append(out, s[start:i]) + start = i + 1 + } + } + return append(out, s[start:]) +} + +// closing is the index of the bracket that closes the one at open, or -1. +func closing(s string, open int) int { + depth := 0 + for i := open; i < len(s); i++ { + switch c := s[i]; { + case c == '\'' || c == '"': + i = stringEnd(s, i) - 1 + case c == '(' || c == '[' || c == '{': + depth++ + case c == ')' || c == ']' || c == '}': + depth-- + if depth == 0 { + return i + } + } + } + return -1 +} diff --git a/plugins/apisurface/pysurface/pysurface.go b/plugins/apisurface/pysurface/pysurface.go new file mode 100644 index 0000000..61ee7ee --- /dev/null +++ b/plugins/apisurface/pysurface/pysurface.go @@ -0,0 +1,597 @@ +package pysurface + +import ( + "path" + "regexp" + "slices" + "strings" +) + +// Surface is a package's public API at one version: every public symbol by +// its import path ("openai.OpenAI", "openai.OpenAI.with_options"). +type Surface map[string]Symbol + +// Symbol is one class, function or method code can reach. +type Symbol struct { + Kind string `json:"kind"` // "class", "function", "method" + File string `json:"file"` // where it's defined, in the artifact + Line int `json:"line"` // its def or class line there + // Signature is the header as written, whitespace collapsed: "def + // create(self, *, model: str, n: int | None = None) -> Completion". A + // class's is its class line, then its __init__ when it has one. + Signature string `json:"signature"` + // Params are what a call passes, in order (a class's are its + // __init__'s); nil when they can't be read for sure (Overloaded). + Params []Param `json:"params,omitempty"` + // Overloaded is a function written as @overload variants: its + // parameters aren't compared. + Overloaded bool `json:"overloaded,omitempty"` +} + +// Param is one parameter. +type Param struct { + Name string `json:"name"` + Kind string `json:"kind"` // "positional" (before /), "either", "keyword" (after *), "args" (*a), "kwargs" (**k) + Default string `json:"default,omitempty"` // as written; "" with HasDefault false is no default + HasDef bool `json:"has_default,omitempty"` +} + +// File is one source file of the package: its path in the artifact, with the +// package's top directory first ("openai/_client.py"), and its text. +type File struct { + Path string + Text string +} + +// Class is what one class's body defines, for following a method that left +// a class: its bases as written (the last part of a dotted name, without +// [...]: "SyncAPIResource", "Generic"), and every name its body defines (defs +// of any name, nested classes, attributes assigned or annotated). +type Class struct { + Bases []string `json:"bases,omitempty"` + Members []string `json:"members,omitempty"` +} + +// Classes are the package's module-level classes by name (private modules +// and names included): where a method that left a class may still be, in +// the class itself (now an attribute) or in a base. Classes of the same +// name in two modules are merged (their members together), which can only +// make a moved method more likely to be found, never less. +type Classes map[string]Class + +// module is one file read: its own definitions and how it re-exports others. +type module struct { + name string // "openai.types.chat" + file string // its path + defs map[string]Symbol // by name in the module ("OpenAI", "OpenAI.with_options") + order []string // defs' names, in file order + all []string // __all__, when it's a plain list of strings + hasAll bool + imports map[string][2]string // local name -> {module, name} from "from M import name as local" + stars []string // modules of "from M import *" + classes map[string]*Class // module-level classes by name +} + +var ( + defLine = regexp.MustCompile(`^(?:async\s+)?def\s+([A-Za-z_]\w*)\s*\(`) + classLine = regexp.MustCompile(`^class\s+([A-Za-z_]\w*)\s*[(:]`) + allLine = regexp.MustCompile(`^__all__\s*(?::[^=]*)?=\s*[\[(](.*)[\])]\s*$`) + fromLine = regexp.MustCompile(`^from\s+(\.*[\w.]*)\s+import\s+(.+)$`) + strLit = regexp.MustCompile(`^[rRuU]?(?:"([^"\\]*)"|'([^'\\]*)')$`) + name = regexp.MustCompile(`^[A-Za-z_]\w*$`) + spaces = regexp.MustCompile(`\s+`) + attrLine = regexp.MustCompile(`^([A-Za-z_]\w*)\s*(?::|=[^=])`) + keywords = map[string]bool{"else": true, "try": true, "finally": true, "except": true, "elif": true, "if": true, "while": true, "for": true, "with": true, "match": true, "case": true} +) + +// Read is the public surface of the package whose files these are. A module +// is public when no part of its path starts with "_" (__init__ aside); its +// public names are its own definitions and, in a package's __init__, the +// names it imports from the package (re-exports, "from ._client import +// OpenAI"), less any starting with "_"; only those in __all__ when it has +// one (re-exports included, in any module). A .pyi stub next to a +// .py file is read instead of it. +func Read(files []File) Surface { + mods := parseAll(files) + out := Surface{} + for _, m := range mods { + if private(m.name) { + continue + } + for _, n := range m.public(mods) { + for k, s := range resolve(mods, m, n, 0) { + out[m.name+"."+k] = s + } + } + } + return out +} + +// ReadClasses is the package's Classes: every module-level class. +func ReadClasses(files []File) Classes { + all := map[string]*Class{} + for _, m := range parseAll(files) { + for n, c := range m.classes { + have := all[n] + if have == nil { + have = &Class{} + all[n] = have + } + have.Bases = appendNew(have.Bases, c.Bases...) + have.Members = appendNew(have.Members, c.Members...) + } + } + out := Classes{} + for n, c := range all { + slices.Sort(c.Bases) + slices.Sort(c.Members) + out[n] = *c + } + return out +} + +// appendNew appends the names list doesn't have yet. +func appendNew(list []string, names ...string) []string { + for _, n := range names { + if !slices.Contains(list, n) { + list = append(list, n) + } + } + return list +} + +// Bases are a class's bases as written in its signature ("class X(a.B[T], +// C, metaclass=M):" is B, C): the last part of each dotted name, without +// [...]; keyword arguments left out. +func Bases(signature string) []string { + sig, _, _ := strings.Cut(signature, " / ") // a class's __init__ follows + if !strings.HasPrefix(sig, "class ") { + return nil + } + open := strings.IndexByte(sig, '(') + if open < 0 { + return nil + } + end := closing(sig, open) + if end < 0 { + return nil + } + var out []string + for _, raw := range splitTop(sig[open+1:end], ',') { + b := strings.TrimSpace(raw) + if b == "" || indexTop(b, '=') >= 0 { + continue + } + if i := strings.IndexByte(b, '['); i >= 0 { + b = b[:i] + } + b = strings.TrimSpace(b[strings.LastIndexByte(b, '.')+1:]) + if b != "" { + out = append(out, b) + } + } + return out +} + +// parseAll parses every .py and .pyi file, by module name; a .pyi stub next +// to a .py file is read instead of it. +func parseAll(files []File) map[string]*module { + byPath := map[string]File{} + for _, f := range files { + byPath[f.Path] = f + } + mods := map[string]*module{} + for _, f := range files { + if !strings.HasSuffix(f.Path, ".py") && !strings.HasSuffix(f.Path, ".pyi") { + continue + } + if strings.HasSuffix(f.Path, ".py") { + if _, stub := byPath[f.Path+"i"]; stub { + continue + } + } + m := parse(f) + mods[m.name] = m + } + return mods +} + +// moduleName is "openai.types.chat" for "openai/types/chat/__init__.py". +func moduleName(p string) string { + p = strings.TrimSuffix(strings.TrimSuffix(p, ".pyi"), ".py") + p = strings.TrimSuffix(p, "/__init__") + return strings.ReplaceAll(p, "/", ".") +} + +// private is a module with a part starting with "_", or a test module. +func private(mod string) bool { + for _, part := range strings.Split(mod, ".") { + if strings.HasPrefix(part, "_") || part == "tests" || part == "test" || strings.HasPrefix(part, "test_") { + return true + } + } + return false +} + +// public are the module's public top-level names, in a stable order. +func (m *module) public(mods map[string]*module) []string { + if m.hasAll { + return m.all + } + var out []string + seen := map[string]bool{} + add := func(n string) { + if !strings.HasPrefix(n, "_") && !seen[n] { + seen[n] = true + out = append(out, n) + } + } + for _, n := range m.order { + if !strings.Contains(n, ".") { + add(n) + } + } + // Imported names are the package's API only where a package says so: + // its __init__ (re-exports) or __all__. Elsewhere an import is the + // module's own business. + if !m.isInit() { + return out + } + locals := make([]string, 0, len(m.imports)) + for n := range m.imports { + locals = append(locals, n) + } + slices.Sort(locals) + for _, n := range locals { + add(n) + } + for _, s := range m.stars { + if t, ok := mods[s]; ok && t != m { + for _, n := range t.public(mods) { + add(n) + } + } + } + return out +} + +// isInit is a package's __init__.py or __init__.pyi. +func (m *module) isInit() bool { + return path.Base(strings.TrimSuffix(strings.TrimSuffix(m.file, "i"), ".py")) == "__init__" +} + +// resolve is name in m and its members ("OpenAI", "OpenAI.with_options"), +// following re-exports a few hops; nothing for a name that isn't a class or +// function the package defines (a constant, a type alias, a module). +func resolve(mods map[string]*module, m *module, n string, hops int) map[string]Symbol { + if hops > 4 { + return nil + } + if s, ok := m.defs[n]; ok { + out := map[string]Symbol{n: s} + for k, v := range m.defs { + if strings.HasPrefix(k, n+".") { + out[k] = v + } + } + return out + } + if imp, ok := m.imports[n]; ok { + if t, ok := mods[imp[0]]; ok { + return rekey(resolve(mods, t, imp[1], hops+1), imp[1], n) + } + return nil + } + for _, s := range m.stars { + if t, ok := mods[s]; ok && t != m { + if got := resolve(mods, t, n, hops+1); got != nil { + return got + } + } + } + return nil +} + +// rekey renames the symbols of name from to name to: a re-export under +// another name ("AsyncClient as Async"). +func rekey(syms map[string]Symbol, from, to string) map[string]Symbol { + if from == to || syms == nil { + return syms + } + out := make(map[string]Symbol, len(syms)) + for k, v := range syms { + out[to+strings.TrimPrefix(k, from)] = v + } + return out +} + +// block is an open def or class while its body is read. +type block struct { + indent int + kind string // "class", "def", "other" + name string // the def's or class's path in the module: "OpenAI.with_options" +} + +// parse reads one file's definitions, __all__ and imports. +func parse(f File) *module { + m := &module{name: moduleName(f.Path), file: f.Path, defs: map[string]Symbol{}, imports: map[string][2]string{}, classes: map[string]*Class{}} + var stack []block + var decorators []string + for _, l := range logicalLines(f.Text) { + for len(stack) > 0 && l.indent <= stack[len(stack)-1].indent { + stack = stack[:len(stack)-1] + } + // Where this line is: at module level (only if/try/with blocks + // around it), in a class body at module level, or anywhere else. + parent, inDef := "", false + for _, b := range stack { + switch b.kind { + case "def": + inDef = true + case "class": + parent = b.name + } + } + nested := strings.Count(parent, ".") > 0 // a class inside a class: not read + t := l.text + opens := strings.HasSuffix(t, ":") + if c := m.classes[parent]; c != nil && !inDef { + // A name the class body defines: a def, a nested class, an + // attribute. + var n string + switch { + case defLine.MatchString(t): + n = defLine.FindStringSubmatch(t)[1] + case classLine.MatchString(t): + n = classLine.FindStringSubmatch(t)[1] + case attrLine.MatchString(t) && !keywords[attrLine.FindStringSubmatch(t)[1]]: + n = attrLine.FindStringSubmatch(t)[1] + } + if n != "" { + c.Members = appendNew(c.Members, n) + } + } + switch { + case strings.HasPrefix(t, "@"): + decorators = append(decorators, strings.TrimSpace(t[1:])) + continue + case defLine.MatchString(t): + n := defLine.FindStringSubmatch(t)[1] + path := n + if parent != "" { + path = parent + "." + n + } + if !inDef && !nested { + m.addDef(path, parent, l, t, decorators) + } + stack = append(stack, block{indent: l.indent, kind: "def", name: path}) + case classLine.MatchString(t): + n := classLine.FindStringSubmatch(t)[1] + path := n + if parent != "" { + path = parent + "." + n + } + if !inDef && parent == "" { + m.defs[path] = Symbol{Kind: "class", File: f.Path, Line: l.num, Signature: header(t)} + m.order = append(m.order, path) + if m.classes[path] == nil { + m.classes[path] = &Class{} + } + m.classes[path].Bases = appendNew(m.classes[path].Bases, Bases(header(t))...) + } + kind := "class" + if inDef { + kind = "def" + } + stack = append(stack, block{indent: l.indent, kind: kind, name: path}) + case opens && !strings.Contains(t, "lambda"): + // if/else/try/except/with/for: what's inside is still at + // this level. + stack = append(stack, block{indent: l.indent, kind: "other", name: parent}) + case parent == "" && !inDef && allLine.MatchString(t): + m.readAll(allLine.FindStringSubmatch(t)[1]) + case parent == "" && !inDef && fromLine.MatchString(t): + fm := fromLine.FindStringSubmatch(t) + m.readImport(fm[1], fm[2]) + } + decorators = nil + } + return m +} + +// addDef records a function, or a method of a module-level class; a +// class's __init__ becomes the class's own parameters. +func (m *module) addDef(path, parent string, l line, text string, decorators []string) { + n := path[strings.LastIndex(path, ".")+1:] + params, ok := params(text) + overloaded := slices.ContainsFunc(decorators, func(d string) bool { return d == "overload" || d == "typing.overload" }) + if !ok { + params = nil + } + if parent != "" && n == "__init__" { + c := m.defs[parent] + c.Signature = strings.TrimSuffix(c.Signature, ":") + " / " + header(text) + if overloaded || c.Overloaded { + c.Params, c.Overloaded = nil, true + } else { + c.Params = params + } + m.defs[parent] = c + return + } + if strings.HasPrefix(n, "_") { + return + } + kind := "function" + if parent != "" { + kind = "method" + } + if have, dup := m.defs[path]; dup && (overloaded || have.Overloaded) { + // @overload variants, then the implementation: one symbol, its + // parameters not compared. + have.Overloaded, have.Params = true, nil + if !overloaded { + have.Line, have.Signature = l.num, header(text) + } + m.defs[path] = have + return + } + s := Symbol{Kind: kind, File: m.file, Line: l.num, Signature: header(text), Params: params, Overloaded: overloaded} + if overloaded { + s.Params = nil + } + if _, dup := m.defs[path]; !dup { + m.order = append(m.order, path) + } + m.defs[path] = s +} + +// header is a def or class line without its body, whitespace collapsed. +func header(text string) string { + if open := strings.IndexByte(text, '('); open >= 0 { + if end := closing(text, open); end > 0 { + rest := text[end+1:] + if colon := indexTop(rest, ':'); colon >= 0 { + rest = rest[:colon] + } + return spaces.ReplaceAllString(strings.TrimSpace(text[:end+1]+rest), " ") + } + } + if colon := strings.IndexByte(text, ':'); colon >= 0 { + text = text[:colon] + } + return spaces.ReplaceAllString(strings.TrimSpace(text), " ") +} + +// indexTop is the first sep outside brackets and strings, or -1. +func indexTop(s string, sep byte) int { + parts := splitTop(s, sep) + if len(parts) < 2 { + return -1 + } + return len(parts[0]) +} + +// params reads a def line's parameter list. ok is false when the list +// can't be read for sure. +func params(text string) ([]Param, bool) { + open := strings.IndexByte(text, '(') + end := closing(text, open) + if open < 0 || end < 0 { + return nil, false + } + inner := strings.TrimSpace(text[open+1 : end]) + if inner == "" { + return []Param{}, true + } + var out []Param + kind := "either" + for _, raw := range splitTop(inner, ',') { + p := strings.TrimSpace(raw) + switch { + case p == "": + continue // a trailing comma + case p == "/": + for i := range out { + out[i].Kind = "positional" + } + continue + case p == "*": + kind = "keyword" + continue + } + var prm Param + if def := indexTop(p, '='); def >= 0 { + prm.Default, prm.HasDef = spaces.ReplaceAllString(strings.TrimSpace(p[def+1:]), " "), true + p = p[:def] + } + if colon := indexTop(p, ':'); colon >= 0 { + p = p[:colon] + } + p = strings.TrimSpace(p) + switch { + case strings.HasPrefix(p, "**"): + prm.Kind, p = "kwargs", p[2:] + case strings.HasPrefix(p, "*"): + prm.Kind, p = "args", p[1:] + kind = "keyword" + default: + prm.Kind = kind + } + if !name.MatchString(p) { + return nil, false + } + prm.Name = p + out = append(out, prm) + } + return out, true +} + +// readAll reads `__all__ = ["a", "b"]`; anything but plain strings leaves +// it unread (every public name counts then). +func (m *module) readAll(list string) { + var names []string + for _, item := range splitTop(list, ',') { + item = strings.TrimSpace(item) + if item == "" { + continue + } + s := strLit.FindStringSubmatch(item) + if s == nil { + return + } + names = append(names, s[1]+s[2]) + } + m.all, m.hasAll = names, true +} + +// readImport reads `from M import a, b as c` (or `*`), keeping imports from +// the package itself: relative ones, and absolute ones under its top module. +func (m *module) readImport(from, names string) { + target := absolute(m, from) + if target == "" { + return + } + names = strings.TrimSpace(strings.Trim(strings.TrimSpace(names), "()")) + if names == "*" { + m.stars = append(m.stars, target) + return + } + for _, item := range splitTop(names, ',') { + f := strings.Fields(item) + switch { + case len(f) == 1 && name.MatchString(f[0]): + m.imports[f[0]] = [2]string{target, f[0]} + case len(f) == 3 && f[1] == "as" && name.MatchString(f[0]) && name.MatchString(f[2]): + m.imports[f[2]] = [2]string{target, f[0]} + } + } +} + +// absolute is the module a from-import names, or "" for one outside the +// package. +func absolute(m *module, from string) string { + top := strings.SplitN(m.name, ".", 2)[0] + dots := len(from) - len(strings.TrimLeft(from, ".")) + if dots == 0 { + if from == top || strings.HasPrefix(from, top+".") { + return from + } + return "" + } + // The package a relative import starts from: the module's own for + // __init__, its parent otherwise; each further dot goes up one. + base := strings.Split(m.name, ".") + if !m.isInit() { + base = base[:len(base)-1] + } + if dots-1 > len(base) { + return "" + } + base = base[:len(base)-(dots-1)] + rest := from[dots:] + if rest != "" { + base = append(base, strings.Split(rest, ".")...) + } + return strings.Join(base, ".") +} diff --git a/plugins/apisurface/pysurface/pysurface_test.go b/plugins/apisurface/pysurface/pysurface_test.go new file mode 100644 index 0000000..880b5cd --- /dev/null +++ b/plugins/apisurface/pysurface/pysurface_test.go @@ -0,0 +1,135 @@ +package pysurface + +import ( + "encoding/json" + "strings" + "testing" +) + +const initPy = `"""Acme.""" +from ._client import Client, AsyncClient as Async +from .version import __version__ +from . import types +from .helpers import * +from os import path + +__all__ = ["Client", "Async", "helper", "VERSION"] +VERSION = "1" +` + +const clientPy = `import typing +from typing import overload + +class Client(Base): + """A client. + + # not a comment + """ + + def __init__(self, api_key: str | None = None, *, timeout: float = 600.0, **kwargs) -> None: + self._x = "a # b" + + def create( + self, + model: str, # the model + /, + n: int = 1, + *, + stream: bool = False, + extra=("a", "b,c"), + ) -> "Result": + def inner(z): + pass + return None + + @property + def models(self) -> int: + return 1 + + def _private(self, x): + pass + + @overload + def get(self, a: int) -> int: ... + @overload + def get(self, a: str) -> str: ... + def get(self, a): + return a + + class Nested: + def deep(self, q): pass + +if typing.TYPE_CHECKING: + class AsyncClient: pass +else: + class AsyncClient(Client): \ + pass + +def _hidden(): pass +` + +const helpersPy = `__all__ = ["helper"] + +async def helper(x, *args, y=None, **kw): + pass + +def not_exported(): pass +` + +func TestRead(t *testing.T) { + s := Read([]File{ + {"acme/__init__.py", initPy}, + {"acme/_client.py", clientPy}, + {"acme/helpers.py", helpersPy}, + {"acme/tests/test_x.py", "def test_a(): pass\n"}, + }) + var keys []string + for k := range s { + keys = append(keys, k) + } + want := map[string]bool{ + "acme.Client": true, "acme.Client.create": true, "acme.Client.models": true, "acme.Client.get": true, + "acme.Async": true, "acme.helper": true, + "acme.helpers.helper": true, + } + if len(s) != len(want) { + b, _ := json.MarshalIndent(s, "", " ") + t.Fatalf("got %d symbols %v, want %v\n%s", len(s), keys, want, b) + } + for k := range want { + if _, ok := s[k]; !ok { + t.Errorf("missing %s (have %v)", k, keys) + } + } + c := s["acme.Client"] + if c.File != "acme/_client.py" || c.Line != 4 || len(c.Params) != 4 || c.Params[1].Name != "api_key" || c.Params[1].Default != "None" || c.Params[2].Kind != "keyword" || c.Params[3].Kind != "kwargs" { + t.Errorf("Client: %+v", c) + } + cr := s["acme.Client.create"] + if cr.Line != 13 || len(cr.Params) != 5 || cr.Params[1].Kind != "positional" || cr.Params[2].Kind != "either" || cr.Params[3].Kind != "keyword" || cr.Params[4].Default != `("a", "b,c")` { + t.Errorf("create: %+v", cr) + } + if g := s["acme.Client.get"]; !g.Overloaded || g.Params != nil || g.Line != 37 { + t.Errorf("get: %+v", g) + } + if h := s["acme.helper"]; h.Params[1].Kind != "args" || h.Params[2].Kind != "keyword" { + t.Errorf("helper: %+v", h) + } +} + +// The class index: every module-level class, with its bases and every name +// its body defines; private modules and names included. +func TestReadClasses(t *testing.T) { + c := ReadClasses([]File{ + {"acme/_resource.py", "class _Base:\n def list(self): pass\n\nclass SyncAPIResource(_Base, Generic[T], metaclass=M):\n _client: Client\n create = _create\n if TYPE_CHECKING:\n def _hidden(self): pass\n else:\n pass\n def _create(self, x):\n y = 1\n return y\n"}, + {"acme/completions.py", "from ._resource import SyncAPIResource\n\nclass Completions(base.SyncAPIResource):\n models = _models\n"}, + }) + got, _ := json.Marshal(c) + want := `{"Completions":{"bases":["SyncAPIResource"],"members":["models"]},"SyncAPIResource":{"bases":["Generic","_Base"],"members":["_client","_create","_hidden","create"]},"_Base":{"members":["list"]}}` + if string(got) != want { + t.Errorf("got %s\nwant %s", got, want) + } + if b := Bases("class X(a.B[T], C, metaclass=M): / def __init__(self, a=(1, 2))"); strings.Join(b, ",") != "B,C" { + t.Errorf("bases %v", b) + } +} diff --git a/plugins/apisurface/testdata/README.md b/plugins/apisurface/testdata/README.md new file mode 100644 index 0000000..5392b88 --- /dev/null +++ b/plugins/apisurface/testdata/README.md @@ -0,0 +1,10 @@ +# Saved releases + +The golden file, `golden/openai-1.1.2.json`, is what the kind stores from the 1.1.1 → 1.1.2 pair (`go test ./plugins/apisurface -update`). + +| File | URL | Saved | License | Quote | +|---|---|---|---|---| +| `openai-1.1.1-py3-none-any.trimmed.whl` | https://files.pythonhosted.org/packages/f7/86/ea99e3f966a639a3256e2f79d78cd63d45d5eb651a5457ccbdcfd9eed24a/openai-1.1.1-py3-none-any.whl | 2026-11-20 | Apache-2.0 (openai-python; the wheel's `licenses/LICENSE` is kept in it). Trimmed: only `openai/__init__.py`, `openai/types/__init__.py`, every file under `openai/types/beta/`, and the dist-info `METADATA`, `WHEEL` and `LICENSE`, each copied byte for byte (46 of the wheel's files); the plugin reads the same symbols under `openai.types.beta` from it as from the whole wheel. | `class AsssitantDeleted(BaseModel):` (`openai/types/beta/asssitant_deleted.py`, line 10) | +| `openai-1.1.2-py3-none-any.trimmed.whl` | https://files.pythonhosted.org/packages/dd/82/b92f73453ea318c0d46f31aeb56e9d94a42606c010fb72a513f4a3cd4bac/openai-1.1.2-py3-none-any.whl | 2026-11-20 | The same, trimmed the same way. | `from .assistant_deleted import AssistantDeleted as AssistantDeleted` (`openai/types/beta/__init__.py`) | +| `pypi-openai-excerpt.json` | https://pypi.org/pypi/openai/json | 2026-11-20 | PyPI metadata. Trimmed: `releases` to 1.0.0rc1 (a pre-release, left out) and 1.1.0 to 1.1.2, each file to `filename`, `packagetype`, `upload_time_iso_8601`, `yanked` | | +| `pypi-openai-1.1.1.json`, `pypi-openai-1.1.2.json` | https://pypi.org/pypi/openai/1.1.1/json, …/1.1.2/json | 2026-11-20 | PyPI metadata. Trimmed: `info.name`, `info.version`, and `urls` to `filename`, `packagetype`, `url`, `yanked` | | diff --git a/plugins/apisurface/testdata/golden/openai-1.1.2.json b/plugins/apisurface/testdata/golden/openai-1.1.2.json new file mode 100644 index 0000000..6390e70 --- /dev/null +++ b/plugins/apisurface/testdata/golden/openai-1.1.2.json @@ -0,0 +1,50 @@ +[ + { + "id": 0, + "fingerprint": "sha256:7c2703dd5112b040c64fd384b102f560a1205f2f540f4ec31cd8310e6a604902", + "api": "openai/python-sdk", + "version": "1.1.2", + "previous_version": "1.1.1", + "change_type": "breaking", + "breaking": true, + "subject": { + "type": "package_release", + "ecosystem": "pypi", + "package": "openai", + "change": "removed_symbol", + "symbols": [ + "types.beta.AsssitantDeleted" + ] + }, + "description": "The class `types.beta.AsssitantDeleted` was removed in openai 1.1.2: code using it fails.", + "migration_hint": "openai 1.1.2 has no `types.beta.AsssitantDeleted`: see the package's release notes for what replaces it.", + "source_url": "https://files.pythonhosted.org/packages/dd/82/b92f73453ea318c0d46f31aeb56e9d94a42606c010fb72a513f4a3cd4bac/openai-1.1.2-py3-none-any.whl", + "source_excerpt": "openai 1.1.1 (openai-1.1.1-py3-none-any.whl), openai/types/beta/asssitant_deleted.py line 10: class AsssitantDeleted(BaseModel)\nopenai 1.1.2 (openai-1.1.2-py3-none-any.whl): not defined", + "confidence": 1, + "detected_at": "2026-11-14T12:00:00Z" + }, + { + "id": 0, + "fingerprint": "sha256:54fc59ce604c0f5bfa1b1f3886d8d79ea37963f05f2fa694ea4d7b68ad720dbd", + "api": "openai/python-sdk", + "version": "1.1.2", + "previous_version": "1.1.1", + "change_type": "breaking", + "breaking": true, + "subject": { + "type": "package_release", + "ecosystem": "pypi", + "package": "openai", + "change": "removed_symbol", + "symbols": [ + "types.beta.asssitant_deleted.AsssitantDeleted" + ] + }, + "description": "The class `types.beta.asssitant_deleted.AsssitantDeleted` was removed in openai 1.1.2: code using it fails.", + "migration_hint": "openai 1.1.2 has no `types.beta.asssitant_deleted.AsssitantDeleted`: see the package's release notes for what replaces it.", + "source_url": "https://files.pythonhosted.org/packages/dd/82/b92f73453ea318c0d46f31aeb56e9d94a42606c010fb72a513f4a3cd4bac/openai-1.1.2-py3-none-any.whl", + "source_excerpt": "openai 1.1.1 (openai-1.1.1-py3-none-any.whl), openai/types/beta/asssitant_deleted.py line 10: class AsssitantDeleted(BaseModel)\nopenai 1.1.2 (openai-1.1.2-py3-none-any.whl): not defined", + "confidence": 1, + "detected_at": "2026-11-14T12:00:00Z" + } +] diff --git a/plugins/apisurface/testdata/openai-1.1.1-py3-none-any.trimmed.whl b/plugins/apisurface/testdata/openai-1.1.1-py3-none-any.trimmed.whl new file mode 100644 index 0000000..8b93cc6 Binary files /dev/null and b/plugins/apisurface/testdata/openai-1.1.1-py3-none-any.trimmed.whl differ diff --git a/plugins/apisurface/testdata/openai-1.1.2-py3-none-any.trimmed.whl b/plugins/apisurface/testdata/openai-1.1.2-py3-none-any.trimmed.whl new file mode 100644 index 0000000..966486b Binary files /dev/null and b/plugins/apisurface/testdata/openai-1.1.2-py3-none-any.trimmed.whl differ diff --git a/plugins/apisurface/testdata/pypi-openai-1.1.1.json b/plugins/apisurface/testdata/pypi-openai-1.1.1.json new file mode 100644 index 0000000..1647019 --- /dev/null +++ b/plugins/apisurface/testdata/pypi-openai-1.1.1.json @@ -0,0 +1,20 @@ +{ + "info": { + "name": "openai", + "version": "1.1.1" + }, + "urls": [ + { + "filename": "openai-1.1.1-py3-none-any.whl", + "packagetype": "bdist_wheel", + "url": "https://files.pythonhosted.org/packages/f7/86/ea99e3f966a639a3256e2f79d78cd63d45d5eb651a5457ccbdcfd9eed24a/openai-1.1.1-py3-none-any.whl", + "yanked": false + }, + { + "filename": "openai-1.1.1.tar.gz", + "packagetype": "sdist", + "url": "https://files.pythonhosted.org/packages/81/f3/77cea3da9cbee3cfd48ef86158a813ab0da4b1827d66537723f2abfc869c/openai-1.1.1.tar.gz", + "yanked": false + } + ] +} diff --git a/plugins/apisurface/testdata/pypi-openai-1.1.2.json b/plugins/apisurface/testdata/pypi-openai-1.1.2.json new file mode 100644 index 0000000..abeacfc --- /dev/null +++ b/plugins/apisurface/testdata/pypi-openai-1.1.2.json @@ -0,0 +1,20 @@ +{ + "info": { + "name": "openai", + "version": "1.1.2" + }, + "urls": [ + { + "filename": "openai-1.1.2-py3-none-any.whl", + "packagetype": "bdist_wheel", + "url": "https://files.pythonhosted.org/packages/dd/82/b92f73453ea318c0d46f31aeb56e9d94a42606c010fb72a513f4a3cd4bac/openai-1.1.2-py3-none-any.whl", + "yanked": false + }, + { + "filename": "openai-1.1.2.tar.gz", + "packagetype": "sdist", + "url": "https://files.pythonhosted.org/packages/ea/98/ee6972358bb7f3d6e2f1c375e6d7d56bf12d66c6547ec08eb627731f8530/openai-1.1.2.tar.gz", + "yanked": false + } + ] +} diff --git a/plugins/apisurface/testdata/pypi-openai-excerpt.json b/plugins/apisurface/testdata/pypi-openai-excerpt.json new file mode 100644 index 0000000..7b9bef8 --- /dev/null +++ b/plugins/apisurface/testdata/pypi-openai-excerpt.json @@ -0,0 +1,63 @@ +{ + "info": { + "name": "openai" + }, + "releases": { + "1.0.0rc1": [ + { + "filename": "openai-1.0.0rc1-py3-none-any.whl", + "packagetype": "bdist_wheel", + "upload_time_iso_8601": "2023-10-28T04:07:47.330003Z", + "yanked": false + }, + { + "filename": "openai-1.0.0rc1.tar.gz", + "packagetype": "sdist", + "upload_time_iso_8601": "2023-10-28T04:07:57.479454Z", + "yanked": false + } + ], + "1.1.0": [ + { + "filename": "openai-1.1.0-py3-none-any.whl", + "packagetype": "bdist_wheel", + "upload_time_iso_8601": "2023-11-06T20:36:42.478835Z", + "yanked": false + }, + { + "filename": "openai-1.1.0.tar.gz", + "packagetype": "sdist", + "upload_time_iso_8601": "2023-11-06T20:36:45.073097Z", + "yanked": false + } + ], + "1.1.1": [ + { + "filename": "openai-1.1.1-py3-none-any.whl", + "packagetype": "bdist_wheel", + "upload_time_iso_8601": "2023-11-06T22:18:59.867320Z", + "yanked": false + }, + { + "filename": "openai-1.1.1.tar.gz", + "packagetype": "sdist", + "upload_time_iso_8601": "2023-11-06T22:19:04.102221Z", + "yanked": false + } + ], + "1.1.2": [ + { + "filename": "openai-1.1.2-py3-none-any.whl", + "packagetype": "bdist_wheel", + "upload_time_iso_8601": "2023-11-08T18:05:27.665476Z", + "yanked": false + }, + { + "filename": "openai-1.1.2.tar.gz", + "packagetype": "sdist", + "upload_time_iso_8601": "2023-11-08T18:05:30.675572Z", + "yanked": false + } + ] + } +} diff --git a/plugins/catalog/catalog.go b/plugins/catalog/catalog.go index 9c257e4..5ef4459 100644 --- a/plugins/catalog/catalog.go +++ b/plugins/catalog/catalog.go @@ -1,7 +1,7 @@ // Package catalog is the source plugin for a provider that publishes its // whole command or endpoint surface as one structured JSON file, one entry -// keyed by name: fetch the newest snapshot, diff it against the last one -// seen (or two given snapshots, to replay a historical change), and report +// keyed by name: read it at a commit, compare it with the one read before, +// and report // every name that disappeared entirely between them. Unlike openapi's typed // spec, an entry here is opaque: no request or response shape to walk, just // whether the name is still there. Redis first: its command surface has no @@ -42,7 +42,7 @@ func init() { // Catalog is one provider's command or endpoint catalog: a single JSON // object, one key per entry, fetched at a git ref. type Catalog struct { - API string // the events' api: "redis" + API string // the source id the events carry: "redis/commands" Ecosystem string // the package_release subject's ecosystem: "redis" Package string // the package_release subject's package: "redis" Repo string // owner/name on GitHub the catalog lives in @@ -54,7 +54,7 @@ type Catalog struct { // release and read by redis.io's own command reference (checked 2026-11-18). // The repo has no tags, so a ref here is a commit SHA, not a release. var Redis = Catalog{ - API: "redis", Ecosystem: "redis", Package: "redis", + API: "redis/commands", Ecosystem: "redis", Package: "redis", Repo: "redis/redis-doc", Path: "commands.json", RefsURL: "https://api.github.com/repos/redis/redis-doc/commits/master", } @@ -129,38 +129,43 @@ func (p Plugin) Run(ctx context.Context, env plugin.Env) (plugin.Result, error) Label: ref, Events: events, Rejected: rejected, - Baselines: []plugin.Spec{plugin.Baseline(c.API, ref, ref, c.URL(ref), newContent, false, now)}, + Baselines: []plugin.Spec{plugin.Baseline(c.API, ref, ref, c.URL(ref), newContent, now)}, }, nil } -// Replay diffs two given snapshots. Both are saved marked as replays, so the -// normal-run baseline never moves; the events are stored like any others. -func (p Plugin) Replay(ctx context.Context, env plugin.Env, from, to string) (plugin.Result, error) { - c := p.Catalog - oldContent, err := env.Get(ctx, c.URL(from)) +// ListVersions is the catalog repo's newest commit: the catalog has no +// releases, so each commit read is a version, and the change into it is +// extracted against the one read before. +func (p Plugin) ListVersions(ctx context.Context, env plugin.Env) ([]plugin.Version, error) { + ref, err := p.latestRef(ctx, env) if err != nil { - return plugin.Result{}, fmt.Errorf("fetching %s: %w", c.URL(from), err) + return nil, err } - newContent, err := env.Get(ctx, c.URL(to)) + return []plugin.Version{{ID: ref, Ref: ref}}, nil +} + +// ReadAt fetches the catalog at v's commit. +func (p Plugin) ReadAt(ctx context.Context, env plugin.Env, v plugin.Version) (plugin.Snapshot, error) { + url := p.Catalog.URL(v.Ref) + body, err := env.Get(ctx, url) if err != nil { - return plugin.Result{}, fmt.Errorf("fetching %s: %w", c.URL(to), err) + return plugin.Snapshot{}, fmt.Errorf("fetching %s: %w", url, err) } - now := env.Now() - events, rejected, err := p.events(oldContent, newContent, from, to, now) + return plugin.Snapshot{Version: v, Content: body, SourceURL: url}, nil +} + +// Extract is an event per command in from's catalog that isn't in to's, +// with previous_version from's commit. A zero from has nothing to compare. +func (p Plugin) Extract(_ context.Context, env plugin.Env, from, to plugin.Snapshot) (plugin.Result, error) { + events, rejected, err := p.events(from.Content, to.Content, from.Version.Ref, to.Version.Ref, env.Now()) if err != nil { return plugin.Result{}, err } - return plugin.Result{ - Label: to, - Events: events, - Rejected: rejected, - Baselines: []plugin.Spec{ - plugin.Baseline(c.API, from, from, c.URL(from), oldContent, true, now), - plugin.Baseline(c.API, to, to, c.URL(to), newContent, true, now), - }, - }, nil + return plugin.Result{Label: to.Version.Ref, Events: events, Rejected: rejected}, nil } +var _ plugin.Versioned = Plugin{} + // latestRef asks GitHub for the catalog repo's newest commit. func (p Plugin) latestRef(ctx context.Context, env plugin.Env) (string, error) { sha, err := github.Head(ctx, env.Get, p.Catalog.RefsURL) @@ -173,7 +178,7 @@ func (p Plugin) latestRef(ctx context.Context, env plugin.Env) (string, error) { // events diffs two parsed snapshots into events. oldContent is empty on a // plugin's first run (no baseline yet): diffing against no snapshot reports // nothing, the same as an unchanged one. -func (p Plugin) events(oldContent, newContent []byte, from, to string, now time.Time) ([]event.EventV2, []error, error) { +func (p Plugin) events(oldContent, newContent []byte, from, to string, now time.Time) ([]event.Event, []error, error) { c := p.Catalog newEntries, err := parse(newContent) if err != nil { @@ -187,14 +192,14 @@ func (p Plugin) events(oldContent, newContent []byte, from, to string, now time. } } - var events []event.EventV2 + var events []event.Event var rejected []error for _, name := range removed(oldEntries, newEntries) { subject := event.Subject{ Type: event.SubjectPackageRelease, Ecosystem: c.Ecosystem, Package: c.Package, Change: event.PackageRemovedSymbol, Symbols: []string{name}, } - e := event.EventV2{ + e := event.Event{ API: c.API, Version: to, PreviousVersion: from, ChangeType: event.ChangeTypeBreaking, Breaking: true, @@ -205,7 +210,7 @@ func (p Plugin) events(oldContent, newContent []byte, from, to string, now time. Confidence: 1.0, DetectedAt: now, } - e.Fingerprint = event.FingerprintV2(e.API, e.Version, e.ChangeType, subject, "") + e.Fingerprint = event.Fingerprint(e.API, e.Version, e.ChangeType, subject, "") if err := e.Validate(); err != nil { rejected = append(rejected, fmt.Errorf("%s: %w", name, err)) continue diff --git a/plugins/catalog/catalog_test.go b/plugins/catalog/catalog_test.go index ad636b2..e904e23 100644 --- a/plugins/catalog/catalog_test.go +++ b/plugins/catalog/catalog_test.go @@ -33,20 +33,20 @@ func fixturePages() kittest.Pages { } } -// The golden test and the replay fixture in one: testdata/redis-doc-cc0427b.json +// The golden test and the pair fixture in one: testdata/redis-doc-cc0427b.json // and redis-doc-06f3598.json are real, trimmed excerpts of redis-doc's // commands.json at those two commits (checked 2026-11-18). Between them, // FUNCTION CREATE and FUNCTION INFO disappear, FUNCTION LOAD appears, and GET -// (an unrelated, long-lived command) is unchanged. This is the pair the -// plugin's Replay from oldRef to newRef recreates. -func TestReplayRecreatesTheRealFunctionCommandRemoval(t *testing.T) { +// (an unrelated, long-lived command) is unchanged: the version pair +// oldRef → newRef, read with ReadAt and Extract. +func TestPairRecreatesTheRealFunctionCommandRemoval(t *testing.T) { ctx := context.Background() s := kittest.NewMem() e := env(s, fixturePages(), t) - rejected, err := kittest.Replay(ctx, e, s, Plugin{Catalog: Redis}, oldRef, newRef) + rejected, err := kittest.Pair(ctx, e, s, Plugin{Catalog: Redis}, oldRef, newRef) if err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + t.Fatalf("pair: rejected=%v err=%v", rejected, err) } events, err := s.All() @@ -75,8 +75,8 @@ func TestReplayRecreatesTheRealFunctionCommandRemoval(t *testing.T) { // Acceptance criteria: every event carries source_url and a non-empty // source_excerpt, is marked breaking, and is placed on the real refs. for _, ev := range events { - if ev.API != "redis" || ev.Version != newRef || ev.PreviousVersion != oldRef { - t.Errorf("event %v: api=%s version=%s previous_version=%s, want redis %s from %s", + if ev.API != "redis/commands" || ev.Version != newRef || ev.PreviousVersion != oldRef { + t.Errorf("event %v: api=%s version=%s previous_version=%s, want redis/commands %s from %s", ev.Subject.Symbols, ev.API, ev.Version, ev.PreviousVersion, newRef, oldRef) } if ev.ChangeType != event.ChangeTypeBreaking || !ev.Breaking { @@ -90,12 +90,12 @@ func TestReplayRecreatesTheRealFunctionCommandRemoval(t *testing.T) { } } - // Replaying the same pair again must not duplicate the events. - if _, err := kittest.Replay(ctx, e, s, Plugin{Catalog: Redis}, oldRef, newRef); err != nil { - t.Fatalf("second replay: %v", err) + // Reading the same pair again must not duplicate the events. + if _, err := kittest.Pair(ctx, e, s, Plugin{Catalog: Redis}, oldRef, newRef); err != nil { + t.Fatalf("second read of the pair: %v", err) } if again, _ := s.All(); len(again) != len(events) { - t.Errorf("repeating the replay added events: %d -> %d", len(events), len(again)) + t.Errorf("reading the pair again added events: %d -> %d", len(events), len(again)) } } diff --git a/plugins/changelog/changelog.go b/plugins/changelog/changelog.go index 25bea03..d7bde86 100644 --- a/plugins/changelog/changelog.go +++ b/plugins/changelog/changelog.go @@ -1,5 +1,9 @@ -// Package changelog is the source plugin for a package's changelog file -// (CHANGELOG.md, CHANGES.rst, HISTORY.rst), read at a release's tag: one +// Package changelog is the kind for a changelog, with a parser for each +// shape: a package's changelog file in Markdown or reStructuredText (File; +// this file, parse.go, classify.go), or a vendor's machine-readable API +// changelog in JSON (Log; json.go). One Plugin reads either. +// +// A changelog file (CHANGELOG.md, CHANGES.rst, HISTORY.rst) is read at a release's tag: one // change event per bullet that plainly removes, renames or deprecates names // code uses. The tag never changes, so its URL is the event's provenance (no // snapshot) and a rerun stores nothing new: the fingerprints dedupe. @@ -30,18 +34,29 @@ func init() { ID: "textual", Name: "Textual", Category: plugin.CategoryPackages, Homepage: "https://textual.textualize.io", Sources: []plugin.Source{{ ID: "textual", Layer: plugin.LayerPackage, Page: "providers/textual.md", - Watches: "Names removed, renamed or deprecated in each release, from the release's section of CHANGELOG.md at its tag", - URLs: []string{"https://github.com/Textualize/textual/blob/main/CHANGELOG.md", "https://pypi.org/project/textual/"}, - Plugin: Plugin{File: Textual}, + Watches: "Names removed, renamed or deprecated in each release, from the release's section of CHANGELOG.md at its tag", + URLs: []string{"https://github.com/Textualize/textual/blob/main/CHANGELOG.md", "https://pypi.org/project/textual/"}, + Packages: []string{"pypi:textual"}, + Plugin: Plugin{File: Textual}, }}, }) plugin.RegisterProvider(plugin.Provider{ ID: "urllib3", Name: "urllib3", Category: plugin.CategoryPackages, Homepage: "https://urllib3.readthedocs.io", Sources: []plugin.Source{{ ID: "urllib3", Layer: plugin.LayerPackage, Page: "providers/urllib3.md", - Watches: "Names removed or deprecated in each release, from the release's section of CHANGES.rst at its tag", - URLs: []string{"https://github.com/urllib3/urllib3/blob/main/CHANGES.rst", "https://pypi.org/project/urllib3/"}, - Plugin: Plugin{File: Urllib3}, + Watches: "Names removed or deprecated in each release, from the release's section of CHANGES.rst at its tag", + URLs: []string{"https://github.com/urllib3/urllib3/blob/main/CHANGES.rst", "https://pypi.org/project/urllib3/"}, + Packages: []string{"pypi:urllib3"}, + Plugin: Plugin{File: Urllib3}, + }}, + }) + plugin.RegisterProvider(plugin.Provider{ + ID: "mongodb", Name: "MongoDB", Category: plugin.CategoryDatabases, Homepage: "https://www.mongodb.com", + Sources: []plugin.Source{{ + ID: "atlas-admin-api", Layer: plugin.LayerAPI, Page: "providers/mongodb-atlas.md", + Watches: "Atlas Administration API versions deprecated and removed at their sunset date, per endpoint, from MongoDB's own API changelog", + URLs: []string{"https://github.com/mongodb/openapi/blob/main/changelog/changelog.json"}, + Plugin: Plugin{Log: MongoDBAtlas}, }}, }) } @@ -50,7 +65,8 @@ func init() { // read release by release: every version on the package registry, the file at // that release's tag (TagPrefix + version). Pinned (At), it is one release. type File struct { - Package string // the installed name and the events' api: "urllib3" + API string // the source id the events carry: "urllib3/urllib3" + Package string // the installed name: "urllib3" Ecosystem string // where its releases are listed: "pypi" Module string // the import name, stripped from a symbol's front: "urllib3" Repo string // owner/name on GitHub @@ -70,7 +86,7 @@ func (f File) At(release string) File { // v0.86.0: "## [0.86.0] - 2024-11-16", "### Removed", and "Breaking change:" // bullets under "### Changed"), tagged v. var Textual = File{ - Package: "textual", Ecosystem: "pypi", Module: "textual", + API: "textual/textual", Package: "textual", Ecosystem: "pypi", Module: "textual", Repo: "Textualize/textual", TagPrefix: "v", Path: "CHANGELOG.md", } @@ -78,7 +94,7 @@ var Textual = File{ // (2023-04-26)" over "=====", "Removed" and "Deprecated" over "-----"), // tagged . var Urllib3 = File{ - Package: "urllib3", Ecosystem: "pypi", Module: "urllib3", + API: "urllib3/urllib3", Package: "urllib3", Ecosystem: "pypi", Module: "urllib3", Repo: "urllib3/urllib3", Path: "CHANGES.rst", } @@ -147,18 +163,32 @@ func (f File) added(sections []Section) map[string]bool { return out } -// Plugin reads a package's changelog: release by release (ListVersions, -// ReadAt, Extract), or, with a pinned File, that one release. +// Plugin reads one changelog, in one of two shapes: set File for a +// Markdown or RST changelog (read release by release: ListVersions, ReadAt, +// Extract; or, pinned, that one release), or Log for a JSON one (read commit +// by commit: json.go). type Plugin struct { File File + Log Log } -func (p Plugin) Name() string { return p.File.Package } +// isLog is a JSON changelog. +func (p Plugin) isLog() bool { return p.Log.API != "" } + +func (p Plugin) Name() string { + if p.isLog() { + return p.Log.API + } + return p.File.API +} // Run reads the pinned release, or the newest one on the registry, and // stores its events. A release's tag never changes, so a rerun stores nothing // new: the fingerprints dedupe. func (p Plugin) Run(ctx context.Context, env plugin.Env) (plugin.Result, error) { + if p.isLog() { + return p.runLog(ctx, env) + } v := plugin.Version{ID: p.File.Release, Ref: p.File.Tag} if p.File.Tag == "" { vs, err := p.ListVersions(ctx, env) @@ -178,13 +208,16 @@ func (p Plugin) Run(ctx context.Context, env plugin.Env) (plugin.Result, error) if err != nil { return plugin.Result{}, err } - res.Baselines = []plugin.Spec{plugin.Baseline(p.File.Package, v.ID, v.Ref, to.SourceURL, to.Content, false, env.Now().UTC())} + res.Baselines = []plugin.Spec{plugin.Baseline(p.File.API, v.ID, v.Ref, to.SourceURL, to.Content, env.Now().UTC())} return res, nil } // ListVersions is every final release of the package on its registry, oldest // first, each read at TagPrefix + version; a pinned File has its one release. func (p Plugin) ListVersions(ctx context.Context, env plugin.Env) ([]plugin.Version, error) { + if p.isLog() { + return p.listLog(ctx, env) + } f := p.File if f.Tag != "" { return []plugin.Version{{ID: f.Release, Ref: f.Tag}}, nil @@ -210,6 +243,9 @@ func (p Plugin) ListVersions(ctx context.Context, env plugin.Env) ([]plugin.Vers // ReadAt fetches the changelog at the release's tag. func (p Plugin) ReadAt(ctx context.Context, env plugin.Env, v plugin.Version) (plugin.Snapshot, error) { + if p.isLog() { + return p.readLog(ctx, env, v) + } f := p.File f.Release, f.Tag = v.ID, v.Ref page, err := env.Get(ctx, f.URL()) @@ -224,6 +260,9 @@ func (p Plugin) ReadAt(ctx context.Context, env plugin.Env, v plugin.Version) (p // from's release. Releases are extracted pair by pair, so from is the release // right before to and to's section is everything between them. func (p Plugin) Extract(_ context.Context, env plugin.Env, from, to plugin.Snapshot) (plugin.Result, error) { + if p.isLog() { + return p.extractLog(env, from, to) + } f := p.File f.Release, f.Tag = to.Version.ID, to.Version.Ref heading, findings, err := f.Read(to.Content) @@ -231,7 +270,7 @@ func (p Plugin) Extract(_ context.Context, env plugin.Env, from, to plugin.Snaps return plugin.Result{}, fmt.Errorf("reading %s: %w", f.URL(), err) } now := env.Now().UTC() - var events []event.EventV2 + var events []event.Event var rejected []error for _, fd := range findings { if fd.Dropped != "" { @@ -243,8 +282,8 @@ func (p Plugin) Extract(_ context.Context, env plugin.Env, from, to plugin.Snaps Type: event.SubjectPackageRelease, Ecosystem: f.Ecosystem, Package: f.Package, Change: c.Change, Symbols: c.Symbols, Replacement: c.Replacement, } - e := event.EventV2{ - API: f.Package, + e := event.Event{ + API: f.API, Version: f.Release, PreviousVersion: from.Version.ID, ChangeType: c.ChangeType, @@ -257,7 +296,7 @@ func (p Plugin) Extract(_ context.Context, env plugin.Env, from, to plugin.Snaps Confidence: 1.0, DetectedAt: now, } - e.Fingerprint = event.FingerprintV2(e.API, e.Version, e.ChangeType, subject, "") + e.Fingerprint = event.Fingerprint(e.API, e.Version, e.ChangeType, subject, "") if err := e.Validate(); err != nil { rejected = append(rejected, fmt.Errorf("%s %s %v: %w", f.Package, f.Release, c.Symbols, err)) continue diff --git a/plugins/apichangelog/apichangelog.go b/plugins/changelog/json.go similarity index 66% rename from plugins/apichangelog/apichangelog.go rename to plugins/changelog/json.go index 271129f..dd340af 100644 --- a/plugins/apichangelog/apichangelog.go +++ b/plugins/changelog/json.go @@ -1,19 +1,22 @@ -// Package apichangelog is the source plugin for a vendor's machine-readable -// API changelog: a JSON file, kept in a repo, that lists per day each -// endpoint's changes per API version, each with a change code (oasdiff's) and -// whether it's backward compatible. MongoDB publishes one for the Atlas -// Administration API. +// The JSON parser: a vendor's machine-readable API changelog, a JSON file +// kept in a repo that lists per day each endpoint's changes per API +// version, each with a change code (oasdiff's) and whether it's backward +// compatible. MongoDB publishes one for the Atlas Administration API. // // It reads only an endpoint's life cycle, in the vendor's own words: an API // version deprecated (`deprecation`), unless the vendor reactivates it later, -// and an API version removed at its sunset (`breaking`). The rest of the changelog is property-level, and the vendor's -// "not backward compatible" there is broad (a response enum gaining a value -// counts), so it isn't read: precision over recall. +// and an API version removed at its sunset (`breaking`). The rest of the +// changelog is property-level, and the vendor's "not backward compatible" +// there is broad (a response enum gaining a value counts), so it isn't read: +// precision over recall. // -// The file is read at the commit that last changed it, whose URL never -// changes, so that URL is the events' provenance (no snapshot). Every run -// reads the whole file; the fingerprints dedupe. -package apichangelog +// Its versions are the commits that changed the file, whose URLs never +// change, so a commit's URL is the events' provenance (no snapshot). A pair +// of commits gives the findings the newer one has and the older one didn't; +// a plain run reads the whole file at the newest commit, and the +// fingerprints dedupe. + +package changelog import ( "bytes" @@ -27,23 +30,12 @@ import ( "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" + "github.com/patch-it-dev/patch-it-plugins/core/versions" ) -func init() { - plugin.RegisterProvider(plugin.Provider{ - ID: "mongodb", Name: "MongoDB", Category: plugin.CategoryDatabases, Homepage: "https://www.mongodb.com", - Sources: []plugin.Source{{ - ID: "atlas-admin-api", Layer: plugin.LayerAPI, Page: "providers/mongodb-atlas.md", - Watches: "Atlas Administration API versions deprecated and removed at their sunset date, per endpoint, from MongoDB's own API changelog", - URLs: []string{"https://github.com/mongodb/openapi/blob/main/changelog/changelog.json"}, - Plugin: Plugin{Log: MongoDBAtlas}, - }}, - }) -} - // Log is one vendor's changelog file. type Log struct { - API string // the events' api: "mongodb-atlas" + API string // the source id the events carry: "mongodb/atlas-admin-api" Vendor string // for sentences: "MongoDB" Name string // the API, for sentences: "Atlas Administration API" Repo string // owner/name on GitHub @@ -58,7 +50,7 @@ type Log struct { // is built from it). Atlas versions each resource by date (`2023-01-01`), // chosen per request in the Accept header. var MongoDBAtlas = Log{ - API: "mongodb-atlas", Vendor: "MongoDB", Name: "Atlas Administration API", + API: "mongodb/atlas-admin-api", Vendor: "MongoDB", Name: "Atlas Administration API", Repo: "mongodb/openapi", Path: "changelog/changelog.json", } @@ -112,8 +104,8 @@ var lifecycle = map[string]event.ChangeType{ // at 2024-05-30 was deprecated on 2024-06-25 and reactivated the next day. const reactivated = "endpoint-reactivated" -// Finding is one life-cycle change. -type Finding struct { +// LogFinding is one life-cycle change. +type LogFinding struct { ChangeType event.ChangeType Date string // the changelog's day Operation string // "GET /api/atlas/v2/groups/{groupId}/clusters" @@ -132,7 +124,7 @@ type Finding struct { // same endpoint and version shows up again on a later day with anything but // another removal (none of the 38 in the file on 2026-11-18 does). The excerpt is the change as the file writes // it, whitespace aside. -func (l Log) Read(b []byte) ([]Finding, error) { +func (l Log) Read(b []byte) ([]LogFinding, error) { var days []day if err := json.Unmarshal(b, &days); err != nil { return nil, fmt.Errorf("not a changelog: %w", err) @@ -142,7 +134,7 @@ func (l Log) Read(b []byte) ([]Finding, error) { } type item struct { seq int - f Finding + f LogFinding } deprecated := map[string]item{} // by operation and version, until reactivated removed := map[string]item{} @@ -176,7 +168,7 @@ func (l Log) Read(b []byte) ([]Finding, error) { if err := json.Compact(&ex, raw); err != nil { return nil, err } - f := Finding{ + f := LogFinding{ ChangeType: ct, Date: d.Date, Operation: op, Version: v.Version, Code: c.ChangeCode, Pointer: fmt.Sprintf("/%d/paths/%d/versions/%d/changes/%d", di, pi, vi, ci), Excerpt: ex.String(), @@ -201,33 +193,25 @@ func (l Log) Read(b []byte) ([]Finding, error) { all = append(all, it) } sort.Slice(all, func(i, j int) bool { return all[i].seq < all[j].seq }) - out := make([]Finding, len(all)) + out := make([]LogFinding, len(all)) for i, it := range all { out[i] = it.f } return out, nil } -// Plugin reads one vendor's changelog. -type Plugin struct { - Log Log -} - -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) { +// runLog reads the file at the newest commit that changed it. +func (p Plugin) runLog(ctx context.Context, env plugin.Env) (plugin.Result, error) { l := p.Log sha, err := github.LatestCommit(ctx, env.Get, l.CommitsURL()) if err != nil { return plugin.Result{}, fmt.Errorf("looking up %s's newest changelog commit (%s in %s): %w", l.API, l.Path, l.Repo, err) } - url := l.URL(sha) - page, err := env.Get(ctx, url) + to, err := p.readLog(ctx, env, plugin.Version{ID: sha, Ref: sha}) if err != nil { - return plugin.Result{}, fmt.Errorf("fetching %s: %w", url, err) + return plugin.Result{}, err } - last, same, err := kit.Unchanged(env, l.API, page) + last, same, err := kit.Unchanged(env, l.API, to.Content) if err != nil { return plugin.Result{}, err } @@ -235,44 +219,88 @@ func (p Plugin) Run(ctx context.Context, env plugin.Env) (plugin.Result, error) log.Printf("%s: no change since %s", l.API, last.SourceURL) return plugin.Result{}, nil } - findings, err := l.Read(page) + res, err := p.extractLog(env, plugin.Snapshot{}, to) + if err != nil { + return plugin.Result{}, err + } + res.Baselines = []plugin.Spec{plugin.Baseline(l.API, sha, sha, to.SourceURL, to.Content, env.Now().UTC())} + return res, nil +} + +// listLog is every commit that changed the file, oldest first: the ID is +// the commit's date, the Ref its SHA. +func (p Plugin) listLog(ctx context.Context, env plugin.Env) ([]plugin.Version, error) { + return versions.GitHubCommits(ctx, env.Get, p.Log.Repo, p.Log.Path) +} + +// readLog fetches the file at the commit v.Ref. +func (p Plugin) readLog(ctx context.Context, env plugin.Env, v plugin.Version) (plugin.Snapshot, error) { + url := p.Log.URL(v.Ref) + page, err := env.Get(ctx, url) if err != nil { - return plugin.Result{}, fmt.Errorf("reading %s: %w", url, err) + return plugin.Snapshot{}, fmt.Errorf("fetching %s: %w", url, err) } + return plugin.Snapshot{Version: v, Content: page, SourceURL: url}, nil +} +// extractLog is an event per life-cycle change that stands at to and didn't +// at from (every one, when from is zero). The events are about the +// endpoint's API version, so they carry that version, not the commit's. +func (p Plugin) extractLog(env plugin.Env, from, to plugin.Snapshot) (plugin.Result, error) { + l := p.Log + findings, err := l.Read(to.Content) + if err != nil { + return plugin.Result{}, fmt.Errorf("reading %s: %w", to.SourceURL, err) + } + if !from.IsZero() { + before, err := l.Read(from.Content) + if err != nil { + return plugin.Result{}, fmt.Errorf("reading %s: %w", from.SourceURL, err) + } + had := map[string]bool{} + for _, f := range before { + had[f.key()] = true + } + kept := findings[:0:0] + for _, f := range findings { + if !had[f.key()] { + kept = append(kept, f) + } + } + findings = kept + } now := env.Now().UTC() - var events []event.EventV2 + var events []event.Event var rejected []error for _, f := range findings { - e := event.EventV2{ + e := event.Event{ API: l.API, Version: f.Version, ChangeType: f.ChangeType, Breaking: f.ChangeType == event.ChangeTypeBreaking, - Subject: event.Subject{Type: event.SubjectAPIOperation, Kind: event.AffectedKindOperation, Side: event.SideRequest, Operation: f.Operation}, - Description: describe(l, f), - SourceURL: url, + Subject: event.Subject{Type: event.SubjectAPIOperation, Kind: event.KindOperation, Side: event.SideRequest, Operation: f.Operation}, + Description: describeLog(l, f), + SourceURL: to.SourceURL, SourcePointer: f.Pointer, SourceExcerpt: f.Excerpt, Confidence: 1.0, DetectedAt: now, } - e.Fingerprint = event.FingerprintV2(e.API, e.Version, e.ChangeType, e.Subject, "") + e.Fingerprint = event.Fingerprint(e.API, e.Version, e.ChangeType, e.Subject, "") if err := e.Validate(); err != nil { rejected = append(rejected, fmt.Errorf("%s %s %s: %w", l.API, f.Operation, f.Version, err)) continue } events = append(events, e) } - return plugin.Result{ - Label: url, - Events: events, - Rejected: rejected, - Baselines: []plugin.Spec{plugin.Baseline(l.API, sha, sha, url, page, false, now)}, - }, nil + return plugin.Result{Label: to.SourceURL, Events: events, Rejected: rejected}, nil } -func describe(l Log, f Finding) string { +// key is what makes two findings the same change: an endpoint's API version +// deprecated, or removed. +func (f LogFinding) key() string { return string(f.ChangeType) + " " + f.Operation + " " + f.Version } + +func describeLog(l Log, f LogFinding) string { switch f.ChangeType { case event.ChangeTypeBreaking: return fmt.Sprintf("%s %s, API version %s, removed on %s (%s's changelog, %s).", l.Name, f.Operation, f.Version, f.Date, l.Vendor, f.Code) diff --git a/plugins/apichangelog/apichangelog_test.go b/plugins/changelog/json_test.go similarity index 78% rename from plugins/apichangelog/apichangelog_test.go rename to plugins/changelog/json_test.go index 21a0eea..c00d89a 100644 --- a/plugins/apichangelog/apichangelog_test.go +++ b/plugins/changelog/json_test.go @@ -1,7 +1,9 @@ -package apichangelog +package changelog import ( + "context" "encoding/json" + "fmt" "reflect" "strconv" "strings" @@ -9,33 +11,34 @@ import ( "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" ) const ( - latestSHA = "c0f99ca9145e5aa74d08ae4451020857e93b5f28" // 2026-11-18 20:15 UTC, "Release API Changelog" - fixture = "testdata/mongodb-atlas-changelog-c0f99ca9.json" + atlasSHA = "c0f99ca9145e5aa74d08ae4451020857e93b5f28" // 2026-11-18 20:15 UTC, "Release API Changelog" + atlasFixture = "testdata/mongodb-atlas-changelog-c0f99ca9.json" ) // saved serves the commits lookup and the changelog at that commit. -func saved(commits, sha, file string) kittest.Pages { +func savedLog(commits, sha, file string) kittest.Pages { return kittest.Pages{MongoDBAtlas.CommitsURL(): commits, MongoDBAtlas.URL(sha): file} } // The golden test: MongoDB's changelog as released at c0f99ca9 (2026-11-18), // with every change this plugin doesn't read replaced by {} so that every // pointer is the one in the real file (testdata/README.md). -func TestGolden(t *testing.T) { - pages := saved("testdata/commits-c0f99ca9.json", latestSHA, fixture) +func TestJSONGolden(t *testing.T) { + pages := savedLog("testdata/commits-c0f99ca9.json", atlasSHA, atlasFixture) got := kittest.Ingest(t, Plugin{Log: MongoDBAtlas}, pages) kittest.Golden(t, "testdata/golden/mongodb-atlas.json", got) // Every event cites the pinned file, and its excerpt is the change its // pointer names there. for _, e := range got { - if e.SourceURL != MongoDBAtlas.URL(latestSHA) { + if e.SourceURL != MongoDBAtlas.URL(atlasSHA) { t.Errorf("%s: source_url %s", e.Subject.Operation, e.SourceURL) } - if node := nodeAt(t, fixture, e.SourcePointer); !sameJSON(node, e.SourceExcerpt) { + if node := nodeAt(t, atlasFixture, e.SourcePointer); !sameJSON(node, e.SourceExcerpt) { t.Errorf("%s: excerpt %s, but %s holds %s", e.Subject.Operation, e.SourceExcerpt, e.SourcePointer, node) } } @@ -45,7 +48,7 @@ func TestGolden(t *testing.T) { // 2023-01-01 of the shared-tier ("tenant") backup endpoints, "as it has // reached its sunset date '2026-01-22'". func TestTenantBackupSunset(t *testing.T) { - fs, err := MongoDBAtlas.Read(kittest.Read(t, fixture)) + fs, err := MongoDBAtlas.Read(kittest.Read(t, atlasFixture)) if err != nil { t.Fatal(err) } @@ -93,9 +96,9 @@ func TestPropertyChangesMakeNoEvent(t *testing.T) { } } if notBC != 23 { - t.Fatalf("the fixture has %d changes not backward compatible, want 23", notBC) + t.Fatalf("the atlasFixture has %d changes not backward compatible, want 23", notBC) } - if got := kittest.Ingest(t, Plugin{Log: MongoDBAtlas}, saved("testdata/commits-day.json", sha, file)); len(got) != 0 { + if got := kittest.Ingest(t, Plugin{Log: MongoDBAtlas}, savedLog("testdata/commits-day.json", sha, file)); len(got) != 0 { for _, e := range got { t.Logf("got: %s", e.Description) } @@ -110,7 +113,7 @@ func TestPropertyChangesMakeNoEvent(t *testing.T) { func TestReactivationWithdrawsTheDeprecation(t *testing.T) { // The saved file does hold those deprecations and reactivations. var days []day - if err := json.Unmarshal(kittest.Read(t, fixture), &days); err != nil { + if err := json.Unmarshal(kittest.Read(t, atlasFixture), &days); err != nil { t.Fatal(err) } codes := map[string]int{} @@ -130,9 +133,9 @@ func TestReactivationWithdrawsTheDeprecation(t *testing.T) { } } if codes["endpoint-deprecated"] == 0 || codes["endpoint-reactivated"] == 0 { - t.Fatalf("the fixture's clusters 2024-05-30 entries are %v: they no longer show a reactivation", codes) + t.Fatalf("the atlasFixture's clusters 2024-05-30 entries are %v: they no longer show a reactivation", codes) } - fs, err := MongoDBAtlas.Read(kittest.Read(t, fixture)) + fs, err := MongoDBAtlas.Read(kittest.Read(t, atlasFixture)) if err != nil { t.Fatal(err) } @@ -146,7 +149,7 @@ func TestReactivationWithdrawsTheDeprecation(t *testing.T) { // Deprecated, reactivated, deprecated again: one deprecation, the second. // Deprecated, then removed: both. And "api path removed without deprecation" // isn't read (its one real entry was an endpoint that stayed). -func TestLifeCycleReplay(t *testing.T) { +func TestLifeCycleInOrder(t *testing.T) { ch := func(code string) string { return `{"change":"x","changeCode":"` + code + `","backwardCompatible":true}` } @@ -241,10 +244,6 @@ func TestReadRefusesWhatIsntAChangelog(t *testing.T) { } } -func TestRegistersItself(t *testing.T) { - kittest.Registered(t, Plugin{Log: MongoDBAtlas}) -} - func sameJSON(a, b string) bool { var x, y any if json.Unmarshal([]byte(a), &x) != nil || json.Unmarshal([]byte(b), &y) != nil { @@ -277,3 +276,49 @@ func nodeAt(t *testing.T, file, pointer string) string { b, _ := json.Marshal(node) return string(b) } + +// Three commits of a JSON changelog are three versions, oldest first, and +// two consecutive pairs; each pair gives only what the newer commit added. +func TestJSONChangelogPairByPair(t *testing.T) { + sha := func(n int) string { return fmt.Sprintf("%040d", n) } + pages := kittest.Pages{ + "https://api.github.com/repos/mongodb/openapi/commits?path=changelog%2Fchangelog.json&per_page=100&page=1": "testdata/log-history/commits.json", + } + for n := 1; n <= 3; n++ { + pages[MongoDBAtlas.URL(sha(n))] = fmt.Sprintf("testdata/log-history/changelog-%d.json", n) + } + env := kittest.Env(t, pages) + ctx := context.Background() + p := Plugin{Log: MongoDBAtlas} + vs, err := p.ListVersions(ctx, env) + if err != nil { + t.Fatal(err) + } + var ids []string + for _, v := range vs { + ids = append(ids, v.ID) + } + if got := strings.Join(ids, " "); got != "2026-01-01 2026-02-01 2026-03-01" { + t.Fatalf("versions %s", got) + } + var got []string + snaps := make([]plugin.Snapshot, len(vs)) + for i, v := range vs { + if snaps[i], err = p.ReadAt(ctx, env, v); err != nil { + t.Fatal(err) + } + } + for _, pair := range [][2]int{{0, 1}, {1, 2}} { + res, err := p.Extract(ctx, env, snaps[pair[0]], snaps[pair[1]]) + if err != nil || len(res.Rejected) > 0 { + t.Fatalf("%v %v", err, res.Rejected) + } + for _, e := range res.Events { + got = append(got, vs[pair[1]].ID+": "+e.Subject.Operation+" "+string(e.ChangeType)) + } + } + want := "2026-02-01: GET /b deprecation; 2026-03-01: GET /a breaking" + if strings.Join(got, "; ") != want { + t.Errorf("pairs gave %q, want %q", strings.Join(got, "; "), want) + } +} diff --git a/plugins/changelog/registered_test.go b/plugins/changelog/registered_test.go index 0a182c8..df91f1e 100644 --- a/plugins/changelog/registered_test.go +++ b/plugins/changelog/registered_test.go @@ -10,4 +10,5 @@ func TestRegistersItself(t *testing.T) { for _, f := range []File{Textual0860, Urllib3200} { kittest.Registered(t, Plugin{File: f}) } + kittest.Registered(t, Plugin{Log: MongoDBAtlas}) } diff --git a/plugins/changelog/testdata/README.md b/plugins/changelog/testdata/README.md index 8196285..305bf8e 100644 --- a/plugins/changelog/testdata/README.md +++ b/plugins/changelog/testdata/README.md @@ -14,3 +14,19 @@ golden files under `golden/` are what the plugin stores from them | File | URL | Saved | License | Use | |---|---|---|---|---| | `pypi-urllib3-excerpt.json` | https://pypi.org/pypi/urllib3/json (shape only) | written for the test, 2026-11-20 | not a saved copy: four releases in the shape of PyPI's JSON API (`releases` → files with `upload_time_iso_8601`, `yanked`), dates approximate, a pre-release among them | for the version-listing test only (ListVersions, consecutive pairs); no golden reads it | + +## JSON changelogs + +Read with `Plugin{Log: ...}` (json.go); `golden/mongodb-atlas.json` is what it stores from the first file. + +| File | URL | Saved | License | Quote | +|---|---|---|---|---| +| `mongodb-atlas-changelog-c0f99ca9.json` | https://raw.githubusercontent.com/mongodb/openapi/c0f99ca9145e5aa74d08ae4451020857e93b5f28/changelog/changelog.json (the "Release API Changelog" commit of 2026-11-18 20:15 UTC; the same file as `main` on 2026-11-19) | 2026-11-19 | Apache-2.0 (mongodb/openapi) | "endpoint with API Version '2023-01-01' was removed as it has reached its sunset date '2026-01-22'" | +| `mongodb-atlas-changelog-2026-11-18-day.json` | The same file's newest day (`2026-11-18`), kept whole and unchanged: the drop test | 2026-11-19 | Apache-2.0 (mongodb/openapi) | `"changeCode": "request-property-one-of-removed"`, `"backwardCompatible": false` | +| `commits-c0f99ca9.json`, `commits-day.json` | Stand-ins for `https://api.github.com/repos/mongodb/openapi/commits?path=changelog/changelog.json&per_page=1`, keeping only the field the plugin reads (`sha`) | 2026-11-19 | n/a (test fixtures) | | + +**Trimmed, positions kept:** the real file is 10 MB. `mongodb-atlas-changelog-c0f99ca9.json` keeps every day, endpoint, API version and change in place. Every change the plugin doesn't read is replaced by `{}`: all but the three life-cycle codes and `endpoint-reactivated`. So is every endpoint or version left with none. So every JSON pointer in `golden/mongodb-atlas.json` names the same change in the real file. The 105 kept changes are copied unchanged. The plugin reads exactly the same 81 findings from this copy as from the real file (checked when the copy was made). The copy is re-indented. + +| File | URL | Saved | License | Use | +|---|---|---|---|---| +| `log-history/commits.json`, `log-history/changelog-{1,2,3}.json` | Stand-ins for the GitHub commits list of `changelog/changelog.json` and the file at three commits, in the real file's shape | written for the test, 2026-11-20 | n/a (test fixtures) | for the pair-by-pair test only (three versions, two pairs); no golden reads them | diff --git a/plugins/apichangelog/testdata/commits-c0f99ca9.json b/plugins/changelog/testdata/commits-c0f99ca9.json similarity index 100% rename from plugins/apichangelog/testdata/commits-c0f99ca9.json rename to plugins/changelog/testdata/commits-c0f99ca9.json diff --git a/plugins/apichangelog/testdata/commits-day.json b/plugins/changelog/testdata/commits-day.json similarity index 100% rename from plugins/apichangelog/testdata/commits-day.json rename to plugins/changelog/testdata/commits-day.json diff --git a/plugins/apichangelog/testdata/golden/mongodb-atlas.json b/plugins/changelog/testdata/golden/mongodb-atlas.json similarity index 87% rename from plugins/apichangelog/testdata/golden/mongodb-atlas.json rename to plugins/changelog/testdata/golden/mongodb-atlas.json index 16b42fe..cacc1ea 100644 --- a/plugins/apichangelog/testdata/golden/mongodb-atlas.json +++ b/plugins/changelog/testdata/golden/mongodb-atlas.json @@ -1,8 +1,8 @@ [ { "id": 1, - "fingerprint": "sha256:50ef7eaf307f672feed4318a5eff83b1ca03e59cdf359968942902f1bc678654", - "api": "mongodb-atlas", + "fingerprint": "sha256:cc24f6195c643b2ebaa07b4ede7d4dfe00bdcb0874c1347e01e017af1fc8fb6f", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "deprecation", "breaking": false, @@ -21,8 +21,8 @@ }, { "id": 2, - "fingerprint": "sha256:e89692319125245d7c80793b7eb504058bcbf8f488e236c5fbb5e040548da6cb", - "api": "mongodb-atlas", + "fingerprint": "sha256:58fc100be70cb15a7e2c83d5977433fc552dcbd271eed4bca7ad55026d72e3d8", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "deprecation", "breaking": false, @@ -41,8 +41,8 @@ }, { "id": 3, - "fingerprint": "sha256:dea2f243f988750bb33e958845f0f4a024e4eb38c4b13f1900b98168e3f74b57", - "api": "mongodb-atlas", + "fingerprint": "sha256:f1a7c1dde961ea7c2da23e52e9a789b096755da256c4f07bde16ab26448e7db5", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "deprecation", "breaking": false, @@ -61,8 +61,8 @@ }, { "id": 4, - "fingerprint": "sha256:f4789d649ddc19243976e6eb6444fcc2203092164ec1d3e439971b3c48c5386c", - "api": "mongodb-atlas", + "fingerprint": "sha256:f912840ec1cdfbde49c8958870be43bf49c4c740308434e1176bd3b9a8a8cd0a", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "deprecation", "breaking": false, @@ -81,8 +81,8 @@ }, { "id": 5, - "fingerprint": "sha256:19c4e00f9bd462ee470d63241dcaa7e6f413857fd9201bad8cf608d76afadbcf", - "api": "mongodb-atlas", + "fingerprint": "sha256:d86286f29ec943830ed073221731f182bbc6402413fc976d09384abf2adf3553", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "deprecation", "breaking": false, @@ -101,8 +101,8 @@ }, { "id": 6, - "fingerprint": "sha256:67f702f781d255a453e2d18add555de1dd91ce40b5a1222f4b3f319401145d7b", - "api": "mongodb-atlas", + "fingerprint": "sha256:2bc605298b2197c441f892d8b363b1d4d906a0fe5852c68a62f751f3f95d2ddc", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "deprecation", "breaking": false, @@ -121,8 +121,8 @@ }, { "id": 7, - "fingerprint": "sha256:5ca6cb3cc62d9bbc71e84ac4cd7735d33299f6473e536ef5fbdeea41053a7551", - "api": "mongodb-atlas", + "fingerprint": "sha256:af5b6044d2d4daafeee3bb3cfc171208ef70fb74d226a9c816bccedf5269b6c7", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "deprecation", "breaking": false, @@ -141,8 +141,8 @@ }, { "id": 8, - "fingerprint": "sha256:46899051fe514ee07d164c2979467dfafdea21d65e6dba23cca45b7ff9616626", - "api": "mongodb-atlas", + "fingerprint": "sha256:7f07e58557631d8d00e31a56f0c5ea611fb3a31675049aa344c08f87f93a3906", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "deprecation", "breaking": false, @@ -161,8 +161,8 @@ }, { "id": 9, - "fingerprint": "sha256:46680413445e23986eef34f9db57581aa73e12e0aa63646c327a8b33966c17f3", - "api": "mongodb-atlas", + "fingerprint": "sha256:ef82850143544d5fa34eb2c35dec55de7eea3f859b77bb4ec5a49a63ef251d4d", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "deprecation", "breaking": false, @@ -181,8 +181,8 @@ }, { "id": 10, - "fingerprint": "sha256:a1a0b7b37522ac72a47b7be98e75f77a669d9ee8a6b09006cf55f738efcf1599", - "api": "mongodb-atlas", + "fingerprint": "sha256:c8e80b8e19b699e5a4419b8ad98140959520fbe6f66a1c24672d1793e9457a09", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "deprecation", "breaking": false, @@ -201,8 +201,8 @@ }, { "id": 11, - "fingerprint": "sha256:7f6cd26e2522029635a6ecadd24701f962f47df8f5036c1ba32f0323d84028b8", - "api": "mongodb-atlas", + "fingerprint": "sha256:bfb77e886c515a27e002946c9dfe495a44612c21c33d545acb72f5477af7f53c", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "deprecation", "breaking": false, @@ -221,8 +221,8 @@ }, { "id": 12, - "fingerprint": "sha256:6bb5f654f1469098b227606ea2c16afecf39e23236b0c84a9003f7a98da9e067", - "api": "mongodb-atlas", + "fingerprint": "sha256:8bb4a901d1c83e82e67c4accbdf2ee67e3fe170d29ba289835a9e68e2f5558b3", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "deprecation", "breaking": false, @@ -241,8 +241,8 @@ }, { "id": 13, - "fingerprint": "sha256:619ee5f02d8f470115a668894c73e84afabf0b73712b88719fd034912283cebd", - "api": "mongodb-atlas", + "fingerprint": "sha256:92d94ba56f6811cc4dad18ede386020e893f66ff9ff9b28f6993e4677ea7be8d", + "api": "mongodb/atlas-admin-api", "version": "2023-02-01", "change_type": "deprecation", "breaking": false, @@ -261,8 +261,8 @@ }, { "id": 14, - "fingerprint": "sha256:6d41076ed7a4d69f43173d15235aed71a9bed14a467e6afb2d78fc73c3ae1150", - "api": "mongodb-atlas", + "fingerprint": "sha256:665bf236dcb1319e2cd5c5da8a271bb0d235917d99e7d9384b7730f35cf9b80f", + "api": "mongodb/atlas-admin-api", "version": "2023-02-01", "change_type": "deprecation", "breaking": false, @@ -281,8 +281,8 @@ }, { "id": 15, - "fingerprint": "sha256:e677922ed71b6fa1309859291b22e7fcd83900a4e713e62576760b18e2a37a40", - "api": "mongodb-atlas", + "fingerprint": "sha256:f3fc7367c663e20fd644b6b96befb1cf5d2185dd3cefab1092897f488580cb50", + "api": "mongodb/atlas-admin-api", "version": "2023-02-01", "change_type": "deprecation", "breaking": false, @@ -301,8 +301,8 @@ }, { "id": 16, - "fingerprint": "sha256:3409590c0cb537abe2844ebd3e1a419ac3ed3a867af1aa53a42c5587b026ad9b", - "api": "mongodb-atlas", + "fingerprint": "sha256:ca95618f62b1986840a47ea36d5ff501008d104abb52318a1af6ab1f847d86d8", + "api": "mongodb/atlas-admin-api", "version": "2023-02-01", "change_type": "deprecation", "breaking": false, @@ -321,8 +321,8 @@ }, { "id": 17, - "fingerprint": "sha256:1cf20285e31ba739ba8323ebd0a83338d211cf6085d92a72e52b5d04ed2ab459", - "api": "mongodb-atlas", + "fingerprint": "sha256:9c307d0bb3ce60d32a75da2afa0555d1233500095be5f51e9c440b49b6f0098d", + "api": "mongodb/atlas-admin-api", "version": "2023-11-15", "change_type": "deprecation", "breaking": false, @@ -341,8 +341,8 @@ }, { "id": 18, - "fingerprint": "sha256:fa893cc89e9484c23596401e9c6310933d44cec878600fe13e2cd3593195129c", - "api": "mongodb-atlas", + "fingerprint": "sha256:dcecedf2e09ebd4a3156b58b05d495c5c4074af97cbd044a06cb9deffaa5eaa9", + "api": "mongodb/atlas-admin-api", "version": "2023-11-15", "change_type": "deprecation", "breaking": false, @@ -361,8 +361,8 @@ }, { "id": 19, - "fingerprint": "sha256:dad53552c64ff83dcf3982d94fc35836e193387b19eff06db98d33f2a4a557c8", - "api": "mongodb-atlas", + "fingerprint": "sha256:160f906532581397e3ebddda5b1b7f056509ae3def7884dd6a9ede41a5f493cc", + "api": "mongodb/atlas-admin-api", "version": "2024-05-30", "change_type": "deprecation", "breaking": false, @@ -381,8 +381,8 @@ }, { "id": 20, - "fingerprint": "sha256:4242099b4346f85c168c78d56530b0e1f90c6bc6273294c59f84d91bf7857916", - "api": "mongodb-atlas", + "fingerprint": "sha256:627be9a47ff6458c73002e89125b40400721e03603963ac478905deee028d8d3", + "api": "mongodb/atlas-admin-api", "version": "2024-05-30", "change_type": "deprecation", "breaking": false, @@ -401,8 +401,8 @@ }, { "id": 21, - "fingerprint": "sha256:1afe4f94a3cce7183aef8c1d6e21032f00f7b2ce1131842b646a584f19c942b9", - "api": "mongodb-atlas", + "fingerprint": "sha256:af242c9e3aae3b5ba5489753c4ecc410ce889cf05fe4f1b1c1fe1a840bb25f2d", + "api": "mongodb/atlas-admin-api", "version": "2024-05-30", "change_type": "deprecation", "breaking": false, @@ -421,8 +421,8 @@ }, { "id": 22, - "fingerprint": "sha256:71f43a23b671e9daf1c2f222b2d3c8ea79c03fc2cbc1a5bbcb83db12337d590c", - "api": "mongodb-atlas", + "fingerprint": "sha256:30d873ec4a52dbb90d6d6fa49fc26e4bcb5e1e8e63601e9743737f002344084b", + "api": "mongodb/atlas-admin-api", "version": "2024-05-30", "change_type": "deprecation", "breaking": false, @@ -441,8 +441,8 @@ }, { "id": 23, - "fingerprint": "sha256:cc873b6a1a7aa887528d4855b37aa875e8d0f16eb3bca2b34ec10ae9f6ee357e", - "api": "mongodb-atlas", + "fingerprint": "sha256:ddb7365f8bf1b14590d796042c46bfc9a2e3fc12991561e835bf5bf9ebbd16f5", + "api": "mongodb/atlas-admin-api", "version": "2024-05-30", "change_type": "deprecation", "breaking": false, @@ -461,8 +461,8 @@ }, { "id": 24, - "fingerprint": "sha256:9fa2bc2f6047482a51e348d90f85206697611d410d1c50f5d672876ce842c2b0", - "api": "mongodb-atlas", + "fingerprint": "sha256:51fabed35665b97a15ad2af6ec7f4de6e7f6c8913b075fae8f3d2badd866f80c", + "api": "mongodb/atlas-admin-api", "version": "2024-08-05", "change_type": "deprecation", "breaking": false, @@ -481,8 +481,8 @@ }, { "id": 25, - "fingerprint": "sha256:4c43bffec1a1b6d75d88120ba84d88fe4b15f63af7968317b513476904974fa3", - "api": "mongodb-atlas", + "fingerprint": "sha256:cb70fc3369d62e371c873c7590d8e64a4aae64e2591e645811fe119eb2cc520c", + "api": "mongodb/atlas-admin-api", "version": "2024-08-05", "change_type": "deprecation", "breaking": false, @@ -501,8 +501,8 @@ }, { "id": 26, - "fingerprint": "sha256:32f76147eba78d0d68c2c3000f347dab77f79dfbd058d077d41907a2d3a5b992", - "api": "mongodb-atlas", + "fingerprint": "sha256:e2ce2e1195ccb2dec2f38d3e2aabd126ef5757e9807cdff3aa27a598fbfdd0e5", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -521,8 +521,8 @@ }, { "id": 27, - "fingerprint": "sha256:91ca0b855ef7e21507fb3566e1550ce8fa1546c341b1dcdeb6a0d5a0aa1cd69e", - "api": "mongodb-atlas", + "fingerprint": "sha256:bef9488df24c4837d134696508790c87450785aeb715017483aa4efce11a5920", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -541,8 +541,8 @@ }, { "id": 28, - "fingerprint": "sha256:411f855ffdfab7f911477ce957b11b5aab210836b348f690982dfd61e9146de9", - "api": "mongodb-atlas", + "fingerprint": "sha256:6f26729ebc2b23eb9cfbf54274a08b8a052333c332fd22ba1600353dd4cd5500", + "api": "mongodb/atlas-admin-api", "version": "2025-02-19", "change_type": "deprecation", "breaking": false, @@ -561,8 +561,8 @@ }, { "id": 29, - "fingerprint": "sha256:63de08074aa4fb46afcadde08c2cd4ff080ecf6de5ec38f24b054509f50c271a", - "api": "mongodb-atlas", + "fingerprint": "sha256:5cc945d7dfc328833dab035345f094a55b0056a6c4c9ebb8dee8d1e16212e7e4", + "api": "mongodb/atlas-admin-api", "version": "2025-02-19", "change_type": "deprecation", "breaking": false, @@ -581,8 +581,8 @@ }, { "id": 30, - "fingerprint": "sha256:44a13d91fbbb011d09ff9987a3209d4b20719ebf1647560a10a268d24ea1a0a8", - "api": "mongodb-atlas", + "fingerprint": "sha256:33e575770ae4ee93abc83c3297a204b9fac76804f78b5afdb9445087cc5a7ebc", + "api": "mongodb/atlas-admin-api", "version": "2025-02-19", "change_type": "deprecation", "breaking": false, @@ -601,8 +601,8 @@ }, { "id": 31, - "fingerprint": "sha256:cc8867400b2014bb76a4eb2ee3c6022ca905b4f12bf861995797088525a8dce4", - "api": "mongodb-atlas", + "fingerprint": "sha256:8de6ab83507db7269db3a639255a2068c387e9785875b2c21d1e7d995be7c482", + "api": "mongodb/atlas-admin-api", "version": "2025-02-19", "change_type": "deprecation", "breaking": false, @@ -621,8 +621,8 @@ }, { "id": 32, - "fingerprint": "sha256:0ab238669bee716ea8d4cec64ef439f6581792bb7bd36f52b2acf543f61d99d1", - "api": "mongodb-atlas", + "fingerprint": "sha256:542ae91c8f1ad44bf462d703f155afbaa85908ac86c09a6d4a4c93b756144e98", + "api": "mongodb/atlas-admin-api", "version": "2025-02-19", "change_type": "deprecation", "breaking": false, @@ -641,8 +641,8 @@ }, { "id": 33, - "fingerprint": "sha256:e31a4aed0ee30ac65ea435e9d158616cb780ddec4456000b7a011631c85b72a8", - "api": "mongodb-atlas", + "fingerprint": "sha256:d2b323f2d8dd032dd30e1646e666563a89226e1a0078c532e5139a348eaeed13", + "api": "mongodb/atlas-admin-api", "version": "2025-02-19", "change_type": "deprecation", "breaking": false, @@ -661,8 +661,8 @@ }, { "id": 34, - "fingerprint": "sha256:dd55ba070d997c95d749cbf99de28482abf1523af6d13941f291ecec8e3e542f", - "api": "mongodb-atlas", + "fingerprint": "sha256:5f6e8e3f099b05d54e52927c9c468842df69607f7a28c3fa86e3f1d0fdf8b86a", + "api": "mongodb/atlas-admin-api", "version": "2025-02-19", "change_type": "deprecation", "breaking": false, @@ -681,8 +681,8 @@ }, { "id": 35, - "fingerprint": "sha256:42879593863a7dc1aedfc565738307e0ac43d6b9df1a25c1ff1ae75b8b069db4", - "api": "mongodb-atlas", + "fingerprint": "sha256:690d31fcafd5209816ad6c16c0ed9199c7599bdba84872bdfa5b6b126238d985", + "api": "mongodb/atlas-admin-api", "version": "2025-02-19", "change_type": "deprecation", "breaking": false, @@ -701,8 +701,8 @@ }, { "id": 36, - "fingerprint": "sha256:5c39826bcf8a1e7b89d02e7184393a051ab979a694b886a8e509853c5fa361f5", - "api": "mongodb-atlas", + "fingerprint": "sha256:d146c472539b4b5494c7f9749a708129bad45aa22ebe8a966e2061f2d68a4c06", + "api": "mongodb/atlas-admin-api", "version": "2025-02-19", "change_type": "deprecation", "breaking": false, @@ -721,8 +721,8 @@ }, { "id": 37, - "fingerprint": "sha256:f56222e59c33af0df85f93982e17731a352995c3eef36a9ac9fc2020f7184de0", - "api": "mongodb-atlas", + "fingerprint": "sha256:9c3c5c4e3f219e8954c0f98003c889eb5b0ee10ddfa858a3350736b48e2a263e", + "api": "mongodb/atlas-admin-api", "version": "2025-02-19", "change_type": "deprecation", "breaking": false, @@ -741,8 +741,8 @@ }, { "id": 38, - "fingerprint": "sha256:e9189cd3bdbc215acb1076908c37f3d5f6433d7237edd71092e66c06de5c7e98", - "api": "mongodb-atlas", + "fingerprint": "sha256:58a98f24cdcd722bad12234a6e5d3d013f63f31b1f121670e93801e2a27713c0", + "api": "mongodb/atlas-admin-api", "version": "2025-02-19", "change_type": "deprecation", "breaking": false, @@ -761,8 +761,8 @@ }, { "id": 39, - "fingerprint": "sha256:7b5bbba472d7e1eda4277c6bdb501c46089e2a1d6643e455bea78658485db85e", - "api": "mongodb-atlas", + "fingerprint": "sha256:329a4a061813ba41a8e5e2ce063df7ce6542b48922730c70778e181a287ad576", + "api": "mongodb/atlas-admin-api", "version": "2025-02-19", "change_type": "deprecation", "breaking": false, @@ -781,8 +781,8 @@ }, { "id": 40, - "fingerprint": "sha256:ec397066f10e29a807ff5482499a1e0bfba612c006569950f6a65190c5d9d57f", - "api": "mongodb-atlas", + "fingerprint": "sha256:e5c8117858980a087db6a750044cc9be9ac1d70e6fa2921191d9affd006bb891", + "api": "mongodb/atlas-admin-api", "version": "2025-02-19", "change_type": "deprecation", "breaking": false, @@ -801,8 +801,8 @@ }, { "id": 41, - "fingerprint": "sha256:6f45d005e7a76d4125801aa194648161a5202993730527cce3d110f4a4f13190", - "api": "mongodb-atlas", + "fingerprint": "sha256:366c39d16e92feed3c2ad2eb125b18d547062da23306e4aeaa96c12446f723f3", + "api": "mongodb/atlas-admin-api", "version": "2025-02-19", "change_type": "deprecation", "breaking": false, @@ -821,8 +821,8 @@ }, { "id": 42, - "fingerprint": "sha256:a2d2f80b7f05c7247a8588a1c44f4b8d62e976691763f49f74d2ecf43e9e56d3", - "api": "mongodb-atlas", + "fingerprint": "sha256:4890187b0f4c5115a06d1b522f78d9c007ac952e2885a00a8096e3ea6b8ea8c6", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -841,8 +841,8 @@ }, { "id": 43, - "fingerprint": "sha256:6bbee9940ba8a7236704d2444c05feed0457a272bcedf08cf501f6191bd7fdc1", - "api": "mongodb-atlas", + "fingerprint": "sha256:f8dd816c9f01dc6dbe5812a32baf1ee83206fe4d4d1aed161d89ebde4ac146d8", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -861,8 +861,8 @@ }, { "id": 44, - "fingerprint": "sha256:63cb4f92c961bab0d93b68e763eaee78b4d88ed6a021a1695dac64e55921c68a", - "api": "mongodb-atlas", + "fingerprint": "sha256:63208e5db910ade6c6639860a329dcab961adf38accb6e17b11d4a0a2dca688c", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -881,8 +881,8 @@ }, { "id": 45, - "fingerprint": "sha256:beda0e8e02b2d2d29d40d535701112cbd3ffda08bd23d5ddf58901fda579571f", - "api": "mongodb-atlas", + "fingerprint": "sha256:9ab1025568f8c14c44bc5b398eb311331d92eda892182eaf7317ef692a3a1415", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -901,8 +901,8 @@ }, { "id": 46, - "fingerprint": "sha256:c559849c75e65a4883544df8d9d1af688d5f91b69657bcc5a78f54e6d0494207", - "api": "mongodb-atlas", + "fingerprint": "sha256:de768eabbd9ddc3f8f7137fbd7e0927f777a18862b48f438c2e94706bcb37b9f", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -921,8 +921,8 @@ }, { "id": 47, - "fingerprint": "sha256:0d8788bcd5ed94aa5c76deeb205ca5adf0e4b2012b74d7f79b3c5620eb5d683d", - "api": "mongodb-atlas", + "fingerprint": "sha256:e7e53fdccbfd094a9c4a8bb9cddfcfe2fc09b668ad0ec23db1e48419018c1f64", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -941,8 +941,8 @@ }, { "id": 48, - "fingerprint": "sha256:93c4af0d3a4bc4c2b94dd3013520cfcfb31278880f15bd0dc6f7b56bdad1d71d", - "api": "mongodb-atlas", + "fingerprint": "sha256:f35f36f036476ee5ac4ddd620455bf07485f1543d37ade3401927505ef3d4a81", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -961,8 +961,8 @@ }, { "id": 49, - "fingerprint": "sha256:54ca7abca1b50f035126b10eb340a7c164ac7de25dd3ce3fa337d3bf42e484d0", - "api": "mongodb-atlas", + "fingerprint": "sha256:78e8e41965696a2ee9a654ec04b8e0aba0da1001908d02f4436497f9a31cbd77", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -981,8 +981,8 @@ }, { "id": 50, - "fingerprint": "sha256:c3ac92ed105577633d90a0e5f5f191a883930d00946c1ad5e6fd6e6e5e17bc19", - "api": "mongodb-atlas", + "fingerprint": "sha256:fdb48987835b96b82d519cf71db83020ea0e356631dcf3fca44e574d700872d2", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -1001,8 +1001,8 @@ }, { "id": 51, - "fingerprint": "sha256:726c64e89a6b36fb0500512112a41f779be225b5f6e9d0250c1efe5b4f46d849", - "api": "mongodb-atlas", + "fingerprint": "sha256:6cf42e038f9a85ce22f032648a2ef29433d2dad4a9ac64c76810374e87729d47", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -1021,8 +1021,8 @@ }, { "id": 52, - "fingerprint": "sha256:15660fe03839d3b8e5284cb48710d65f8014d04a681abc5c15ee0e4d624cf205", - "api": "mongodb-atlas", + "fingerprint": "sha256:7adb19759eded477fd14b56d08342d1fc625237d32d241f2aa53b34b04eaaa59", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -1041,8 +1041,8 @@ }, { "id": 53, - "fingerprint": "sha256:33345023b57650ffa23fed8a9152bd0b90ba5b254a43456c0815c93f6304e660", - "api": "mongodb-atlas", + "fingerprint": "sha256:5477185bf15848e9d350630af08a953686c5c0ce5bc723f70aca7b51c3322820", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -1061,8 +1061,8 @@ }, { "id": 54, - "fingerprint": "sha256:1ba28c2c601a54d4af8660ed53a0ba558c89b8d7efc1b8f03c5e2dec9fd6e14c", - "api": "mongodb-atlas", + "fingerprint": "sha256:4e17ab6c53866e464715eab44c347d868a8edc504310292a57887c5f522774a0", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -1081,8 +1081,8 @@ }, { "id": 55, - "fingerprint": "sha256:3cd0c0f5938f723a8577bde110e95a8792ffbc84efbc1db35e1b178ee8efaf47", - "api": "mongodb-atlas", + "fingerprint": "sha256:3ecfbb5e27cafcf1d7d2d420151284423f0ab29286866952e555fe2f440b3afb", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -1101,8 +1101,8 @@ }, { "id": 56, - "fingerprint": "sha256:6957a0e099d2ff3dd5c2262774cc61c976bf598d7d3cffccb12411f6fe177494", - "api": "mongodb-atlas", + "fingerprint": "sha256:c18980b3f5677145215991caf64657f8c60728bceb9bb521f0456e7411a5288e", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -1121,8 +1121,8 @@ }, { "id": 57, - "fingerprint": "sha256:d0eaa7a2ed37c2ae73ca0de17b57d62398bded0891051b77d53529ffe121f0ca", - "api": "mongodb-atlas", + "fingerprint": "sha256:bb1c6412e90a6fd06acfa4ea522059f8cc35c05d0657b1ec9c9ba18d6a855394", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -1141,8 +1141,8 @@ }, { "id": 58, - "fingerprint": "sha256:f5b2df23e481440adefc6c3424ec6e6a0ecc85ef0a6b95399ba8fdb4567deeb5", - "api": "mongodb-atlas", + "fingerprint": "sha256:75b2abc3ffbf51bbd3054fc0eff45f6e634c79714829d3143284ce879f910a29", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -1161,8 +1161,8 @@ }, { "id": 59, - "fingerprint": "sha256:1cf6ef93cfab02876c2b6e5d99524375dd7d9573cfe603b263f7a7a6641c3bf0", - "api": "mongodb-atlas", + "fingerprint": "sha256:d4b564c377109df103774c094235e12c57a91aa3c175f937df4cebf0b85e8c7d", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -1181,8 +1181,8 @@ }, { "id": 60, - "fingerprint": "sha256:ed98366a3075ac9faa6e9031bb45e5a70ec9e2873d3b46af4a367b134e8dee6b", - "api": "mongodb-atlas", + "fingerprint": "sha256:85da70f97ee83f2b7e20f558827e85c0ae5495c9ed2d0d5f29f660149f3a0c6d", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -1201,8 +1201,8 @@ }, { "id": 61, - "fingerprint": "sha256:1c05da02feae11760a790f58cbd37ad6e36825c671a962f8ea6ba8c1117c65e8", - "api": "mongodb-atlas", + "fingerprint": "sha256:f5a4afc82f69d52e2d338ab66ab99d992d6dca427c8e01a4233816c36395e559", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -1221,8 +1221,8 @@ }, { "id": 62, - "fingerprint": "sha256:3c5493c5b2e8445c3ad9358b8b5572847ccdaa64674daf36eab253fddb597b4c", - "api": "mongodb-atlas", + "fingerprint": "sha256:8c76d61398f0274d7d124ba7317cefa454002ad52f876e50ce7125142f779411", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -1241,8 +1241,8 @@ }, { "id": 63, - "fingerprint": "sha256:93700769859f8dc5099263338888560948f31e966f2c5128e1b6716e388e519f", - "api": "mongodb-atlas", + "fingerprint": "sha256:3c9ef94fb769309eb53458f755b3bc93dff3d65e24c295ab41dfbc45721e66fd", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -1261,8 +1261,8 @@ }, { "id": 64, - "fingerprint": "sha256:7e34764073a7756ef2a208cc8794400db225889028d74e2503bbb4c1e42f0d8b", - "api": "mongodb-atlas", + "fingerprint": "sha256:4905693ad5f2aff385bffea0f61718029280874bcd59fe50a3b592a018ca205f", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -1281,8 +1281,8 @@ }, { "id": 65, - "fingerprint": "sha256:6a81be0741702e412860c93199c4bba18b3f1672362e3398095587ed29e33608", - "api": "mongodb-atlas", + "fingerprint": "sha256:6f9dc9d86fa2003c7a2f1c196f6dc09f082ace53d395808a3d850d4a71359377", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -1301,8 +1301,8 @@ }, { "id": 66, - "fingerprint": "sha256:f92a56db838792d8369658259baa021b0ffe4d7b2ffd6661dff4c1d310244d8e", - "api": "mongodb-atlas", + "fingerprint": "sha256:3c3975b9a70621c359747fa9c8597c3f1456108a8382de5f95e3852fd6c8063a", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -1321,8 +1321,8 @@ }, { "id": 67, - "fingerprint": "sha256:5307201604174c3d36f1a5ea3b3390273295382d16f3f183f932924fcf81969e", - "api": "mongodb-atlas", + "fingerprint": "sha256:7ef39f4601e0bce6744f057c9b9e4c34bc8d07b10f6f8fe6a1ecce0a2cbccb30", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -1341,8 +1341,8 @@ }, { "id": 68, - "fingerprint": "sha256:0568f4a2ede88a3227fc1660d4dd5ee04e44995fa6e119283d9f2495965d5da0", - "api": "mongodb-atlas", + "fingerprint": "sha256:82a31b85f9ab9bc72917add466d2777b231db5be1e432c24faaae68f4446885e", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -1361,8 +1361,8 @@ }, { "id": 69, - "fingerprint": "sha256:9e9664ff4538b4ed4208a0e50bf83361e90c7f7f9135fccdcfe0988341df215a", - "api": "mongodb-atlas", + "fingerprint": "sha256:ea55329b1a7e5b44dbd7497720a0ca34bbc3d54a72ebd3dbeb0620db50fc18b2", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -1381,8 +1381,8 @@ }, { "id": 70, - "fingerprint": "sha256:0df0d4a2b82712ff2cd52af1c28a2945a5759496200bca855bf7a435f792c108", - "api": "mongodb-atlas", + "fingerprint": "sha256:faaad8344369d497fbc754cdbbcfedc0261b525476d232cefab22d14e8b93229", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -1401,8 +1401,8 @@ }, { "id": 71, - "fingerprint": "sha256:1060a1305d0217033202e87fea7961651bb6525430537b4df13e1aea79aab12f", - "api": "mongodb-atlas", + "fingerprint": "sha256:9b50bf722ec1eae087c5f8c15eead886c6d744b0a0b1285ca8270528678c0fb1", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -1421,8 +1421,8 @@ }, { "id": 72, - "fingerprint": "sha256:f2a4460f5cbb72fe9f5d5f075caf02f45dadf9f6a1d7cfd5c872f38061ff41f0", - "api": "mongodb-atlas", + "fingerprint": "sha256:afd8e5317d1698efecca262b0bba602ef658e6178cec2045f47f2bd906c0aa79", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -1441,8 +1441,8 @@ }, { "id": 73, - "fingerprint": "sha256:1fb2c016f4f1eaac2a9ef9f73ba51def2a0f7c59c2ff4d8782938e73fd3e9476", - "api": "mongodb-atlas", + "fingerprint": "sha256:297eff6dc3b5ec919ddd92f130c1059a75af839a5275f465f5f03d65d64bc3e0", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -1461,8 +1461,8 @@ }, { "id": 74, - "fingerprint": "sha256:b2a3a650e62f542192bb958288825b4919d8f1a3e0951a99e198ceaff3427cd3", - "api": "mongodb-atlas", + "fingerprint": "sha256:771dabda44befcc4292720b7492b668e55a0851ca50a9ca65e64422caec4f975", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -1481,8 +1481,8 @@ }, { "id": 75, - "fingerprint": "sha256:046c27b9778b7fa8e0573fbf89730f915e74d6173b8ef61e6b67e7a213e03f68", - "api": "mongodb-atlas", + "fingerprint": "sha256:3f3a9dd94fb934fcd26949ca865abfc990630cd24db5cb40623a78ba7d516ef6", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -1501,8 +1501,8 @@ }, { "id": 76, - "fingerprint": "sha256:e43bb00876edede8dd1d2837f347e49a222fb4567189638686dd0b30689b8f0c", - "api": "mongodb-atlas", + "fingerprint": "sha256:d131e731e86b2fbe4b3e546d785602d6f65422ebfaed33195c9bae954a094e09", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -1521,8 +1521,8 @@ }, { "id": 77, - "fingerprint": "sha256:72a6f60e65e9cd394ee7d73f80476d39f5183d827073b5df2987842906490bfb", - "api": "mongodb-atlas", + "fingerprint": "sha256:a78eea7be07575a3bb36c5526348ab752fee07176bae200dce40fa316fdd08dc", + "api": "mongodb/atlas-admin-api", "version": "2023-01-01", "change_type": "breaking", "breaking": true, @@ -1541,8 +1541,8 @@ }, { "id": 78, - "fingerprint": "sha256:a75e1b8df2609ec96a117c6b652c54558169c6f8034077e975c61d5daa63e23f", - "api": "mongodb-atlas", + "fingerprint": "sha256:16c25ef30e3ca196af5f94eb2a15c327b7408a059e08647eb3952c0c260a5750", + "api": "mongodb/atlas-admin-api", "version": "2025-03-12", "change_type": "deprecation", "breaking": false, @@ -1561,8 +1561,8 @@ }, { "id": 79, - "fingerprint": "sha256:ca9f6b16fbf65ba9dc544dad643af4216bdb3b042a52bca3cab7082e094c8568", - "api": "mongodb-atlas", + "fingerprint": "sha256:2bb72b9a509e7e1c82c80f7c19d34d5840d0dff7b9d2db6283729f52c111c2eb", + "api": "mongodb/atlas-admin-api", "version": "2025-03-12", "change_type": "deprecation", "breaking": false, @@ -1581,8 +1581,8 @@ }, { "id": 80, - "fingerprint": "sha256:d13a8cfe17a4970d9465f4add7f7e50bc854c16884c4650cbe16cb6275575c1b", - "api": "mongodb-atlas", + "fingerprint": "sha256:3d8712c8fd430ebc1c2ca68ce8f2db339d7b5521eeecf35ebfccfe5abdb009c4", + "api": "mongodb/atlas-admin-api", "version": "2025-03-12", "change_type": "deprecation", "breaking": false, @@ -1601,8 +1601,8 @@ }, { "id": 81, - "fingerprint": "sha256:3fad7a4fa2890912db0292412ae49168dae5305846eb2628fc251bd521165c10", - "api": "mongodb-atlas", + "fingerprint": "sha256:b1da7820ea9b85583c0270feae07d446556fb0468da2b61b1dd666f9d0b63f9d", + "api": "mongodb/atlas-admin-api", "version": "2025-03-12", "change_type": "deprecation", "breaking": false, diff --git a/plugins/changelog/testdata/golden/textual-0.86.0.json b/plugins/changelog/testdata/golden/textual-0.86.0.json index 39aa147..2beb129 100644 --- a/plugins/changelog/testdata/golden/textual-0.86.0.json +++ b/plugins/changelog/testdata/golden/textual-0.86.0.json @@ -1,8 +1,8 @@ [ { "id": 1, - "fingerprint": "sha256:24d9bb42e9abe2644dbb30433702c9d94f1598d7143ad708c2fe09568f9437c0", - "api": "textual", + "fingerprint": "sha256:fac4cb01fbe4eb33b37f1ec953ac0abfe97c3444aaa22cdbe9118fb6f4b56e48", + "api": "textual/textual", "version": "0.86.0", "change_type": "breaking", "breaking": true, @@ -24,8 +24,8 @@ }, { "id": 2, - "fingerprint": "sha256:852863d8d05a5753b2d64b4b0dc3717fce11f753727c586cd18eae7f7059dfc9", - "api": "textual", + "fingerprint": "sha256:6a0ba08e00b5d4d4f349a526a43ddef1bb84fe2bad9ef83111074fc2a690723c", + "api": "textual/textual", "version": "0.86.0", "change_type": "breaking", "breaking": true, diff --git a/plugins/changelog/testdata/golden/urllib3-2.0.0.json b/plugins/changelog/testdata/golden/urllib3-2.0.0.json index 8e790dc..019ee37 100644 --- a/plugins/changelog/testdata/golden/urllib3-2.0.0.json +++ b/plugins/changelog/testdata/golden/urllib3-2.0.0.json @@ -1,8 +1,8 @@ [ { "id": 1, - "fingerprint": "sha256:eae9f46e65df370e9a389913f8b726cb59479f97e0f1a0379ece1a1ac02ee084", - "api": "urllib3", + "fingerprint": "sha256:565fb74f16769a316da5d73cfb0c28c3aaa71b380cc6ac892e3c6a1b3532c4f9", + "api": "urllib3/urllib3", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -24,8 +24,8 @@ }, { "id": 2, - "fingerprint": "sha256:4b651d9f82fa23c1f044e54df1f3f2201ed75f95e88906229250ff101f40d4de", - "api": "urllib3", + "fingerprint": "sha256:e1c8e0509a8217a6f9a8e5ed8966f1ea13f1c713068e3065879b3e4ad2841e4c", + "api": "urllib3/urllib3", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -47,8 +47,8 @@ }, { "id": 3, - "fingerprint": "sha256:076ecf01a372ed8249425c78f9567484ba6bb2b93b014920b88ab993af3428a7", - "api": "urllib3", + "fingerprint": "sha256:2bd2e3969f9bf6485261b2fce984053fb86f92f8da9c7286574067e4aff75779", + "api": "urllib3/urllib3", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -70,8 +70,8 @@ }, { "id": 4, - "fingerprint": "sha256:044a3e14ed78e58031de6193746551f0855f3e7d2301ea245bec5b912f98c5bb", - "api": "urllib3", + "fingerprint": "sha256:a70d74d5ec403834ee6b3983da713930c891e9c9e5a2c6b2ac9ffcd10bd1af68", + "api": "urllib3/urllib3", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -93,8 +93,8 @@ }, { "id": 5, - "fingerprint": "sha256:81faaf5c8d89b30236258585ff6e5cfb0f200aa6d0cf68d7c471efda7c4edf4e", - "api": "urllib3", + "fingerprint": "sha256:7606c6922d7e3efda6589fc8266028b28ac7a74710c58fdc37358398855ac98c", + "api": "urllib3/urllib3", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -116,8 +116,8 @@ }, { "id": 6, - "fingerprint": "sha256:ce792af7dd7bc3ed3318e89507e60f495a431a8e840d30763a706d48d7238dc3", - "api": "urllib3", + "fingerprint": "sha256:8af004c9a0ba8e72258d2f43ab47b92a007468f6aee662b332afdef3370e5b1f", + "api": "urllib3/urllib3", "version": "2.0.0", "change_type": "deprecation", "breaking": false, @@ -140,8 +140,8 @@ }, { "id": 7, - "fingerprint": "sha256:30d4426399a9705181de125e34e186ef1aef9bcd9f12f6212513bb371a8cd979", - "api": "urllib3", + "fingerprint": "sha256:bbef62c5f4f8c4a73497468084c88085703613cf84ca801fc166f660970dd802", + "api": "urllib3/urllib3", "version": "2.0.0", "change_type": "deprecation", "breaking": false, @@ -163,8 +163,8 @@ }, { "id": 8, - "fingerprint": "sha256:aa634fb973e53235a99b7c8e1aaba98b3d11efcd404e1c87a7a43db0310653f2", - "api": "urllib3", + "fingerprint": "sha256:286dce48e3ed461fe14bb2350c560709459821ffa331e7eea09922ae59db1491", + "api": "urllib3/urllib3", "version": "2.0.0", "change_type": "deprecation", "breaking": false, @@ -186,8 +186,8 @@ }, { "id": 9, - "fingerprint": "sha256:862dd1626f30afb034581ba6d00d7c02b262e9f0bf50e49afd4d8d8e132a12c0", - "api": "urllib3", + "fingerprint": "sha256:d85bf269a9bc3ef4e5282d3fb165481b04d7206e75bbd5f655c11ab5f1ad69fa", + "api": "urllib3/urllib3", "version": "2.0.0", "change_type": "deprecation", "breaking": false, @@ -209,8 +209,8 @@ }, { "id": 10, - "fingerprint": "sha256:29623796f12a6dfdda28b88b2bf4fc020c8f14955a132bf890bb65c02b440ff8", - "api": "urllib3", + "fingerprint": "sha256:deaa904363334a867a2a212042a73358699122b789858feb014268773d8a7979", + "api": "urllib3/urllib3", "version": "2.0.0", "change_type": "deprecation", "breaking": false, @@ -234,8 +234,8 @@ }, { "id": 11, - "fingerprint": "sha256:68e644ae2a7f6386b541a7a5faaae32c2b4897d63154b18c3d0fe41b1ce85222", - "api": "urllib3", + "fingerprint": "sha256:90ab9071df0b3a7b40197842b4a9966eb64e099dfb474d3c231dc11da00a7a7a", + "api": "urllib3/urllib3", "version": "2.0.0", "change_type": "deprecation", "breaking": false, @@ -257,8 +257,8 @@ }, { "id": 12, - "fingerprint": "sha256:e933598726e75efd4be2f3c08639f52648119833b6f4846f452e4138061c534b", - "api": "urllib3", + "fingerprint": "sha256:84d7a90515e16d4ef2b7af2b15ec076e8b165c1201cef525d7fbdf5a55f1777d", + "api": "urllib3/urllib3", "version": "2.0.0", "change_type": "deprecation", "breaking": false, diff --git a/plugins/changelog/testdata/log-history/changelog-1.json b/plugins/changelog/testdata/log-history/changelog-1.json new file mode 100644 index 0000000..07964e1 --- /dev/null +++ b/plugins/changelog/testdata/log-history/changelog-1.json @@ -0,0 +1 @@ +[{"date":"2026-01-01","paths":[{"path":"/a","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"deprecated","changeCode":"endpoint-deprecated","backwardCompatible":true}]}]}]}] diff --git a/plugins/changelog/testdata/log-history/changelog-2.json b/plugins/changelog/testdata/log-history/changelog-2.json new file mode 100644 index 0000000..11e4655 --- /dev/null +++ b/plugins/changelog/testdata/log-history/changelog-2.json @@ -0,0 +1 @@ +[{"date":"2026-02-01","paths":[{"path":"/b","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"deprecated","changeCode":"resource-version-deprecated","backwardCompatible":true}]}]}]},{"date":"2026-01-01","paths":[{"path":"/a","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"deprecated","changeCode":"endpoint-deprecated","backwardCompatible":true}]}]}]}] diff --git a/plugins/changelog/testdata/log-history/changelog-3.json b/plugins/changelog/testdata/log-history/changelog-3.json new file mode 100644 index 0000000..9bb8e06 --- /dev/null +++ b/plugins/changelog/testdata/log-history/changelog-3.json @@ -0,0 +1 @@ +[{"date":"2026-03-01","paths":[{"path":"/a","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"removed","changeCode":"endpoint-removed","backwardCompatible":false}]}]}]},{"date":"2026-02-01","paths":[{"path":"/b","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"deprecated","changeCode":"resource-version-deprecated","backwardCompatible":true}]}]}]},{"date":"2026-01-01","paths":[{"path":"/a","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"deprecated","changeCode":"endpoint-deprecated","backwardCompatible":true}]}]}]}] diff --git a/plugins/changelog/testdata/log-history/commits.json b/plugins/changelog/testdata/log-history/commits.json new file mode 100644 index 0000000..c86fa74 --- /dev/null +++ b/plugins/changelog/testdata/log-history/commits.json @@ -0,0 +1,5 @@ +[ + {"sha":"0000000000000000000000000000000000000003","html_url":"https://github.com/mongodb/openapi/commit/0000000000000000000000000000000000000003","commit":{"committer":{"date":"2026-03-01T00:00:00Z"}}}, + {"sha":"0000000000000000000000000000000000000002","html_url":"https://github.com/mongodb/openapi/commit/0000000000000000000000000000000000000002","commit":{"committer":{"date":"2026-02-01T00:00:00Z"}}}, + {"sha":"0000000000000000000000000000000000000001","html_url":"https://github.com/mongodb/openapi/commit/0000000000000000000000000000000000000001","commit":{"committer":{"date":"2026-01-01T00:00:00Z"}}} +] diff --git a/plugins/apichangelog/testdata/mongodb-atlas-changelog-2026-11-18-day.json b/plugins/changelog/testdata/mongodb-atlas-changelog-2026-11-18-day.json similarity index 100% rename from plugins/apichangelog/testdata/mongodb-atlas-changelog-2026-11-18-day.json rename to plugins/changelog/testdata/mongodb-atlas-changelog-2026-11-18-day.json diff --git a/plugins/apichangelog/testdata/mongodb-atlas-changelog-c0f99ca9.json b/plugins/changelog/testdata/mongodb-atlas-changelog-c0f99ca9.json similarity index 100% rename from plugins/apichangelog/testdata/mongodb-atlas-changelog-c0f99ca9.json rename to plugins/changelog/testdata/mongodb-atlas-changelog-c0f99ca9.json diff --git a/plugins/feed/feed.go b/plugins/feed/feed.go deleted file mode 100644 index dba0f77..0000000 --- a/plugins/feed/feed.go +++ /dev/null @@ -1,165 +0,0 @@ -// Package feed is the source plugin for a vendor's RSS or Atom changelog -// feed: one event per breaking or deprecation entry (or per name such an -// entry lists), quoting the line that says so. Rung 3 of the source ladder. -// -// A feed is prose, so each feed comes with a Reader that knows what its -// vendor's entries look like and which subject they describe. The rules are -// the same for every reader (precision over recall): -// -// - An entry the vendor doesn't mark as breaking or deprecation (a category, -// a heading) is skipped. -// - A marked entry becomes an event only when the reader finds a typed -// subject in it (a runner label, a model id in code) and a dated -// sentence. Otherwise it is dropped, logged with why, never guessed. -// - `breaking` needs the vendor to say the thing stops on a date ("will be -// retired on", "will be shut down on"). Anything softer ("we recommend -// updating before") is downgraded to `deprecation`. -// -// A feed is a live document, so the events cite a Wayback Machine snapshot -// of it, read back and checked against the live feed (kit.Cite), like the -// retirements plugin. -package feed - -import ( - "context" - "fmt" - "log" - - "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() { - plugin.RegisterProvider(plugin.Provider{ - ID: "github", Name: "GitHub", Category: plugin.CategoryDevTools, Homepage: "https://github.com", - Sources: []plugin.Source{{ - ID: "actions", Layer: plugin.LayerCI, Page: "providers/github-actions.md", - Watches: "GitHub Actions retirements, such as runner images and the `runs-on` labels they remove", - URLs: []string{"https://github.blog/changelog/label/actions/feed/"}, - Plugin: Plugin{Feed: GitHubActions, Archiver: kit.Wayback{}}, - }}, - }) - plugin.RegisterProvider(plugin.Provider{ - ID: "google", Name: "Google", Category: plugin.CategoryAI, Homepage: "https://cloud.google.com", - Sources: []plugin.Source{{ - ID: "vertex-ai-models", Layer: plugin.LayerAIModels, Page: "providers/vertex-ai-models.md", - Watches: "Generative AI model deprecations on Vertex AI", - URLs: []string{"https://docs.cloud.google.com/feeds/generative-ai-on-vertex-ai-release-notes.xml"}, - Plugin: Plugin{Feed: VertexAIModels, Archiver: kit.Wayback{}}, - }}, - }) - plugin.RegisterProvider(plugin.Provider{ - ID: "cloudflare", Name: "Cloudflare", Category: plugin.CategoryInfrastructure, Homepage: "https://www.cloudflare.com", - Sources: []plugin.Source{{ - ID: "api", Layer: plugin.LayerAPI, Page: "providers/cloudflare.md", - Watches: "REST API operations Cloudflare deprecates, breaking on their end-of-life date when it gives one", - URLs: []string{"https://developers.cloudflare.com/fundamentals/api/reference/deprecations/index.xml"}, - Plugin: Plugin{Feed: CloudflareAPI, Archiver: kit.Wayback{}}, - }}, - }) -} - -// Feed is one vendor feed and how to read its entries. -type Feed struct { - API string // the events' api: "github-actions" - Vendor string // for sentences: "GitHub" - URL string // the feed itself - Read Reader -} - -// Reader turns one entry into findings: what it can name for sure, and what -// it drops. It returns nothing for an entry that isn't breaking or a -// deprecation. -type Reader func(e Entry) []Finding - -// Finding is one change a reader found in an entry, or one it dropped. -type Finding struct { - ChangeType event.ChangeType // breaking or deprecation - Version string // per the subject's type: the removal or shutdown date - Subject event.Subject - Description string - Hint string - Excerpt string // the entry's own lines that say so - Entry string // the entry's link, for the log - Dropped string // set: the entry was marked but this is why no event -} - -// Findings reads every entry of a feed. -func (f Feed) Findings(b []byte) ([]Finding, error) { - entries, err := Parse(b) - if err != nil { - return nil, err - } - var out []Finding - for _, e := range entries { - out = append(out, f.Read(e)...) - } - return out, nil -} - -// Plugin reads one feed. -type Plugin struct { - Feed Feed - Archiver kit.Archiver -} - -func (p Plugin) Name() string { return p.Feed.API } - -// Run reads the feed as it is now. An unchanged feed since the last run costs -// one GET (a 304 with the HTTP cache) and no snapshot. -func (p Plugin) Run(ctx context.Context, env plugin.Env) (plugin.Result, error) { - f := p.Feed - live, err := env.Get(ctx, f.URL) - if err != nil { - return plugin.Result{}, fmt.Errorf("fetching %s: %w", f.URL, err) - } - last, same, err := kit.Unchanged(env, f.API, live) - if err != nil { - return plugin.Result{}, err - } - if same { - log.Printf("%s: no change since %s", f.API, last.SourceURL) - return plugin.Result{}, nil - } - want, err := f.Findings(live) - if err != nil { - return plugin.Result{}, fmt.Errorf("reading %s: %w", f.URL, err) - } - snapURL, snap, got, err := kit.Cite(ctx, p.Archiver, f.URL, f.Findings, want) - if err != nil { - return plugin.Result{}, err - } - - now := env.Now().UTC() - var events []event.EventV2 - var rejected []error - for _, fd := range got { - if fd.Dropped != "" { - log.Printf("%s: dropped %s: %s", f.API, fd.Entry, fd.Dropped) - continue - } - e := event.EventV2{ - API: f.API, - Version: fd.Version, - ChangeType: fd.ChangeType, - Breaking: fd.ChangeType == event.ChangeTypeBreaking, - Subject: fd.Subject, - Description: fd.Description, - MigrationHint: fd.Hint, - SourceURL: snapURL, - SourceExcerpt: fd.Excerpt, - Confidence: 1.0, - DetectedAt: now, - } - e.Fingerprint = event.FingerprintV2(e.API, e.Version, e.ChangeType, e.Subject, "") - if err := e.Validate(); err != nil { - rejected = append(rejected, fmt.Errorf("%s %s: %w", f.API, fd.Entry, err)) - continue - } - events = append(events, e) - } - baseline := plugin.Baseline(f.API, now.Format("2006-01-02"), snapURL, snapURL, snap, false, now) - baseline.SHA256 = plugin.SHA256(live) // so the next run compares like with like - return plugin.Result{Label: snapURL, Events: events, Rejected: rejected, Baselines: []plugin.Spec{baseline}}, nil -} diff --git a/plugins/feed/registered_test.go b/plugins/feed/registered_test.go deleted file mode 100644 index 83c9671..0000000 --- a/plugins/feed/registered_test.go +++ /dev/null @@ -1,13 +0,0 @@ -package feed - -import ( - "testing" - - "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" -) - -func TestRegistersItself(t *testing.T) { - for _, f := range []Feed{GitHubActions, VertexAIModels, CloudflareAPI} { - kittest.Registered(t, Plugin{Feed: f}) - } -} diff --git a/plugins/migrationguide/members/export_test.go b/plugins/migrationguide/members/export_test.go new file mode 100644 index 0000000..8667a92 --- /dev/null +++ b/plugins/migrationguide/members/export_test.go @@ -0,0 +1,11 @@ +package members + +// What the external tests (package members_test, which can import the kind +// that imports this package) reach of the unexported helpers. +var ( + PipeCells = pipeCells + SoleName = soleName +) + +func (g Guide) Tag() string { return g.tag() } +func (g Guide) AbsoluteLinks(s string) string { return g.absoluteLinks(s) } diff --git a/plugins/migrationguide/members/golden_test.go b/plugins/migrationguide/members/golden_test.go new file mode 100644 index 0000000..e091953 --- /dev/null +++ b/plugins/migrationguide/members/golden_test.go @@ -0,0 +1,18 @@ +package members_test + +import ( + "testing" + + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" + + "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide" + . "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/members" // the reader under test +) + +// The guide at tag v2.0.0 (saved 2026-11-04) in, every event out. +func TestGolden(t *testing.T) { + got := kittest.Ingest(t, migrationguide.Plugin{Guide: NumPy2}, kittest.Pages{ + NumPy2.URL(): "testdata/numpy_2_0_migration_guide-v2.0.0.rst", + }) + kittest.Golden(t, "../testdata/golden/numpy-2.0.0.json", got) +} diff --git a/plugins/removedmembers/markdown.go b/plugins/migrationguide/members/markdown.go similarity index 99% rename from plugins/removedmembers/markdown.go rename to plugins/migrationguide/members/markdown.go index dc44fdb..d87d3e2 100644 --- a/plugins/removedmembers/markdown.go +++ b/plugins/migrationguide/members/markdown.go @@ -1,4 +1,4 @@ -package removedmembers +package members import ( "fmt" diff --git a/plugins/removedmembers/removedmembers.go b/plugins/migrationguide/members/members.go similarity index 71% rename from plugins/removedmembers/removedmembers.go rename to plugins/migrationguide/members/members.go index ec78e71..7344699 100644 --- a/plugins/removedmembers/removedmembers.go +++ b/plugins/migrationguide/members/members.go @@ -1,7 +1,8 @@ -// Package removedmembers is the source plugin for a package release that -// removed members of its top-level module, read from the release's own -// migration guide at its tag: change event v2's `package_release` subject -// . NumPy 2.0 first: its guide lists about 60 members of the main `np` +// Package members is the migration-guide kind's reader for a package release +// that removed members of its top-level module, read from the release's own +// migration guide at its tag: change event v2's `package_release` subject. +// The kind (plugins/migrationguide) reads the guide and calls Read; this +// package knows where the guide is and how its table reads. NumPy 2.0 first: its guide lists about 60 members of the main `np` // namespace that were removed, each with a migration guideline, and code using // one raises AttributeError on NumPy 2 (checked 2026-11-04 at tag v2.0.0). // @@ -17,7 +18,7 @@ // each is its own event, as each NumPy row is. A row the reader can't read as // members of the package (prose, an argument value, an environment variable) // is dropped and logged, never guessed at. -package removedmembers +package members import ( "context" @@ -26,45 +27,17 @@ import ( "regexp" "slices" "strings" + "time" "github.com/patch-it-dev/patch-it-plugins/core/event" "github.com/patch-it-dev/patch-it-plugins/core/plugin" "github.com/patch-it-dev/patch-it-plugins/core/versions" ) -func init() { - plugin.RegisterProvider(plugin.Provider{ - ID: "numpy", Name: "NumPy", Category: plugin.CategoryPackages, Homepage: "https://numpy.org", - Sources: []plugin.Source{{ - ID: "numpy", Layer: plugin.LayerPackage, Page: "providers/numpy.md", - Watches: "Members removed or renamed in the main namespace in NumPy 2.0", - URLs: []string{"https://github.com/numpy/numpy/blob/v2.0.0/doc/source/numpy_2_0_migration_guide.rst"}, - Plugin: Plugin{Guide: NumPy2}, - }}, - }) - plugin.RegisterProvider(plugin.Provider{ - ID: "posthog", Name: "PostHog", Category: plugin.CategoryAnalytics, Homepage: "https://posthog.com", - Sources: []plugin.Source{{ - ID: "python-sdk", Layer: plugin.LayerSDK, Page: "providers/posthog.md", - Watches: "Members removed in the posthog Python SDK 8.0.0", - URLs: []string{"https://github.com/PostHog/posthog-python/blob/posthog-v8.0.0/docs/migration-7.x-to-8.0.md"}, - Plugin: Plugin{Guide: PostHog8}, - }}, - }) - plugin.RegisterProvider(plugin.Provider{ - ID: "newrelic", Name: "New Relic", Category: plugin.CategoryMonitoring, Homepage: "https://newrelic.com", - Sources: []plugin.Source{{ - ID: "python-agent", Layer: plugin.LayerSDK, Page: "providers/newrelic.md", - Watches: "Members removed in the New Relic Python agent 11.0.0", - URLs: []string{"https://github.com/newrelic/docs-website/blob/f0b4f817bf9a7b76a78e26609369a8a7ce764c8e/src/content/docs/release-notes/agent-release-notes/python-release-notes/python-agent-110000.mdx"}, - Plugin: Plugin{Guide: NewRelic11}, - }}, - }) -} - // Guide is one package's guide to one release. type Guide struct { - Package string // the PyPI name and the events' api: "numpy" + API string // the source id the events carry: "numpy/numpy" + Package string // the PyPI name: "numpy" Module string // how the guide writes the module in a replacement: "np" Release string // "2.0.0" Repo string // owner/name on GitHub @@ -167,6 +140,7 @@ func (g Guide) header() string { // NumPy2 is NumPy's 2.0 migration guide, "Main namespace" table. var NumPy2 = Guide{ + API: "numpy/numpy", Package: "numpy", Module: "np", Release: "2.0.0", @@ -268,71 +242,43 @@ func parseRST(page []byte, g Guide) ([]Removal, error) { return out, nil } -// Plugin reads one guide. -type Plugin struct { - Guide Guide -} - -func (p Plugin) Name() string { return p.Guide.Package } +// Slug is the source id the events carry: "numpy/numpy". +func (g Guide) Slug() string { return g.API } -// Run reads the guide at its release's tag. The tag never changes, so a -// rerun stores nothing new: the fingerprints dedupe. -func (p Plugin) Run(ctx context.Context, env plugin.Env) (plugin.Result, error) { - g := p.Guide - v := plugin.Version{ID: g.Release, Ref: g.tag()} - to, err := p.ReadAt(ctx, env, v) - if err != nil { - return plugin.Result{}, err - } - res, err := p.Extract(ctx, env, plugin.Snapshot{}, to) - if err != nil { - return plugin.Result{}, err - } - res.Baselines = []plugin.Spec{plugin.Baseline(g.Package, g.Release, g.tag(), g.URL(), to.Content, false, env.Now().UTC())} - return res, nil +// Current is the release the guide documents: what a plain run reads. +func (g Guide) Current(context.Context, plugin.Env) (plugin.Version, error) { + return plugin.Version{ID: g.Release, Ref: g.tag()}, nil } -// ListVersions is every final release of the package on PyPI, oldest first, +// Releases is every final release of the package on PyPI, oldest first, // each with the ref its guide would be read at. -func (p Plugin) ListVersions(ctx context.Context, env plugin.Env) ([]plugin.Version, error) { - vs, err := versions.PyPIReleases(ctx, env.Get, p.Guide.Package) +func (g Guide) Releases(ctx context.Context, env plugin.Env) ([]plugin.Version, error) { + vs, err := versions.PyPIReleases(ctx, env.Get, g.Package) if err != nil { return nil, err } for i := range vs { - vs[i].Ref = p.Guide.tagOf(vs[i].ID) + vs[i].Ref = g.tagOf(vs[i].ID) } return vs, nil } -// ReadAt fetches the guide when v is the release it documents; any other -// release has no guide and reads as nothing (a snapshot with no content). -func (p Plugin) ReadAt(ctx context.Context, env plugin.Env, v plugin.Version) (plugin.Snapshot, error) { - g := p.Guide +// GuideURL is the guide when v is the release it documents; any other +// release has no guide (""). +func (g Guide) GuideURL(v plugin.Version) string { if v.ID != g.Release { - return plugin.Snapshot{Version: v}, nil - } - page, err := env.Get(ctx, g.URL()) - if err != nil { - return plugin.Snapshot{}, fmt.Errorf("fetching %s: %w", g.URL(), err) + return "" } - return plugin.Snapshot{Version: v, Content: page, SourceURL: g.URL()}, nil + return g.URL() } -// Extract is an event per removed member in the to release's guide, with -// previous_version from's release; a release with no guide has none. -func (p Plugin) Extract(_ context.Context, env plugin.Env, from, to plugin.Snapshot) (plugin.Result, error) { - g := p.Guide - if to.Content == nil { - return plugin.Result{Label: to.Version.ID}, nil - } - removals, err := Parse(to.Content, g) +// Read is an event per removed member in the guide, with previous_version +// from's release. +func (g Guide) Read(page []byte, from, _ plugin.Version, now time.Time) (events []event.Event, rejected []error, err error) { + removals, err := Parse(page, g) if err != nil { - return plugin.Result{}, fmt.Errorf("reading %s: %w", g.URL(), err) + return nil, nil, err } - now := env.Now().UTC() - var events []event.EventV2 - var rejected []error for _, r := range removals { if r.Dropped != "" { log.Printf("%s %s: dropped %q: %s", g.Package, g.Release, r.Member, r.Dropped) @@ -349,9 +295,9 @@ func (p Plugin) Extract(_ context.Context, env plugin.Env, from, to plugin.Snaps if r.Replacement != "" && !g.NewReplacements && (g.DropIns == nil || slices.Contains(g.DropIns, r.Member)) { subject.Change, subject.Replacement = event.PackageRenamedSymbol, r.Replacement } - e := event.EventV2{ - API: g.Package, - PreviousVersion: from.Version.ID, + e := event.Event{ + API: g.API, + PreviousVersion: from.ID, Version: g.Release, ChangeType: event.ChangeTypeBreaking, Breaking: true, @@ -363,18 +309,16 @@ func (p Plugin) Extract(_ context.Context, env plugin.Env, from, to plugin.Snaps Confidence: 1.0, DetectedAt: now, } - e.Fingerprint = event.FingerprintV2(e.API, e.Version, e.ChangeType, subject, "") + e.Fingerprint = event.Fingerprint(e.API, e.Version, e.ChangeType, subject, "") if err := e.Validate(); err != nil { rejected = append(rejected, fmt.Errorf("%s %s: %w", g.Package, r.Member, err)) continue } events = append(events, e) } - return plugin.Result{Label: g.URL(), Events: events, Rejected: rejected}, nil + return events, rejected, nil } -var _ plugin.Versioned = Plugin{} - // absoluteLinks prefixes LinkBase to every Markdown link target in s that // starts with "/". func (g Guide) absoluteLinks(s string) string { diff --git a/plugins/removedmembers/removedmembers_test.go b/plugins/migrationguide/members/members_test.go similarity index 86% rename from plugins/removedmembers/removedmembers_test.go rename to plugins/migrationguide/members/members_test.go index afab21b..c413c77 100644 --- a/plugins/removedmembers/removedmembers_test.go +++ b/plugins/migrationguide/members/members_test.go @@ -1,4 +1,4 @@ -package removedmembers +package members_test import ( "strings" @@ -6,6 +6,9 @@ import ( "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/migrationguide" + . "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/members" // the reader under test ) // The guide as published at tag v2.0.0 (fetched 2026-11-04). @@ -69,20 +72,20 @@ func TestOnlyOnePlainReplacementInNpIsARename(t *testing.T) { func TestTheGuideStoresOneEventPerMemberAndARerunNothing(t *testing.T) { // The guide at the v2.0.0 tag, and nothing else; kittest reruns it and // fails on anything new. - events := kittest.Ingest(t, Plugin{Guide: NumPy2}, kittest.Pages{ + events := kittest.Ingest(t, migrationguide.Plugin{Guide: NumPy2}, kittest.Pages{ "https://raw.githubusercontent.com/numpy/numpy/v2.0.0/doc/source/numpy_2_0_migration_guide.rst": "testdata/numpy_2_0_migration_guide-v2.0.0.rst", }) if len(events) != 56 { t.Fatalf("%d events, want 56", len(events)) } - var float *event.EventV2 + var float *event.Event for i := range events { if events[i].Subject.Symbols[0] == "float_" { float = &events[i] } } if float == nil || float.Subject.Change != event.PackageRenamedSymbol || float.Subject.Replacement != "float64" || - float.API != "numpy" || float.Version != "2.0.0" || !strings.Contains(float.SourceExcerpt, "float\\_") { + float.API != "numpy/numpy" || float.Version != "2.0.0" || !strings.Contains(float.SourceExcerpt, "float\\_") { t.Errorf("float_: %+v", float) } } diff --git a/plugins/removedmembers/newrelic.go b/plugins/migrationguide/members/newrelic.go similarity index 99% rename from plugins/removedmembers/newrelic.go rename to plugins/migrationguide/members/newrelic.go index 1fb3cd5..a4bc4fb 100644 --- a/plugins/removedmembers/newrelic.go +++ b/plugins/migrationguide/members/newrelic.go @@ -1,4 +1,4 @@ -package removedmembers +package members // NewRelic11 is New Relic's release note for the Python agent 11.0.0 (the // `newrelic` package on PyPI), in newrelic/docs-website at commit @@ -62,6 +62,7 @@ package removedmembers // Setting |, lists configuration settings (newrelic.ini keys), not members // of the package: only the section's first table is read, so it never is. var NewRelic11 = Guide{ + API: "newrelic/python-agent", Package: "newrelic", Module: "newrelic", Release: "11.0.0", diff --git a/plugins/removedmembers/newrelic_test.go b/plugins/migrationguide/members/newrelic_test.go similarity index 88% rename from plugins/removedmembers/newrelic_test.go rename to plugins/migrationguide/members/newrelic_test.go index 220052b..bf00468 100644 --- a/plugins/removedmembers/newrelic_test.go +++ b/plugins/migrationguide/members/newrelic_test.go @@ -1,4 +1,4 @@ -package removedmembers +package members_test import ( "os" @@ -9,6 +9,9 @@ import ( "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/migrationguide" + . "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/members" // the reader under test ) // An excerpt of the release note at commit f0b4f817 (fetched 2026-11-19): the @@ -16,12 +19,12 @@ import ( const newrelicSource = "testdata/python-agent-110000-f0b4f817.mdx" func TestNewRelicRegistersItself(t *testing.T) { - kittest.Registered(t, Plugin{Guide: NewRelic11}) + kittest.Registered(t, migrationguide.Plugin{Guide: NewRelic11}) } // The golden test: the saved excerpt in, every event out. func TestNewRelicGolden(t *testing.T) { - kittest.Golden(t, "testdata/golden/newrelic-11.0.0.json", newrelicIngest(t)) + kittest.Golden(t, "../testdata/golden/newrelic-11.0.0.json", newrelicIngest(t)) } // Each of the "Legacy API" table's 8 rows, decided: a rename only for the two @@ -39,7 +42,7 @@ func TestNewRelicEachRowOfTheTable(t *testing.T) { if len(e.Subject.Symbols) != 1 { t.Fatalf("%v: one symbol per event", e.Subject.Symbols) } - if e.API != "newrelic" || e.Version != "11.0.0" || e.Subject.Ecosystem != "pypi" || e.Subject.Package != "newrelic" || + if e.API != "newrelic/python-agent" || e.Version != "11.0.0" || e.Subject.Ecosystem != "pypi" || e.Subject.Package != "newrelic" || e.ChangeType != event.ChangeTypeBreaking || !strings.HasPrefix(e.SourceExcerpt, "Removed features\n | Legacy API ") || !strings.HasSuffix(e.MigrationHint, "(newrelic's release notes for 11.0.0)") { t.Errorf("%+v", e) @@ -171,8 +174,8 @@ func TestSoleNameReadsALinkedName(t *testing.T) { "[`x=1`](/docs/x)": "", "[`a`](/a) and [`b`](/b)": "", } { - if got := soleName(cell, "acme"); got != want { - t.Errorf("soleName(%q) = %q, want %q", cell, got, want) + if got := SoleName(cell, "acme"); got != want { + t.Errorf("SoleName(%q) = %q, want %q", cell, got, want) } } } @@ -187,12 +190,12 @@ func TestDropInsLimitsRenames(t *testing.T) { "| `old_a` | [`new_a`](/a) |", "| `old_b` | `new_b` |", }, "\n") - g := Guide{Package: "acme", Module: "acme", Release: "2.0.0", Repo: "acme/acme", Path: "MIGRATION.md", + g := Guide{API: "acme/sdk", Package: "acme", Module: "acme", Release: "2.0.0", Repo: "acme/acme", Path: "MIGRATION.md", Section: "Removed", Format: FormatMarkdown, Header: "Removed", Paths: map[string]string{"old_a": "mod.old_a", "new_a": "mod.new_a"}} run := func(g Guide) map[string]string { out := map[string]string{} - for _, e := range kittest.Ingest(t, Plugin{Guide: g}, kittest.Pages{g.URL(): writeTemp(t, page)}) { + for _, e := range kittest.Ingest(t, migrationguide.Plugin{Guide: g}, kittest.Pages{g.URL(): writeTemp(t, page)}) { out[e.Subject.Symbols[0]] = string(e.Subject.Change) + " " + e.Subject.Replacement } return out @@ -231,9 +234,9 @@ func readNames(t *testing.T, page string, g Guide) []string { } // newrelicIngest runs the plugin over the saved excerpt. -func newrelicIngest(t *testing.T) []event.EventV2 { +func newrelicIngest(t *testing.T) []event.Event { t.Helper() - return kittest.Ingest(t, Plugin{Guide: NewRelic11}, kittest.Pages{NewRelic11.URL(): newrelicSource}) + return kittest.Ingest(t, migrationguide.Plugin{Guide: NewRelic11}, kittest.Pages{NewRelic11.URL(): newrelicSource}) } // The hint is shown in a pull request or an issue, where a site-relative link @@ -242,10 +245,10 @@ func TestAbsoluteLinks(t *testing.T) { g := Guide{LinkBase: "https://docs.newrelic.com/"} in := "Replacement API: [`notice_error()`](/docs/x/notice_error), see [here](https://example.test/y)" want := "Replacement API: [`notice_error()`](https://docs.newrelic.com/docs/x/notice_error), see [here](https://example.test/y)" - if got := g.absoluteLinks(in); got != want { + if got := g.AbsoluteLinks(in); got != want { t.Errorf("got %q, want %q", got, want) } - if got := (Guide{}).absoluteLinks(in); got != in { + if got := (Guide{}).AbsoluteLinks(in); got != in { t.Errorf("no LinkBase changed the hint: %q", got) } } diff --git a/plugins/removedmembers/posthog.go b/plugins/migrationguide/members/posthog.go similarity index 98% rename from plugins/removedmembers/posthog.go rename to plugins/migrationguide/members/posthog.go index 9250e5c..c22c1f3 100644 --- a/plugins/removedmembers/posthog.go +++ b/plugins/migrationguide/members/posthog.go @@ -1,4 +1,4 @@ -package removedmembers +package members // PostHog8 is the posthog Python SDK's guide to 8.0.0, // docs/migration-7.x-to-8.0.md at tag posthog-v8.0.0 (commit @@ -56,6 +56,7 @@ package removedmembers // fields, retries, dropped events, options, and "Rename deprecated settings", // whose old names still work) aren't under the heading, so they're never read. var PostHog8 = Guide{ + API: "posthog/python-sdk", Package: "posthog", Module: "posthog", Release: "8.0.0", diff --git a/plugins/removedmembers/posthog_test.go b/plugins/migrationguide/members/posthog_test.go similarity index 91% rename from plugins/removedmembers/posthog_test.go rename to plugins/migrationguide/members/posthog_test.go index 8b7d70a..f082ee4 100644 --- a/plugins/removedmembers/posthog_test.go +++ b/plugins/migrationguide/members/posthog_test.go @@ -1,4 +1,4 @@ -package removedmembers +package members_test import ( "slices" @@ -7,18 +7,21 @@ import ( "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/migrationguide" + . "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/members" // the reader under test ) // The guide as published at tag posthog-v8.0.0 (fetched 2026-11-19), whole. const posthogSource = "testdata/migration-7.x-to-8.0-posthog-v8.0.0.md" func TestPostHogRegistersItself(t *testing.T) { - kittest.Registered(t, Plugin{Guide: PostHog8}) + kittest.Registered(t, migrationguide.Plugin{Guide: PostHog8}) } // The golden test: the saved guide in, every event out. func TestPostHogGolden(t *testing.T) { - kittest.Golden(t, "testdata/golden/posthog-8.0.0.json", posthogIngest(t)) + kittest.Golden(t, "../testdata/golden/posthog-8.0.0.json", posthogIngest(t)) } // Each of the "Fix removed APIs" table's 7 rows, decided: every name is a @@ -35,7 +38,7 @@ func TestPostHogEachRowOfTheTable(t *testing.T) { if len(e.Subject.Symbols) != 1 { t.Fatalf("%v: one symbol per event", e.Subject.Symbols) } - if e.API != "posthog" || e.Version != "8.0.0" || e.Subject.Ecosystem != "pypi" || e.Subject.Package != "posthog" || + if e.API != "posthog/python-sdk" || e.Version != "8.0.0" || e.Subject.Ecosystem != "pypi" || e.Subject.Package != "posthog" || e.ChangeType != event.ChangeTypeBreaking || !strings.HasPrefix(e.SourceExcerpt, "Fix removed APIs\n| Removed | Use instead |") { t.Errorf("%+v", e) } @@ -155,8 +158,8 @@ func TestPipeCells(t *testing.T) { "| `request.batch_post`, `EVENTS_ENDPOINT` |": {"`request.batch_post`, `EVENTS_ENDPOINT`"}, "| one | two | three |": {"one", "two", "three"}, } { - if got := pipeCells(row); !slices.Equal(got, want) { - t.Errorf("pipeCells(%q) = %q, want %q", row, got, want) + if got := PipeCells(row); !slices.Equal(got, want) { + t.Errorf("PipeCells(%q) = %q, want %q", row, got, want) } } } @@ -231,7 +234,7 @@ func TestMarkdownTable(t *testing.T) { } // posthogIngest runs the plugin over the saved guide. -func posthogIngest(t *testing.T) []event.EventV2 { +func posthogIngest(t *testing.T) []event.Event { t.Helper() - return kittest.Ingest(t, Plugin{Guide: PostHog8}, kittest.Pages{PostHog8.URL(): posthogSource}) + return kittest.Ingest(t, migrationguide.Plugin{Guide: PostHog8}, kittest.Pages{PostHog8.URL(): posthogSource}) } diff --git a/plugins/migrationguide/members/registered_test.go b/plugins/migrationguide/members/registered_test.go new file mode 100644 index 0000000..750b03f --- /dev/null +++ b/plugins/migrationguide/members/registered_test.go @@ -0,0 +1,14 @@ +package members_test + +import ( + "testing" + + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" + + "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide" + . "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/members" // the reader under test +) + +func TestRegistersItself(t *testing.T) { + kittest.Registered(t, migrationguide.Plugin{Guide: NumPy2}) +} diff --git a/plugins/removedmembers/testdata/README.md b/plugins/migrationguide/members/testdata/README.md similarity index 91% rename from plugins/removedmembers/testdata/README.md rename to plugins/migrationguide/members/testdata/README.md index 05e4aa5..12bc3cf 100644 --- a/plugins/removedmembers/testdata/README.md +++ b/plugins/migrationguide/members/testdata/README.md @@ -1,6 +1,6 @@ # Saved removed-members guides -The golden files under `golden/` are what the plugin stores from them (`go test ./plugins/removedmembers -update`). +The golden files, `../../testdata/golden/{numpy-2.0.0,posthog-8.0.0,newrelic-11.0.0}.json`, are what the migration-guide kind stores from them (`go test ./plugins/migrationguide/members -update`). | File | URL | Fetched | License | Quote | |---|---|---|---|---| diff --git a/plugins/removedmembers/testdata/migration-7.x-to-8.0-posthog-v8.0.0.md b/plugins/migrationguide/members/testdata/migration-7.x-to-8.0-posthog-v8.0.0.md similarity index 100% rename from plugins/removedmembers/testdata/migration-7.x-to-8.0-posthog-v8.0.0.md rename to plugins/migrationguide/members/testdata/migration-7.x-to-8.0-posthog-v8.0.0.md diff --git a/plugins/removedmembers/testdata/numpy_2_0_migration_guide-v2.0.0.rst b/plugins/migrationguide/members/testdata/numpy_2_0_migration_guide-v2.0.0.rst similarity index 100% rename from plugins/removedmembers/testdata/numpy_2_0_migration_guide-v2.0.0.rst rename to plugins/migrationguide/members/testdata/numpy_2_0_migration_guide-v2.0.0.rst diff --git a/plugins/removedmembers/testdata/pypi-numpy-excerpt.json b/plugins/migrationguide/members/testdata/pypi-numpy-excerpt.json similarity index 100% rename from plugins/removedmembers/testdata/pypi-numpy-excerpt.json rename to plugins/migrationguide/members/testdata/pypi-numpy-excerpt.json diff --git a/plugins/removedmembers/testdata/python-agent-110000-f0b4f817.mdx b/plugins/migrationguide/members/testdata/python-agent-110000-f0b4f817.mdx similarity index 100% rename from plugins/removedmembers/testdata/python-agent-110000-f0b4f817.mdx rename to plugins/migrationguide/members/testdata/python-agent-110000-f0b4f817.mdx diff --git a/plugins/removedmembers/versions_test.go b/plugins/migrationguide/members/versions_test.go similarity index 88% rename from plugins/removedmembers/versions_test.go rename to plugins/migrationguide/members/versions_test.go index a48552f..4ada100 100644 --- a/plugins/removedmembers/versions_test.go +++ b/plugins/migrationguide/members/versions_test.go @@ -1,4 +1,4 @@ -package removedmembers +package members_test import ( "context" @@ -8,6 +8,9 @@ import ( "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" "github.com/patch-it-dev/patch-it-plugins/core/versions" + + "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide" + . "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/members" // the reader under test ) // The package's releases come from PyPI; only the pair into the release the @@ -17,7 +20,7 @@ func TestOnlyTheGuidesReleaseHasEvents(t *testing.T) { "https://pypi.org/pypi/numpy/json": "testdata/pypi-numpy-excerpt.json", NumPy2.URL(): "testdata/numpy_2_0_migration_guide-v2.0.0.rst", }) - p := Plugin{Guide: NumPy2} + p := migrationguide.Plugin{Guide: NumPy2} ctx := context.Background() vs, err := p.ListVersions(ctx, env) if err != nil { @@ -54,7 +57,7 @@ func TestOnlyTheGuidesReleaseHasEvents(t *testing.T) { // Each release's ref follows the guide's tag shape. func TestTagsFollowTheGuide(t *testing.T) { for g, want := range map[*Guide]string{&NumPy2: "v2.0.0", &PostHog8: "posthog-v8.0.0", &NewRelic11: "f0b4f817bf9a7b76a78e26609369a8a7ce764c8e"} { - if got := g.tag(); got != want { + if got := g.Tag(); got != want { t.Errorf("%s: tag %q, want %q", g.Package, got, want) } } diff --git a/plugins/migrationguide/migrationguide.go b/plugins/migrationguide/migrationguide.go index 825a8b4..ab63625 100644 --- a/plugins/migrationguide/migrationguide.go +++ b/plugins/migrationguide/migrationguide.go @@ -1,16 +1,24 @@ -// Package migrationguide is the source plugin for an SDK's migration guide, -// read at the release tag of each major it describes: an event per request -// parameter the release removed (sdkguide/). A tag never changes, so a rerun -// stores nothing new: the fingerprints dedupe. +// Package migrationguide is the kind for a guide that lists what a release +// removed, read at the tag of the release it describes: an SDK's +// MIGRATION.md and the request parameters a major removed (sdkguide/), or a +// package's migration guide and the members of its module a release removed +// (members/, RST or Markdown tables). The tag never changes, so the guide's +// URL is the events' provenance and a rerun stores nothing new: the +// fingerprints dedupe. +// +// Every source is one Plugin with a Guide, the reader that knows which +// releases there are, where the guide is at each, and how its table reads. +// Listing, reading and extracting are written once, here. package migrationguide import ( "context" "fmt" + "time" - "github.com/patch-it-dev/patch-it-plugins/core/migrate" + "github.com/patch-it-dev/patch-it-plugins/core/event" "github.com/patch-it-dev/patch-it-plugins/core/plugin" - "github.com/patch-it-dev/patch-it-plugins/core/versions" + "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/members" "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/sdkguide" ) @@ -19,39 +27,76 @@ func init() { ID: "anthropic", Name: "Anthropic", Category: plugin.CategoryAI, Homepage: "https://www.anthropic.com", Sources: []plugin.Source{{ ID: "python-sdk", Layer: plugin.LayerSDK, Page: "providers/anthropic.md", - Watches: "Request parameters each new major of the Python SDK removes from `messages.create()` and friends, from MIGRATION.md at the major's tag", - URLs: []string{"https://github.com/anthropics/anthropic-sdk-python/blob/main/MIGRATION.md", "https://pypi.org/project/anthropic/"}, - Plugin: Plugin{Guide: sdkguide.Anthropic}, + Watches: "Request parameters each new major of the Python SDK removes from `messages.create()` and friends, from MIGRATION.md at the major's tag", + URLs: []string{"https://github.com/anthropics/anthropic-sdk-python/blob/main/MIGRATION.md", "https://pypi.org/project/anthropic/"}, + Packages: []string{"pypi:anthropic"}, + Plugin: Plugin{Guide: sdkguide.Anthropic}, + }}, + }) + plugin.RegisterProvider(plugin.Provider{ + ID: "numpy", Name: "NumPy", Category: plugin.CategoryPackages, Homepage: "https://numpy.org", + Sources: []plugin.Source{{ + ID: "numpy", Layer: plugin.LayerPackage, Page: "providers/numpy.md", + Watches: "Members removed or renamed in the main namespace in NumPy 2.0", + URLs: []string{"https://github.com/numpy/numpy/blob/v2.0.0/doc/source/numpy_2_0_migration_guide.rst"}, + Packages: []string{"pypi:numpy"}, + Plugin: Plugin{Guide: members.NumPy2}, + }}, + }) + plugin.RegisterProvider(plugin.Provider{ + ID: "posthog", Name: "PostHog", Category: plugin.CategoryAnalytics, Homepage: "https://posthog.com", + Sources: []plugin.Source{{ + ID: "python-sdk", Layer: plugin.LayerSDK, Page: "providers/posthog.md", + Watches: "Members removed in the posthog Python SDK 8.0.0", + URLs: []string{"https://github.com/PostHog/posthog-python/blob/posthog-v8.0.0/docs/migration-7.x-to-8.0.md"}, + Packages: []string{"pypi:posthog"}, + Plugin: Plugin{Guide: members.PostHog8}, + }}, + }) + plugin.RegisterProvider(plugin.Provider{ + ID: "newrelic", Name: "New Relic", Category: plugin.CategoryMonitoring, Homepage: "https://newrelic.com", + Sources: []plugin.Source{{ + ID: "python-agent", Layer: plugin.LayerSDK, Page: "providers/newrelic.md", + Watches: "Members removed in the New Relic Python agent 11.0.0", + URLs: []string{"https://github.com/newrelic/docs-website/blob/f0b4f817bf9a7b76a78e26609369a8a7ce764c8e/src/content/docs/release-notes/agent-release-notes/python-release-notes/python-agent-110000.mdx"}, + Packages: []string{"pypi:newrelic"}, + Plugin: Plugin{Guide: members.NewRelic11}, }}, }) } -// Plugin reads an SDK's migration guide: at the first release of each major -// (ListVersions, ReadAt, Extract), or, with a pinned Guide, that one major. +// Guide is one source's migration guide: which releases there are, where the +// guide is at each, and how its table reads. sdkguide.Guide and +// members.Guide are the two readers. +type Guide interface { + // Slug is the source id the events carry in api: "anthropic/python-sdk". + Slug() string + // Releases are the versions, oldest first, each with the ref its guide + // would be read at. + Releases(ctx context.Context, env plugin.Env) ([]plugin.Version, error) + // Current is the release a plain run (Run) reads. + Current(ctx context.Context, env plugin.Env) (plugin.Version, error) + // GuideURL is where the guide is at v, pinned to v's tag, or "" when v + // has no guide (a release that isn't a new major). + GuideURL(v plugin.Version) string + // Read turns the guide, as read at to, into events with + // previous_version from, and the rows that failed to become events. err + // is a guide it can't read. + Read(page []byte, from, to plugin.Version, now time.Time) (events []event.Event, rejected []error, err error) +} + +// Plugin reads one source's migration guide. type Plugin struct { - Guide sdkguide.Guide + Guide Guide } -func (p Plugin) Name() string { return p.Guide.API } +func (p Plugin) Name() string { return p.Guide.Slug() } -// Run reads the pinned major's guide, or the newest major's. +// Run reads the guide at its current release and stores its events. func (p Plugin) Run(ctx context.Context, env plugin.Env) (plugin.Result, error) { - g := p.Guide - v := plugin.Version{ID: g.Version(), Ref: "v" + g.Version()} - if g.Major == 0 { - vs, err := p.ListVersions(ctx, env) - if err != nil { - return plugin.Result{}, err - } - v = plugin.Version{} - for _, c := range vs { - if firstOfMajor(c.ID) { - v = c - } - } - if v.ID == "" { - return plugin.Result{}, fmt.Errorf("%s: no major release listed", g.API) - } + v, err := p.Guide.Current(ctx, env) + if err != nil { + return plugin.Result{}, err } to, err := p.ReadAt(ctx, env, v) if err != nil { @@ -61,66 +106,40 @@ func (p Plugin) Run(ctx context.Context, env plugin.Env) (plugin.Result, error) if err != nil { return plugin.Result{}, err } - res.Baselines = []plugin.Spec{plugin.Baseline(g.API, v.ID, v.Ref, to.SourceURL, to.Content, false, env.Now().UTC())} + res.Baselines = []plugin.Spec{plugin.Baseline(p.Name(), v.ID, v.Ref, to.SourceURL, to.Content, env.Now().UTC())} return res, nil } -// ListVersions is every final release of the SDK on PyPI, oldest first; a -// pinned Guide has its one major. +// ListVersions is every release of the source, oldest first. func (p Plugin) ListVersions(ctx context.Context, env plugin.Env) ([]plugin.Version, error) { - g := p.Guide - if g.Major != 0 { - return []plugin.Version{{ID: g.Version(), Ref: "v" + g.Version()}}, nil - } - vs, err := versions.PyPIReleases(ctx, env.Get, g.API) - if err != nil { - return nil, err - } - for i := range vs { - vs[i].Ref = "v" + vs[i].ID - } - return vs, nil + return p.Guide.Releases(ctx, env) } -// ReadAt fetches the guide at the release's tag, when the release is the -// first of its major (X.0.0): only a new major has a guide to read. Any other -// release reads as nothing (a snapshot with no content). +// ReadAt fetches the guide at v; a release with no guide reads as nothing (a +// snapshot with no content). func (p Plugin) ReadAt(ctx context.Context, env plugin.Env, v plugin.Version) (plugin.Snapshot, error) { - if !firstOfMajor(v.ID) { + url := p.Guide.GuideURL(v) + if url == "" { return plugin.Snapshot{Version: v}, nil } - g := p.Guide.At(versions.Major(v.ID)) - page, err := env.Get(ctx, g.URL()) + page, err := env.Get(ctx, url) if err != nil { - return plugin.Snapshot{}, fmt.Errorf("fetching %s: %w", g.URL(), err) + return plugin.Snapshot{}, fmt.Errorf("fetching %s: %w", url, err) } - return plugin.Snapshot{Version: v, Content: page, SourceURL: g.URL()}, nil + return plugin.Snapshot{Version: v, Content: page, SourceURL: url}, nil } -// Extract is an event per request parameter the to major removed, read from -// its guide, with previous_version from's release. A release that isn't a new -// major has no guide and no events. +// Extract is an event per removal in to's guide, with previous_version +// from's release. A release with no guide has no events. func (p Plugin) Extract(_ context.Context, env plugin.Env, from, to plugin.Snapshot) (plugin.Result, error) { if to.Content == nil { return plugin.Result{Label: to.Version.ID}, nil } - g := p.Guide.At(versions.Major(to.Version.ID)) - removals, err := sdkguide.Parse(to.Content, g) + events, rejected, err := p.Guide.Read(to.Content, from.Version, to.Version, env.Now().UTC()) if err != nil { - return plugin.Result{}, fmt.Errorf("reading %s: %w", g.URL(), err) - } - events, errs := sdkguide.Events(g, removals, env.Now().UTC()) - for i := range events { - events[i].PreviousVersion = from.Version.ID + return plugin.Result{}, fmt.Errorf("reading %s: %w", to.SourceURL, err) } - converted, invalid := migrate.Fresh(events) - return plugin.Result{Label: g.URL(), Events: converted, Rejected: append(errs, invalid...)}, nil -} - -// firstOfMajor is true for X.0.0, the release a major's guide is tagged at. -func firstOfMajor(v string) bool { - m := versions.Major(v) - return m > 0 && v == fmt.Sprintf("%d.0.0", m) + return plugin.Result{Label: to.SourceURL, Events: events, Rejected: rejected}, nil } var _ plugin.Versioned = Plugin{} diff --git a/plugins/migrationguide/sdkguide/sdkguide.go b/plugins/migrationguide/sdkguide/sdkguide.go index 903d194..42071ff 100644 --- a/plugins/migrationguide/sdkguide/sdkguide.go +++ b/plugins/migrationguide/sdkguide/sdkguide.go @@ -22,29 +22,28 @@ import ( // Guide is one SDK's migration guide for one major release. type Guide struct { - API string // the SDK's slug in change events and its PyPI name, e.g. "anthropic" - Repo string // its GitHub repository, owner/name - Major int // pinned: the release the guide describes, 1 for "Migrating to v1"; 0 lists them - Operation string // the API operation the removed parameters were sent to + API string // the source id the events carry: "anthropic/python-sdk" + Package string // its PyPI name: "anthropic" + Repo string // its GitHub repository, owner/name + Major int // pinned: the release the guide describes, 1 for "Migrating to v1"; 0 lists them // 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). + // first (`messages.create()`, `messages.stream()`, `messages.parse()`). Symbols []string } // Anthropic is anthropic-sdk-python's MIGRATION.md, unpinned: read at the // first release of each major (Major 0; At pins it). var Anthropic = Guide{ - API: "anthropic", - Repo: "anthropics/anthropic-sdk-python", - Operation: "POST /v1/messages", - Methods: "`messages.create()`", - Symbols: []string{"messages.create", "messages.stream", "messages.parse"}, + API: "anthropic/python-sdk", + Package: "anthropic", + Repo: "anthropics/anthropic-sdk-python", + Methods: "`messages.create()`", + Symbols: []string{"messages.create", "messages.stream", "messages.parse"}, } // AnthropicV1 is anthropic-sdk-python's guide to 1.0.0: what the golden pins. @@ -147,26 +146,24 @@ func cut(s string, n int) string { 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 +// Events turns removals into change events: one breaking removed_parameter +// event per parameter, on the SDK calls it can no longer be passed to. +func Events(g Guide, rs []Removal, now time.Time) ([]event.Event, []error) { + var events []event.Event var errs []error for _, r := range rs { - affected := event.Affected{ - Kind: event.AffectedKindRequestParameter, - Side: event.SideRequest, - Operation: g.Operation, - Property: r.Param, + subject := event.Subject{ + Type: event.SubjectPackageRelease, Ecosystem: "pypi", Package: g.Package, + Change: event.PackageRemovedParameter, Parameter: r.Param, Symbols: g.Symbols, } - e := event.ChangeEvent{ - Fingerprint: event.Fingerprint(g.API, g.Version(), event.ChangeTypeBreaking, affected, "removed"), + e := event.Event{ + Fingerprint: event.Fingerprint(g.API, g.Version(), event.ChangeTypeBreaking, subject, ""), 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()), + Subject: subject, + 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.Package, g.Version()), MigrationHint: fmt.Sprintf("%s Source: %s", r.Instead, g.Page()), SourceURL: g.URL(), SourceExcerpt: r.Excerpt, diff --git a/plugins/migrationguide/sdkguide/sdkguide_test.go b/plugins/migrationguide/sdkguide/sdkguide_test.go index d0c3fcb..5e6055a 100644 --- a/plugins/migrationguide/sdkguide/sdkguide_test.go +++ b/plugins/migrationguide/sdkguide/sdkguide_test.go @@ -58,8 +58,9 @@ func TestEventsAreValidAndCiteTheTag(t *testing.T) { t.Fatalf("%d events, %v", len(events), errs) } e := events[0] - if e.API != "anthropic" || e.Version != "1.0.0" || !e.Breaking || - e.Affected != (event.Affected{Kind: event.AffectedKindRequestParameter, Side: event.SideRequest, Operation: "POST /v1/messages", Property: "temperature"}) || + if e.API != "anthropic/python-sdk" || e.Version != "1.0.0" || !e.Breaking || + e.Subject.Type != event.SubjectPackageRelease || e.Subject.Package != "anthropic" || e.Subject.Change != event.PackageRemovedParameter || + e.Subject.Parameter != "temperature" || strings.Join(e.Subject.Symbols, ",") != "messages.create,messages.stream,messages.parse" || e.SourceURL != "https://raw.githubusercontent.com/anthropics/anthropic-sdk-python/v1.0.0/MIGRATION.md" { t.Errorf("%+v", e) } diff --git a/plugins/migrationguide/sdkguide/versions.go b/plugins/migrationguide/sdkguide/versions.go new file mode 100644 index 0000000..4174213 --- /dev/null +++ b/plugins/migrationguide/sdkguide/versions.go @@ -0,0 +1,84 @@ +package sdkguide + +import ( + "context" + "fmt" + "time" + + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" + "github.com/patch-it-dev/patch-it-plugins/core/versions" +) + +// What the migration-guide kind (plugins/migrationguide) asks of a guide. + +// Slug is the source id the events carry: "anthropic/python-sdk". +func (g Guide) Slug() string { return g.API } + +// Releases is every final release of the SDK on PyPI, oldest first, each +// read at its v tag; a pinned Guide has its one major. +func (g Guide) Releases(ctx context.Context, env plugin.Env) ([]plugin.Version, error) { + if g.Major != 0 { + return []plugin.Version{{ID: g.Version(), Ref: "v" + g.Version()}}, nil + } + vs, err := versions.PyPIReleases(ctx, env.Get, g.Package) + if err != nil { + return nil, err + } + for i := range vs { + vs[i].Ref = "v" + vs[i].ID + } + return vs, nil +} + +// Current is the pinned major's first release, or the newest major's. +func (g Guide) Current(ctx context.Context, env plugin.Env) (plugin.Version, error) { + if g.Major != 0 { + return plugin.Version{ID: g.Version(), Ref: "v" + g.Version()}, nil + } + vs, err := g.Releases(ctx, env) + if err != nil { + return plugin.Version{}, err + } + var v plugin.Version + for _, c := range vs { + if FirstOfMajor(c.ID) { + v = c + } + } + if v.ID == "" { + return plugin.Version{}, fmt.Errorf("%s: no major release listed", g.API) + } + return v, nil +} + +// GuideURL is the guide at v's tag when v is the first release of its major +// (X.0.0): only a new major has a guide to read. Any other release has none +// (""). +func (g Guide) GuideURL(v plugin.Version) string { + if !FirstOfMajor(v.ID) { + return "" + } + return g.At(versions.Major(v.ID)).URL() +} + +// Read is an event per parameter the to major removed, read from its +// guide, with previous_version from's release. +func (g Guide) Read(page []byte, from, to plugin.Version, now time.Time) (_ []event.Event, rejected []error, err error) { + g = g.At(versions.Major(to.ID)) + removals, err := Parse(page, g) + if err != nil { + return nil, nil, err + } + events, errs := Events(g, removals, now) + for i := range events { + events[i].PreviousVersion = from.ID + } + return events, errs, nil +} + +// FirstOfMajor is true for X.0.0, the release a major's guide is tagged at. +func FirstOfMajor(v string) bool { + m := versions.Major(v) + return m > 0 && v == fmt.Sprintf("%d.0.0", m) +} diff --git a/plugins/migrationguide/testdata/README.md b/plugins/migrationguide/testdata/README.md index 7646c57..5362a94 100644 --- a/plugins/migrationguide/testdata/README.md +++ b/plugins/migrationguide/testdata/README.md @@ -1,6 +1,8 @@ # Golden events -`golden/anthropic-1.0.0.json` is what the `anthropic` plugin stores from anthropic-sdk-python's MIGRATION.md at v1.0.0. The saved guide itself is shared with the `sdkguide` package: see [`sdkguide/testdata/README.md`](../../../sdkguide/testdata/README.md) for its URL, date and license. +`golden/anthropic-1.0.0.json` is what the `anthropic` plugin stores from anthropic-sdk-python's MIGRATION.md at v1.0.0. The saved guide itself is shared with the `sdkguide` package: see [`sdkguide/testdata/README.md`](../sdkguide/testdata/README.md) for its URL, date and license. + +`golden/numpy-2.0.0.json`, `golden/posthog-8.0.0.json` and `golden/newrelic-11.0.0.json` are what the removed-members reader's sources store; their saved guides are in [`members/testdata/`](../members/testdata/README.md), and their tests in `members/` (`go test ./plugins/migrationguide/members -update`). Rewrite it after an intended change with `go test ./plugins/migrationguide -update`, and say in the PR why the new output is right. diff --git a/plugins/migrationguide/testdata/golden/anthropic-1.0.0.json b/plugins/migrationguide/testdata/golden/anthropic-1.0.0.json index 80a6518..038306b 100644 --- a/plugins/migrationguide/testdata/golden/anthropic-1.0.0.json +++ b/plugins/migrationguide/testdata/golden/anthropic-1.0.0.json @@ -1,8 +1,8 @@ [ { "id": 1, - "fingerprint": "sha256:16f13db8470e2299ccdfc6564519417bacb8101ff6884ebfcaf989f59c7ed021", - "api": "anthropic", + "fingerprint": "sha256:07170c43fdc6d298df0a7752b72ad8977df95bccaaadb95fdfafbcf5d30286a0", + "api": "anthropic/python-sdk", "version": "1.0.0", "change_type": "breaking", "breaking": true, @@ -27,8 +27,8 @@ }, { "id": 2, - "fingerprint": "sha256:61b3739d72b6dff1f2192fb4f553ff86ef77c2d33bbb6def80c99ac58ebb4382", - "api": "anthropic", + "fingerprint": "sha256:61c02ba43dda9bf576bc55cd9564fbad623951df898b2653a79e572806bd70e2", + "api": "anthropic/python-sdk", "version": "1.0.0", "change_type": "breaking", "breaking": true, @@ -53,8 +53,8 @@ }, { "id": 3, - "fingerprint": "sha256:b39ce1b3d18e8f138ae5a09d03edab9f1793ddbe030d090c90f8c2cd958ac474", - "api": "anthropic", + "fingerprint": "sha256:0845af07684a241eb1300ad5b161b21fa6a026584ee8f088a416c7c918cfffd0", + "api": "anthropic/python-sdk", "version": "1.0.0", "change_type": "breaking", "breaking": true, diff --git a/plugins/removedmembers/testdata/golden/newrelic-11.0.0.json b/plugins/migrationguide/testdata/golden/newrelic-11.0.0.json similarity index 92% rename from plugins/removedmembers/testdata/golden/newrelic-11.0.0.json rename to plugins/migrationguide/testdata/golden/newrelic-11.0.0.json index 4d1544f..0cd06f3 100644 --- a/plugins/removedmembers/testdata/golden/newrelic-11.0.0.json +++ b/plugins/migrationguide/testdata/golden/newrelic-11.0.0.json @@ -1,8 +1,8 @@ [ { "id": 1, - "fingerprint": "sha256:a2f86cae07b29326ca93be5f66515f27d1040d5f189e103911dd93ba739e0b96", - "api": "newrelic", + "fingerprint": "sha256:7f09f0bebf3e229d1a8f43574c224b8a6e186b4e0228f62c793afd10156569fe", + "api": "newrelic/python-agent", "version": "11.0.0", "change_type": "breaking", "breaking": true, @@ -24,8 +24,8 @@ }, { "id": 2, - "fingerprint": "sha256:dfc0f5f20b000248f48960b089533d37b2a98857ab86b34ef58bbadc2a79a331", - "api": "newrelic", + "fingerprint": "sha256:033c7dc942625f1d07ef976edf7dcc22b458dd2786eeab3d5a7a0889dfe100e3", + "api": "newrelic/python-agent", "version": "11.0.0", "change_type": "breaking", "breaking": true, @@ -48,8 +48,8 @@ }, { "id": 3, - "fingerprint": "sha256:76b3c3353469c9b8fa468e742f019b0a625fba73be37263cec6db0c8a616a512", - "api": "newrelic", + "fingerprint": "sha256:2260cefe21b2807a9abc2144b46fd967e728f7e73dc2a489babb8ca0d77fa2b8", + "api": "newrelic/python-agent", "version": "11.0.0", "change_type": "breaking", "breaking": true, @@ -72,8 +72,8 @@ }, { "id": 4, - "fingerprint": "sha256:cc82dac7778ed8efcd9e407d06f00b5bd3180f3c7d471363c6b5b0f55feaa6fa", - "api": "newrelic", + "fingerprint": "sha256:a26a9a7d453398aa11ba51c77edf340e83d0eee8657c87a8a25ee517729648ba", + "api": "newrelic/python-agent", "version": "11.0.0", "change_type": "breaking", "breaking": true, @@ -95,8 +95,8 @@ }, { "id": 5, - "fingerprint": "sha256:c8d9b51b7477b5f17f7cd121463061fe58b21ebc7deeb51d64087eb84569b20a", - "api": "newrelic", + "fingerprint": "sha256:0d2b52b1e7f8601a5ccb6efa65ad4c028f2c8faceec43672af3f8e9f3de7183a", + "api": "newrelic/python-agent", "version": "11.0.0", "change_type": "breaking", "breaking": true, @@ -118,8 +118,8 @@ }, { "id": 6, - "fingerprint": "sha256:67f424f610fbafc21776c15219e51662c6f8b21d12db8039a104afe6a6ca6138", - "api": "newrelic", + "fingerprint": "sha256:6dac3561485ac1b50b934c773fbdf9d34244b6a238d4ffba84649653093ae020", + "api": "newrelic/python-agent", "version": "11.0.0", "change_type": "breaking", "breaking": true, @@ -141,8 +141,8 @@ }, { "id": 7, - "fingerprint": "sha256:8940a71ce47a561fd62c949d2b0ba691cd8b7f7d0a5fa8366dc5d56d411bfbf2", - "api": "newrelic", + "fingerprint": "sha256:726ecaafb7ec01c6471fa78cb1d90ba403489b8900b1d403c24f087e18cccbb7", + "api": "newrelic/python-agent", "version": "11.0.0", "change_type": "breaking", "breaking": true, diff --git a/plugins/removedmembers/testdata/golden/numpy-2.0.0.json b/plugins/migrationguide/testdata/golden/numpy-2.0.0.json similarity index 89% rename from plugins/removedmembers/testdata/golden/numpy-2.0.0.json rename to plugins/migrationguide/testdata/golden/numpy-2.0.0.json index aaddc0d..991600d 100644 --- a/plugins/removedmembers/testdata/golden/numpy-2.0.0.json +++ b/plugins/migrationguide/testdata/golden/numpy-2.0.0.json @@ -1,8 +1,8 @@ [ { "id": 1, - "fingerprint": "sha256:15ca3bff786fc3561429e5eb69ac1da7d0bce22bd5bded3d12bbdf878cec1237", - "api": "numpy", + "fingerprint": "sha256:b0783c632fa593bf60b79b17a531b3b57a421e999cf53927142ba7edb8ce3169", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -24,8 +24,8 @@ }, { "id": 2, - "fingerprint": "sha256:31adef4fb433c3a1cd5aec6cf01b2ce4a39767aa19890bb87637ec5b52d7597b", - "api": "numpy", + "fingerprint": "sha256:b41e888a7433412bc61a81d6ceba463fcafc9276fc09976ed6b32319388d2f81", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -47,8 +47,8 @@ }, { "id": 3, - "fingerprint": "sha256:e0ca458b9411438867eb70927c36c4e76ddb97ec52c3b9c931962f0b897653e0", - "api": "numpy", + "fingerprint": "sha256:126c06d99b4ddc08be5f6c574d69f5593f73bdaa9dfe4551741a54962aa902a1", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -70,8 +70,8 @@ }, { "id": 4, - "fingerprint": "sha256:a880a83ae4a2e2214a51d4fe3ab1f67c5bdf70141e3966e41509581817586d3c", - "api": "numpy", + "fingerprint": "sha256:143771722bc49885b35d3b9c7001fd19e56b9c26f4b21946e73c2e40e6fa4504", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -93,8 +93,8 @@ }, { "id": 5, - "fingerprint": "sha256:4080d657c3e2a0e548af8dc3658ca06f91023cf64533e4f56a00dcc5b3e0b0f6", - "api": "numpy", + "fingerprint": "sha256:4327f8787005edc444aece39bda8bdde02c8bbb2c725882200ae14674ca1116c", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -116,8 +116,8 @@ }, { "id": 6, - "fingerprint": "sha256:8bc3175f3e0e197a5fd4c9b1a4f8cee790e2663b526ca1dd1bcd94a1d9b63131", - "api": "numpy", + "fingerprint": "sha256:34eb3c1db0e9914ab4b3e0f7f4dc80cc1d1d5d2d1d743663aede4bcaaa5d66c1", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -139,8 +139,8 @@ }, { "id": 7, - "fingerprint": "sha256:bdd935da224960adcfd1d2b049fa065acb21b9964847030e40233f67caf95dc3", - "api": "numpy", + "fingerprint": "sha256:7b413031e868403cfadd2229a68286bc67c12fcfd9f99ae6936cc89333b7ad60", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -162,8 +162,8 @@ }, { "id": 8, - "fingerprint": "sha256:31be9451beae30671892b9c9cc9fb7853a978184758bca179c864f40a548cc24", - "api": "numpy", + "fingerprint": "sha256:96efba0d4e96431f67360a67c792c4d2e6a7d3b300593d3f5499d402a8a141fe", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -186,8 +186,8 @@ }, { "id": 9, - "fingerprint": "sha256:67a3cf67691368680dee4a27e2efa922cf3aab8860a3f21968c5a89bc706b812", - "api": "numpy", + "fingerprint": "sha256:2c9778be1dd3f63b98e74f9c07c0a6bdf18e26784c8f002ed2cc39b9f52aec8d", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -210,8 +210,8 @@ }, { "id": 10, - "fingerprint": "sha256:6e5320feb35889323ccd3d0296e4aeb7ee23114e6298966a3fa570d1d48e73bc", - "api": "numpy", + "fingerprint": "sha256:17cf21d49a707d39eb5bac336e6e915ba800f76cfe50d3aa7a33d5de7fbc3543", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -233,8 +233,8 @@ }, { "id": 11, - "fingerprint": "sha256:d3efb66bfb97ffe7095f82a1b6ea589e52e34a9f23b465c619fac2af5ca08b53", - "api": "numpy", + "fingerprint": "sha256:ff51f64a013851f451e5776574e3a65e81cf2656c1573635f21323da7861c455", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -257,8 +257,8 @@ }, { "id": 12, - "fingerprint": "sha256:a0c45f87acdd2ecfc8231e86b58dcbdfde45d15dc63ff23d9b8dd8da01c647ae", - "api": "numpy", + "fingerprint": "sha256:69a3ba2862b32c578da907e78f05206cee14710ef791fdb55c8996f2268984d3", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -281,8 +281,8 @@ }, { "id": 13, - "fingerprint": "sha256:0030b240846eb6fcf0c4298e29ed2fb7d04dc6d4c0296e5a6e078fc0cb45528a", - "api": "numpy", + "fingerprint": "sha256:e9143511f87c438ed0ab56301560b4daba766c10b336bea7be5bcc97efb9b4bf", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -304,8 +304,8 @@ }, { "id": 14, - "fingerprint": "sha256:7cda747a751f26ff3e7b9bd74eba2597feab78e1e9cd8c9e73c07fc7f99a26ff", - "api": "numpy", + "fingerprint": "sha256:764794a1bf403c2c6095e79a508ef212f954b1ec6f6619d3ae54355adef33d4b", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -327,8 +327,8 @@ }, { "id": 15, - "fingerprint": "sha256:8f0cd5edeab67e754702c65c3a3ed4b85dbc115dcc1462334fdfa711dcd92bde", - "api": "numpy", + "fingerprint": "sha256:8715ec0959044c083b44c8c9535f74c742ae3a544671f43d5abfa5087be7790e", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -350,8 +350,8 @@ }, { "id": 16, - "fingerprint": "sha256:58706e17b74f39ebfb8a82edaee01e0639d3c31cbeb2ec8df6e0e50ecd3dfc07", - "api": "numpy", + "fingerprint": "sha256:2be00bcbf01b6dd7451390a12425e16d9cc3d994b01f17fc6278f479c746b062", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -373,8 +373,8 @@ }, { "id": 17, - "fingerprint": "sha256:296d49650c8693884ae3462931747e2855d76d007d7a4c15b5a6d78cf7112842", - "api": "numpy", + "fingerprint": "sha256:f56cd36c2524684fbcbe8bd45bf74610d19797ab9cfc045f209c065d5c6a2b15", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -396,8 +396,8 @@ }, { "id": 18, - "fingerprint": "sha256:f0027b95736ab12febb6e08f480bfe95de911cfaa817b27d867cce069ec29b83", - "api": "numpy", + "fingerprint": "sha256:dd911afbc6bdb4121681393823532d3eed009a278ce1e0eec6452b3e43deedaa", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -419,8 +419,8 @@ }, { "id": 19, - "fingerprint": "sha256:43741a40b134e0770d1c4d6d1d6f1ed5515f64b18d68015455cb9035ce566ed8", - "api": "numpy", + "fingerprint": "sha256:7b44dc9e7fe08590408c8f94edacfcb036286de2c7e2e80d9a92c81afdcd6a46", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -442,8 +442,8 @@ }, { "id": 20, - "fingerprint": "sha256:18938bf76e659fe0e7f7180141f9d35f9ea93fa79a91f91a9f72aeb1c58bba14", - "api": "numpy", + "fingerprint": "sha256:8711daa446d6d4a8683f49f9db118ae5bdf53c31b4c9f77a0398d816fc25980a", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -466,8 +466,8 @@ }, { "id": 21, - "fingerprint": "sha256:7cacd8aaadd83c25504c353adbdc041e12620a438136765ef807f47b6b50f8b6", - "api": "numpy", + "fingerprint": "sha256:dfbe1b3d248418215f52b5f2c8e8c0b69d2b71989fa5f94f98c855f02ac5eb97", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -489,8 +489,8 @@ }, { "id": 22, - "fingerprint": "sha256:e872dbb246ccc076a0316c2b8976bb7136a30af743bcafca7df46ee19e91d5f1", - "api": "numpy", + "fingerprint": "sha256:f129fb52117ed68b20a0aa025644c24e048a6bf66deabbe05ec506094c2550ef", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -513,8 +513,8 @@ }, { "id": 23, - "fingerprint": "sha256:9759a187d780c88637c0715501f9b6702cbea6be1c2ea4c4958bece3455ba117", - "api": "numpy", + "fingerprint": "sha256:c527e0e526ce8934592299baf54a586aca4a7668a12f9e74b71cc7cc39738dc4", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -537,8 +537,8 @@ }, { "id": 24, - "fingerprint": "sha256:a09224e2ef5444c9eccb6e5d7dca373bb19cae967839bc3b22fecc6defb8dd6b", - "api": "numpy", + "fingerprint": "sha256:0daa283517da38834730ed51076b83f24d0ad28e9fa5baf7efc56247623fdcf8", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -561,8 +561,8 @@ }, { "id": 25, - "fingerprint": "sha256:dbdd41b69dfec3cd9e6cd11a464ed14f45b2d2c46da45dbd7532bd7eb0622060", - "api": "numpy", + "fingerprint": "sha256:4e160f1fe78740c45b7668fb06a5176734867992b9f37ac4eb1680b18bf87260", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -584,8 +584,8 @@ }, { "id": 26, - "fingerprint": "sha256:e65a1389f496e28b194eadce0cd227a359ff361bee0db4cb5a55f25d31597f0d", - "api": "numpy", + "fingerprint": "sha256:154c87acc07c26f96f8516063d516eee04a1d6b60840e7acf505b651d6677add", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -607,8 +607,8 @@ }, { "id": 27, - "fingerprint": "sha256:c02c17094b4d43e477530bc816219f322d2a41272fc62152540926cf78ede9fa", - "api": "numpy", + "fingerprint": "sha256:4bbfbf7969500581b7d16e9651d80d1b9358921bf589307704e2385bbedc59ac", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -631,8 +631,8 @@ }, { "id": 28, - "fingerprint": "sha256:25253550b494a1da396614b2b35dbebc138501c541e093e2f52ff588dbea5a73", - "api": "numpy", + "fingerprint": "sha256:d4a1985a0357792efe4789c2233bad139cf8928458e0ec785ce1b1cd7fb11e73", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -655,8 +655,8 @@ }, { "id": 29, - "fingerprint": "sha256:1cf8b9821742bc5dc37853fd44b300cdd367d935697f97570f075749f0a5cb20", - "api": "numpy", + "fingerprint": "sha256:c88871cfc1ecb72bc4aad8cd5b6f23bcf15e380846669f8af005e30de83ef47c", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -678,8 +678,8 @@ }, { "id": 30, - "fingerprint": "sha256:943c39007430553d0618e207c7d22227f1adae5e034e95430d33a5352acb5f19", - "api": "numpy", + "fingerprint": "sha256:4863038fb9b91d931b5fdc30826b3ad1ea5ba69328c37260ae0959fadbed7aee", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -702,8 +702,8 @@ }, { "id": 31, - "fingerprint": "sha256:36ef006fd617b6fea0238bd570a894bcc58664d7ce3b0cdb9112dfce8be40166", - "api": "numpy", + "fingerprint": "sha256:ec88ce6ee9843e242b2389245d90ddc4f9ec7dc22e1116f6bfe430949da19005", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -725,8 +725,8 @@ }, { "id": 32, - "fingerprint": "sha256:dece31f907bc1de0e1f62c40575ea06f1fc38caa0cfedf11c1325c75452c7f2d", - "api": "numpy", + "fingerprint": "sha256:eed7dac5bb066436ce0df5666bc15e405ec3955c9e167439b588243e878bff11", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -748,8 +748,8 @@ }, { "id": 33, - "fingerprint": "sha256:13aa7c2a699cbf1ef45bb673f17dbd2deac81957a6f59d0a150df5392bade17b", - "api": "numpy", + "fingerprint": "sha256:caca0ecc8275dd7119f4f04f80c3e8b9783d6016ba28221a4238eb2dff79e3bb", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -771,8 +771,8 @@ }, { "id": 34, - "fingerprint": "sha256:288ad6e666d5a56a2f47647c111151b9db456eef88d276bed86ae0bb3b6e2f3e", - "api": "numpy", + "fingerprint": "sha256:dc18158f7f52098c8fa5647ad0f3ac016020f23d684bf3e8a204c33cf855a394", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -795,8 +795,8 @@ }, { "id": 35, - "fingerprint": "sha256:26b2f0ce1ba6a884e6dafea4f8cc9b8377ad85feb628895b7c493a896a322e72", - "api": "numpy", + "fingerprint": "sha256:abdf8696910cd0012a63c8c7826a3a4ed1c43872627247b449a69d2bad8434de", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -819,8 +819,8 @@ }, { "id": 36, - "fingerprint": "sha256:9dfe8575c70bcd4246326930a7f9f55910f187b79d914e4de158d3e93cd21155", - "api": "numpy", + "fingerprint": "sha256:863640a58894e351474344af0dbdfafd91fd40aef2323e21ded6b6d43ba5da23", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -842,8 +842,8 @@ }, { "id": 37, - "fingerprint": "sha256:276d393aac6bcd797df9065d46af3b097c1777ad6f5e3bfd6cd006576cdf1468", - "api": "numpy", + "fingerprint": "sha256:5a8b83d2b15698a7e304bc6b5d7b2ccd073f4502705fb64e5db5d60218d594c1", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -865,8 +865,8 @@ }, { "id": 38, - "fingerprint": "sha256:73549489018185907fb06522b14b37dba277fda5ff38ac98120455cc9cee1371", - "api": "numpy", + "fingerprint": "sha256:35c02de167c3581dbfbbd1cb2ef0a42398a7fe0759792b5c71ba2f45ffa6af7a", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -889,8 +889,8 @@ }, { "id": 39, - "fingerprint": "sha256:966e363f14bb09c9e62ff95a5407f03edba58391171de8ed47f1691971c2aba4", - "api": "numpy", + "fingerprint": "sha256:868ad45a4f8c29663f19bdeb84ee97653721419c4457ec2431271509ed57387f", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -913,8 +913,8 @@ }, { "id": 40, - "fingerprint": "sha256:efdbf7cfe045999a63e9c7bbf2e5735dc536d537ae9b186fc580d7a3d95eb409", - "api": "numpy", + "fingerprint": "sha256:13f12000b0678c2a9990c8aba54e12e4574edd78f624e0d88fcdb981ac2d32e2", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -936,8 +936,8 @@ }, { "id": 41, - "fingerprint": "sha256:6a4405f736f938b02903ba7f9b8d5b38df782fbda7ae257795b82b946a458e80", - "api": "numpy", + "fingerprint": "sha256:136c816d0e1236b96b4f5b19fa9fd6675cf09e64048d459cd14cc014f4aafd49", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -959,8 +959,8 @@ }, { "id": 42, - "fingerprint": "sha256:e97c77fcc18491acc9ed4cd1ea6fd7f29aae24ee1fa169db62b7f7a31b7bc827", - "api": "numpy", + "fingerprint": "sha256:5ed93388730232ca923f22a1647cba930bedc3114dde3a5433ab2f8698dee684", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -983,8 +983,8 @@ }, { "id": 43, - "fingerprint": "sha256:6c959fbdd43160b9a41db2011948c1fd88ce7198b32b6eded5a71bdde5e39fe2", - "api": "numpy", + "fingerprint": "sha256:b6db560c04fea4149c33667d36aeba13d6706d1f78887f9e7e7f38dcdd61f92d", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -1007,8 +1007,8 @@ }, { "id": 44, - "fingerprint": "sha256:7f3fad835d10581ee56dc0a6ad91cb67e144d12a973ce9c969c5940213217ad3", - "api": "numpy", + "fingerprint": "sha256:bee468fe3c58f14587d4a58871a1662d9f0d832361b740634683a7a285ac43f0", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -1030,8 +1030,8 @@ }, { "id": 45, - "fingerprint": "sha256:9611a26e2eb09d38e7433fa076d1bb2ec839c5d902dcbac4c1938af197f6a8bd", - "api": "numpy", + "fingerprint": "sha256:914dfac763acc9361bbfdec6541a697ae7763bf09a2240c9cbd1fafe78d1f531", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -1053,8 +1053,8 @@ }, { "id": 46, - "fingerprint": "sha256:f9f9805e34a27f268e063aa6d53ba51a02ed5b07e4af35cd2ebfb5141bd841b2", - "api": "numpy", + "fingerprint": "sha256:ba6b201483db19e04bacc9e46ee1c2c9e58ec4cd51bb9216e2be39fe3a76d594", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -1076,8 +1076,8 @@ }, { "id": 47, - "fingerprint": "sha256:aae912e01e4f6aa9bb104dea9d74df1afeb980f8f624ba717b05f234f6d05f76", - "api": "numpy", + "fingerprint": "sha256:7d680b6a440b3a14ac495e905a379f0eec3527c49e1cc98403bff35ff6bd66f0", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -1099,8 +1099,8 @@ }, { "id": 48, - "fingerprint": "sha256:c9d99c27e0930ff70cf589356f74ab0114dab15abeb8e2795f4f151fa1fbf20e", - "api": "numpy", + "fingerprint": "sha256:9ed3f595c62d8e9780887a58970e82c9af7d416b0457ceac0bf1cc55a518b0c6", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -1122,8 +1122,8 @@ }, { "id": 49, - "fingerprint": "sha256:c1df4a2128af0680e401486f20180186da52ff92ea0c5bdf2dedc11fecccddb4", - "api": "numpy", + "fingerprint": "sha256:ced822e6a5b1ef208d6a8df0f78f9f542bd19bf3219fffeda83039d3bdd3c492", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -1145,8 +1145,8 @@ }, { "id": 50, - "fingerprint": "sha256:c3efb85726892dc1421804f037cd85247d642fc99fb44fc916ce88bb2d510b38", - "api": "numpy", + "fingerprint": "sha256:d94b2c6839f05465a1c6437c3e1a5316596258e5d999abca0e3f942cf8b1bdd7", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -1169,8 +1169,8 @@ }, { "id": 51, - "fingerprint": "sha256:3ce841cef5c56603ffda8bc14ace116d8eb54c9e367b8c4f9925ca4cc13aec0e", - "api": "numpy", + "fingerprint": "sha256:da92a61aba8cbc8ae017a52ed418811d6c464e05c7df1945bf513e2f1617c667", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -1193,8 +1193,8 @@ }, { "id": 52, - "fingerprint": "sha256:62f3f736f96c393c86870c3817cb03305abe0b98ee04fbc2d019809318ee279d", - "api": "numpy", + "fingerprint": "sha256:0d4bd197cb31ba8d395640fe104102c0e549b4e0f63c3a6557159f62f28255d1", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -1216,8 +1216,8 @@ }, { "id": 53, - "fingerprint": "sha256:35df9a18690f8a99e2f519b0edc215e4a7ac9f605d70ae8f37895493dfc9d972", - "api": "numpy", + "fingerprint": "sha256:0244a14e2f675fc4f2d854012e79e2242c3441b855dfc0acad32a69fcd837121", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -1239,8 +1239,8 @@ }, { "id": 54, - "fingerprint": "sha256:700e9b695d9c57e1dfe878849f3829d1023334cfab92727806c861e025db1ab8", - "api": "numpy", + "fingerprint": "sha256:120004adecac61928b41859f183e0ea707c9218d6d1270b743699b1980984c7b", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -1262,8 +1262,8 @@ }, { "id": 55, - "fingerprint": "sha256:e8b05f5f78a91df2ab0925e7569580527a21de6ef70eda22f2ebfa1e9fd44f93", - "api": "numpy", + "fingerprint": "sha256:a142b4adeea44bce0f23cdd28e54f874fd13f180494362e26aa85ae825ec80a8", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, @@ -1286,8 +1286,8 @@ }, { "id": 56, - "fingerprint": "sha256:60c6a22d6aab5ef8d2c3a1e48d86ace1f9a2a85d7b462ea0554df76db7be0e40", - "api": "numpy", + "fingerprint": "sha256:d2ba751b9e8289c6e868330d2ea952ba118290c301dea8c809e8b617bbdc1f1c", + "api": "numpy/numpy", "version": "2.0.0", "change_type": "breaking", "breaking": true, diff --git a/plugins/removedmembers/testdata/golden/posthog-8.0.0.json b/plugins/migrationguide/testdata/golden/posthog-8.0.0.json similarity index 86% rename from plugins/removedmembers/testdata/golden/posthog-8.0.0.json rename to plugins/migrationguide/testdata/golden/posthog-8.0.0.json index 4439b59..83330ff 100644 --- a/plugins/removedmembers/testdata/golden/posthog-8.0.0.json +++ b/plugins/migrationguide/testdata/golden/posthog-8.0.0.json @@ -1,8 +1,8 @@ [ { "id": 1, - "fingerprint": "sha256:cc0790387fbe50505a8c3116cb1678892d2b49643002a99259eeb81144bc4159", - "api": "posthog", + "fingerprint": "sha256:75d945cf03e52543a2fdabae1c94e6e81322a2fee42c6623830c6b9b5ffc4e40", + "api": "posthog/python-sdk", "version": "8.0.0", "change_type": "breaking", "breaking": true, @@ -24,8 +24,8 @@ }, { "id": 2, - "fingerprint": "sha256:0ac3ae87979a15b9bd217da712b7deb2c20063e72f2a717a436c11040384fd37", - "api": "posthog", + "fingerprint": "sha256:d91ba129157bb359c50102c4c532f811a949d0612abb8d45d0992e4dc7aefcbf", + "api": "posthog/python-sdk", "version": "8.0.0", "change_type": "breaking", "breaking": true, @@ -47,8 +47,8 @@ }, { "id": 3, - "fingerprint": "sha256:1a38df0902754ee8485ccc7462afb9cff35c7de933e11b3205c93babbdb05863", - "api": "posthog", + "fingerprint": "sha256:7b1dbda0f8429ab629a5a041205a2e2e036e348e6810f9ee62f372e7446b2dd8", + "api": "posthog/python-sdk", "version": "8.0.0", "change_type": "breaking", "breaking": true, @@ -70,8 +70,8 @@ }, { "id": 4, - "fingerprint": "sha256:0736d4f7aee4ddfa0c13654ba26a45586844d6628d353e5d43b84f646b6dd0f6", - "api": "posthog", + "fingerprint": "sha256:94d72e7984b7e207ea3eee48a2047efdcfb651bb3774a0af926c5368b351a3e4", + "api": "posthog/python-sdk", "version": "8.0.0", "change_type": "breaking", "breaking": true, @@ -93,8 +93,8 @@ }, { "id": 5, - "fingerprint": "sha256:417930dab98562db2bb15d2bd3926baf9689950100e9e9ffe78d5bc9c26602ad", - "api": "posthog", + "fingerprint": "sha256:fcee60f271c6aec47734b6a4577de6b3f06e32f1e025e98a625f675fa794c41c", + "api": "posthog/python-sdk", "version": "8.0.0", "change_type": "breaking", "breaking": true, @@ -116,8 +116,8 @@ }, { "id": 6, - "fingerprint": "sha256:4184ff3cbb866e22be67075e91e9e1d05b6ac9711ea5fc0bbae6b7a8d3b2d814", - "api": "posthog", + "fingerprint": "sha256:9fb8ed99a7840f76c8148d3da79ee9d391a5db28579219d944d3d2ecc96418ae", + "api": "posthog/python-sdk", "version": "8.0.0", "change_type": "breaking", "breaking": true, @@ -139,8 +139,8 @@ }, { "id": 7, - "fingerprint": "sha256:8639fcae424bb8a4c15aebef34c5aa1f6c1fd80ed5d5817b7ff07d8ea57c6ef6", - "api": "posthog", + "fingerprint": "sha256:c39d1f380b736e1e5bb84d008ef468e59469aec919aabeef97ea412549c9e139", + "api": "posthog/python-sdk", "version": "8.0.0", "change_type": "breaking", "breaking": true, diff --git a/plugins/eol/eol.go b/plugins/notices/eol/eol.go similarity index 62% rename from plugins/eol/eol.go rename to plugins/notices/eol/eol.go index 4bd1e31..76d85d8 100644 --- a/plugins/eol/eol.go +++ b/plugins/notices/eol/eol.go @@ -1,4 +1,5 @@ -// Package eol is the source plugin for a vendor's own API end-of-life page: a +// Package eol is the notices kind's reader for a vendor's own API +// end-of-life page (plugins/notices reads it, snapshots and cites it): a // table of whole version ranges, each with a support status. One event per // version number a row says is already retired (breaking) or scheduled to be // (deprecation); a row that only says "Supported." names nothing to report. @@ -8,12 +9,13 @@ // it, taken after a successful read of the live page, so the citation always // says what the plugin actually saw. // -// Salesforce's docs site is the one difference from retirements and feed: it -// answers 403 to a plain GET (checked 2026-11-20, including with a browser -// User-Agent), so Run's direct read of the live page fails every time. The +// Salesforce's docs site is the one difference from the other notices +// readers: it answers 403 to a plain GET (checked 2026-11-20, including with +// a browser User-Agent), so a direct read of the live page fails every time. The // Wayback Machine's own save-page-now request succeeds against it anyway, // and its capture parses to the same findings the live page would (checked -// the same day), so Run falls back to a fresh snapshot on a 401 or 403, +// the same day), so the kind falls back to a fresh snapshot on a 401 or 403 +// (ArchiveWhenBlocked), // used directly as both the content and its own citation, kit.Cite's // double-check skipped: there is no separate live read left to agree with. // @@ -23,35 +25,20 @@ package eol import ( - "context" - "errors" "fmt" "log" "regexp" "strconv" "strings" + "time" "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() { - plugin.RegisterProvider(plugin.Provider{ - ID: "salesforce", Name: "Salesforce", Category: plugin.CategoryCRM, Homepage: "https://www.salesforce.com", - Sources: []plugin.Source{{ - ID: "rest-api", Layer: plugin.LayerAPI, Page: "providers/salesforce.md", - Watches: "REST API version ranges deprecated and retired, from Salesforce's own API end-of-life policy page", - URLs: []string{"https://developer.salesforce.com/docs/platform/api-rest/guide/api-rest-eol.html"}, - Plugin: Plugin{Page: Salesforce, Archiver: kit.Wayback{}}, - }}, - }) -} - // Page is one vendor's end-of-life table. type Page struct { - API string // the events' api: "salesforce" + API string // the source id the events carry: "salesforce/rest-api" Vendor string // for sentences: "Salesforce" URL string // the page, as HTML // Operation names the one real, documented, version-rooted resource a @@ -71,7 +58,7 @@ type Page struct { // policy text above the table says the notice is at least a year ahead of // retirement. var Salesforce = Page{ - API: "salesforce", Vendor: "Salesforce", + API: "salesforce/rest-api", Vendor: "Salesforce", URL: "https://developer.salesforce.com/docs/platform/api-rest/guide/api-rest-eol.html", Operation: func(v string) string { return "GET /services/data/v" + v + "/" }, } @@ -183,111 +170,67 @@ func Findings(page []byte) ([]Finding, error) { return out, nil } -// Plugin reads one vendor's end-of-life page. -type Plugin struct { - Page Page - Archiver kit.Archiver -} +// What the notices kind (plugins/notices) asks of an end-of-life page. -func (p Plugin) Name() string { return p.Page.API } +// Read is what one read of a page found, dropped rows included. +type Read []Finding -// Run reads the page as it is now. An unchanged page since the last run costs -// one GET and no snapshot, unless the live page is blocked: see liveOrArchived. -func (p Plugin) Run(ctx context.Context, env plugin.Env) (plugin.Result, error) { - pg := p.Page - live, archived, err := liveOrArchived(ctx, env, p.Archiver, pg.URL) - if err != nil { - return plugin.Result{}, fmt.Errorf("fetching %s: %w", pg.URL, err) - } - hash := plugin.SHA256(live) - last, same, err := kit.Unchanged(env, pg.API, live) - if err != nil { - return plugin.Result{}, err - } - if same { - log.Printf("%s: no change since %s", pg.API, last.SourceURL) - return plugin.Result{}, nil - } +// Count is how many findings the page gave. +func (r Read) Count() int { return len(r) } - want, err := Findings(live) - if err != nil { - return plugin.Result{}, fmt.Errorf("reading %s: %w", pg.URL, err) - } +// Slug is the source id the events carry: "salesforce/rest-api". +func (pg Page) Slug() string { return pg.API } - snapURL, snap, got := archived, live, want - if snapURL == "" { - snapURL, snap, got, err = kit.Cite(ctx, p.Archiver, pg.URL, Findings, want) - if err != nil { - return plugin.Result{}, err - } - } +// PageURL is the page, as HTML. +func (pg Page) PageURL() string { return pg.URL } + +// Find reads every row of the page. +func (pg Page) Find(page []byte) (kit.Notices, error) { + fs, err := Findings(page) + return Read(fs), err +} - now := env.Now().UTC() - var events []event.EventV2 +// ArchiveWhenBlocked is on: Salesforce's docs site answers 403 to a plain +// GET, so the kind reads a fresh Wayback Machine snapshot instead (see the +// package comment). +func (Page) ArchiveWhenBlocked() bool { return true } + +// Events are an event per version number a row retires or deprecates, +// citing citeURL; a dropped row is logged with why. +func (pg Page) Events(found kit.Notices, citeURL string, now time.Time) ([]event.Event, []error) { + var events []event.Event var rejected []error - for _, f := range got { + for _, f := range found.(Read) { if f.Dropped != "" { log.Printf("%s: dropped %s: %s", pg.API, f.Row, f.Dropped) continue } - e := event.EventV2{ + e := event.Event{ API: pg.API, Version: f.Version, ChangeType: f.ChangeType, Breaking: f.ChangeType == event.ChangeTypeBreaking, Subject: event.Subject{ Type: event.SubjectAPIOperation, - Kind: event.AffectedKindOperation, + Kind: event.KindOperation, Side: event.SideRequest, Operation: pg.Operation(f.Version), }, Description: describe(pg, f), - MigrationHint: fmt.Sprintf("Pin a newer %s REST API version: %s names which ones are still supported.", pg.Vendor, snapURL), - SourceURL: snapURL, + MigrationHint: fmt.Sprintf("Pin a newer %s REST API version: %s names which ones are still supported.", pg.Vendor, citeURL), + SourceURL: citeURL, SourceExcerpt: f.Excerpt, Confidence: 1.0, DetectedAt: now, } - e.Fingerprint = event.FingerprintV2(e.API, e.Version, e.ChangeType, e.Subject, "") + e.Fingerprint = event.Fingerprint(e.API, e.Version, e.ChangeType, e.Subject, "") if err := e.Validate(); err != nil { rejected = append(rejected, fmt.Errorf("%s %s: %w", pg.API, f.Version, err)) continue } events = append(events, e) } - baseline := plugin.Baseline(pg.API, now.Format("2006-01-02"), snapURL, snapURL, snap, false, now) - baseline.SHA256 = hash - return plugin.Result{Label: snapURL, Events: events, Rejected: rejected, Baselines: []plugin.Spec{baseline}}, nil -} - -// liveOrArchived reads pageURL directly. When the provider's own site -// blocks a plain fetch with 401 or 403 (Salesforce's docs site, every time, -// checked 2026-11-20; confirmed the same day that a real Wayback Machine -// save-page-now capture of this exact page parses to the same findings as -// the live page would), it falls back to a fresh Wayback Machine snapshot, -// taken right now by the archive's own crawler rather than patch-it's, and -// returns that content with its own permanent URL in archivedURL: it needs -// no further citation step, having come from the archive already. -// -// Only 401 and 403 fall back. A 404 or 410 means the page moved, not that -// it's blocked: asking the archive to snapshot a page that's gone would -// waste the call and hide the real cause behind the archive's own error. -// A 429 or a 5xx is returned as is: retrying it against the archive would -// hide a transient failure as a real page, not fix one. -func liveOrArchived(ctx context.Context, env plugin.Env, a kit.Archiver, pageURL string) (body []byte, archivedURL string, err error) { - body, err = env.Get(ctx, pageURL) - if err == nil { - return body, "", nil - } - var se *fetch.StatusError - if !errors.As(err, &se) || (se.StatusCode != 401 && se.StatusCode != 403) { - return nil, "", err - } - archivedURL, body, archErr := a.Snapshot(ctx, pageURL) - if archErr != nil { - return nil, "", fmt.Errorf("fetching it directly failed (%w), and so did asking the Wayback Machine to: %w", err, archErr) - } - return body, archivedURL, nil + return events, rejected } func describe(pg Page, f Finding) string { diff --git a/plugins/eol/testdata/README.md b/plugins/notices/eol/testdata/README.md similarity index 100% rename from plugins/eol/testdata/README.md rename to plugins/notices/eol/testdata/README.md diff --git a/plugins/eol/testdata/salesforce-api-rest-eol-2026-10-31.html b/plugins/notices/eol/testdata/salesforce-api-rest-eol-2026-10-31.html similarity index 100% rename from plugins/eol/testdata/salesforce-api-rest-eol-2026-10-31.html rename to plugins/notices/eol/testdata/salesforce-api-rest-eol-2026-10-31.html diff --git a/plugins/eol/eol_test.go b/plugins/notices/eol_test.go similarity index 76% rename from plugins/eol/eol_test.go rename to plugins/notices/eol_test.go index 6ceac40..eea4725 100644 --- a/plugins/eol/eol_test.go +++ b/plugins/notices/eol_test.go @@ -1,4 +1,4 @@ -package eol +package notices import ( "context" @@ -9,13 +9,14 @@ import ( "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" + "github.com/patch-it-dev/patch-it-plugins/plugins/notices/eol" ) -func TestRegistersItself(t *testing.T) { - kittest.Registered(t, Plugin{Page: Salesforce}) +func TestEOLRegistersItself(t *testing.T) { + kittest.Registered(t, Plugin{Page: eol.Salesforce}) } -// The golden test: Salesforce's own end-of-life policy page (checked +// The golden test: eol.Salesforce's own end-of-life policy page (checked // 2026-11-20, saved 2026-10-31), real and unedited but for dropping the // surrounding navigation chrome. It already holds two real, past retirements // (versions 7.0 through 20.0, retired as of Summer '22; versions 21.0 @@ -23,10 +24,10 @@ func TestRegistersItself(t *testing.T) { // (versions 31.0 through 40.0, deprecated from Summer '27, retired from // Summer '28): 34 events, and the still-"Supported." 41.0 through 67.0 band // names none, the pinned drop test. -func TestGolden(t *testing.T) { - saved := kittest.Pages{Salesforce.URL: "testdata/salesforce-api-rest-eol-2026-10-31.html"} +func TestEOLGolden(t *testing.T) { + saved := kittest.Pages{eol.Salesforce.URL: "eol/testdata/salesforce-api-rest-eol-2026-10-31.html"} archive := &kittest.Archive{T: t, Pages: saved} - got := kittest.IngestWith(t, kittest.Env(t, saved), Plugin{Page: Salesforce, Archiver: archive}) + got := kittest.IngestWith(t, kittest.Env(t, saved), Plugin{Page: eol.Salesforce, Archiver: archive}) if archive.Calls != 1 { t.Errorf("%d snapshots, want 1: the second run's page is unchanged", archive.Calls) } @@ -36,8 +37,8 @@ func TestGolden(t *testing.T) { // The pinned drop test: "Versions 41.0 through 67.0: Supported." is a real // row on the page, and it must name no version. func TestDropsAStillSupportedBand(t *testing.T) { - page := kittest.Read(t, "testdata/salesforce-api-rest-eol-2026-10-31.html") - found, err := Findings(page) + page := kittest.Read(t, "eol/testdata/salesforce-api-rest-eol-2026-10-31.html") + found, err := eol.Findings(page) if err != nil { t.Fatal(err) } @@ -59,23 +60,23 @@ func TestDropsAStillSupportedBand(t *testing.T) { } } -// Salesforce's docs site answers 403 to a plain GET; the live page is never +// eol.Salesforce's docs site answers 403 to a plain GET; the live page is never // reachable through env.Get. Run must fall back to the Wayback Machine's own // fetch and use its snapshot directly, not fail outright. 401 falls back the // same way. func TestFallsBackToTheArchiveWhenTheLiveFetchIsBlocked(t *testing.T) { for _, code := range []int{401, 403} { t.Run(fmt.Sprint(code), func(t *testing.T) { - saved := kittest.Pages{Salesforce.URL: "testdata/salesforce-api-rest-eol-2026-10-31.html"} + saved := kittest.Pages{eol.Salesforce.URL: "eol/testdata/salesforce-api-rest-eol-2026-10-31.html"} archive := &kittest.Archive{T: t, Pages: saved} env := plugin.Env{ Baselines: kittest.NewMem(), Get: func(context.Context, string) ([]byte, error) { - return nil, &fetch.StatusError{URL: Salesforce.URL, StatusCode: code} + return nil, &fetch.StatusError{URL: eol.Salesforce.URL, StatusCode: code} }, Now: func() time.Time { return kittest.Clock }, } - got := kittest.IngestWith(t, env, Plugin{Page: Salesforce, Archiver: archive}) + got := kittest.IngestWith(t, env, Plugin{Page: eol.Salesforce, Archiver: archive}) if len(got) == 0 { t.Fatal("no events: the archive fallback didn't run") } @@ -88,7 +89,7 @@ func TestFallsBackToTheArchiveWhenTheLiveFetchIsBlocked(t *testing.T) { t.Errorf("%d snapshots, want 2: the live page is blocked every run", archive.Calls) } for _, e := range got { - if e.SourceURL == Salesforce.URL { + if e.SourceURL == eol.Salesforce.URL { t.Errorf("%s: source_url is the blocked live page, want the archive's snapshot", e.Fingerprint) } } @@ -105,13 +106,13 @@ func TestDoesNotFallBackOnATransientError(t *testing.T) { env := plugin.Env{ Baselines: kittest.NewMem(), Get: func(context.Context, string) ([]byte, error) { - return nil, &fetch.StatusError{URL: Salesforce.URL, StatusCode: code} + return nil, &fetch.StatusError{URL: eol.Salesforce.URL, StatusCode: code} }, Now: func() time.Time { return kittest.Clock }, } // No Pages: a fallback here would fail the test by asking the // archive for a snapshot it was never given. - _, err := Plugin{Page: Salesforce, Archiver: &kittest.Archive{T: t}}.Run(context.Background(), env) + _, err := Plugin{Page: eol.Salesforce, Archiver: &kittest.Archive{T: t}}.Run(context.Background(), env) if err == nil { t.Fatalf("want an error for a %d, got none", code) } diff --git a/plugins/feed/cloudflare_test.go b/plugins/notices/feed/cloudflare_test.go similarity index 99% rename from plugins/feed/cloudflare_test.go rename to plugins/notices/feed/cloudflare_test.go index 83d23fe..2989a10 100644 --- a/plugins/feed/cloudflare_test.go +++ b/plugins/notices/feed/cloudflare_test.go @@ -47,7 +47,7 @@ func TestCloudflareRegistrarEndOfLife(t *testing.T) { if f.ChangeType != event.ChangeTypeBreaking || f.Version != "2026-09-27" { t.Errorf("%s: %s %s, want breaking 2026-09-27", f.Subject.Operation, f.ChangeType, f.Version) } - if f.Subject.Type != event.SubjectAPIOperation || f.Subject.Kind != event.AffectedKindOperation || f.Subject.Side != event.SideRequest { + if f.Subject.Type != event.SubjectAPIOperation || f.Subject.Kind != event.KindOperation || f.Subject.Side != event.SideRequest { t.Errorf("%s: subject %+v", f.Subject.Operation, f.Subject) } for _, line := range []string{"API deprecations - Legacy Registrar Domain Management API", "End of life date: September 27, 2026", diff --git a/plugins/notices/feed/extract.go b/plugins/notices/feed/extract.go new file mode 100644 index 0000000..c7d14fe --- /dev/null +++ b/plugins/notices/feed/extract.go @@ -0,0 +1,19 @@ +package feed + +import "github.com/patch-it-dev/patch-it-plugins/core/extract" + +// The feed and HTML helpers live in core/extract, for every reader; these +// names keep the readers here (and code that imports them) as they were. +type ( + Entry = extract.Entry + Section = extract.Section +) + +var ( + Parse = extract.ParseFeed + Text = extract.Text + Lines = extract.Lines + SplitBy = extract.SplitBy + Date = extract.Date + Codes = extract.Codes +) diff --git a/plugins/notices/feed/feed.go b/plugins/notices/feed/feed.go new file mode 100644 index 0000000..59f5deb --- /dev/null +++ b/plugins/notices/feed/feed.go @@ -0,0 +1,121 @@ +// Package feed is the notices kind's reader for a vendor's RSS or Atom +// changelog feed (plugins/notices reads it, snapshots and cites it): one event per breaking or deprecation entry (or per name such an +// entry lists), quoting the line that says so. Rung 3 of the source ladder. +// +// A feed is prose, so each feed comes with a Reader that knows what its +// vendor's entries look like and which subject they describe. The rules are +// the same for every reader (precision over recall): +// +// - An entry the vendor doesn't mark as breaking or deprecation (a category, +// a heading) is skipped. +// - A marked entry becomes an event only when the reader finds a typed +// subject in it (a runner label, a model id in code) and a dated +// sentence. Otherwise it is dropped, logged with why, never guessed. +// - `breaking` needs the vendor to say the thing stops on a date ("will be +// retired on", "will be shut down on"). Anything softer ("we recommend +// updating before") is downgraded to `deprecation`. +// +// A feed is a live document, so the events cite a Wayback Machine snapshot +// of it, read back and checked against the live feed (kit.Cite), like every +// notices source. +package feed + +import ( + "fmt" + "log" + "time" + + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/kit" +) + +// Feed is one vendor feed and how to read its entries. +type Feed struct { + API string // the source id the events carry: "github/actions" + Vendor string // for sentences: "GitHub" + URL string // the feed itself + Read Reader +} + +// Reader turns one entry into findings: what it can name for sure, and what +// it drops. It returns nothing for an entry that isn't breaking or a +// deprecation. +type Reader func(e Entry) []Finding + +// Finding is one change a reader found in an entry, or one it dropped. +type Finding struct { + ChangeType event.ChangeType // breaking or deprecation + Version string // per the subject's type: the removal or shutdown date + Subject event.Subject + Description string + Hint string + Excerpt string // the entry's own lines that say so + Entry string // the entry's link, for the log + Dropped string // set: the entry was marked but this is why no event +} + +// Findings reads every entry of a feed. +func (f Feed) Findings(b []byte) ([]Finding, error) { + entries, err := Parse(b) + if err != nil { + return nil, err + } + var out []Finding + for _, e := range entries { + out = append(out, f.Read(e)...) + } + return out, nil +} + +// What the notices kind (plugins/notices) asks of a feed. + +// Findings are what one read of a feed found, dropped entries included. +type Findings []Finding + +// Count is how many findings the feed gave. +func (fs Findings) Count() int { return len(fs) } + +// Slug is the source id the events carry: "github/actions". +func (f Feed) Slug() string { return f.API } + +// PageURL is the feed itself. +func (f Feed) PageURL() string { return f.URL } + +// Find reads every entry of the feed. +func (f Feed) Find(b []byte) (kit.Notices, error) { + fs, err := f.Findings(b) + return Findings(fs), err +} + +// Events are an event per finding, citing citeURL; a dropped finding is +// logged with why. +func (f Feed) Events(found kit.Notices, citeURL string, now time.Time) ([]event.Event, []error) { + var events []event.Event + var rejected []error + for _, fd := range found.(Findings) { + if fd.Dropped != "" { + log.Printf("%s: dropped %s: %s", f.API, fd.Entry, fd.Dropped) + continue + } + e := event.Event{ + API: f.API, + Version: fd.Version, + ChangeType: fd.ChangeType, + Breaking: fd.ChangeType == event.ChangeTypeBreaking, + Subject: fd.Subject, + Description: fd.Description, + MigrationHint: fd.Hint, + SourceURL: citeURL, + SourceExcerpt: fd.Excerpt, + Confidence: 1.0, + DetectedAt: now, + } + e.Fingerprint = event.Fingerprint(e.API, e.Version, e.ChangeType, e.Subject, "") + if err := e.Validate(); err != nil { + rejected = append(rejected, fmt.Errorf("%s %s: %w", f.API, fd.Entry, err)) + continue + } + events = append(events, e) + } + return events, rejected +} diff --git a/plugins/feed/feed_test.go b/plugins/notices/feed/feed_test.go similarity index 82% rename from plugins/feed/feed_test.go rename to plugins/notices/feed/feed_test.go index fe58a89..01158cd 100644 --- a/plugins/feed/feed_test.go +++ b/plugins/notices/feed/feed_test.go @@ -7,31 +7,6 @@ import ( "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 -// whole plugin: live feed and snapshot are the same copy, so the events cite -// the snapshot, and kittest's second run over the unchanged feed asks for no -// second snapshot and stores nothing new. -func TestGolden(t *testing.T) { - for _, c := range []struct { - feed Feed - file string - }{ - {GitHubActions, "testdata/github-changelog-actions.rss.xml"}, - {VertexAIModels, "testdata/vertex-ai-generative-ai.atom.xml"}, - {CloudflareAPI, "testdata/cloudflare-api-deprecations.rss.xml"}, - } { - t.Run(c.feed.API, func(t *testing.T) { - saved := kittest.Pages{c.feed.URL: c.file} - archive := &kittest.Archive{T: t, Pages: saved} - got := kittest.IngestWith(t, kittest.Env(t, saved), Plugin{Feed: c.feed, Archiver: archive}) - if archive.Calls != 1 { - t.Errorf("%d snapshots, want 1", archive.Calls) - } - kittest.Golden(t, "testdata/golden/"+c.feed.API+".json", got) - }) - } -} - // What each feed's marked entries came to, kept and dropped: the golden files // pin the events, this pins that the unsure ones were dropped, not guessed. func TestUnsureEntriesAreDropped(t *testing.T) { diff --git a/plugins/feed/readers.go b/plugins/notices/feed/readers.go similarity index 98% rename from plugins/feed/readers.go rename to plugins/notices/feed/readers.go index b343708..2e69318 100644 --- a/plugins/feed/readers.go +++ b/plugins/notices/feed/readers.go @@ -15,7 +15,7 @@ import ( // runner image retirement names the date ("The macOS 14 runner image will be // retired on November 2, 2026.") and lists the `runs-on` labels it removes. var GitHubActions = Feed{ - API: "github-actions", + API: "github/actions", Vendor: "GitHub", URL: "https://github.blog/changelog/label/actions/feed/", Read: readGitHubActions, @@ -27,7 +27,7 @@ var GitHubActions = Feed{ // deprecation is a "Deprecated" section with a table of model ids in // (discontinued, recommended migration) and the date to move by. var VertexAIModels = Feed{ - API: "vertex-ai-models", + API: "google/vertex-ai-models", Vendor: "Google", URL: "https://docs.cloud.google.com/feeds/generative-ai-on-vertex-ai-release-notes.xml", Read: readVertexAI, @@ -40,7 +40,7 @@ var VertexAIModels = Feed{ // list item, kept apart from "Affected APIs:" (endpoints that only change), // and gives "Deprecation date:" and, for most since 2025, "End of life date:". var CloudflareAPI = Feed{ - API: "cloudflare", + API: "cloudflare/api", Vendor: "Cloudflare", URL: "https://developers.cloudflare.com/fundamentals/api/reference/deprecations/index.xml", Read: readCloudflareAPI, @@ -335,7 +335,7 @@ func readCloudflareAPI(e Entry) []Finding { out = append(out, Finding{ ChangeType: ct, Version: date, - Subject: event.Subject{Type: event.SubjectAPIOperation, Kind: event.AffectedKindOperation, Side: event.SideRequest, Operation: operation}, + Subject: event.Subject{Type: event.SubjectAPIOperation, Kind: event.KindOperation, Side: event.SideRequest, Operation: operation}, Description: desc, Hint: "Move to the replacement Cloudflare names in its deprecation notice: " + e.Link, Excerpt: excerpt(append(quote, "Deprecated APIs:", text)...), diff --git a/plugins/feed/testdata/README.md b/plugins/notices/feed/testdata/README.md similarity index 88% rename from plugins/feed/testdata/README.md rename to plugins/notices/feed/testdata/README.md index eff3f6f..47ec016 100644 --- a/plugins/feed/testdata/README.md +++ b/plugins/notices/feed/testdata/README.md @@ -1,7 +1,7 @@ # Saved feeds -Real copies, saved once with `curl`. The golden files under `golden/` are what -the plugin stores from them (`go test ./plugins/feed -update`). +Real copies, saved once with `curl`. The golden files, `../../testdata/golden/-.json`, +are what the notices kind stores from them (`go test ./plugins/notices -update`). | File | URL | Saved | License | Quote | |---|---|---|---|---| diff --git a/plugins/feed/testdata/cloudflare-api-deprecations.rss.xml b/plugins/notices/feed/testdata/cloudflare-api-deprecations.rss.xml similarity index 100% rename from plugins/feed/testdata/cloudflare-api-deprecations.rss.xml rename to plugins/notices/feed/testdata/cloudflare-api-deprecations.rss.xml diff --git a/plugins/feed/testdata/github-changelog-actions.rss.xml b/plugins/notices/feed/testdata/github-changelog-actions.rss.xml similarity index 100% rename from plugins/feed/testdata/github-changelog-actions.rss.xml rename to plugins/notices/feed/testdata/github-changelog-actions.rss.xml diff --git a/plugins/feed/testdata/vertex-ai-generative-ai.atom.xml b/plugins/notices/feed/testdata/vertex-ai-generative-ai.atom.xml similarity index 100% rename from plugins/feed/testdata/vertex-ai-generative-ai.atom.xml rename to plugins/notices/feed/testdata/vertex-ai-generative-ai.atom.xml diff --git a/plugins/notices/feed_golden_test.go b/plugins/notices/feed_golden_test.go new file mode 100644 index 0000000..40953b0 --- /dev/null +++ b/plugins/notices/feed_golden_test.go @@ -0,0 +1,34 @@ +package notices + +import ( + "strings" + "testing" + + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/plugins/notices/feed" +) + +// The two feeds as saved on 2026-11-14 (feed/testdata/README.md), each through the +// whole plugin: live feed and snapshot are the same copy, so the events cite +// the snapshot, and kittest's second run over the unchanged feed asks for no +// second snapshot and stores nothing new. +func TestFeedsGolden(t *testing.T) { + for _, c := range []struct { + feed feed.Feed + file string + }{ + {feed.GitHubActions, "feed/testdata/github-changelog-actions.rss.xml"}, + {feed.VertexAIModels, "feed/testdata/vertex-ai-generative-ai.atom.xml"}, + {feed.CloudflareAPI, "feed/testdata/cloudflare-api-deprecations.rss.xml"}, + } { + t.Run(c.feed.API, func(t *testing.T) { + saved := kittest.Pages{c.feed.URL: c.file} + archive := &kittest.Archive{T: t, Pages: saved} + got := kittest.IngestWith(t, kittest.Env(t, saved), Plugin{Page: c.feed, Archiver: archive}) + if archive.Calls != 1 { + t.Errorf("%d snapshots, want 1", archive.Calls) + } + kittest.Golden(t, "testdata/golden/"+strings.ReplaceAll(c.feed.API, "/", "-")+".json", got) + }) + } +} diff --git a/plugins/notices/feed_registered_test.go b/plugins/notices/feed_registered_test.go new file mode 100644 index 0000000..646800c --- /dev/null +++ b/plugins/notices/feed_registered_test.go @@ -0,0 +1,14 @@ +package notices + +import ( + "testing" + + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/plugins/notices/feed" +) + +func TestFeedsRegisterThemselves(t *testing.T) { + for _, f := range []feed.Feed{feed.GitHubActions, feed.VertexAIModels, feed.CloudflareAPI} { + kittest.Registered(t, Plugin{Page: f}) + } +} diff --git a/plugins/notices/notices.go b/plugins/notices/notices.go new file mode 100644 index 0000000..a01d8a9 --- /dev/null +++ b/plugins/notices/notices.go @@ -0,0 +1,266 @@ +// Package notices is the kind for a live page of dated notices: something +// stops, or is deprecated, on a date. A model provider's deprecations table +// (retire/), a vendor's RSS or Atom changelog feed (feed/), a vendor's API +// end-of-life table (eol/). Each Page reader knows how its page reads; the +// steps around it are written once, here: fetch the live page, stop when it +// hasn't changed since the last run, read it, snapshot it in the Wayback +// Machine and check the snapshot says the same (kit.Cite), make the events +// from the snapshot so each cites what it quotes, and save the baseline. +// +// Two options a reader turns on with a method: ShapeGuard (a read with fewer +// than 90% of the last one's notices is an error: the page changed shape), +// and ArchiveWhenBlocked (a live page that answers 401 or 403 is read from a +// fresh Wayback Machine snapshot instead). +package notices + +import ( + "cmp" + "context" + "errors" + "fmt" + "log" + "time" + + "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" + "github.com/patch-it-dev/patch-it-plugins/core/versions" + "github.com/patch-it-dev/patch-it-plugins/plugins/notices/eol" + "github.com/patch-it-dev/patch-it-plugins/plugins/notices/feed" + "github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire" +) + +func init() { + plugin.RegisterProvider(plugin.Provider{ + ID: "openai", Name: "OpenAI", Category: plugin.CategoryAI, Homepage: "https://openai.com", + Sources: []plugin.Source{{ + ID: "models", Layer: plugin.LayerAIModels, Page: "providers/openai-models.md", + Watches: "Model deprecations and shutdown dates (Chat Completions and Responses text models)", + URLs: []string{"https://developers.openai.com/api/docs/deprecations"}, + Packages: []string{"pypi:openai", "npm:openai"}, + Plugin: Plugin{Page: retire.OpenAI, Archiver: kit.Wayback{}}, + }}, + }) + plugin.RegisterProvider(plugin.Provider{ + ID: "anthropic", Name: "Anthropic", Category: plugin.CategoryAI, Homepage: "https://www.anthropic.com", + Sources: []plugin.Source{{ + ID: "models", Layer: plugin.LayerAIModels, Page: "providers/anthropic-models.md", + Watches: "Model deprecations and retirement dates (Messages API models)", + URLs: []string{"https://platform.claude.com/docs/en/about-claude/model-deprecations"}, + Packages: []string{"pypi:anthropic", "npm:@anthropic-ai/sdk"}, + Plugin: Plugin{Page: retire.Anthropic, Archiver: kit.Wayback{}}, + }}, + }) + plugin.RegisterProvider(plugin.Provider{ + ID: "github", Name: "GitHub", Category: plugin.CategoryDevTools, Homepage: "https://github.com", + Sources: []plugin.Source{{ + ID: "actions", Layer: plugin.LayerCI, Page: "providers/github-actions.md", + Watches: "GitHub Actions retirements, such as runner images and the `runs-on` labels they remove", + URLs: []string{"https://github.blog/changelog/label/actions/feed/"}, + Plugin: Plugin{Page: feed.GitHubActions, Archiver: kit.Wayback{}}, + }}, + }) + plugin.RegisterProvider(plugin.Provider{ + ID: "google", Name: "Google", Category: plugin.CategoryAI, Homepage: "https://cloud.google.com", + Sources: []plugin.Source{{ + ID: "vertex-ai-models", Layer: plugin.LayerAIModels, Page: "providers/vertex-ai-models.md", + Watches: "Generative AI model deprecations on Vertex AI", + URLs: []string{"https://docs.cloud.google.com/feeds/generative-ai-on-vertex-ai-release-notes.xml"}, + Plugin: Plugin{Page: feed.VertexAIModels, Archiver: kit.Wayback{}}, + }}, + }) + plugin.RegisterProvider(plugin.Provider{ + ID: "cloudflare", Name: "Cloudflare", Category: plugin.CategoryInfrastructure, Homepage: "https://www.cloudflare.com", + Sources: []plugin.Source{{ + ID: "api", Layer: plugin.LayerAPI, Page: "providers/cloudflare.md", + Watches: "REST API operations Cloudflare deprecates, breaking on their end-of-life date when it gives one", + URLs: []string{"https://developers.cloudflare.com/fundamentals/api/reference/deprecations/index.xml"}, + Packages: []string{"pypi:cloudflare", "npm:cloudflare"}, + Plugin: Plugin{Page: feed.CloudflareAPI, Archiver: kit.Wayback{}}, + }}, + }) + plugin.RegisterProvider(plugin.Provider{ + ID: "salesforce", Name: "Salesforce", Category: plugin.CategoryCRM, Homepage: "https://www.salesforce.com", + Sources: []plugin.Source{{ + ID: "rest-api", Layer: plugin.LayerAPI, Page: "providers/salesforce.md", + Watches: "REST API version ranges deprecated and retired, from Salesforce's own API end-of-life policy page", + URLs: []string{"https://developer.salesforce.com/docs/platform/api-rest/guide/api-rest-eol.html"}, + Plugin: Plugin{Page: eol.Salesforce, Archiver: kit.Wayback{}}, + }}, + }) +} + +// Page is one live page of notices and how it reads: retire.Page, +// feed.Feed and eol.Page. +type Page interface { + // Slug is the source id the events carry in api: "openai/models". + Slug() string + // PageURL is the live page. + PageURL() string + // Find reads the page's notices. + Find(page []byte) (kit.Notices, error) + // Events turn what Find read into events citing citeURL, and the + // notices that failed to become events. + Events(found kit.Notices, citeURL string, now time.Time) ([]event.Event, []error) +} + +// shapeGuarded is a Page whose read with far fewer notices than the last +// is an error. +type shapeGuarded interface{ ShapeGuard() bool } + +// archivedWhenBlocked is a Page read from a fresh Wayback Machine snapshot +// when the live page refuses a plain fetch. +type archivedWhenBlocked interface{ ArchiveWhenBlocked() bool } + +// Plugin reads one page. +type Plugin struct { + Page Page + Archiver kit.Archiver +} + +func (p Plugin) Name() string { return p.Page.Slug() } + +// Run stores an event per notice on the page. The events are read from the +// snapshot itself, so every excerpt is on the page it cites; a snapshot that +// doesn't hold what the live page says (the page changed in between) stores +// nothing this run. An unchanged page since the last run costs one GET (a +// 304 with the HTTP cache) and no snapshot. +func (p Plugin) Run(ctx context.Context, env plugin.Env) (plugin.Result, error) { + pg := p.Page + api, url := pg.Slug(), pg.PageURL() + live, archived, err := p.fetch(ctx, env, url) + if err != nil { + return plugin.Result{}, fmt.Errorf("fetching %s: %w", url, err) + } + hash := plugin.SHA256(live) + last, same, err := kit.Unchanged(env, api, live) + if err != nil { + return plugin.Result{}, err + } + if same { + log.Printf("%s: no change since %s", api, last.SourceURL) + return plugin.Result{}, nil + } + want, err := pg.Find(live) + if err != nil { + return plugin.Result{}, fmt.Errorf("reading %s: %w", url, err) + } + // A provider renaming a column makes its table unreadable, and the run + // would quietly read fewer notices. Past notices stay on the page, so a + // real drop is rare: fail loudly instead of storing a partial list. + if g, ok := pg.(shapeGuarded); ok && g.ShapeGuard() && last != nil { + if before, err := pg.Find(last.Content); err == nil && want.Count()*10 < before.Count()*9 { + return plugin.Result{}, fmt.Errorf("%s now lists %d notices, %d at %s: the page's shape may have changed", url, want.Count(), before.Count(), last.SourceURL) + } + } + + snapURL, snap, got := archived, live, want + if snapURL == "" { + if snapURL, snap, got, err = kit.Cite(ctx, p.Archiver, url, pg.Find, want); err != nil { + return plugin.Result{}, err + } + } + + now := env.Now().UTC() + events, rejected := pg.Events(got, snapURL, now) + // The hash of the live page, so the next run compares like with like. + baseline := plugin.Baseline(api, now.Format("2006-01-02"), snapURL, snapURL, snap, now) + baseline.SHA256 = hash + return plugin.Result{Label: snapURL, Events: events, Rejected: rejected, Baselines: []plugin.Spec{baseline}}, nil +} + +// fetch reads the live page. When the page's reader asks for it +// (ArchiveWhenBlocked) and the provider's own site blocks a plain fetch with +// 401 or 403 (Salesforce's docs site, every time, checked 2026-11-20; +// confirmed the same day that a real Wayback Machine save-page-now capture +// of that page parses to the same findings as the live page would), it +// falls back to a fresh Wayback Machine snapshot, taken right now by the +// archive's own crawler rather than patch-it's, and returns that content +// with its own permanent URL in archivedURL: it needs no further citation +// step, having come from the archive already. +// +// Only 401 and 403 fall back. A 404 or 410 means the page moved, not that +// it's blocked: asking the archive to snapshot a page that's gone would +// waste the call and hide the real cause behind the archive's own error. +// A 429 or a 5xx is returned as is: retrying it against the archive would +// hide a transient failure as a real page, not fix one. +func (p Plugin) fetch(ctx context.Context, env plugin.Env, pageURL string) (body []byte, archivedURL string, err error) { + body, err = env.Get(ctx, pageURL) + if err == nil { + return body, "", nil + } + b, ok := p.Page.(archivedWhenBlocked) + var se *fetch.StatusError + if !ok || !b.ArchiveWhenBlocked() || !errors.As(err, &se) || (se.StatusCode != 401 && se.StatusCode != 403) { + return nil, "", err + } + archivedURL, body, archErr := p.Archiver.Snapshot(ctx, pageURL) + if archErr != nil { + return nil, "", fmt.Errorf("fetching it directly failed (%w), and so did asking the Wayback Machine to: %w", err, archErr) + } + return body, archivedURL, nil +} + +// A living page has no versions of its own, so its history is the Web +// Archive's: every distinct capture is a version, dated (I19.11). A backfill +// reads the page at each capture and extracts each consecutive pair, the +// same events a run on that day would have stored, each citing its capture. + +// ListVersions is every distinct Web Archive capture of the page, oldest +// first (versions.WaybackCaptures); the caller keeps the ones in its window. +func (p Plugin) ListVersions(ctx context.Context, env plugin.Env) ([]plugin.Version, error) { + return versions.WaybackCaptures(ctx, env.Get, p.Page.PageURL(), time.Time{}, time.Time{}) +} + +// ReadAt reads the page as the capture v holds it: the capture's original +// bytes (v.Ref), cited by its address (v.URL). +func (p Plugin) ReadAt(ctx context.Context, env plugin.Env, v plugin.Version) (plugin.Snapshot, error) { + body, err := env.Get(ctx, v.Ref) + if err != nil { + return plugin.Snapshot{}, fmt.Errorf("fetching %s as captured on %s: %w", p.Page.PageURL(), v.ID, err) + } + return plugin.Snapshot{Version: v, Content: body, SourceURL: cmp.Or(v.URL, v.Ref)}, nil +} + +// Extract is an event per notice on the page at to that wasn't at from +// (every one when from is zero), citing to's capture. The events keep the +// notice's own version (its date or API version), so previous_version stays +// empty: from is an earlier day of the page, not an earlier release. +func (p Plugin) Extract(_ context.Context, env plugin.Env, from, to plugin.Snapshot) (plugin.Result, error) { + now := env.Now().UTC() + events, rejected, err := p.events(to, now) + if err != nil { + return plugin.Result{}, err + } + if !from.IsZero() { + before, _, err := p.events(from, now) + if err != nil { + return plugin.Result{}, err + } + had := map[string]bool{} + for _, e := range before { + had[e.Fingerprint] = true + } + kept := events[:0:0] + for _, e := range events { + if !had[e.Fingerprint] { + kept = append(kept, e) + } + } + events = kept + } + return plugin.Result{Label: to.SourceURL, Events: events, Rejected: rejected}, nil +} + +// events reads one snapshot's notices into events citing it. +func (p Plugin) events(s plugin.Snapshot, now time.Time) ([]event.Event, []error, error) { + found, err := p.Page.Find(s.Content) + if err != nil { + return nil, nil, fmt.Errorf("reading %s: %w", s.SourceURL, err) + } + events, rejected := p.Page.Events(found, s.SourceURL, now) + return events, rejected, nil +} + +var _ plugin.Versioned = Plugin{} diff --git a/plugins/notices/retire/notices.go b/plugins/notices/retire/notices.go new file mode 100644 index 0000000..dc365f8 --- /dev/null +++ b/plugins/notices/retire/notices.go @@ -0,0 +1,38 @@ +package retire + +import ( + "time" + + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/kit" +) + +// What the notices kind (plugins/notices) asks of a deprecations page. + +// Retirements are what one read of a page found. +type Retirements []Retirement + +// Count is how many retirements the page lists. +func (rs Retirements) Count() int { return len(rs) } + +// Slug is the source id the events carry: "openai/models". +func (p Page) Slug() string { return p.API } + +// PageURL is the page, as markdown. +func (p Page) PageURL() string { return p.URL } + +// Find reads every retirement on the page. +func (p Page) Find(page []byte) (kit.Notices, error) { + rs, err := Parse(page, p.Keep) + return Retirements(rs), err +} + +// Events are an event per retired model, citing citeURL. +func (p Page) Events(found kit.Notices, citeURL string, now time.Time) ([]event.Event, []error) { + return Events(p, found.(Retirements), citeURL, now) +} + +// ShapeGuard is on: past retirements stay on the page, so a read with far +// fewer than the last one means the table changed shape, not that models +// came back. +func (Page) ShapeGuard() bool { return true } diff --git a/plugins/retirements/retire/providers.go b/plugins/notices/retire/providers.go similarity index 72% rename from plugins/retirements/retire/providers.go rename to plugins/notices/retire/providers.go index 9495561..61fbc03 100644 --- a/plugins/retirements/retire/providers.go +++ b/plugins/notices/retire/providers.go @@ -8,21 +8,21 @@ import "strings" // sends (a fine-tuned model is "ft:gpt-4-0613:org::id"), and the "-completions" // aliases belong to the legacy Completions endpoint. var OpenAI = Page{ - API: "openai-models", - Vendor: "OpenAI", - URL: "https://developers.openai.com/api/docs/deprecations.md", - Operation: "POST /v1/chat/completions", - Keep: openAIText, + API: "openai/models", + Provider: "openai", + Vendor: "OpenAI", + URL: "https://developers.openai.com/api/docs/deprecations.md", + Keep: openAIText, } // Anthropic's model deprecations page (checked 2026-10-13): every model in // its deprecation history is a Messages API model. var Anthropic = Page{ - API: "anthropic-models", - Vendor: "Anthropic", - URL: "https://platform.claude.com/docs/en/about-claude/model-deprecations.md", - Operation: "POST /v1/messages", - Keep: func(name string) bool { return strings.HasPrefix(name, "claude-") }, + API: "anthropic/models", + Provider: "anthropic", + Vendor: "Anthropic", + URL: "https://platform.claude.com/docs/en/about-claude/model-deprecations.md", + Keep: func(name string) bool { return strings.HasPrefix(name, "claude-") }, } var ( diff --git a/plugins/retirements/retire/retire.go b/plugins/notices/retire/retire.go similarity index 84% rename from plugins/retirements/retire/retire.go rename to plugins/notices/retire/retire.go index 1c3d673..4b5960d 100644 --- a/plugins/retirements/retire/retire.go +++ b/plugins/notices/retire/retire.go @@ -21,10 +21,10 @@ import ( // 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 + API string // the source id the events carry: "openai/models" + Provider string // the model subject's provider: "openai" + Vendor string // for sentences: "OpenAI" + URL string // the page as markdown // 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 @@ -191,33 +191,27 @@ func parseDate(s string) (string, error) { 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 +// Events turns retirements into change events, one per model name: a model +// subject, the provider and the name, and the replacement when the provider +// names exactly one model. 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. 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.Event, []error) { + var events []event.Event 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), + h := hint(p.Vendor, r) + subject := event.Subject{Type: event.SubjectModel, Provider: p.Provider, Name: r.Model, Replacement: replacement(r.Replacement)} + e := event.Event{ + Fingerprint: event.Fingerprint(p.API, r.Date, event.ChangeTypeBreaking, subject, ""), API: p.API, Version: r.Date, ChangeType: event.ChangeTypeBreaking, Breaking: true, - Affected: affected, + Subject: subject, 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), + MigrationHint: h, SourceURL: sourceURL, SourceExcerpt: r.Excerpt, Confidence: 1.0, @@ -232,6 +226,19 @@ func Events(p Page, rs []Retirement, sourceURL string, now time.Time) ([]event.C return events, errs } +// replacement is the one model the provider names, when its replacement cell +// is exactly one model name: not none, 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. +func replacement(cell string) string { + cell = strings.TrimSpace(cell) + name := First(cell) + if name == "" || cell != "`"+name+"`" { + return "" + } + return name +} + func hint(vendor string, r Retirement) string { repl := strings.TrimSpace(r.Replacement) if First(repl) == "" { diff --git a/plugins/retirements/retire/retire_test.go b/plugins/notices/retire/retire_test.go similarity index 89% rename from plugins/retirements/retire/retire_test.go rename to plugins/notices/retire/retire_test.go index 02f3c20..505108e 100644 --- a/plugins/retirements/retire/retire_test.go +++ b/plugins/notices/retire/retire_test.go @@ -168,16 +168,22 @@ func TestEventsOnePerModel(t *testing.T) { t.Fatalf("events %d, errs %v", len(events), errs) } e := events[0] - want := event.Affected{Kind: event.AffectedKindRequestParameter, Side: event.SideRequest, Operation: "POST /v1/chat/completions", Property: "model", Value: "gpt-4"} - if e.Affected != want { - t.Errorf("affected: %+v", e.Affected) + want := event.Subject{Type: event.SubjectModel, Provider: "openai", Name: "gpt-4", Replacement: "gpt-5.6-sol"} + if e.Subject.Type != want.Type || e.Subject.Provider != want.Provider || e.Subject.Name != want.Name || e.Subject.Replacement != want.Replacement { + t.Errorf("subject: %+v", e.Subject) } - if e.API != "openai-models" || e.Version != "2026-10-23" || e.PreviousVersion != "" || !e.Breaking || + if e.API != "openai/models" || e.Version != "2026-10-23" || e.PreviousVersion != "" || !e.Breaking || e.SourceURL != src || e.SourceExcerpt != rs[0].Excerpt || e.Confidence != 1.0 { t.Errorf("event: %+v", e) } - if e.Fingerprint != event.Fingerprint("openai-models", "2026-10-23", event.ChangeTypeBreaking, e.Affected, "gpt-4") { - t.Error("the fingerprint's detail is the model name") + if e.Fingerprint != event.Fingerprint("openai/models", "2026-10-23", event.ChangeTypeBreaking, e.Subject, "") { + t.Error("the fingerprint is the contract's formula over the model subject") + } + // The replacement is set only when the provider names exactly one model. + for cell, want := range map[string]string{"`gpt-5.6-sol`": "gpt-5.6-sol", "`a` or `b`": "", "`gpt-5.6-sol` (`reasoning.mode: pro`)": "", "none": ""} { + if got := replacement(cell); got != want { + t.Errorf("replacement(%q) = %q, want %q", cell, got, want) + } } if !strings.Contains(e.Description, `"gpt-4"`) || !strings.Contains(e.MigrationHint, "gpt-5.6-sol") { t.Errorf("%q / %q", e.Description, e.MigrationHint) diff --git a/plugins/retirements/retire/testdata/README.md b/plugins/notices/retire/testdata/README.md similarity index 94% rename from plugins/retirements/retire/testdata/README.md rename to plugins/notices/retire/testdata/README.md index e71abfb..b4c3b47 100644 --- a/plugins/retirements/retire/testdata/README.md +++ b/plugins/notices/retire/testdata/README.md @@ -1,6 +1,6 @@ # Saved model deprecations pages -The two providers' deprecations pages, as markdown (each page's URL plus `.md`). `retire`'s tests and the `openai-models` / `anthropic-models` golden tests (`plugins/retirements`) read them. +The two providers' deprecations pages, as markdown (each page's URL plus `.md`). `retire`'s tests and the `openai-models` / `anthropic-models` golden tests (`plugins/notices`) read them. **License:** excerpts for testing; © OpenAI and © Anthropic respectively. Not covered by this repo's license. diff --git a/plugins/retirements/retire/testdata/anthropic-deprecations.md b/plugins/notices/retire/testdata/anthropic-deprecations.md similarity index 100% rename from plugins/retirements/retire/testdata/anthropic-deprecations.md rename to plugins/notices/retire/testdata/anthropic-deprecations.md diff --git a/plugins/retirements/retire/testdata/openai-deprecations.md b/plugins/notices/retire/testdata/openai-deprecations.md similarity index 100% rename from plugins/retirements/retire/testdata/openai-deprecations.md rename to plugins/notices/retire/testdata/openai-deprecations.md diff --git a/plugins/retirements/golden_test.go b/plugins/notices/retirements_golden_test.go similarity index 77% rename from plugins/retirements/golden_test.go rename to plugins/notices/retirements_golden_test.go index b4095c9..2ec3eb0 100644 --- a/plugins/retirements/golden_test.go +++ b/plugins/notices/retirements_golden_test.go @@ -1,16 +1,17 @@ -package retirements +package notices import ( + "strings" "testing" "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" - "github.com/patch-it-dev/patch-it-plugins/plugins/retirements/retire" + "github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire" ) // Both providers' saved pages (2026-10-13) in, every event out. The archive // serves the same copy as the snapshot, so the events cite it; a second run // over the unchanged page asks for no snapshot. -func TestGolden(t *testing.T) { +func TestRetirementsGolden(t *testing.T) { for file, page := range map[string]retire.Page{ "openai-deprecations.md": retire.OpenAI, "anthropic-deprecations.md": retire.Anthropic, @@ -22,7 +23,7 @@ func TestGolden(t *testing.T) { if archive.Calls != 1 { t.Errorf("%d snapshots, want 1: the second run's page is unchanged", archive.Calls) } - kittest.Golden(t, "testdata/golden/"+page.API+".json", got) + kittest.Golden(t, "testdata/golden/"+strings.ReplaceAll(page.API, "/", "-")+".json", got) }) } } diff --git a/plugins/retirements/registered_test.go b/plugins/notices/retirements_registered_test.go similarity index 59% rename from plugins/retirements/registered_test.go rename to plugins/notices/retirements_registered_test.go index c5be64c..42cee34 100644 --- a/plugins/retirements/registered_test.go +++ b/plugins/notices/retirements_registered_test.go @@ -1,13 +1,13 @@ -package retirements +package notices import ( "testing" "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" - "github.com/patch-it-dev/patch-it-plugins/plugins/retirements/retire" + "github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire" ) -func TestRegistersItself(t *testing.T) { +func TestRetirementsRegisterThemselves(t *testing.T) { for _, p := range []retire.Page{retire.OpenAI, retire.Anthropic} { kittest.Registered(t, Plugin{Page: p}) } diff --git a/plugins/retirements/retirements_test.go b/plugins/notices/retirements_retirements_test.go similarity index 98% rename from plugins/retirements/retirements_test.go rename to plugins/notices/retirements_retirements_test.go index fe89d4d..5af6e91 100644 --- a/plugins/retirements/retirements_test.go +++ b/plugins/notices/retirements_retirements_test.go @@ -1,4 +1,4 @@ -package retirements +package notices import ( "context" @@ -9,7 +9,7 @@ import ( "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" + "github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire" ) const deprecations = `### 2026-04-22: Legacy GPT model snapshots diff --git a/plugins/notices/testdata/README.md b/plugins/notices/testdata/README.md new file mode 100644 index 0000000..fb557f5 --- /dev/null +++ b/plugins/notices/testdata/README.md @@ -0,0 +1,7 @@ +# Golden events + +`golden/openai-models.json` and `golden/anthropic-models.json` are what the `openai-models` and `anthropic-models` plugins store from the saved deprecations pages. The pages themselves are shared with the `retire` package: see [`retire/testdata/README.md`](../retire/testdata/README.md) for their URLs, dates and licenses. + +`golden/github-actions.json`, `golden/google-vertex-ai-models.json` and `golden/cloudflare-api.json` come from the saved feeds in [`feed/testdata/`](../feed/testdata/README.md); `golden/salesforce.json` from the saved page in [`eol/testdata/`](../eol/testdata/README.md). + +Rewrite them after an intended change with `go test ./plugins/notices -update`, and say in the PR why the new output is right. diff --git a/plugins/retirements/testdata/golden/anthropic-models.json b/plugins/notices/testdata/golden/anthropic-models.json similarity index 87% rename from plugins/retirements/testdata/golden/anthropic-models.json rename to plugins/notices/testdata/golden/anthropic-models.json index 39f5393..911286f 100644 --- a/plugins/retirements/testdata/golden/anthropic-models.json +++ b/plugins/notices/testdata/golden/anthropic-models.json @@ -1,8 +1,8 @@ [ { "id": 1, - "fingerprint": "sha256:084327582be7b72ed1dab946e16cc3df07f54e24294a0e23ffb14169ff822b26", - "api": "anthropic-models", + "fingerprint": "sha256:bf9dc66e694d48792f443cfa0a83407438ba84d9908fe8d159440896068ac486", + "api": "anthropic/models", "version": "2026-11-30", "change_type": "breaking", "breaking": true, @@ -21,8 +21,8 @@ }, { "id": 2, - "fingerprint": "sha256:de5c53ea734f00774aee2b30102294a59218f270d9eba3d1134b54a44a38e6b3", - "api": "anthropic-models", + "fingerprint": "sha256:bb9908fbd60b90f608a4d2527ab5e1b0e308387e7f95fbd5434712668555db03", + "api": "anthropic/models", "version": "2026-08-05", "change_type": "breaking", "breaking": true, @@ -41,8 +41,8 @@ }, { "id": 3, - "fingerprint": "sha256:fd964537b6da9ee4f3164f4cb710a53b31a1e97941aebaf6f573052dbdfaece3", - "api": "anthropic-models", + "fingerprint": "sha256:acbe6e761b6bc504fcc0a76745325c1debee73580cde96660d9831f57269fad9", + "api": "anthropic/models", "version": "2026-06-15", "change_type": "breaking", "breaking": true, @@ -61,8 +61,8 @@ }, { "id": 4, - "fingerprint": "sha256:ebe12a21a35277f4d52a341cef868461b12d1eb6af273acde8c55039e1f50dc0", - "api": "anthropic-models", + "fingerprint": "sha256:e8595a6279ec27c8401bb8e22040ea635d62229de1895e07272ba147b8f23cc0", + "api": "anthropic/models", "version": "2026-06-15", "change_type": "breaking", "breaking": true, @@ -81,8 +81,8 @@ }, { "id": 5, - "fingerprint": "sha256:03eea9104a387fd961d2700e4003239a78a00792cb7398f40f7a796f20848cbd", - "api": "anthropic-models", + "fingerprint": "sha256:dd9954ebdca4a5b7bebc9a3eb90b12692d5aef06cbeb83f98d35c1b613fc4144", + "api": "anthropic/models", "version": "2026-04-20", "change_type": "breaking", "breaking": true, @@ -101,8 +101,8 @@ }, { "id": 6, - "fingerprint": "sha256:22bf5e0f9b79bc77948998da9f0a5d198aa9281cbb0ec5942c123b6b9c4236c8", - "api": "anthropic-models", + "fingerprint": "sha256:806bb2b5795722c4fa651bc70f43f812fc28a7f02c97c75c6080b1a5ae234878", + "api": "anthropic/models", "version": "2026-02-19", "change_type": "breaking", "breaking": true, @@ -121,8 +121,8 @@ }, { "id": 7, - "fingerprint": "sha256:90cca623ba7cffd30a8c0538ed15709408cee309c8b6708497d178576ff64f20", - "api": "anthropic-models", + "fingerprint": "sha256:17b575b6086b4189e150014dca87c0e6bf856e64f772b24b538f180beea81f56", + "api": "anthropic/models", "version": "2026-02-19", "change_type": "breaking", "breaking": true, @@ -141,8 +141,8 @@ }, { "id": 8, - "fingerprint": "sha256:05c32a5887d178daa274431aefe103f86af244ab71e16c61b8043aa3bd2112ab", - "api": "anthropic-models", + "fingerprint": "sha256:bd42e7d7a185f3edd5d21f300d5f350f960079ce1de4676949a0d83e6140ce74", + "api": "anthropic/models", "version": "2025-10-28", "change_type": "breaking", "breaking": true, @@ -161,8 +161,8 @@ }, { "id": 9, - "fingerprint": "sha256:0c9ee5a399c70ff35b35767313d79b794d8f3d8c2673a70b15eb2930f2f7741c", - "api": "anthropic-models", + "fingerprint": "sha256:1f6698c66029b5d94cb452eeb8ecc6a03f623759833b6f21a69f53a0c5b2984d", + "api": "anthropic/models", "version": "2025-10-28", "change_type": "breaking", "breaking": true, @@ -181,8 +181,8 @@ }, { "id": 10, - "fingerprint": "sha256:f53cd0d0bb782d85312468938c7fe5a6236d49564db0d26405e4e5289e99c4ee", - "api": "anthropic-models", + "fingerprint": "sha256:0428d4c806abbf7ccf25718a3fe238279b280d2e8f6b8fe689d1a786481f9f40", + "api": "anthropic/models", "version": "2026-01-05", "change_type": "breaking", "breaking": true, @@ -201,8 +201,8 @@ }, { "id": 11, - "fingerprint": "sha256:7927bd5d04931984a0fe16766ec971df4a833bc651608a3ebe811f6c5ec5ba67", - "api": "anthropic-models", + "fingerprint": "sha256:bbe44fbfc6527ac3b4fd0b481eff836c6f0995700ecc4b94d930bc8941e0d597", + "api": "anthropic/models", "version": "2025-07-21", "change_type": "breaking", "breaking": true, @@ -221,8 +221,8 @@ }, { "id": 12, - "fingerprint": "sha256:ca052eb79284d07aa694e624136a1d7b5faef1a73ac909a516d76a3e8d1313df", - "api": "anthropic-models", + "fingerprint": "sha256:146d061d088109e98ae03d63a075e5e06ebb513d5d2143fafc0596b91daa4256", + "api": "anthropic/models", "version": "2025-07-21", "change_type": "breaking", "breaking": true, @@ -241,8 +241,8 @@ }, { "id": 13, - "fingerprint": "sha256:6d728cac5aa3315f62b432608b50f17746b1440c23be6fbabcc6dbc69eceb6c9", - "api": "anthropic-models", + "fingerprint": "sha256:eadc4ebf13f46a084d4331c734ac8e6550dc6d53c0f93b9083ceb849b8fe1be6", + "api": "anthropic/models", "version": "2025-07-21", "change_type": "breaking", "breaking": true, @@ -261,8 +261,8 @@ }, { "id": 14, - "fingerprint": "sha256:8ed0aa3c3bc723fb037da3081e121465555e9ffb5974f8d352fac3e6ae11d673", - "api": "anthropic-models", + "fingerprint": "sha256:8b03c1ec82e23fe22c0d178d92ea22b1154adbffede5509af1d77439009c70c2", + "api": "anthropic/models", "version": "2024-11-06", "change_type": "breaking", "breaking": true, @@ -281,8 +281,8 @@ }, { "id": 15, - "fingerprint": "sha256:f08e6cd2a06258d5d814fc971cc135e90c7341f94debd60376103924e1de07a4", - "api": "anthropic-models", + "fingerprint": "sha256:7527709cc6692b6c31ae8149fcfda97149b28d41a9fa7437c2848c17e639893d", + "api": "anthropic/models", "version": "2024-11-06", "change_type": "breaking", "breaking": true, @@ -301,8 +301,8 @@ }, { "id": 16, - "fingerprint": "sha256:13efff6d094eb24a1b2965a07b52338bdce99f41a9e35dceed8532b583585738", - "api": "anthropic-models", + "fingerprint": "sha256:5e4dd9e6a098fc16bf1db022e3d9aab838a657ef4b7284996a0f39c1475bdaac", + "api": "anthropic/models", "version": "2024-11-06", "change_type": "breaking", "breaking": true, @@ -321,8 +321,8 @@ }, { "id": 17, - "fingerprint": "sha256:d7486d997bc1263f928dec6d235cfb953d7d7b9498d84bb47cf91af328216d75", - "api": "anthropic-models", + "fingerprint": "sha256:33f19a2640035c553ab915ec77169bc3f74e7664733c391eb509587977c6b180", + "api": "anthropic/models", "version": "2024-11-06", "change_type": "breaking", "breaking": true, @@ -341,8 +341,8 @@ }, { "id": 18, - "fingerprint": "sha256:e86ec257be0151e390960ebabd7ce295dee95ea5f61ae3c99ea1173eb3850fd9", - "api": "anthropic-models", + "fingerprint": "sha256:deda532ae210b3cef3858d6e93d60c6bf1d399da9cf4a3e5cc99878ba28dbe3e", + "api": "anthropic/models", "version": "2024-11-06", "change_type": "breaking", "breaking": true, @@ -361,8 +361,8 @@ }, { "id": 19, - "fingerprint": "sha256:9da76f1f748a2dc4b385db61dc185b78ecd20a8fffb2ddbac5b2ed8f248b62ab", - "api": "anthropic-models", + "fingerprint": "sha256:a6b4d99422328b062908402e3099c31ae310217f7fec120a3edc7fed68e6d761", + "api": "anthropic/models", "version": "2024-11-06", "change_type": "breaking", "breaking": true, @@ -381,8 +381,8 @@ }, { "id": 20, - "fingerprint": "sha256:38f84d91196bce749ca3796d9fe6b29150f98b80c954bc4483a9c80783cfae27", - "api": "anthropic-models", + "fingerprint": "sha256:bb55c886fefe4e73c8aeed5252eec689481baa9778c2bc3c75f89eb3882b16d9", + "api": "anthropic/models", "version": "2024-11-06", "change_type": "breaking", "breaking": true, diff --git a/plugins/feed/testdata/golden/cloudflare.json b/plugins/notices/testdata/golden/cloudflare-api.json similarity index 89% rename from plugins/feed/testdata/golden/cloudflare.json rename to plugins/notices/testdata/golden/cloudflare-api.json index ea3315b..8f49629 100644 --- a/plugins/feed/testdata/golden/cloudflare.json +++ b/plugins/notices/testdata/golden/cloudflare-api.json @@ -1,8 +1,8 @@ [ { "id": 1, - "fingerprint": "sha256:209ddd00515aa5cebf08cb938b875fd2ef664727df8bb83fdea189732f5168e8", - "api": "cloudflare", + "fingerprint": "sha256:cb56adac1f3a1b3f106171fbc370c0ed910ca4e26c265a8af4d9b611a8ccd28d", + "api": "cloudflare/api", "version": "2026-10-02", "change_type": "deprecation", "breaking": false, @@ -21,8 +21,8 @@ }, { "id": 2, - "fingerprint": "sha256:095bb0d08a6d7ab6159f96dd4c191b56dd836f287cb96d969e5a6d6350d5754a", - "api": "cloudflare", + "fingerprint": "sha256:09b314da125464c093d1f10907f3fbe93ba350f997632cac22cc01c508128c0d", + "api": "cloudflare/api", "version": "2026-10-02", "change_type": "deprecation", "breaking": false, @@ -41,8 +41,8 @@ }, { "id": 3, - "fingerprint": "sha256:706bbb62f4ff0de0061393f4c4c18e854cd2360ccd4f726d032d1cb8b43c1a82", - "api": "cloudflare", + "fingerprint": "sha256:30a6eacd3f6453c61a3c773d58d7562cf8a385bd5a27a0d63ebf1b4d0ebd2a7c", + "api": "cloudflare/api", "version": "2026-10-02", "change_type": "deprecation", "breaking": false, @@ -61,8 +61,8 @@ }, { "id": 4, - "fingerprint": "sha256:3df534ff61a7b210ebe1310dbf47e1ba32229f9bcf1e7585d652b79235749168", - "api": "cloudflare", + "fingerprint": "sha256:c7819950049c77f39919033207cbc15c099ab07cb905ca86160ecb8a155082cd", + "api": "cloudflare/api", "version": "2027-03-31", "change_type": "breaking", "breaking": true, @@ -81,8 +81,8 @@ }, { "id": 5, - "fingerprint": "sha256:a09cf2e8d23cf3ade9289ce97b91df9b314daa6050d14b4c86157f6c51520e5a", - "api": "cloudflare", + "fingerprint": "sha256:bedb26c4e258748b9b5cc003f057ec7f35f4d24d06fa20f6f8c9ff2f31057e92", + "api": "cloudflare/api", "version": "2027-03-31", "change_type": "breaking", "breaking": true, @@ -101,8 +101,8 @@ }, { "id": 6, - "fingerprint": "sha256:189782cdada124dcd9ea5e8cd3e6dcdac707d6209fdc7da6174dc8a404273362", - "api": "cloudflare", + "fingerprint": "sha256:42e4b366ee1ff7e298943b79aa8a6dc4463d359040fab9dad8b01c151d3e778b", + "api": "cloudflare/api", "version": "2026-07-21", "change_type": "deprecation", "breaking": false, @@ -121,8 +121,8 @@ }, { "id": 7, - "fingerprint": "sha256:7eb4e1ca1ad0bb61ea024565a99ee48e76a3adbb77b6ac8f2f57026c1d2eaf78", - "api": "cloudflare", + "fingerprint": "sha256:bb96b97266df769aa7fcaccb9acb5a9c45d6710dae6cdd7dbe896b0f8ae2c50e", + "api": "cloudflare/api", "version": "2026-07-21", "change_type": "deprecation", "breaking": false, @@ -141,8 +141,8 @@ }, { "id": 8, - "fingerprint": "sha256:d128202f22ae680b9a03f9d3d3475a91140ae84044c4b98152dfc7d96121bf13", - "api": "cloudflare", + "fingerprint": "sha256:5e8f496408a25bba3b6e1df484c6bad28589213a2ed30ad95d60bf9b7248ca36", + "api": "cloudflare/api", "version": "2026-07-15", "change_type": "deprecation", "breaking": false, @@ -161,8 +161,8 @@ }, { "id": 9, - "fingerprint": "sha256:1afde189e87011f919bb956877bfa84c1d2f3b4c958f611bd391943b94d8011e", - "api": "cloudflare", + "fingerprint": "sha256:c74cc4fe6bd7220de67702e2c4b95c769b5a25ae9268568fc0dfb8cb7b511284", + "api": "cloudflare/api", "version": "2026-07-15", "change_type": "deprecation", "breaking": false, @@ -181,8 +181,8 @@ }, { "id": 10, - "fingerprint": "sha256:83bad8063ef5cd42941e191cb55f9ca0da0c9943708d94c1d91f6b3bf353bca1", - "api": "cloudflare", + "fingerprint": "sha256:18cad2ef2fe48e787f1aa8f03a2585bf488789b96454cf62f33dc110a7fd7faa", + "api": "cloudflare/api", "version": "2026-07-09", "change_type": "deprecation", "breaking": false, @@ -201,8 +201,8 @@ }, { "id": 11, - "fingerprint": "sha256:a755942720b697c4c3de6632044774b926263ba4ba7af49fe6e513ac8f35eb44", - "api": "cloudflare", + "fingerprint": "sha256:a6adf32eab7e1b63c7147678a4954ba76bff4b087e0ac7fcc3c6c5e738ff16d3", + "api": "cloudflare/api", "version": "2026-07-09", "change_type": "deprecation", "breaking": false, @@ -221,8 +221,8 @@ }, { "id": 12, - "fingerprint": "sha256:e60470c34960ec5b86ddc473e4cb3452f8398499338b0a42cd0ccbda1f08c6ea", - "api": "cloudflare", + "fingerprint": "sha256:3ea497d35767362d916e4a043f4f5b9c1305ef5a195a83bab759492e980f5d2a", + "api": "cloudflare/api", "version": "2026-07-09", "change_type": "deprecation", "breaking": false, @@ -241,8 +241,8 @@ }, { "id": 13, - "fingerprint": "sha256:8398452c438a2b45a3d0a959957372e493aa23550e0138668d3700fe686417f4", - "api": "cloudflare", + "fingerprint": "sha256:a22b1027c2c81b3b926ba8e9efba378a018be84818dd90e46d6e18173bda543a", + "api": "cloudflare/api", "version": "2025-09-18", "change_type": "deprecation", "breaking": false, @@ -261,8 +261,8 @@ }, { "id": 14, - "fingerprint": "sha256:7232528a748069c053a9e96e9fb8f43a6d7cdfacfad100fb69095d57b1f66791", - "api": "cloudflare", + "fingerprint": "sha256:17b581c0fb930cece080b79d7274e6d5b6a0d3008bd35c42d02dfe61664bc486", + "api": "cloudflare/api", "version": "2025-09-18", "change_type": "deprecation", "breaking": false, @@ -281,8 +281,8 @@ }, { "id": 15, - "fingerprint": "sha256:7f3f03f8b019badcf7557176aef5644abdbe8362c7347f0a2b7c3e7358259536", - "api": "cloudflare", + "fingerprint": "sha256:75d26824c9ee18c8106edf4ddbae2a72d8a437fc109b4d76c029a43076e2311b", + "api": "cloudflare/api", "version": "2026-09-27", "change_type": "breaking", "breaking": true, @@ -301,8 +301,8 @@ }, { "id": 16, - "fingerprint": "sha256:ed9ddd02851073a6d0bac4c12f236d61a5d6af16ceb55ed4b32dc87c2741a6b3", - "api": "cloudflare", + "fingerprint": "sha256:f40cf57ea9ebde836781999db0c4ed64e61d03ccf1d9f52842c9b3df9d54bc9b", + "api": "cloudflare/api", "version": "2026-09-27", "change_type": "breaking", "breaking": true, @@ -321,8 +321,8 @@ }, { "id": 17, - "fingerprint": "sha256:907cc7e4b5f4e00cbdc0dba6d090b5a957fea0fa1ba1ea11b73747a53160d5c8", - "api": "cloudflare", + "fingerprint": "sha256:1c722f6fea1c80a215657c119c6a26790387d00a538a95005a82e46c9488e56c", + "api": "cloudflare/api", "version": "2026-09-27", "change_type": "breaking", "breaking": true, @@ -341,8 +341,8 @@ }, { "id": 18, - "fingerprint": "sha256:59a179a3b256a1a8fb6aa1ca82415bb1aa6731ecd370144b010ec45ba871fdda", - "api": "cloudflare", + "fingerprint": "sha256:9c4478afa6ea8f69da6bb8621392fd5d8c02e3ccb3f5c75670fe10e720983428", + "api": "cloudflare/api", "version": "2025-12-09", "change_type": "deprecation", "breaking": false, @@ -361,8 +361,8 @@ }, { "id": 19, - "fingerprint": "sha256:f04495a8c3948059289f591d613fee71644907251bf014999e9f6b10dfc3d562", - "api": "cloudflare", + "fingerprint": "sha256:1b1459ce03ac27a49e8d75678ca4f389130da1083b4042b4ad92fe9ed022beb5", + "api": "cloudflare/api", "version": "2025-12-09", "change_type": "deprecation", "breaking": false, @@ -381,8 +381,8 @@ }, { "id": 20, - "fingerprint": "sha256:f71e2b70483429b09ed8234c4c65467a547bca6cc748739d52c5f52ea0cca242", - "api": "cloudflare", + "fingerprint": "sha256:3d3a8051a8e6fafad5e79bc47334f8a4fbd4c01d3796d96d52583f674dd28e45", + "api": "cloudflare/api", "version": "2025-11-11", "change_type": "deprecation", "breaking": false, @@ -401,8 +401,8 @@ }, { "id": 21, - "fingerprint": "sha256:d7fce55c7ed5362902f9d79ac3abcc126915b4cf5798af923641a3f2feb19ad8", - "api": "cloudflare", + "fingerprint": "sha256:4e60f8fa58582e8def499610e7b81eab46dade7ec3964299482626980995d627", + "api": "cloudflare/api", "version": "2025-11-11", "change_type": "deprecation", "breaking": false, @@ -421,8 +421,8 @@ }, { "id": 22, - "fingerprint": "sha256:96de321c4419cf143ce9103ad9018c4cf4e634c5fe279532e148197bcddd8d3d", - "api": "cloudflare", + "fingerprint": "sha256:1853eaf0d910625df4d8d43bb8f2440f9d92c0465c4cf64dc5c4d96c129510a0", + "api": "cloudflare/api", "version": "2025-11-11", "change_type": "deprecation", "breaking": false, @@ -441,8 +441,8 @@ }, { "id": 23, - "fingerprint": "sha256:961a36a4de964359c0732a579fa61417731a7c3cb9ab3c1932c08f6594971996", - "api": "cloudflare", + "fingerprint": "sha256:e36dc8458b216953d0efd03dd378d68ec7cf0cf6ddea8a2fe38887399f7abeec", + "api": "cloudflare/api", "version": "2025-11-11", "change_type": "deprecation", "breaking": false, @@ -461,8 +461,8 @@ }, { "id": 24, - "fingerprint": "sha256:172b49f795efc781579953e0400d0007b618e5a7b0e115ef464d8abef5cfc86b", - "api": "cloudflare", + "fingerprint": "sha256:ad3e460c87337f2a896091614fdcd3b88d72720dc312a79b0aebe50246fbbf8d", + "api": "cloudflare/api", "version": "2025-11-11", "change_type": "deprecation", "breaking": false, @@ -481,8 +481,8 @@ }, { "id": 25, - "fingerprint": "sha256:daaf98779f5f83c9a5f34d0ed67847230d45f1825e94456fdc5111cae820dbfb", - "api": "cloudflare", + "fingerprint": "sha256:f8a8cfd845a7c2ab4c1b7c050d847ae2c47c804e8b99b7f60e9097a945a273a7", + "api": "cloudflare/api", "version": "2025-11-03", "change_type": "deprecation", "breaking": false, @@ -501,8 +501,8 @@ }, { "id": 26, - "fingerprint": "sha256:c57dea043cc2a04ce7df956b4b61c63e40657b336e37be3ba65c46d3fda64d87", - "api": "cloudflare", + "fingerprint": "sha256:8c78397dd771f2d2bb226d7dcaaaf583ed67953839244a16df26e77348fbcf52", + "api": "cloudflare/api", "version": "2025-11-03", "change_type": "deprecation", "breaking": false, @@ -521,8 +521,8 @@ }, { "id": 27, - "fingerprint": "sha256:e987c02319e1f96b95aaec1b23ee4ee9fedc1cd98130fc23a4e8f0cc015062a1", - "api": "cloudflare", + "fingerprint": "sha256:d87ac63c4f437079a03c4ce1cb086d0c2e3359d1430aae6868feace096519e7b", + "api": "cloudflare/api", "version": "2025-07-01", "change_type": "deprecation", "breaking": false, @@ -541,8 +541,8 @@ }, { "id": 28, - "fingerprint": "sha256:3f004d30d18cd6ad9586fe4f48e0318e47918357fd2d7ce67bf675d5a76128b3", - "api": "cloudflare", + "fingerprint": "sha256:3415b78258b0540ed234add1379e0e735f46b695e98096dba089e707e3d1b045", + "api": "cloudflare/api", "version": "2025-07-01", "change_type": "deprecation", "breaking": false, @@ -561,8 +561,8 @@ }, { "id": 29, - "fingerprint": "sha256:e5dc3d6affae56a3b6e97af875cc96e1f0dd7b75ef52437e0adfb2b8bd467549", - "api": "cloudflare", + "fingerprint": "sha256:ce2ffc810d604c55bec6b39856d3a81e2c97a8283b88e49dc7558f58f29ae344", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -581,8 +581,8 @@ }, { "id": 30, - "fingerprint": "sha256:402f5e42634b5eeeb4de6e3f1b1cb1a234669a84b870ddd9c5d6b2c46a3abe3c", - "api": "cloudflare", + "fingerprint": "sha256:425ed49112f2e3782b9094a56fb34b5151353382ecef7bec60afc83aa67910f4", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -601,8 +601,8 @@ }, { "id": 31, - "fingerprint": "sha256:e0e4c986cc8f7c03bcabeb77569c816e4597aaefb5cbbb015904c10d2627deef", - "api": "cloudflare", + "fingerprint": "sha256:33414c74a174db4bed18b866950ab5369f7225077c2d2733c3c5edb19d3a834f", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -621,8 +621,8 @@ }, { "id": 32, - "fingerprint": "sha256:ed927ea74c0cdddd52eeb7fc9269f34fb70d1df4b849698a0cf1f00f9f514d78", - "api": "cloudflare", + "fingerprint": "sha256:64805446332835abca89e331bb8f3916f8cabe89c49dff6fc2ea491717b1a938", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -641,8 +641,8 @@ }, { "id": 33, - "fingerprint": "sha256:ad3882c16f87d633df7ddc6e012be0d9363557a5a45bde019fc2ec8c051654a8", - "api": "cloudflare", + "fingerprint": "sha256:9a10ede8b22e5eb07b0270642d9d39e2ba8b3e00e4aace6fc438ce3fdb3f55a7", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -661,8 +661,8 @@ }, { "id": 34, - "fingerprint": "sha256:196bcef2f268e3e088f14c0ddecb9cec7671a8c15a93c0ae64be882fb814cf6b", - "api": "cloudflare", + "fingerprint": "sha256:f9cc9aa0cc85b5387ef64d7f9425d900227ee0b1aa04ec006e98f54cec0107c5", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -681,8 +681,8 @@ }, { "id": 35, - "fingerprint": "sha256:1bde4fe7f5ec72fda97db844589f7e14277a0106295a235fe4ca99e8bb49c604", - "api": "cloudflare", + "fingerprint": "sha256:a180c38f16c53abdebcee4a7965a74d83c2a1183d997b6511fd5db39759f9fd9", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -701,8 +701,8 @@ }, { "id": 36, - "fingerprint": "sha256:da138a45d989dae74388c2b44f85921a8a44890cf123b299062b962b4df36399", - "api": "cloudflare", + "fingerprint": "sha256:7bc7e7bdfa4d514d8036aff3230c68729db4071ea4a31eef78cae0429da7a8aa", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -721,8 +721,8 @@ }, { "id": 37, - "fingerprint": "sha256:67ca1d4437e0e2290b10dd8715dec045bd96eab914eca999825fc97391cae79f", - "api": "cloudflare", + "fingerprint": "sha256:3eb5ba7e10f2f270de01e4ae557d65309444fc7d1e44a12393c284806a8f274a", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -741,8 +741,8 @@ }, { "id": 38, - "fingerprint": "sha256:84cc22ea52e09053729b1019e63a0a13a1bf4cf4ec51afd21999beb293f9889d", - "api": "cloudflare", + "fingerprint": "sha256:1191798fc9d356794bb34dacbb1c4ee0eefb8ef43cfe003507249c6d38bb8ddd", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -761,8 +761,8 @@ }, { "id": 39, - "fingerprint": "sha256:13373688facf20f79d9306387f66d8ec67ea30174d4327e83fa556cc73b38822", - "api": "cloudflare", + "fingerprint": "sha256:d869c9d886727d0a740569404f4cb6204ef9c90f951ef4b5068671fd2966247d", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -781,8 +781,8 @@ }, { "id": 40, - "fingerprint": "sha256:ad704018da18a5e7f72a901f3b4f3d93c8cd61a5521cb2864e03d7ae3eb23e66", - "api": "cloudflare", + "fingerprint": "sha256:06436d2eebf1ca793d5866ebb84b07f631f591a2efa15e0d2c52cad055ce0cd2", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -801,8 +801,8 @@ }, { "id": 41, - "fingerprint": "sha256:abef4b70fe7bd32c3f85cbd888c46e906e424466a945337feaa5de3ebe3132e1", - "api": "cloudflare", + "fingerprint": "sha256:b137d7f6e30122960f81975f3db97d7dc65291be284820b2e8595d7a517da2ad", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -821,8 +821,8 @@ }, { "id": 42, - "fingerprint": "sha256:2b0b3f686fa6c635cfa6fcb866562eb43bfaa2c14cd15846208963f79d515ed7", - "api": "cloudflare", + "fingerprint": "sha256:f52cb95e17a1267a8712549f2ea7b74748bcf0e0cd49fc2e5b2b0f289556b2d2", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -841,8 +841,8 @@ }, { "id": 43, - "fingerprint": "sha256:140e71667d384915cb91380499c9fc811b30abc13cb522b19809e3da114ba4fe", - "api": "cloudflare", + "fingerprint": "sha256:259a3b7f1d8fd6ad5af3a6b5ce2448c0dc4b0720e5be5b962956d2cf89f13618", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -861,8 +861,8 @@ }, { "id": 44, - "fingerprint": "sha256:abab68d6a871edbeafd0934b4747b1eb0b5ea456bb0a7120ab71f15d685d3ac0", - "api": "cloudflare", + "fingerprint": "sha256:be17ebd2c1ae1257cc3466756f3becd673cffaccc7cfbd51c78c7a8bb4a68f2f", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -881,8 +881,8 @@ }, { "id": 45, - "fingerprint": "sha256:a1f14c52f06417de1dbba847e4b3a18cdcec344eeaf1be192e3f304664d4a75b", - "api": "cloudflare", + "fingerprint": "sha256:498acad448ff11d1ca7b4adf1743dc8319610e1e363cb8eef6ef06fb894fd752", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -901,8 +901,8 @@ }, { "id": 46, - "fingerprint": "sha256:fcb029390bb09704f2b6b66d86eaaff0cf6b1a44657ba17546ba954f36c59b1a", - "api": "cloudflare", + "fingerprint": "sha256:cecdafa7ca394cd10c66b4d1391d8cd0cb1406a98d562306945b65cf12f7d95c", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -921,8 +921,8 @@ }, { "id": 47, - "fingerprint": "sha256:cd6aa6460c6515dfaa77ad4132f7d7e302ed9dce79410ef089a1a96d50cd4ce9", - "api": "cloudflare", + "fingerprint": "sha256:8e18580b12de646fced9e8639c075485602934bbecf31fb3fcd4626965e3130d", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -941,8 +941,8 @@ }, { "id": 48, - "fingerprint": "sha256:82241cac7c0e6880c0604bb63eab3acfa518084190d764c8b0bc526ad938e084", - "api": "cloudflare", + "fingerprint": "sha256:5cf1987f172cad5871dc6e3431a88d91ac22d9d71139d76b1796382afd9ac354", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -961,8 +961,8 @@ }, { "id": 49, - "fingerprint": "sha256:ef787080dfebbf6a83df76a4798732ce81cf8c5bb194bd90b09628cfdde91954", - "api": "cloudflare", + "fingerprint": "sha256:6ffc521452c053a0219f42d91aee94d7258cc86595367653bfe258cbb9a58461", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -981,8 +981,8 @@ }, { "id": 50, - "fingerprint": "sha256:722ad19c762df8abc40217d69ace0f58a1793ddfa8dac95a9a58bed2a43e36be", - "api": "cloudflare", + "fingerprint": "sha256:23496598d02a7dacc0db57301a3b758249b00c6f9bbd8d4db7b8d46c0ac6d9d8", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -1001,8 +1001,8 @@ }, { "id": 51, - "fingerprint": "sha256:c00265a6469a5f58b5a2daee7134aa5d956efd6fbef8c5e805574dc4aa738f57", - "api": "cloudflare", + "fingerprint": "sha256:503a4d7c97c38f6ea08752cde821c0013a3ea1b255a23e1ea261150d4728e110", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -1021,8 +1021,8 @@ }, { "id": 52, - "fingerprint": "sha256:6b913d06ac816d2691178a00c39edf8bcb8626e97be59f083add9223fd3ef4b6", - "api": "cloudflare", + "fingerprint": "sha256:3135305369b1b70e2f7d7e013de4dada5ee453d10af6b06f4c1079a929294bae", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -1041,8 +1041,8 @@ }, { "id": 53, - "fingerprint": "sha256:873623d5814c1dc0cf3d3f0ce6512d307f2b9594a62808424f2276f96ee2c8aa", - "api": "cloudflare", + "fingerprint": "sha256:adec4debce9bb93c7982100da8ea92300e9340bcb6f7d812a6af3683568094ca", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -1061,8 +1061,8 @@ }, { "id": 54, - "fingerprint": "sha256:113ba45ec5dea21a28854d7f85e0152fb1214e9f20c15d0dcd31d9d7615e9623", - "api": "cloudflare", + "fingerprint": "sha256:fc10048108b7ca3d08aba952289499ffa4ce3bd9a7f7bd16dddee5aef857e7ca", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -1081,8 +1081,8 @@ }, { "id": 55, - "fingerprint": "sha256:9292f2552dab12753439ba70cd7a43cf04b73a113782a4c9ced690ce1c61fb93", - "api": "cloudflare", + "fingerprint": "sha256:1bfef3838571477e1fa07a240dbd0aa4d7dbc5bbcd5ee6e3c039906ca230277d", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -1101,8 +1101,8 @@ }, { "id": 56, - "fingerprint": "sha256:052e0fe801ccf77c57f0971651bc0b21a5672de1fedaf5e8c4170f49bcc1cac2", - "api": "cloudflare", + "fingerprint": "sha256:295c6ae1775686ce83ddc54c0f37fdfa1ce0fbcb402f41386a9d657f9875ad2a", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -1121,8 +1121,8 @@ }, { "id": 57, - "fingerprint": "sha256:e83d1f1f71310ffcbd0acfbc178e9f0088b579eb5b4459065410281b6eb0165a", - "api": "cloudflare", + "fingerprint": "sha256:8661542398e02bcc1177b42fdea573219d96c63f95e0e8da732e8c2ae29e2a70", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -1141,8 +1141,8 @@ }, { "id": 58, - "fingerprint": "sha256:215f05da01f561e584b3f9f91f725be059a30573cbe65067007f6eb6ef552b81", - "api": "cloudflare", + "fingerprint": "sha256:3ba9c7a5958e72c3fc7126273c692fae0c764ff0a6ebbc5b95259913a4edce36", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -1161,8 +1161,8 @@ }, { "id": 59, - "fingerprint": "sha256:2c0bf4eda7cd1f3fd9e90ed90825400c6312931949f175b90764835dd2510120", - "api": "cloudflare", + "fingerprint": "sha256:f0e7ad06ea3277a4913178fb4496ca6f97c54ceb82a58d17da8fd1f01df0213e", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -1181,8 +1181,8 @@ }, { "id": 60, - "fingerprint": "sha256:593d2524280b0af8d52087b7a1172214eecc201b03edef47f9d19ec9e8f2109f", - "api": "cloudflare", + "fingerprint": "sha256:d21dcb330f6468445190911528a37aadb910918003ea905a09854c99ba329af7", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -1201,8 +1201,8 @@ }, { "id": 61, - "fingerprint": "sha256:9009e4cdae0f774732d80f8ebffb71ca9f0d20964aaae67db7b8af9efd7a9907", - "api": "cloudflare", + "fingerprint": "sha256:36bcd50c977f7fdc6a5454e930bd68320f86c25ead8c812748c3201f82a067f6", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -1221,8 +1221,8 @@ }, { "id": 62, - "fingerprint": "sha256:f4ad2fc70533dc70e0a94cb08f9397dc9dcf2ca25df1d0fa1a07bfcf1348bd16", - "api": "cloudflare", + "fingerprint": "sha256:99d329002c578abd3af2041c2b4682d55de66c529a3a9fbe89d433ffa01b8481", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -1241,8 +1241,8 @@ }, { "id": 63, - "fingerprint": "sha256:fefbd411b03a645d2149f585808e334cb7fcf9253b043a2c16fc6f762f0024bc", - "api": "cloudflare", + "fingerprint": "sha256:de8b13bb295b1ff6caae04a075e87216f0587cefd47662958966a24cb5e3aa4e", + "api": "cloudflare/api", "version": "2025-06-15", "change_type": "deprecation", "breaking": false, @@ -1261,8 +1261,8 @@ }, { "id": 64, - "fingerprint": "sha256:3ea68d670fadd202cc5740ff08b2ded911977053f59707ad3f3a977f1f8fca0a", - "api": "cloudflare", + "fingerprint": "sha256:b4fbb0d5da10ef76dd972b661434a6384f51c5da400e35fa0e5b3a223c560f4e", + "api": "cloudflare/api", "version": "2025-06-08", "change_type": "deprecation", "breaking": false, @@ -1281,8 +1281,8 @@ }, { "id": 65, - "fingerprint": "sha256:8b928cc39b74991bc8dd7abac061d79b152c514803afe408130ba223cb73cac7", - "api": "cloudflare", + "fingerprint": "sha256:c7d5d01f2cbe9dc85c2d26beba55283a2d3d342bb7c4d86b575e39ea2acdb039", + "api": "cloudflare/api", "version": "2025-06-08", "change_type": "deprecation", "breaking": false, @@ -1301,8 +1301,8 @@ }, { "id": 66, - "fingerprint": "sha256:a656a715771f1d9d50ad38125f2508f5ba5a778288ee28d06e524ba5c1f8e9d4", - "api": "cloudflare", + "fingerprint": "sha256:936804624340abb866835350b87afd294a4a0c2a14720ee399fa971fe99722a1", + "api": "cloudflare/api", "version": "2025-03-23", "change_type": "deprecation", "breaking": false, @@ -1321,8 +1321,8 @@ }, { "id": 67, - "fingerprint": "sha256:76143718cd7007d1f64bbc070d221a5421ac0849862b22e4c6cda855c262f8e3", - "api": "cloudflare", + "fingerprint": "sha256:ae54224a3bc5f6c162d2a39c7ad1e2d8bfc294e8f095a6fb425b7fa92453991b", + "api": "cloudflare/api", "version": "2024-09-13", "change_type": "deprecation", "breaking": false, @@ -1341,8 +1341,8 @@ }, { "id": 68, - "fingerprint": "sha256:41ce262b4808d88a988fb9d2a060ea0a557ce5b98808c8ac12d7f79eb3e8ec10", - "api": "cloudflare", + "fingerprint": "sha256:109443f03dbd74f10fe9f23473f35c6c1a77a7a52fb1eeae2bc598e4da27d374", + "api": "cloudflare/api", "version": "2024-09-13", "change_type": "deprecation", "breaking": false, @@ -1361,8 +1361,8 @@ }, { "id": 69, - "fingerprint": "sha256:3772460f2e087f788df4d1a25bf8e7ef8729f397e24925982689e861db517c64", - "api": "cloudflare", + "fingerprint": "sha256:369c1017e008311e30160fe237ba412fdfd5f7ea7fa371b0898aa9a6f1641c20", + "api": "cloudflare/api", "version": "2024-09-13", "change_type": "deprecation", "breaking": false, @@ -1381,8 +1381,8 @@ }, { "id": 70, - "fingerprint": "sha256:d22b6deadefd215c5b664fb54ff74364c3e44234ce27e71053617da46167df47", - "api": "cloudflare", + "fingerprint": "sha256:3ed49bd15de4fe5681062e4ada006ef5db3a5c74d7e49297978b1f57750d8117", + "api": "cloudflare/api", "version": "2024-09-13", "change_type": "deprecation", "breaking": false, @@ -1401,8 +1401,8 @@ }, { "id": 71, - "fingerprint": "sha256:d895cf63ec92441421d1fc15ea1d5c6defecb4926d14a5134f2faa6d8c23a71d", - "api": "cloudflare", + "fingerprint": "sha256:1bbcf47531039df6cf26589463f5a2f842ceb391955619ee7870e81de246ea54", + "api": "cloudflare/api", "version": "2024-08-15", "change_type": "deprecation", "breaking": false, @@ -1421,8 +1421,8 @@ }, { "id": 72, - "fingerprint": "sha256:ef87cb5946658e40cefeaa43f40fd8739220167676a40aa45e4c2c43877910ff", - "api": "cloudflare", + "fingerprint": "sha256:236695e093c2ccc67a5d0e6934ed284839882d9d3f90fc090c9a835ac820c425", + "api": "cloudflare/api", "version": "2024-08-15", "change_type": "deprecation", "breaking": false, @@ -1441,8 +1441,8 @@ }, { "id": 73, - "fingerprint": "sha256:bdac35c4e1066ef7f2f97f44a07b477834ec8477f1f581a55d257052de56d3b0", - "api": "cloudflare", + "fingerprint": "sha256:8c9c7efb1ab475de41a640b1a5beacce9a7fb432140d7f6ef2c1ed59ca5b2a43", + "api": "cloudflare/api", "version": "2024-08-05", "change_type": "deprecation", "breaking": false, @@ -1461,8 +1461,8 @@ }, { "id": 74, - "fingerprint": "sha256:1e193b2db1b32d1f598fdafdc0de01506cda1c1ecd43f6042d2691aff325327f", - "api": "cloudflare", + "fingerprint": "sha256:e4bf3bfcd9b07ccea28cd701297ebcd097a8c076b278e433c421289ccbb97fd3", + "api": "cloudflare/api", "version": "2024-08-05", "change_type": "deprecation", "breaking": false, @@ -1481,8 +1481,8 @@ }, { "id": 75, - "fingerprint": "sha256:69bb9383f8c9161b003beac80477548824351264c8add2f755a6f72be3214842", - "api": "cloudflare", + "fingerprint": "sha256:9aafe90e8006993b02af0a7598b9fe358b7461a50a26c9ef3bcd476bb7117151", + "api": "cloudflare/api", "version": "2024-06-30", "change_type": "deprecation", "breaking": false, @@ -1501,8 +1501,8 @@ }, { "id": 76, - "fingerprint": "sha256:c13e8c0cb8a66167b2897de1bfbe019cc48380acbf8057c2b77b3e906c6986de", - "api": "cloudflare", + "fingerprint": "sha256:8509160822c4ef1a919f6aa3dd4398cfcebd69871640d77e4157fcf2e15e3132", + "api": "cloudflare/api", "version": "2024-06-30", "change_type": "deprecation", "breaking": false, @@ -1521,8 +1521,8 @@ }, { "id": 77, - "fingerprint": "sha256:8524fcd9c28f92e0d657e1d5bc1040c33d95847bba5ab1ca20cf3555d498c4ae", - "api": "cloudflare", + "fingerprint": "sha256:0aaac98e595e36b46ceb4254db6cc4962321843161ca40d0bdf18bcbed8b8b95", + "api": "cloudflare/api", "version": "2024-06-14", "change_type": "deprecation", "breaking": false, @@ -1541,8 +1541,8 @@ }, { "id": 78, - "fingerprint": "sha256:494c35d7a6b5f12c713cac51ded1c05d63633672a81e11639bf47759f8fee2fe", - "api": "cloudflare", + "fingerprint": "sha256:a8456ffb133b7cb1820c54e4d18d9f0c183b4a883f7f1350d778be153b193849", + "api": "cloudflare/api", "version": "2024-06-14", "change_type": "deprecation", "breaking": false, @@ -1561,8 +1561,8 @@ }, { "id": 79, - "fingerprint": "sha256:8a0414167374e569a3bd93198ad56f1f1e86b28dd80322ae2508e150109118ac", - "api": "cloudflare", + "fingerprint": "sha256:f2cfb40aaeeab4290539cebc6893fca6e587f52077a98afbe884b0b32d225eb6", + "api": "cloudflare/api", "version": "2024-03-31", "change_type": "deprecation", "breaking": false, @@ -1581,8 +1581,8 @@ }, { "id": 80, - "fingerprint": "sha256:9ce9f1cf3ac03ff226946c714571bd82de15e49f9095d7591d58b76e7b48c7b4", - "api": "cloudflare", + "fingerprint": "sha256:fcc3a0e044104a636e7af25ca521259f1414eda448a7332a7fdf2099e9d5d39f", + "api": "cloudflare/api", "version": "2024-03-31", "change_type": "deprecation", "breaking": false, @@ -1601,8 +1601,8 @@ }, { "id": 81, - "fingerprint": "sha256:29c3d85b45378dfefb2629ad15e0e8688aa3d0c8d02acfdd8cd9d9a33193c39f", - "api": "cloudflare", + "fingerprint": "sha256:ee771e91c7b543523172bbdfb878a4af0ee347e11fadb7ed1033c0b6f14dd409", + "api": "cloudflare/api", "version": "2024-02-04", "change_type": "deprecation", "breaking": false, @@ -1621,8 +1621,8 @@ }, { "id": 82, - "fingerprint": "sha256:11429b81a8878d5a7b076a0d7989ee8c74ee56d0ee5690a20a452a566adcc587", - "api": "cloudflare", + "fingerprint": "sha256:a6142510065d1ffcf3c9c9a8f3388407a4ebc6cc3ef6981d82a159182f7ff0d5", + "api": "cloudflare/api", "version": "2024-02-04", "change_type": "deprecation", "breaking": false, @@ -1641,8 +1641,8 @@ }, { "id": 83, - "fingerprint": "sha256:612f7a78f42051e7acb4fd42401bdf14617a7b897c444d781281a024413ea7de", - "api": "cloudflare", + "fingerprint": "sha256:5be7bbc18164d845bb6d4adf5279c70cec4bd5fafd8299cea0aaeda47e7a84ba", + "api": "cloudflare/api", "version": "2024-02-04", "change_type": "deprecation", "breaking": false, @@ -1661,8 +1661,8 @@ }, { "id": 84, - "fingerprint": "sha256:71d87a69068d827ef0ef8f7adbeead373413c231bd1fcebd01532b1f7036053f", - "api": "cloudflare", + "fingerprint": "sha256:365dabe9d8029ff07060a034692552147bd5a2dc6f4c244f473972bcceb3904d", + "api": "cloudflare/api", "version": "2024-02-04", "change_type": "deprecation", "breaking": false, @@ -1681,8 +1681,8 @@ }, { "id": 85, - "fingerprint": "sha256:7746689ebb3f0f202baab80b57fa327be8a72379950fbba0e6789e2112104d92", - "api": "cloudflare", + "fingerprint": "sha256:c06f2d43b44ce024984cc1ca7f8bfc5b91e8fe0f8a9572722dd894f650aab269", + "api": "cloudflare/api", "version": "2023-06-06", "change_type": "deprecation", "breaking": false, @@ -1701,8 +1701,8 @@ }, { "id": 86, - "fingerprint": "sha256:4ac06fe9f65fa856441dd1a7a94db17e19f47464e00ed806e33aa1607cba03fb", - "api": "cloudflare", + "fingerprint": "sha256:d786e20b8b7fbfdf71c9f93ddeac2af72f846b0d205d06a0537090868dafbeb6", + "api": "cloudflare/api", "version": "2023-06-06", "change_type": "deprecation", "breaking": false, @@ -1721,8 +1721,8 @@ }, { "id": 87, - "fingerprint": "sha256:a82e21186295d77b70978ef4b1d43090311f80cd3d2e611d9b1e3caa8240603b", - "api": "cloudflare", + "fingerprint": "sha256:b2afbae55523fba186e40b5bfbb15aa462217115282bce343803f3ddb0877f08", + "api": "cloudflare/api", "version": "2023-06-06", "change_type": "deprecation", "breaking": false, @@ -1741,8 +1741,8 @@ }, { "id": 88, - "fingerprint": "sha256:25ede29cbeb851c1f3a4600e7b6c4ef2720ffec4977a422af69801679310b844", - "api": "cloudflare", + "fingerprint": "sha256:726e750596fe086865365c9e5eec48b163a17a4bb5d0b3b1abb6e24f1c6b59b0", + "api": "cloudflare/api", "version": "2023-03-19", "change_type": "deprecation", "breaking": false, @@ -1761,8 +1761,8 @@ }, { "id": 89, - "fingerprint": "sha256:a13ebcfcb9c339ee8bb1218581ee1c37690fee295ff6806ace36bea51e9ca506", - "api": "cloudflare", + "fingerprint": "sha256:9d7a295c950e6fc992e756fe4b308a0a7cbe6848b748dceb1e577644f63a2b30", + "api": "cloudflare/api", "version": "2023-03-19", "change_type": "deprecation", "breaking": false, @@ -1781,8 +1781,8 @@ }, { "id": 90, - "fingerprint": "sha256:e89180ebef6a0c40a2a49204fc9dc9a27491a4fc5bf2d42a065899dd60d40731", - "api": "cloudflare", + "fingerprint": "sha256:e7702469b58b59996a7c31f6d209015972cc45baafdb1dde110612124691ae29", + "api": "cloudflare/api", "version": "2023-03-19", "change_type": "deprecation", "breaking": false, @@ -1801,8 +1801,8 @@ }, { "id": 91, - "fingerprint": "sha256:f17d0456bb3a0a51b070f5609cee1cbdbb60919cb3a67c38f1cef4e0ba80fc54", - "api": "cloudflare", + "fingerprint": "sha256:610abf032e5253a64d0750e8681965f304f4d06d793408c8e08bf484faec226f", + "api": "cloudflare/api", "version": "2023-03-19", "change_type": "deprecation", "breaking": false, @@ -1821,8 +1821,8 @@ }, { "id": 92, - "fingerprint": "sha256:dcb342032e2d34bd5e1a6c05bfcc974af327558dd827245e821c318999d27135", - "api": "cloudflare", + "fingerprint": "sha256:2b731caf0e50c134499509637343797743b8a2023659200500aa13ded66c67ba", + "api": "cloudflare/api", "version": "2023-03-19", "change_type": "deprecation", "breaking": false, @@ -1841,8 +1841,8 @@ }, { "id": 93, - "fingerprint": "sha256:1b433d97fddf5d472973a72d9d1972e2b56b7227611ff97ba8773e6eaa38d866", - "api": "cloudflare", + "fingerprint": "sha256:355a1b1dccc1f6848805f1db00f2ce6e0f9a1109a2419e04e33d8f37c7a6fdc5", + "api": "cloudflare/api", "version": "2021-03-01", "change_type": "deprecation", "breaking": false, @@ -1861,8 +1861,8 @@ }, { "id": 94, - "fingerprint": "sha256:85d501de27a68f98047b68cc467ac05d76ea3438365e36858674d079a5a34f57", - "api": "cloudflare", + "fingerprint": "sha256:e7c7fb5bff926f4f70853f4e1870f11094b77c7127bf353f33b193fcde2e0e49", + "api": "cloudflare/api", "version": "2021-03-01", "change_type": "deprecation", "breaking": false, @@ -1881,8 +1881,8 @@ }, { "id": 95, - "fingerprint": "sha256:e4396b53f421754a972237ce1d33f05aba1af22defdf03375c17847f406e3a6f", - "api": "cloudflare", + "fingerprint": "sha256:b5255ba6484e57bf92ebccbed2bd621177ad3d7e3b7971bae28f86ba9b6e09e6", + "api": "cloudflare/api", "version": "2020-04-02", "change_type": "deprecation", "breaking": false, @@ -1901,8 +1901,8 @@ }, { "id": 96, - "fingerprint": "sha256:2742091f3a755e16ea63265caf9f371b25f9530a0bad23437c5c17d8537ac0e4", - "api": "cloudflare", + "fingerprint": "sha256:24877e00b429dd7e1584482a562806e2e5da591145ff82d13219ffaea8886b8c", + "api": "cloudflare/api", "version": "2020-04-02", "change_type": "deprecation", "breaking": false, @@ -1921,8 +1921,8 @@ }, { "id": 97, - "fingerprint": "sha256:ae6856bdf958dedf74897bbfabf97b7a1415419ebfd43d48194422e46c639196", - "api": "cloudflare", + "fingerprint": "sha256:b1b258188b319bdf1081f66da17b8e10c17fb7cc27f9dde1e8543bd4f9b6afd0", + "api": "cloudflare/api", "version": "2020-04-02", "change_type": "deprecation", "breaking": false, @@ -1941,8 +1941,8 @@ }, { "id": 98, - "fingerprint": "sha256:91aa1804bb4fcf3b868af8d143bb82c36ad0e3830087f4a319db1c74b538dc71", - "api": "cloudflare", + "fingerprint": "sha256:b079a8269aa22a30276a3a69e8b93f74ab8e9d1fb515ee292986e6e0380d8d79", + "api": "cloudflare/api", "version": "2020-04-02", "change_type": "deprecation", "breaking": false, @@ -1961,8 +1961,8 @@ }, { "id": 99, - "fingerprint": "sha256:8cda3ee46a442608a8494c295869db1b5fec639e3a1ea5fcb487a3848484be6c", - "api": "cloudflare", + "fingerprint": "sha256:fe435ea852be1ef8de5a64415eb78b6b2919b116784fc2c8cc8230bef77ad18c", + "api": "cloudflare/api", "version": "2020-04-02", "change_type": "deprecation", "breaking": false, @@ -1981,8 +1981,8 @@ }, { "id": 100, - "fingerprint": "sha256:eb2ade41a06d3aed8a4f916720379309d8f748636023584d0e14587090c9fac0", - "api": "cloudflare", + "fingerprint": "sha256:7b9f1d90fa4b5fa3bd6d6a00710899b1c498a342e7acd16878ed5bc5c91c67db", + "api": "cloudflare/api", "version": "2020-04-02", "change_type": "deprecation", "breaking": false, @@ -2001,8 +2001,8 @@ }, { "id": 101, - "fingerprint": "sha256:2f45cd9a65a329b3276385b4e0922df23ad25f8ea71c6c55cce0c4f0775430b9", - "api": "cloudflare", + "fingerprint": "sha256:671bde92a237483c9a9eedb2e1a71b8232c5a0ded304d482526a99dcdcc9a054", + "api": "cloudflare/api", "version": "2020-04-02", "change_type": "deprecation", "breaking": false, @@ -2021,8 +2021,8 @@ }, { "id": 102, - "fingerprint": "sha256:77bc63f086fc2e1ce770b590c83e18e37a29e61e679a817750a84054bb22e661", - "api": "cloudflare", + "fingerprint": "sha256:db3297f35829831ac31d4104ffe1a20351ea7dd8755befb052587f1b7ef6c961", + "api": "cloudflare/api", "version": "2020-04-02", "change_type": "deprecation", "breaking": false, @@ -2041,8 +2041,8 @@ }, { "id": 103, - "fingerprint": "sha256:53cd2ca671825f0fabe62fed3a7a1f17233a95902ddf733f9e8b8ee22aa930c1", - "api": "cloudflare", + "fingerprint": "sha256:ab70507b04fd7821be636e6c23c700bb3dd4c8a08a8bcd7a69cca6d2b8d64b2d", + "api": "cloudflare/api", "version": "2020-04-02", "change_type": "deprecation", "breaking": false, @@ -2061,8 +2061,8 @@ }, { "id": 104, - "fingerprint": "sha256:950cd3ec3decbed9961241b5f1f2dda9006459b2be6a78bf9a98e1f9581df344", - "api": "cloudflare", + "fingerprint": "sha256:c268766c19deb3e42cafc70b0dc8a985ab4916225e175696d9cb440637d713f1", + "api": "cloudflare/api", "version": "2020-04-02", "change_type": "deprecation", "breaking": false, @@ -2081,8 +2081,8 @@ }, { "id": 105, - "fingerprint": "sha256:ceeaf6f0e663b587a2b886dd3ce3fa5980d3671450e804d38d99d574b8366a21", - "api": "cloudflare", + "fingerprint": "sha256:a187bc3652c53e1ac3fc4c1eed3e46c2dd381b9012be5553a4fac5acc6828d45", + "api": "cloudflare/api", "version": "2020-04-02", "change_type": "deprecation", "breaking": false, @@ -2101,8 +2101,8 @@ }, { "id": 106, - "fingerprint": "sha256:07b26bf4f30b8203ad1f87e8e74bc1dfcce573eb311a4554ccc97d4026c466b5", - "api": "cloudflare", + "fingerprint": "sha256:6d4f2d565998c8a63c6ed6dea40e33ba734e531b0c4ce473cfde38e47128990f", + "api": "cloudflare/api", "version": "2020-04-02", "change_type": "deprecation", "breaking": false, @@ -2121,8 +2121,8 @@ }, { "id": 107, - "fingerprint": "sha256:f77532cf6a888d0c58adc1b28817260805264525b65aa800d9dc2972c6c92cc8", - "api": "cloudflare", + "fingerprint": "sha256:07b87c3debecbe821246c3cd1ff699edbe01235447c7b115d889bb3690752cdc", + "api": "cloudflare/api", "version": "2020-04-02", "change_type": "deprecation", "breaking": false, @@ -2141,8 +2141,8 @@ }, { "id": 108, - "fingerprint": "sha256:4a4051bd43d0c13a08b5c25ef661a80ba3d417efb4d0ea316315af99b16848fa", - "api": "cloudflare", + "fingerprint": "sha256:0026aad502bf82ec5afdc69f049a5b20930d1f62f0ec8401416f4b16a69e7089", + "api": "cloudflare/api", "version": "2020-04-02", "change_type": "deprecation", "breaking": false, @@ -2161,8 +2161,8 @@ }, { "id": 109, - "fingerprint": "sha256:138291351a584f62faae1f0185294f4c9222e3c81052878158f4c502ad6f73e3", - "api": "cloudflare", + "fingerprint": "sha256:de966d817e65f6765628df10f79e7fc1dea3ca99da31d41373992476cabab73e", + "api": "cloudflare/api", "version": "2020-04-02", "change_type": "deprecation", "breaking": false, @@ -2181,8 +2181,8 @@ }, { "id": 110, - "fingerprint": "sha256:3eb1b2160bd4f145e391c297796259d1b0d6e6b7c645308cf934e829f04ed961", - "api": "cloudflare", + "fingerprint": "sha256:fa54d9d710ccf64cce5de99d76ffeefac524a1e7a2bd54a50665a3cde74b20a5", + "api": "cloudflare/api", "version": "2020-04-02", "change_type": "deprecation", "breaking": false, @@ -2201,8 +2201,8 @@ }, { "id": 111, - "fingerprint": "sha256:0ae28a40c9eb7d42d1c0c2d4754104e403839d9af513aced01289e678b6c9b01", - "api": "cloudflare", + "fingerprint": "sha256:19c8ac3a1f58527481afe59697f2c1a3e74f0dcd43db9fca373e3e2ca5130456", + "api": "cloudflare/api", "version": "2020-04-02", "change_type": "deprecation", "breaking": false, @@ -2221,8 +2221,8 @@ }, { "id": 112, - "fingerprint": "sha256:69933e9ad14fcbd1a15b5c8777b44364582163546de1bbc2bed48b8dca0eb090", - "api": "cloudflare", + "fingerprint": "sha256:2d2bff1a5afd28fd3b2e075980fd6eb896a78c4c0eab50a1ab6b181af012bd17", + "api": "cloudflare/api", "version": "2020-04-02", "change_type": "deprecation", "breaking": false, @@ -2241,8 +2241,8 @@ }, { "id": 113, - "fingerprint": "sha256:25c9b731e783cbea7c577bc0ddbffd4c78a535e4d38699f7e97f6f5f533a28d4", - "api": "cloudflare", + "fingerprint": "sha256:67c9f4884ff77bc7d09bd034d69d3589beb7cc43d651685a9663722a29b2117c", + "api": "cloudflare/api", "version": "2020-04-02", "change_type": "deprecation", "breaking": false, @@ -2261,8 +2261,8 @@ }, { "id": 114, - "fingerprint": "sha256:7ae73318dc7f30d3c47f74c2b01332c81c777f0c89fa831dcbd8bb95ae5182b5", - "api": "cloudflare", + "fingerprint": "sha256:e9f5ebfee335467683ad29c64f264d5ab45ca22c9c25a7d7c724e27c9a76f0ee", + "api": "cloudflare/api", "version": "2020-04-02", "change_type": "deprecation", "breaking": false, diff --git a/plugins/feed/testdata/golden/github-actions.json b/plugins/notices/testdata/golden/github-actions.json similarity index 89% rename from plugins/feed/testdata/golden/github-actions.json rename to plugins/notices/testdata/golden/github-actions.json index 0892839..4b5cda7 100644 --- a/plugins/feed/testdata/golden/github-actions.json +++ b/plugins/notices/testdata/golden/github-actions.json @@ -1,8 +1,8 @@ [ { "id": 1, - "fingerprint": "sha256:d067089552e48ba93490a1dd4ed264e0c374abf1a7c32d31f654333b8ef29383", - "api": "github-actions", + "fingerprint": "sha256:bdfcfa49f99297e3e205a803e01a25285fa7b5b07b1cb98b4c9d716aec4c12f4", + "api": "github/actions", "version": "2026-11-02", "change_type": "breaking", "breaking": true, @@ -20,8 +20,8 @@ }, { "id": 2, - "fingerprint": "sha256:f12c343a95fdc0d86525094476637ab2b1b05cc1d0d10e3c9e0ef606cc559bec", - "api": "github-actions", + "fingerprint": "sha256:a4de3d5a12c726e5ed2733253429730a0a456113302b879f0d0219419d3ca474", + "api": "github/actions", "version": "2026-11-02", "change_type": "breaking", "breaking": true, @@ -39,8 +39,8 @@ }, { "id": 3, - "fingerprint": "sha256:ae17303775653df724346bd47eea5997a342378f78c2e8bf80510d50d424ea7b", - "api": "github-actions", + "fingerprint": "sha256:2f2185ea0c64bbed2075d64d5a8f697a0b9ef179ae65a221d19816305ad11030", + "api": "github/actions", "version": "2026-11-02", "change_type": "breaking", "breaking": true, diff --git a/plugins/feed/testdata/golden/vertex-ai-models.json b/plugins/notices/testdata/golden/google-vertex-ai-models.json similarity index 89% rename from plugins/feed/testdata/golden/vertex-ai-models.json rename to plugins/notices/testdata/golden/google-vertex-ai-models.json index ae9f8ec..ed7b170 100644 --- a/plugins/feed/testdata/golden/vertex-ai-models.json +++ b/plugins/notices/testdata/golden/google-vertex-ai-models.json @@ -1,8 +1,8 @@ [ { "id": 1, - "fingerprint": "sha256:0f5e79c13e364f582195949330aa17e5c9d4151362f0914d3e5b55bec4fcebbf", - "api": "vertex-ai-models", + "fingerprint": "sha256:4627337a65ee7ecc6e02ac97ae51834d56722fa732ef67a19eca027b566a4f44", + "api": "google/vertex-ai-models", "version": "2026-06-30", "change_type": "deprecation", "breaking": false, @@ -21,8 +21,8 @@ }, { "id": 2, - "fingerprint": "sha256:5ea59f6bae5251fdddc19dfd2068487e38e16f3ed4c14d3732f89ad80ba9f3f0", - "api": "vertex-ai-models", + "fingerprint": "sha256:7da0d2dd46fa4f16ed41f9857ac90de07be28a2e165544c3212e2b975296a0e5", + "api": "google/vertex-ai-models", "version": "2026-06-30", "change_type": "deprecation", "breaking": false, @@ -41,8 +41,8 @@ }, { "id": 3, - "fingerprint": "sha256:4b3d8e8e9a9c26b15641b76047fbdd751eb38d02dc67184bd41a42c5123dba9a", - "api": "vertex-ai-models", + "fingerprint": "sha256:366d6614ee42be4bd650704aa459e9d7a338cb682119f0b66123d030184ebc8d", + "api": "google/vertex-ai-models", "version": "2026-06-30", "change_type": "deprecation", "breaking": false, @@ -61,8 +61,8 @@ }, { "id": 4, - "fingerprint": "sha256:7a869d0728c23c1d9467b8339cca9d3a1d6bd6bfb713d97bba14aafee33b8156", - "api": "vertex-ai-models", + "fingerprint": "sha256:54113780d0f2717208cd90ff8f76e4ac24f19302aa2e89ca10dfb4ca767f6236", + "api": "google/vertex-ai-models", "version": "2026-06-30", "change_type": "deprecation", "breaking": false, @@ -81,8 +81,8 @@ }, { "id": 5, - "fingerprint": "sha256:788404627769b8fa60709fce8e1d3ad22631bdd2007c90d883a9c0ad704308ab", - "api": "vertex-ai-models", + "fingerprint": "sha256:e4cf8857ddd3731ed2853071312f49588e79c47e81de698aa3458e0ed551b6fa", + "api": "google/vertex-ai-models", "version": "2026-06-30", "change_type": "deprecation", "breaking": false, @@ -101,8 +101,8 @@ }, { "id": 6, - "fingerprint": "sha256:692c4163cdb6bea77df0f41930d396e076cac4ca5ffbbca4608497da1595cf36", - "api": "vertex-ai-models", + "fingerprint": "sha256:70e23f95c88d498b93825af99e0790a21b80cdd1903b522f36ccf7a76fa09182", + "api": "google/vertex-ai-models", "version": "2026-06-30", "change_type": "deprecation", "breaking": false, @@ -121,8 +121,8 @@ }, { "id": 7, - "fingerprint": "sha256:6dc7af5708772ad89a8af1458dcdbeaba4aa1edbac81ef24a24dd4019301c4a2", - "api": "vertex-ai-models", + "fingerprint": "sha256:7ccb799cf84268de5106b8509e4c0706f7165eab3b189bcf171df9c4b08f9bf9", + "api": "google/vertex-ai-models", "version": "2026-06-30", "change_type": "deprecation", "breaking": false, @@ -141,8 +141,8 @@ }, { "id": 8, - "fingerprint": "sha256:8f4954dc8110183332daa2c0599acf1eb480fe8a7625681acc19260c52469279", - "api": "vertex-ai-models", + "fingerprint": "sha256:2edea0439cd41993804f3165d122d92f88f95fa5d22da1ae8a72c54562df56b9", + "api": "google/vertex-ai-models", "version": "2026-06-30", "change_type": "deprecation", "breaking": false, @@ -161,8 +161,8 @@ }, { "id": 9, - "fingerprint": "sha256:18882130e85984f1289667a0336174179192417971a1256038b4391e3f2d202e", - "api": "vertex-ai-models", + "fingerprint": "sha256:ab4cd57e14aa05f619251f4e234f9b6faa5719f2599efd9c0f0ddf17242bf400", + "api": "google/vertex-ai-models", "version": "2026-06-30", "change_type": "deprecation", "breaking": false, @@ -181,8 +181,8 @@ }, { "id": 10, - "fingerprint": "sha256:66bdd91e4b7bd86a67547ad13be1ff17c0143aa82563d2df07a07563b19d4aeb", - "api": "vertex-ai-models", + "fingerprint": "sha256:8d25d3020603811f27cfd86a17ddd27626682a65a09bd6286fad5488dfa04800", + "api": "google/vertex-ai-models", "version": "2026-06-30", "change_type": "deprecation", "breaking": false, @@ -201,8 +201,8 @@ }, { "id": 11, - "fingerprint": "sha256:f600afe7780213164a28b9f471eea689ae3c982cbc6079d1e15a9c93d1934227", - "api": "vertex-ai-models", + "fingerprint": "sha256:39ca8174998ababa3c0c7c5438e1792de7b4133980c2038cce2f0e5eefde9ac9", + "api": "google/vertex-ai-models", "version": "2026-06-30", "change_type": "deprecation", "breaking": false, @@ -221,8 +221,8 @@ }, { "id": 12, - "fingerprint": "sha256:eda860833ba104f4fc5d1dfcaf19f17888218f405743c32929549c46025ca72b", - "api": "vertex-ai-models", + "fingerprint": "sha256:dfba27e6493a553e4976424fe316649f6111d3925c8443ac562ace71c5327183", + "api": "google/vertex-ai-models", "version": "2026-06-30", "change_type": "deprecation", "breaking": false, @@ -241,8 +241,8 @@ }, { "id": 13, - "fingerprint": "sha256:f88d17b03256295e4cbd2c63d32fedf768c9e6d09afbb9aa8d916a7a1434b451", - "api": "vertex-ai-models", + "fingerprint": "sha256:e498e7d1768eb1327445f5589b9b5cf1eeede6a8fccecd98896ac39fdb6cf93b", + "api": "google/vertex-ai-models", "version": "2026-06-30", "change_type": "deprecation", "breaking": false, @@ -261,8 +261,8 @@ }, { "id": 14, - "fingerprint": "sha256:c00c71e4574c444cc0123067d8e22f1f23aeb81f1869d58b6da824eb7b0503d4", - "api": "vertex-ai-models", + "fingerprint": "sha256:91583fe5103284396c784ccc01d805ff0b3df116b2f39a1ff594292c6c19f3c9", + "api": "google/vertex-ai-models", "version": "2026-06-30", "change_type": "deprecation", "breaking": false, @@ -281,8 +281,8 @@ }, { "id": 15, - "fingerprint": "sha256:db4114d7dd166f3bbe3e8f41d3a635609646688714c2b97bf54e3eaff0447021", - "api": "vertex-ai-models", + "fingerprint": "sha256:5d95e1087917d0ca68631f30d564790fbf485bf9f8c946d38b602191bcc5eff2", + "api": "google/vertex-ai-models", "version": "2026-06-30", "change_type": "deprecation", "breaking": false, @@ -301,8 +301,8 @@ }, { "id": 16, - "fingerprint": "sha256:ffce6cb7b473d003b1ef369d2e71467f81fda18ed6cfe9759da5dd1f16fc2d55", - "api": "vertex-ai-models", + "fingerprint": "sha256:8e8d56f1d8bd361be7f4eb6516da283bec666b26d4cc5d8eea5efe3c979aadd6", + "api": "google/vertex-ai-models", "version": "2026-06-30", "change_type": "deprecation", "breaking": false, @@ -321,8 +321,8 @@ }, { "id": 17, - "fingerprint": "sha256:f911516ae80652bed0283094892f9c446c556553b01d346b50dd302de8b71eee", - "api": "vertex-ai-models", + "fingerprint": "sha256:97f4aacf7dd601956041e3d0bca0708cf5236e4e26e71019919fc9cf9c7b9c36", + "api": "google/vertex-ai-models", "version": "2026-06-30", "change_type": "deprecation", "breaking": false, @@ -341,8 +341,8 @@ }, { "id": 18, - "fingerprint": "sha256:7f4058ca7aa25de9dbcd4c545af314f505fc6fdc0428cddea60ebe87a4cd1496", - "api": "vertex-ai-models", + "fingerprint": "sha256:717de8a8c0f4ffbcb5e35f0440648d2ff8533165261a04e8f3d7112ce265ba20", + "api": "google/vertex-ai-models", "version": "2026-04-02", "change_type": "deprecation", "breaking": false, @@ -361,8 +361,8 @@ }, { "id": 19, - "fingerprint": "sha256:0c51a24744cecbf0fb1421e97c90ac6a87dfd8c86291eebbdaeeb3c9e25fd6bb", - "api": "vertex-ai-models", + "fingerprint": "sha256:43c9247f0fe52ba4f8b04d0efd09eb724b997fb9fd6d2ccf2f4cf8e39eaab770", + "api": "google/vertex-ai-models", "version": "2026-04-02", "change_type": "deprecation", "breaking": false, @@ -380,8 +380,8 @@ }, { "id": 20, - "fingerprint": "sha256:fff7b3ac8fd2afe26bf625af257c58ca932e147bc1d1efc6aaa8c44a3fbadb4c", - "api": "vertex-ai-models", + "fingerprint": "sha256:81c5020f2b5e4bf5ac41f41d74ab25411de5709661e6bf2c58880b2dc334eb5e", + "api": "google/vertex-ai-models", "version": "2026-04-02", "change_type": "deprecation", "breaking": false, @@ -400,8 +400,8 @@ }, { "id": 21, - "fingerprint": "sha256:2ee0383f5522593eac8bf36472897a414ba3f4919896e584acaf36d414c1fbfc", - "api": "vertex-ai-models", + "fingerprint": "sha256:f603b43ee261cb8092b8dea3fb0ef7f11d7052595a5aaa23b2a350fae0744aff", + "api": "google/vertex-ai-models", "version": "2026-04-02", "change_type": "deprecation", "breaking": false, @@ -420,8 +420,8 @@ }, { "id": 22, - "fingerprint": "sha256:1c9b4de87f0ffa9300fedde2b15ea587c2fcaa789878fa0d4263f13a831966a6", - "api": "vertex-ai-models", + "fingerprint": "sha256:f522717bee23205fa997dd1a055708e7ca210c5dc035f88920463fa14e57af5a", + "api": "google/vertex-ai-models", "version": "2026-04-02", "change_type": "deprecation", "breaking": false, @@ -440,8 +440,8 @@ }, { "id": 23, - "fingerprint": "sha256:b2c129ec35c2078aabf91b7a4fe8a1e7b32f75b2d24f71429679d42794efe595", - "api": "vertex-ai-models", + "fingerprint": "sha256:8f8284129c2702e11752022571ae87f6b1c383bedf0e97b57cb4448ec0f5ca98", + "api": "google/vertex-ai-models", "version": "2026-04-02", "change_type": "deprecation", "breaking": false, @@ -460,8 +460,8 @@ }, { "id": 24, - "fingerprint": "sha256:84f3822d9f8220fdd5698435944a3855a3a3695ac5307a22a8c8bb8909561953", - "api": "vertex-ai-models", + "fingerprint": "sha256:94012bcb9d12655a7703235f5fcd7686f4ab638449b1dcf4274021c2d57e15b3", + "api": "google/vertex-ai-models", "version": "2026-04-02", "change_type": "deprecation", "breaking": false, @@ -480,8 +480,8 @@ }, { "id": 25, - "fingerprint": "sha256:eee28c0d67a8bde3b4457e586bc15d45e41145c2c1cf3df0ce4b87221db21817", - "api": "vertex-ai-models", + "fingerprint": "sha256:f940d36a57c55555c4a77ad0e81374a5384b2dc465a2545d8d80856ed5ceb0e9", + "api": "google/vertex-ai-models", "version": "2026-04-02", "change_type": "deprecation", "breaking": false, @@ -500,8 +500,8 @@ }, { "id": 26, - "fingerprint": "sha256:ff545ee513d1836e9886341c232ec1b97c3a7d5695d56eb8ae28ab0f8f519986", - "api": "vertex-ai-models", + "fingerprint": "sha256:ead9022ac7480a58f5e5592aa1052a795436440bf8f1c44f06bd0dfa924b3fd3", + "api": "google/vertex-ai-models", "version": "2026-03-19", "change_type": "deprecation", "breaking": false, @@ -520,8 +520,8 @@ }, { "id": 27, - "fingerprint": "sha256:984c2fed1d81d1a7855bb5482a25be0e5dbca8d7df4a6efcb311cb7e772be980", - "api": "vertex-ai-models", + "fingerprint": "sha256:6d498a1d266365bad2125ea26ed5f34d10c55d1dcc59d72d7feb2db19d63a17b", + "api": "google/vertex-ai-models", "version": "2026-03-19", "change_type": "deprecation", "breaking": false, @@ -539,8 +539,8 @@ }, { "id": 28, - "fingerprint": "sha256:755d77bc3a6469fffe3ba3469343217103bf796b20c7fbca8c765b8236c3e97e", - "api": "vertex-ai-models", + "fingerprint": "sha256:1f62ea6bf271e2b64a26cd0f64b679d0058b1d63e3551dd64fbe58fe849fc1b4", + "api": "google/vertex-ai-models", "version": "2026-03-19", "change_type": "deprecation", "breaking": false, @@ -558,8 +558,8 @@ }, { "id": 29, - "fingerprint": "sha256:7bd941e020f89704dd588745a801d7ca06be040a01ffbb5bd6cdbcbf355379d9", - "api": "vertex-ai-models", + "fingerprint": "sha256:7f6da3ceb3be5b19a4a84b34bfc738a3c907f79614f6924b79bb9d8fe5e15f04", + "api": "google/vertex-ai-models", "version": "2026-03-19", "change_type": "deprecation", "breaking": false, @@ -577,8 +577,8 @@ }, { "id": 30, - "fingerprint": "sha256:3890b3e4167e6e14e6b4010cc5efa73e8a2477a8ad0b632dbec1be14064591be", - "api": "vertex-ai-models", + "fingerprint": "sha256:aaf7a42341e623059379622c1f42b13ac3db869956d0c7783c2c6b208e8fc9cb", + "api": "google/vertex-ai-models", "version": "2026-03-19", "change_type": "deprecation", "breaking": false, @@ -596,8 +596,8 @@ }, { "id": 31, - "fingerprint": "sha256:0a742cc5aa7b799359ec3ce39c831f19e33e9bde4b3c96f37232697685f01ec3", - "api": "vertex-ai-models", + "fingerprint": "sha256:a1634ca7146b93f7d208e08f064923ac3bc2c39fd5e838706a36c0891f70f4d2", + "api": "google/vertex-ai-models", "version": "2026-03-19", "change_type": "deprecation", "breaking": false, @@ -615,8 +615,8 @@ }, { "id": 32, - "fingerprint": "sha256:fecc1a31c266860d32797c9d105ec12cee5ab85ce670c6299f96f0dbd115c74e", - "api": "vertex-ai-models", + "fingerprint": "sha256:94fff9b9d36a3cc8ce8b764ecbc4cf78c7544fab37518ed1ddc09ba7b77de150", + "api": "google/vertex-ai-models", "version": "2026-03-19", "change_type": "deprecation", "breaking": false, @@ -635,8 +635,8 @@ }, { "id": 33, - "fingerprint": "sha256:080e7458169bf6776309ebdcb9089a6d4379173f022a35c23c8cb570e9175218", - "api": "vertex-ai-models", + "fingerprint": "sha256:76dc2c9d131c5f4440bb4d3359bb613fbd78762b5fb63e969d93205bc8914a03", + "api": "google/vertex-ai-models", "version": "2026-03-19", "change_type": "deprecation", "breaking": false, @@ -655,8 +655,8 @@ }, { "id": 34, - "fingerprint": "sha256:53a7cf907dd48b38b6f41e079ca637c1b057e3a44d45d4194da00bee7633013b", - "api": "vertex-ai-models", + "fingerprint": "sha256:5ce0ba566a3c908960246f8a12eb65a096c47730c7947c81371c8c01e2071717", + "api": "google/vertex-ai-models", "version": "2026-03-19", "change_type": "deprecation", "breaking": false, @@ -675,8 +675,8 @@ }, { "id": 35, - "fingerprint": "sha256:b8aa1a9f5bf9e02375d6b65c32606474db34cb2afcec0b2568a60c173e940cd4", - "api": "vertex-ai-models", + "fingerprint": "sha256:ae6ad7fcb917173ee50e45c04736c2f9cabec071da307402916398d6203a9ab2", + "api": "google/vertex-ai-models", "version": "2026-03-19", "change_type": "deprecation", "breaking": false, diff --git a/plugins/retirements/testdata/golden/openai-models.json b/plugins/notices/testdata/golden/openai-models.json similarity index 88% rename from plugins/retirements/testdata/golden/openai-models.json rename to plugins/notices/testdata/golden/openai-models.json index 49db9a7..c55deda 100644 --- a/plugins/retirements/testdata/golden/openai-models.json +++ b/plugins/notices/testdata/golden/openai-models.json @@ -1,8 +1,8 @@ [ { "id": 1, - "fingerprint": "sha256:42388e820b0a7d00e7bf964ab1b152758ed364860f4bab2b4d0fe584429af14e", - "api": "openai-models", + "fingerprint": "sha256:e83a8785aa6d1906e4892462f0f62fa5b84084e2329286623563aecdf88249ba", + "api": "openai/models", "version": "2027-04-01", "change_type": "breaking", "breaking": true, @@ -21,8 +21,8 @@ }, { "id": 2, - "fingerprint": "sha256:a2b093fef6f16658554b0ad905366380f557a1807af2995df4da7b09196d919b", - "api": "openai-models", + "fingerprint": "sha256:9c716074471064f27c0955e58528789627b3e305f8e9f484f802ffce272a02b1", + "api": "openai/models", "version": "2027-04-01", "change_type": "breaking", "breaking": true, @@ -41,8 +41,8 @@ }, { "id": 3, - "fingerprint": "sha256:f79902ee8c07c3e2757e4d216f4a09b0a0f501bbceeff28bca11b40a9ea5a861", - "api": "openai-models", + "fingerprint": "sha256:5468ca8ed9e11617bf886b8295f73ae0dab23e44cd09ff066dfe205f0f532453", + "api": "openai/models", "version": "2027-04-01", "change_type": "breaking", "breaking": true, @@ -61,8 +61,8 @@ }, { "id": 4, - "fingerprint": "sha256:c140d34b0457a6dc57a688e7c360f4dedac5b18d539ff974b8aae202bbe9b6a4", - "api": "openai-models", + "fingerprint": "sha256:fd7343b0764b86973207e103c720c03cc5ad27ad09e0f178b5c02c2706d883e3", + "api": "openai/models", "version": "2026-12-11", "change_type": "breaking", "breaking": true, @@ -81,8 +81,8 @@ }, { "id": 5, - "fingerprint": "sha256:db17dd17b62923090964c8c5d13a6c6fa510f1ad9d34dd0124ee6b321b184fa8", - "api": "openai-models", + "fingerprint": "sha256:9a9550f80f08e21273eda077e7419d2e3bb18846552791072afcb0059e95b2fe", + "api": "openai/models", "version": "2026-12-11", "change_type": "breaking", "breaking": true, @@ -101,8 +101,8 @@ }, { "id": 6, - "fingerprint": "sha256:07df9f561719ef7a15a7f6dd80259b01795c468966630625e2d68d41756a5915", - "api": "openai-models", + "fingerprint": "sha256:158fd36994686a79bf82bfbd377ed17c6567546fbbbb36791f11ca390faa4081", + "api": "openai/models", "version": "2026-12-11", "change_type": "breaking", "breaking": true, @@ -121,8 +121,8 @@ }, { "id": 7, - "fingerprint": "sha256:5bbc72be619dacebd8411eac696e94509a079171f491a2587e42f2658b24cf50", - "api": "openai-models", + "fingerprint": "sha256:2513bab92d4daf80ce3a3341677c48567a142a27968890bddaa39b349443ac4a", + "api": "openai/models", "version": "2026-12-11", "change_type": "breaking", "breaking": true, @@ -140,8 +140,8 @@ }, { "id": 8, - "fingerprint": "sha256:d8a013a8cf1c6cee2e3e1b90357b521ad3ced146318be596ae77e7011353e8f0", - "api": "openai-models", + "fingerprint": "sha256:3aaa754c27ec3dcf296ba9eca13168cc0c4260f578dd5487fa452ae0406444dd", + "api": "openai/models", "version": "2026-12-11", "change_type": "breaking", "breaking": true, @@ -160,8 +160,8 @@ }, { "id": 9, - "fingerprint": "sha256:fd7c2fabbd94c0eb6fd24ae7568a31533b83a63a61bb71d7d89ed966efe7f58f", - "api": "openai-models", + "fingerprint": "sha256:e38b1b847caef42cbed0c277347fe0dcab40032ff344b7252a00fd3c18e49b5c", + "api": "openai/models", "version": "2026-12-11", "change_type": "breaking", "breaking": true, @@ -179,8 +179,8 @@ }, { "id": 10, - "fingerprint": "sha256:4b1daccf92b70cbd4191989c452248915ff017a7b98697f711645ccf4b55695a", - "api": "openai-models", + "fingerprint": "sha256:0bc7c996a01e3dd0fae14537400f8bf77fb9ec8dd33c10c5b6458315ba8eb6d5", + "api": "openai/models", "version": "2026-10-01", "change_type": "breaking", "breaking": true, @@ -198,8 +198,8 @@ }, { "id": 11, - "fingerprint": "sha256:396c799693251a663ae5b5f06d1457fce990d7e25828e4d7d7ecbd73c6482856", - "api": "openai-models", + "fingerprint": "sha256:9f118e5bd24e073e6ed3cd7dc41a27322b18f714a30a2c3dff9ced089c9c6832", + "api": "openai/models", "version": "2026-08-10", "change_type": "breaking", "breaking": true, @@ -218,8 +218,8 @@ }, { "id": 12, - "fingerprint": "sha256:860adbaee02f25c0cdaeba0bfb21a14274d0a775cb1571a7144f12ef8d74be0c", - "api": "openai-models", + "fingerprint": "sha256:b843df920a2fb85eedc486fab1ca241676cf4d3e15ed6983e2913d38dc602bc2", + "api": "openai/models", "version": "2026-08-10", "change_type": "breaking", "breaking": true, @@ -238,8 +238,8 @@ }, { "id": 13, - "fingerprint": "sha256:ce26aa764cab39b9d0a9e69a55c1a8bb089f9d76b4babff17f5abd032d842864", - "api": "openai-models", + "fingerprint": "sha256:9de4b398a49814fc611c1f914d0caa04e3b49bb8bd820030e6dfa3d008eb525c", + "api": "openai/models", "version": "2026-10-23", "change_type": "breaking", "breaking": true, @@ -258,8 +258,8 @@ }, { "id": 14, - "fingerprint": "sha256:4192b9a11d08c878837cde100ccb5295ed2d6e684f9c34730a994eb90202cf1f", - "api": "openai-models", + "fingerprint": "sha256:f22d331f61c1e7558b711cc8fdec2c60f563f52a132dbdc3e297c38440460453", + "api": "openai/models", "version": "2026-10-23", "change_type": "breaking", "breaking": true, @@ -278,8 +278,8 @@ }, { "id": 15, - "fingerprint": "sha256:0b728cec3efd96ef7ca8765c34aef84c2e13887fdc5274c069984c8aee120aee", - "api": "openai-models", + "fingerprint": "sha256:addb33cfa80c881094a669f95b412315e962f57818d9b2c60bf10b457384fd06", + "api": "openai/models", "version": "2026-10-23", "change_type": "breaking", "breaking": true, @@ -298,8 +298,8 @@ }, { "id": 16, - "fingerprint": "sha256:8339104fec6d3ac38394a5902bfd896a1fbe864a6434ecf607e22faaae7662e9", - "api": "openai-models", + "fingerprint": "sha256:fa804d562f3745055a2a0102bfc04b2e9bf83c1f009b01b6011da54a42698743", + "api": "openai/models", "version": "2026-10-23", "change_type": "breaking", "breaking": true, @@ -318,8 +318,8 @@ }, { "id": 17, - "fingerprint": "sha256:ff6ba96f8b5e4b0788e3a4267215fc864b7afa24deb44a1427602089af35f6db", - "api": "openai-models", + "fingerprint": "sha256:e7368b0ebebe0b0d76c287216e5028a43aa67c5bd19d93100b0a5f578f4de3a1", + "api": "openai/models", "version": "2026-10-23", "change_type": "breaking", "breaking": true, @@ -338,8 +338,8 @@ }, { "id": 18, - "fingerprint": "sha256:ff410b834f7b61c26f5f6efa6d2925a8ad7b8fe9836be048b18afcc5649b7bf0", - "api": "openai-models", + "fingerprint": "sha256:d028abbd1dbe941ef3ddc502493237ac63618d5bb6dfddb97f865238b953e87b", + "api": "openai/models", "version": "2026-10-23", "change_type": "breaking", "breaking": true, @@ -358,8 +358,8 @@ }, { "id": 19, - "fingerprint": "sha256:6e193d723a4d3b995ceb4a14acfe60a7346f2fc479432e053f2e8d421ee1e8cc", - "api": "openai-models", + "fingerprint": "sha256:2366f086a80491576145afe7cf510c55ac4e0d2de7bf441bc75ef612d6167e2b", + "api": "openai/models", "version": "2026-10-23", "change_type": "breaking", "breaking": true, @@ -378,8 +378,8 @@ }, { "id": 20, - "fingerprint": "sha256:44528ba7f19ebb51ec9055123c0774263a3deb77d8fd8ccb0c3629e8968efb34", - "api": "openai-models", + "fingerprint": "sha256:94b73f3151693c11fde24e3848af27c40865037cbd9cf4115e3bc19fd8c60052", + "api": "openai/models", "version": "2026-10-23", "change_type": "breaking", "breaking": true, @@ -398,8 +398,8 @@ }, { "id": 21, - "fingerprint": "sha256:6ebc3787c51d8082fe265819faa8d32c50c5989a404144cdfb9d593d71a03bc5", - "api": "openai-models", + "fingerprint": "sha256:d759ff817c84f9d74272fcb91cbdae5221e974eb47b0b55b7dd7147aa1e31602", + "api": "openai/models", "version": "2026-10-23", "change_type": "breaking", "breaking": true, @@ -418,8 +418,8 @@ }, { "id": 22, - "fingerprint": "sha256:5484892bfe6ea2a10d9f2f858b646814273888619cfa77ffefb14e474ae91ddd", - "api": "openai-models", + "fingerprint": "sha256:0480d1edc177c250b09e7a924a9b40657b44783e7c9bbbb0ffacb80db251fc7f", + "api": "openai/models", "version": "2026-10-23", "change_type": "breaking", "breaking": true, @@ -438,8 +438,8 @@ }, { "id": 23, - "fingerprint": "sha256:b63b86a39ecf25bb85b58e670346ab72b7b5d9017862c20749cfd47cdbbea309", - "api": "openai-models", + "fingerprint": "sha256:ba214836ceb8d67ee994e2dc21f34390630a25c9980f28027d406a6e6cf20aa8", + "api": "openai/models", "version": "2026-10-23", "change_type": "breaking", "breaking": true, @@ -458,8 +458,8 @@ }, { "id": 24, - "fingerprint": "sha256:45307e4078b45d31ae96526982d65375586045547491465a7fcd2939d29afbcd", - "api": "openai-models", + "fingerprint": "sha256:12144bbcd4bc23bd91febd9d2f96b3a9e9579dc4e04bb63422771f69f18721ce", + "api": "openai/models", "version": "2026-10-23", "change_type": "breaking", "breaking": true, @@ -478,8 +478,8 @@ }, { "id": 25, - "fingerprint": "sha256:a6a5649fce6528970f9594cccb059977ec95d6acab772672615c179b4ed29d01", - "api": "openai-models", + "fingerprint": "sha256:3ea97dbeb2ae5fd8b306c204b89426d83f17e1beb06f435b482e50355f0c4205", + "api": "openai/models", "version": "2026-10-23", "change_type": "breaking", "breaking": true, @@ -497,8 +497,8 @@ }, { "id": 26, - "fingerprint": "sha256:e8f619b1367f98f14d21392595abb6ecaeb7cc5aa04d7d3fa9318407f4af2b1f", - "api": "openai-models", + "fingerprint": "sha256:e363ee6a9fae0c10ff5e99b538929cb5fb8df270659832f5dfca1c193f54a6ec", + "api": "openai/models", "version": "2026-10-23", "change_type": "breaking", "breaking": true, @@ -516,8 +516,8 @@ }, { "id": 27, - "fingerprint": "sha256:89d91a7ec88dd9ad6b51f5d1eb1f77071cd7de7f7bfe2c52f41ed1b4a02e97ca", - "api": "openai-models", + "fingerprint": "sha256:059635ab8cb64b86d7650d4d42358d1df622089f98660b185409f348314f71b7", + "api": "openai/models", "version": "2026-10-23", "change_type": "breaking", "breaking": true, @@ -536,8 +536,8 @@ }, { "id": 28, - "fingerprint": "sha256:0d59189db33469b6118d40b1579c4089b30bfd296989ef5530b0af2525b54d78", - "api": "openai-models", + "fingerprint": "sha256:21bc5747c723b0cfeca2e75de8d84ef25dd917f07c6a2ac265e2c357a8acf249", + "api": "openai/models", "version": "2026-10-23", "change_type": "breaking", "breaking": true, @@ -556,8 +556,8 @@ }, { "id": 29, - "fingerprint": "sha256:01dd3828678189ac6cdfa4d5d9b25c49cc81067f90b211afc0283bcf90eac9f2", - "api": "openai-models", + "fingerprint": "sha256:a6aa8b28c72878f6c9e1ac51de793db65b5c56ce74e868cb0f0a662f1feda5b2", + "api": "openai/models", "version": "2026-10-23", "change_type": "breaking", "breaking": true, @@ -576,8 +576,8 @@ }, { "id": 30, - "fingerprint": "sha256:c81454c4dfd092f9d68a5240d0304bb9a78a623e08a446adbf58877906624284", - "api": "openai-models", + "fingerprint": "sha256:cd2490b99479131812970751179d5b2d096f418b46c7dcf29a82fa5af87cbadc", + "api": "openai/models", "version": "2026-10-23", "change_type": "breaking", "breaking": true, @@ -596,8 +596,8 @@ }, { "id": 31, - "fingerprint": "sha256:a7d99c56423521bfdd1994d830eb98ed9eadb95ba4d914e5ac6e7cc3336d4768", - "api": "openai-models", + "fingerprint": "sha256:ae0f2cf43e75ed043a653886b7978c010d5b195b1b4be4609d7a2b080b29c348", + "api": "openai/models", "version": "2026-07-23", "change_type": "breaking", "breaking": true, @@ -616,8 +616,8 @@ }, { "id": 32, - "fingerprint": "sha256:ca9d0a7234b4d5f8b9fde6059522d24b6fec292d0ec596aaad25f5c4653c6f43", - "api": "openai-models", + "fingerprint": "sha256:f64b3b40fa81e5b72254b5d7a165b0be6936f6ee31963e69e93a6cd2c4b17905", + "api": "openai/models", "version": "2026-07-23", "change_type": "breaking", "breaking": true, @@ -636,8 +636,8 @@ }, { "id": 33, - "fingerprint": "sha256:2b70c42f6edc749874d81ad5179b6ec024e14071e1e223522a0d0d308e120b96", - "api": "openai-models", + "fingerprint": "sha256:3184eaa1b6321186722ddf12d85c295ca6732c56325354c3c265a430d2d51414", + "api": "openai/models", "version": "2026-07-23", "change_type": "breaking", "breaking": true, @@ -656,8 +656,8 @@ }, { "id": 34, - "fingerprint": "sha256:2c77ece4681f5c6a00ee2ab7d758ee2b117608730e84bd6634de019def746fd5", - "api": "openai-models", + "fingerprint": "sha256:fd572c9b7dae1089003abd9a293d105bf70673081d4d878fb74135e17062ac02", + "api": "openai/models", "version": "2026-07-23", "change_type": "breaking", "breaking": true, @@ -676,8 +676,8 @@ }, { "id": 35, - "fingerprint": "sha256:f36568905d53276d44f4d9098a3c1eb188b1ba2b72fb7cc0e22d76cd226f59e9", - "api": "openai-models", + "fingerprint": "sha256:33518065dd3aa5c749949289dd72055b6fdb79f3835073b34a412b2e451c93d0", + "api": "openai/models", "version": "2026-07-23", "change_type": "breaking", "breaking": true, @@ -696,8 +696,8 @@ }, { "id": 36, - "fingerprint": "sha256:dfd970dc0f07fb5070dcff7e58b4563e823c1d4e1bb7cc5ea2b463c2dd39118a", - "api": "openai-models", + "fingerprint": "sha256:40d04868cd14e2aff7523f717367a5a6632542015a489c31b27f9b85aae3052c", + "api": "openai/models", "version": "2026-07-23", "change_type": "breaking", "breaking": true, @@ -716,8 +716,8 @@ }, { "id": 37, - "fingerprint": "sha256:f762416989e9e7631f165724833a191eda5ed1137207de696c9f9e9243cd7927", - "api": "openai-models", + "fingerprint": "sha256:ff2bbf4f9bb9231f9b4a5603899c0fc752f6a37f6e26a5c7e1fe5790f409ca48", + "api": "openai/models", "version": "2026-07-23", "change_type": "breaking", "breaking": true, @@ -736,8 +736,8 @@ }, { "id": 38, - "fingerprint": "sha256:43124e10c999e062a69b7b8b1d2dbd4c077ce160376e46c6343623cccc3848a4", - "api": "openai-models", + "fingerprint": "sha256:362e7e03afadd59d0cdbfff7e736e0f735ae9eea79fe5720bf920bfceb62162a", + "api": "openai/models", "version": "2026-07-23", "change_type": "breaking", "breaking": true, @@ -756,8 +756,8 @@ }, { "id": 39, - "fingerprint": "sha256:126ac994f3aa3ad3c09c156bcdf5bc718745f4a5eb3446ade01fd9763c78c6d4", - "api": "openai-models", + "fingerprint": "sha256:af71610f01e6ddf5b3afb5d282bf8946761ae2b998b2a2b331e222fc56c7ca74", + "api": "openai/models", "version": "2026-07-23", "change_type": "breaking", "breaking": true, @@ -776,8 +776,8 @@ }, { "id": 40, - "fingerprint": "sha256:64f6c89efb82a96dcd2ea6eb444532e2014fe58abeb714571799e64446d1d298", - "api": "openai-models", + "fingerprint": "sha256:f24c2a080eba5b89e6ea591af12a14645c80791266b45856420396ffd532f939", + "api": "openai/models", "version": "2026-07-23", "change_type": "breaking", "breaking": true, @@ -796,8 +796,8 @@ }, { "id": 41, - "fingerprint": "sha256:490b8746c969a8c57b52c5703c0cf9904d329d76cbe46d5cd2910e608084e512", - "api": "openai-models", + "fingerprint": "sha256:0e2a5ba7b05b9c093526bdf9afcabf862d9f31e84e42a4ba14b159838ecd880a", + "api": "openai/models", "version": "2026-07-23", "change_type": "breaking", "breaking": true, @@ -816,8 +816,8 @@ }, { "id": 42, - "fingerprint": "sha256:dde88b1c5c95adc94870279136f242a0fe034ef61cbcb0508185c603f6af719e", - "api": "openai-models", + "fingerprint": "sha256:c6b498786a70cce3450693d63d40983af1593a32ef9dd1dfdd5d8bd36922ca58", + "api": "openai/models", "version": "2026-07-23", "change_type": "breaking", "breaking": true, @@ -836,8 +836,8 @@ }, { "id": 43, - "fingerprint": "sha256:c414f177cfa703eb48624f92ef7a5b26c3161649f4e880766deb2e3e4bdd7383", - "api": "openai-models", + "fingerprint": "sha256:1bb911d293d7d2dbd20f2a89a97d9c3fab308d0bbff74bfea2d220a8e3fc1f07", + "api": "openai/models", "version": "2026-07-23", "change_type": "breaking", "breaking": true, @@ -856,8 +856,8 @@ }, { "id": 44, - "fingerprint": "sha256:4c57ce2ffdb86f2c2d7b6b9019efafa40b560b0126112cdc524770f7d65ee8cb", - "api": "openai-models", + "fingerprint": "sha256:a56b2eb3fce5c64b1981cb90610e8d3eb4f4f5917203b5b2d36d574de381c171", + "api": "openai/models", "version": "2026-07-23", "change_type": "breaking", "breaking": true, @@ -876,8 +876,8 @@ }, { "id": 45, - "fingerprint": "sha256:10ffc1a4720af9fc00d34d0d25a1717c154e1582e21fc5609084a703f74f8410", - "api": "openai-models", + "fingerprint": "sha256:e92ab5f3acdea6243818e8cc5645187cd71ac3ea985bc7a0900f8b856b50c923", + "api": "openai/models", "version": "2026-07-23", "change_type": "breaking", "breaking": true, @@ -896,8 +896,8 @@ }, { "id": 46, - "fingerprint": "sha256:537f3ede89cbedfcd88c69705210766610f288f2f946a7d09d5efb180b667ce7", - "api": "openai-models", + "fingerprint": "sha256:22c3df936ace8a0652431ca2a769dd8b039404c588b4c7f911dabd1d64e770b0", + "api": "openai/models", "version": "2026-02-17", "change_type": "breaking", "breaking": true, @@ -916,8 +916,8 @@ }, { "id": 47, - "fingerprint": "sha256:bcf6128e377c8d7f1dbedec1b6ad6002cf11a67561eceab7e40a98f88a937c52", - "api": "openai-models", + "fingerprint": "sha256:e2b44aa8420f408ceab29fb272f2e0f2baec9893a04c62f93688995ed53481c8", + "api": "openai/models", "version": "2026-02-12", "change_type": "breaking", "breaking": true, @@ -936,8 +936,8 @@ }, { "id": 48, - "fingerprint": "sha256:d4827e4f335eaac69ad1df195901c290acf963f0d6fdc9163c151439049ff26b", - "api": "openai-models", + "fingerprint": "sha256:298d52e2df997a412541c04406569482b54cc7b2736b7a54b64a47636ee5adac", + "api": "openai/models", "version": "2026-09-28", "change_type": "breaking", "breaking": true, @@ -956,8 +956,8 @@ }, { "id": 49, - "fingerprint": "sha256:d4ac9adae612e7b32462578d10fffc3f8c60801069e7b453948f95018626b755", - "api": "openai-models", + "fingerprint": "sha256:6e31004123e3abadcfd61472f45a91f584a5216750debd24a7893c1e3f1d74be", + "api": "openai/models", "version": "2026-09-28", "change_type": "breaking", "breaking": true, @@ -976,8 +976,8 @@ }, { "id": 50, - "fingerprint": "sha256:d6b036197bebb4d320f56fbb1b9703dfb826aacb44015558f6db69f4b49f8d45", - "api": "openai-models", + "fingerprint": "sha256:ce07a31125e454c6347940c57d9f3954c1464e7c4d115b9e613f608fc311fd39", + "api": "openai/models", "version": "2025-07-28", "change_type": "breaking", "breaking": true, @@ -996,8 +996,8 @@ }, { "id": 51, - "fingerprint": "sha256:cbfe4a6c507234baa08fe888d106b0315094568d4c037c51ff4088a7b2cf5a70", - "api": "openai-models", + "fingerprint": "sha256:df9d790a772a62b909bf66d840de74633c2a1389f66cca3ba5bda96343b237eb", + "api": "openai/models", "version": "2025-10-27", "change_type": "breaking", "breaking": true, @@ -1016,8 +1016,8 @@ }, { "id": 52, - "fingerprint": "sha256:a31c2dbbc2b61b192a3f7c600b930258a92054516e289e11fdfd9aeae4ece698", - "api": "openai-models", + "fingerprint": "sha256:47cf31bd0a2dc60fd9bbdce8cc286426e2cc28baebd2072c5c1bfce1e8108a40", + "api": "openai/models", "version": "2025-07-14", "change_type": "breaking", "breaking": true, @@ -1036,8 +1036,8 @@ }, { "id": 53, - "fingerprint": "sha256:981faa711b568aba0c1a83997c9344c09a00313f10c721d06477101ba4fe6bc6", - "api": "openai-models", + "fingerprint": "sha256:9ca7706bae32fba43a64b7089716eb87a6b90c91b15aaf6b32b120e3f6399a79", + "api": "openai/models", "version": "2025-06-06", "change_type": "breaking", "breaking": true, @@ -1056,8 +1056,8 @@ }, { "id": 54, - "fingerprint": "sha256:3a21d230a15dc0d80a4d49753c88cc14540c3ffeda0f23aa57db6fbf742f4d0a", - "api": "openai-models", + "fingerprint": "sha256:72ccffb5565f02b44b1f0f106fbfe718533126191db0ec66fa622b3510a45247", + "api": "openai/models", "version": "2025-06-06", "change_type": "breaking", "breaking": true, @@ -1076,8 +1076,8 @@ }, { "id": 55, - "fingerprint": "sha256:6af617bed4ade27661a14252e84fe3d493152285c673df7847f32ce2343b526d", - "api": "openai-models", + "fingerprint": "sha256:e3b22f3e67667c12321d23412ea6c1b2f98ef44d345f2b0ca173fcb6353037ee", + "api": "openai/models", "version": "2025-06-06", "change_type": "breaking", "breaking": true, @@ -1096,8 +1096,8 @@ }, { "id": 56, - "fingerprint": "sha256:a4b36dbb16c42d2abaf0e83b491b7d3253d5ae86ab88617be69dff190bbdc3eb", - "api": "openai-models", + "fingerprint": "sha256:1bd4a6f96c1537c7f8cde0f2643a337c0497e994226bb3a88739f197ed57ba1e", + "api": "openai/models", "version": "2024-12-06", "change_type": "breaking", "breaking": true, @@ -1116,8 +1116,8 @@ }, { "id": 57, - "fingerprint": "sha256:34d631767f5ec467ba6d50f3c0ceae19b6e4557a1444079ae70005bfb38728ac", - "api": "openai-models", + "fingerprint": "sha256:23b7fa9ef60a7125375298ead1585c704724d03667dbeb24e6e23caa94b6be55", + "api": "openai/models", "version": "2024-12-06", "change_type": "breaking", "breaking": true, @@ -1136,8 +1136,8 @@ }, { "id": 58, - "fingerprint": "sha256:f1628b016c89c646af7b5899f831cfd1f14134691dfaa8a2b1073a12078509c8", - "api": "openai-models", + "fingerprint": "sha256:ea4d8ba55b674c1a828858251ff7506a9fcb5d229db0dddfc7cca370e063c148", + "api": "openai/models", "version": "2024-09-13", "change_type": "breaking", "breaking": true, @@ -1156,8 +1156,8 @@ }, { "id": 59, - "fingerprint": "sha256:986a2a4648ac8603c829df3890977fb6bf934df01254a817f8dfcc82a2a0040b", - "api": "openai-models", + "fingerprint": "sha256:e3a9e9a088427c22fae9b2199e34612bd62d03753de88defe42b55c0df16a17f", + "api": "openai/models", "version": "2024-09-13", "change_type": "breaking", "breaking": true, @@ -1176,8 +1176,8 @@ }, { "id": 60, - "fingerprint": "sha256:8277d56d92a81586e3eab30094661964e1c32212dd1eb14e1c7f620b362f4056", - "api": "openai-models", + "fingerprint": "sha256:18546ec0a58809196edb87d8141cfecd799cdc4dc50aba6314401318002aa002", + "api": "openai/models", "version": "2024-09-13", "change_type": "breaking", "breaking": true, diff --git a/plugins/eol/testdata/golden/salesforce.json b/plugins/notices/testdata/golden/salesforce.json similarity index 88% rename from plugins/eol/testdata/golden/salesforce.json rename to plugins/notices/testdata/golden/salesforce.json index 4d9140c..4d0c678 100644 --- a/plugins/eol/testdata/golden/salesforce.json +++ b/plugins/notices/testdata/golden/salesforce.json @@ -1,8 +1,8 @@ [ { "id": 1, - "fingerprint": "sha256:5712d5a3f809b2edd3032446bfe6a0a654eb113f1f7e0e80b0d673132dced685", - "api": "salesforce", + "fingerprint": "sha256:96a4bf95d203b442628962583c15c58ce031da50dfe37335ddde6269fb426feb", + "api": "salesforce/rest-api", "version": "31.0", "change_type": "deprecation", "breaking": false, @@ -21,8 +21,8 @@ }, { "id": 2, - "fingerprint": "sha256:d5cd04d4a65a7ba09f4a71e7c346a4be3309451212787016d5c614498b556516", - "api": "salesforce", + "fingerprint": "sha256:012c28a49c2340048dc090672525f2982c8f3f2dca395972738e7964b2d192b0", + "api": "salesforce/rest-api", "version": "32.0", "change_type": "deprecation", "breaking": false, @@ -41,8 +41,8 @@ }, { "id": 3, - "fingerprint": "sha256:c009d4f0635e311b34acfbb6696c6d2aacbcd7c102ebc56d13036044f10910bf", - "api": "salesforce", + "fingerprint": "sha256:1f2b8339e9ef0ff5c5febe23dc2a21908b8d5523c3116adcec7fb364d328ac94", + "api": "salesforce/rest-api", "version": "33.0", "change_type": "deprecation", "breaking": false, @@ -61,8 +61,8 @@ }, { "id": 4, - "fingerprint": "sha256:08ef4a0e2b7798dd6e15087bfc30505dd412de40c553d3617f3d4533730b3931", - "api": "salesforce", + "fingerprint": "sha256:3a0d271a4843c6933542538bcb8d6e8073e264f4fef985ae8ea45545a64c5079", + "api": "salesforce/rest-api", "version": "34.0", "change_type": "deprecation", "breaking": false, @@ -81,8 +81,8 @@ }, { "id": 5, - "fingerprint": "sha256:f8b44ec3074f7f9d2ea45e3d2e681dc7e0bfca83a3c046d188e90a63295c06bd", - "api": "salesforce", + "fingerprint": "sha256:b0f532972d7edeac88234c226f9d13aa739e22ccdb76d0c715cc9a983909ced4", + "api": "salesforce/rest-api", "version": "35.0", "change_type": "deprecation", "breaking": false, @@ -101,8 +101,8 @@ }, { "id": 6, - "fingerprint": "sha256:edc028b547f9ed0ec5559febeb2ea9a04eb681e4d53fd15fe98961d110fbe3d3", - "api": "salesforce", + "fingerprint": "sha256:df9e4eab6337c0b0ac95964aa2d55048c5010280fb695f5472639939d9cfaa2d", + "api": "salesforce/rest-api", "version": "36.0", "change_type": "deprecation", "breaking": false, @@ -121,8 +121,8 @@ }, { "id": 7, - "fingerprint": "sha256:a00a996c75520031b4df78d500f327f9b9c94706753f2e8beb8ec123ee3e37e1", - "api": "salesforce", + "fingerprint": "sha256:beb4c877840a1e54436cdec1b331ba770a018e50a459286d71198becdef92b80", + "api": "salesforce/rest-api", "version": "37.0", "change_type": "deprecation", "breaking": false, @@ -141,8 +141,8 @@ }, { "id": 8, - "fingerprint": "sha256:ae8c254aa2eeb784a0cda9eaafeedf617991223b3ebcdf6c12bfd56e496712f9", - "api": "salesforce", + "fingerprint": "sha256:0ac93a885e8f93f3d5a0c254f80a2f9d3cc342f0a42049cae8c0db64a66a1580", + "api": "salesforce/rest-api", "version": "38.0", "change_type": "deprecation", "breaking": false, @@ -161,8 +161,8 @@ }, { "id": 9, - "fingerprint": "sha256:5f738a2088c9e818c5da229746de80ff1966e94b454eddcd1ea7e2fb6323bb27", - "api": "salesforce", + "fingerprint": "sha256:d4e47848b8cce83fcd7a5bab59a04cd0c799fd677066634e5d2c158c01bf11d3", + "api": "salesforce/rest-api", "version": "39.0", "change_type": "deprecation", "breaking": false, @@ -181,8 +181,8 @@ }, { "id": 10, - "fingerprint": "sha256:01287da0f76665a83b6d2cf46f99ea4b189e3b5e4a3f1370d03e59da9928fc09", - "api": "salesforce", + "fingerprint": "sha256:0ad4bdfbe6fb425cf970046b57277acc27139d72d3fc671d9c8088622087b00d", + "api": "salesforce/rest-api", "version": "40.0", "change_type": "deprecation", "breaking": false, @@ -201,8 +201,8 @@ }, { "id": 11, - "fingerprint": "sha256:3196e696d971115984b011f675c6625471769a9bed370f39fa34697cabb2a568", - "api": "salesforce", + "fingerprint": "sha256:c4dca9562fd787bfba9d73d3d942cf9f86c4fa297950dae813ef45755fd9f422", + "api": "salesforce/rest-api", "version": "21.0", "change_type": "breaking", "breaking": true, @@ -221,8 +221,8 @@ }, { "id": 12, - "fingerprint": "sha256:b01efdc1068b028b253b16195c3a40220f2c38a47692b039c972ad860fd04aa5", - "api": "salesforce", + "fingerprint": "sha256:ce3136f63f99d74730d055a9ae0b9786b3cb09afda65e679ee7ca4f02f0bbb4f", + "api": "salesforce/rest-api", "version": "22.0", "change_type": "breaking", "breaking": true, @@ -241,8 +241,8 @@ }, { "id": 13, - "fingerprint": "sha256:6d416539f96a25434c34a311bbc0f5c946c07a9a2f87bcb3c58b04e0d47fb15f", - "api": "salesforce", + "fingerprint": "sha256:bcfef560d3295295df22bb0e1e23dbe2073f7ccdeca0af60939d7f473bc2d2a7", + "api": "salesforce/rest-api", "version": "23.0", "change_type": "breaking", "breaking": true, @@ -261,8 +261,8 @@ }, { "id": 14, - "fingerprint": "sha256:54e2b6dde407bf4e2cbe571daf71c7759c625b079c6e7fc9e0b9ed630745edcf", - "api": "salesforce", + "fingerprint": "sha256:9533ab4a1f46c424c9bb551eb7caaee1d30adabae3ef275fcfa9bfb321bcd273", + "api": "salesforce/rest-api", "version": "24.0", "change_type": "breaking", "breaking": true, @@ -281,8 +281,8 @@ }, { "id": 15, - "fingerprint": "sha256:0c4183136450ca1afccd23bf6e4e9f25f08f2a0470c55032e0724312b616a7e1", - "api": "salesforce", + "fingerprint": "sha256:479da007024f7c36ae3c0406e8fe5c438362b8f1c30d725833bd3e37d7b965ae", + "api": "salesforce/rest-api", "version": "25.0", "change_type": "breaking", "breaking": true, @@ -301,8 +301,8 @@ }, { "id": 16, - "fingerprint": "sha256:2f8518fb4d77876618e24c6848977e471825e305404f234c349b9af56e731078", - "api": "salesforce", + "fingerprint": "sha256:9d42c0cb78dd8add1cf01e74eadb1bb1b765c95e5bd201b6c003e83f8290386d", + "api": "salesforce/rest-api", "version": "26.0", "change_type": "breaking", "breaking": true, @@ -321,8 +321,8 @@ }, { "id": 17, - "fingerprint": "sha256:44ed65c3d55263ee40bdf9324715ad0b31c727f927a172a38cc0162bf796d325", - "api": "salesforce", + "fingerprint": "sha256:832dfa7fcacaf76ceac4b91e281458a87f0c8d3f973d1d53aac55026e4b1fb7b", + "api": "salesforce/rest-api", "version": "27.0", "change_type": "breaking", "breaking": true, @@ -341,8 +341,8 @@ }, { "id": 18, - "fingerprint": "sha256:3da22cdfd664c8f52ebb476cd278bfdeb460918c50d8b0184a542ce091fd72e8", - "api": "salesforce", + "fingerprint": "sha256:409dbd170c4aa71923824e95d9b458d1b88c37b255104a6c86dec67b8a100ac8", + "api": "salesforce/rest-api", "version": "28.0", "change_type": "breaking", "breaking": true, @@ -361,8 +361,8 @@ }, { "id": 19, - "fingerprint": "sha256:f3d260b9acef562eaf5f530d3a253176d878d7788bf827441745ee93b32c6787", - "api": "salesforce", + "fingerprint": "sha256:561d8e2e8c4ffee2fd071b62d03f8d7d37fa21ec0c9faf9f3efde1943a4fd83c", + "api": "salesforce/rest-api", "version": "29.0", "change_type": "breaking", "breaking": true, @@ -381,8 +381,8 @@ }, { "id": 20, - "fingerprint": "sha256:01ccee5cbdd725ba99be6328151e1366be0efa49d6431a3b0e93bb09a3676131", - "api": "salesforce", + "fingerprint": "sha256:a8f3b6a7ef22d26b047ffa1beeb398afcd5c3d73af7263d1ddfd60796b18f45f", + "api": "salesforce/rest-api", "version": "30.0", "change_type": "breaking", "breaking": true, @@ -401,8 +401,8 @@ }, { "id": 21, - "fingerprint": "sha256:e9867faae1b6920e6c39cedeaf143997102f9a91d9515a442e1cc4f9cffae820", - "api": "salesforce", + "fingerprint": "sha256:0fcc2e13469764fdb95343e3c97aa15232f5a46ba6e09e091ed1618d22858c6b", + "api": "salesforce/rest-api", "version": "7.0", "change_type": "breaking", "breaking": true, @@ -421,8 +421,8 @@ }, { "id": 22, - "fingerprint": "sha256:d35aebdfad2134fd75a451817b2a347633eed5d94a53e96b1665bb800d557863", - "api": "salesforce", + "fingerprint": "sha256:1836f945f91e9c4bfd6393341729d5c795894db8988d5c53af017f902e529b2e", + "api": "salesforce/rest-api", "version": "8.0", "change_type": "breaking", "breaking": true, @@ -441,8 +441,8 @@ }, { "id": 23, - "fingerprint": "sha256:f5af0d2c541f41c371b8dbfe80cb9abeedb7758c6fd8a79d0251c1b763578549", - "api": "salesforce", + "fingerprint": "sha256:4aca007478f276b46117b3c9f4aa5a289cebd818e69e3e83dfacb3e1583d1072", + "api": "salesforce/rest-api", "version": "9.0", "change_type": "breaking", "breaking": true, @@ -461,8 +461,8 @@ }, { "id": 24, - "fingerprint": "sha256:1975b2eb2a035e983a81cfe32fa432edaa62ec0ab7b1d7aea1b542f194ca6170", - "api": "salesforce", + "fingerprint": "sha256:cce9cf0404b112076ffd3814efaa70238c942420a9893a1fc6a93250904a75c6", + "api": "salesforce/rest-api", "version": "10.0", "change_type": "breaking", "breaking": true, @@ -481,8 +481,8 @@ }, { "id": 25, - "fingerprint": "sha256:39d1421f1d4675f662bd0d3e984fd813de2ba740438c09d9ecdd96f9c5e517cc", - "api": "salesforce", + "fingerprint": "sha256:2314981ead2820e1523bf7ca29b8cefde9b445c3a5ddaaf501ffbeabf56a8a99", + "api": "salesforce/rest-api", "version": "11.0", "change_type": "breaking", "breaking": true, @@ -501,8 +501,8 @@ }, { "id": 26, - "fingerprint": "sha256:9a3cb32fac90139da92e6e9de3e67261309654ee5ee2fc0f149133af811ad96e", - "api": "salesforce", + "fingerprint": "sha256:8acca78bbf8ce6adb5d16d7b767a36c79b1ad32f2e3a00c09e29b41e3b061cc6", + "api": "salesforce/rest-api", "version": "12.0", "change_type": "breaking", "breaking": true, @@ -521,8 +521,8 @@ }, { "id": 27, - "fingerprint": "sha256:ac37dc2324273bc9523c0ff620f7de402ad0e6350d930c9f6f2d4c3644e2a956", - "api": "salesforce", + "fingerprint": "sha256:759fd344f34b106ccd906a70c2d0830f0e85ecaf1e5058a9c4d2be70b317874d", + "api": "salesforce/rest-api", "version": "13.0", "change_type": "breaking", "breaking": true, @@ -541,8 +541,8 @@ }, { "id": 28, - "fingerprint": "sha256:4364f685eb1cb5b90db0a979bc329dc7df0a03ca0e85626c981a5119f0acdd41", - "api": "salesforce", + "fingerprint": "sha256:3900ae246cbcde03edddb7b23644c2219e0db3b476ed1369ef8b9457f87e05e8", + "api": "salesforce/rest-api", "version": "14.0", "change_type": "breaking", "breaking": true, @@ -561,8 +561,8 @@ }, { "id": 29, - "fingerprint": "sha256:c26fd727091b806bd34d1761e4b7801d24256e7567e9c65dd41171c6e3b7b1ff", - "api": "salesforce", + "fingerprint": "sha256:a54e091c042d0b6207daae68c86fff56a610db97f3c5efed453eb39120e10cc5", + "api": "salesforce/rest-api", "version": "15.0", "change_type": "breaking", "breaking": true, @@ -581,8 +581,8 @@ }, { "id": 30, - "fingerprint": "sha256:0241eda116305ecfd420fa6f42900e4db478297db732a21beff08b1e21ae96b6", - "api": "salesforce", + "fingerprint": "sha256:a8f6e65b0994234b81fd370d6647ba1a478206398c27967aa3d2e59ce2fbee8c", + "api": "salesforce/rest-api", "version": "16.0", "change_type": "breaking", "breaking": true, @@ -601,8 +601,8 @@ }, { "id": 31, - "fingerprint": "sha256:b95ba1dc0afc72b21b40e934ec2d8549da5bf406a5cae9feaba94e7a0fb7ec63", - "api": "salesforce", + "fingerprint": "sha256:7ca796235cd5f96170640fdc6c381cf5c08822d860d2baf8e13c59f03070c76b", + "api": "salesforce/rest-api", "version": "17.0", "change_type": "breaking", "breaking": true, @@ -621,8 +621,8 @@ }, { "id": 32, - "fingerprint": "sha256:44912e7a1618ccf57e957a8219609236f6757381eb4f590c66f95978fffe5af2", - "api": "salesforce", + "fingerprint": "sha256:841b996096bd90d89db132bd96fd8386913fc2f05f26c8c268b550c883d4f506", + "api": "salesforce/rest-api", "version": "18.0", "change_type": "breaking", "breaking": true, @@ -641,8 +641,8 @@ }, { "id": 33, - "fingerprint": "sha256:94cefbc9eb19323ce7fcf84fc0ee7b2f0a9064046959c52c64bfa755e3ba13c6", - "api": "salesforce", + "fingerprint": "sha256:a3f3f6021a40ab52092b92f59b1ced42891e298a6b75486c93971cc1a63feaf9", + "api": "salesforce/rest-api", "version": "19.0", "change_type": "breaking", "breaking": true, @@ -661,8 +661,8 @@ }, { "id": 34, - "fingerprint": "sha256:8f15f28dabaee09688f5588d5c939c72053f0c6002bb4c239c48eb22ba20e3cc", - "api": "salesforce", + "fingerprint": "sha256:718d1a6a17fe65fd7a7cd327ed6167f20f99f9ac87c05bda663b878684cd3e3c", + "api": "salesforce/rest-api", "version": "20.0", "change_type": "breaking", "breaking": true, diff --git a/plugins/notices/versions_test.go b/plugins/notices/versions_test.go new file mode 100644 index 0000000..a3691b4 --- /dev/null +++ b/plugins/notices/versions_test.go @@ -0,0 +1,110 @@ +package notices + +import ( + "context" + "fmt" + "os" + "strings" + "testing" + "time" + + "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/core/versions" + "github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire" +) + +// A year of a living page from its Web Archive captures alone: four +// captures, two of them the same content, are three versions; reading each +// and extracting each consecutive pair gives every retirement once, each +// citing the capture where it first appeared. Nothing reaches the network: +// the CDX answer and the captures are served from memory. +func TestBackfillAYearFromCaptures(t *testing.T) { + full, err := os.ReadFile("retire/testdata/openai-deprecations.md") + if err != nil { + t.Fatal(err) + } + lines := strings.SplitAfter(string(full), "\n") + header := strings.Join(lines[:2], "") + // The page as it grew: the oldest capture has the sections from the + // 2026-04-22 announcement down, the next adds three, the newest is today's. + older := header + strings.Join(lines[34:], "") + middle := header + strings.Join(lines[10:], "") + pg := retire.OpenAI + capture := func(ts string) string { return "https://web.archive.org/web/" + ts + "id_/" + pg.URL } + captures := map[string]string{ + capture("20250115000000"): older, + capture("20250601000000"): middle, + capture("20251201000000"): string(full), + } + cdx := fmt.Sprintf(`[["timestamp","original","digest"], +["20250115000000",%[1]q,"A"],["20250301000000",%[1]q,"A"],["20250601000000",%[1]q,"B"],["20251201000000",%[1]q,"C"]]`, pg.URL) + env := plugin.Env{ + Baselines: kittest.NewMem(), + Now: func() time.Time { return kittest.Clock }, + Get: func(_ context.Context, u string) ([]byte, error) { + if strings.HasPrefix(u, versions.Wayback+"/cdx/search/cdx?") { + return []byte(cdx), nil + } + if body, ok := captures[u]; ok { + return []byte(body), nil + } + t.Errorf("fetched %s", u) + return nil, fmt.Errorf("no saved copy of %s", u) + }, + } + ctx := context.Background() + p := Plugin{Page: pg} + vs, err := p.ListVersions(ctx, env) + if err != nil { + t.Fatal(err) + } + if len(vs) != 3 || vs[0].ID != "2025-01-15" || vs[2].ID != "2025-12-01" { + t.Fatalf("versions %v", vs) + } + var snaps []plugin.Snapshot + for _, v := range vs { + s, err := p.ReadAt(ctx, env, v) + if err != nil { + t.Fatal(err) + } + snaps = append(snaps, s) + } + firstSeen := map[string]string{} // fingerprint -> the capture it's cited from + for i := range snaps { + var from plugin.Snapshot + if i > 0 { + from = snaps[i-1] + } + res, err := p.Extract(ctx, env, from, snaps[i]) + if err != nil || len(res.Rejected) > 0 { + t.Fatalf("%v %v", err, res.Rejected) + } + if len(res.Events) == 0 { + t.Errorf("%s: no new retirement", vs[i].ID) + } + for _, e := range res.Events { + if _, dup := firstSeen[e.Fingerprint]; dup { + t.Errorf("%s: %s again", vs[i].ID, e.Subject.Name) + } + if e.SourceURL != vs[i].URL { + t.Errorf("%s cites %s, want %s", e.Subject.Name, e.SourceURL, vs[i].URL) + } + firstSeen[e.Fingerprint] = e.SourceURL + } + } + // Today's page, read in one go, holds every retirement the history found + // (a retirement can only change its fingerprint, never vanish). + today, err := p.Extract(ctx, env, plugin.Snapshot{}, snaps[2]) + if err != nil { + t.Fatal(err) + } + for _, e := range today.Events { + if _, ok := firstSeen[e.Fingerprint]; !ok { + t.Errorf("%s on today's page, never seen in the history", e.Subject.Name) + } + } + if strings.Contains(firstSeen[today.Events[0].Fingerprint], "20250115") { + t.Errorf("today's newest retirement is cited from the oldest capture") + } +} diff --git a/plugins/openapi/adapter/adapter.go b/plugins/openapi/adapter/adapter.go index 871d23e..32349ef 100644 --- a/plugins/openapi/adapter/adapter.go +++ b/plugins/openapi/adapter/adapter.go @@ -22,7 +22,7 @@ type Spec struct { // Adapter is the shape every source adapter follows. Community and private // adapters implement the same three methods. type Adapter interface { - API() string // lowercase slug, e.g. "stripe" + API() string // the source id events carry, e.g. "stripe/api" LatestTag(ctx context.Context) (string, error) // newest release tag Fetch(ctx context.Context, tag string) (Spec, error) // spec for that exact tag } diff --git a/plugins/openapi/adapter/algolia.go b/plugins/openapi/adapter/algolia.go index 37a70d0..b49cff2 100644 --- a/plugins/openapi/adapter/algolia.go +++ b/plugins/openapi/adapter/algolia.go @@ -35,7 +35,7 @@ type Algolia struct { var _ Adapter = Algolia{} -func (a Algolia) API() string { return "algolia-" + a.Spec } +func (a Algolia) API() string { return "algolia/" + a.Spec + "-api" } var algoliaTag = regexp.MustCompile(`^released-(\d{4}-\d{2}-\d{2})(-[0-9a-f]+)?$`) @@ -43,24 +43,15 @@ 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, github.Headers()) + tags, err := algoliaTags(ctx) if err != nil { - return "", fmt.Errorf("listing algolia's release tags: %w", err) - } - var refs []struct { - Ref string `json:"ref"` - } - if err := json.Unmarshal(body, &refs); err != nil { - return "", fmt.Errorf("parsing github's tag refs: %w", err) + return "", err } var day string var sameDay []string - for _, r := range refs { - tag := strings.TrimPrefix(r.Ref, "refs/tags/") + for _, tag := range tags { m := algoliaTag.FindStringSubmatch(tag) switch { - case m == nil: - continue case m[1] > day: day, sameDay = m[1], []string{tag} case m[1] == day: @@ -87,6 +78,27 @@ func (a Algolia) LatestTag(ctx context.Context) (string, error) { return latest, nil } +// algoliaTags are every release tag, in the listing's order. +func algoliaTags(ctx context.Context) ([]string, error) { + body, err := fetch.Get(ctx, algoliaRefsURL, github.Headers()) + if err != nil { + return nil, fmt.Errorf("listing algolia's release tags: %w", err) + } + var refs []struct { + Ref string `json:"ref"` + } + if err := json.Unmarshal(body, &refs); err != nil { + return nil, fmt.Errorf("parsing github's tag refs: %w", err) + } + var tags []string + for _, r := range refs { + if tag := strings.TrimPrefix(r.Ref, "refs/tags/"); algoliaTag.MatchString(tag) { + tags = append(tags, tag) + } + } + return tags, nil +} + func algoliaCommitDate(ctx context.Context, tag string) (time.Time, error) { _, date, err := github.Commit(ctx, github.Get, fmt.Sprintf(algoliaCommitURL, tag)) if err != nil { diff --git a/plugins/openapi/adapter/algolia_test.go b/plugins/openapi/adapter/algolia_test.go index 4c75673..80432a2 100644 --- a/plugins/openapi/adapter/algolia_test.go +++ b/plugins/openapi/adapter/algolia_test.go @@ -93,7 +93,7 @@ func TestAlgoliaFetch(t *testing.T) { if spec.Version != "2025-04-01" || string(spec.Content) != want || !strings.HasSuffix(spec.SourceURL, "/released-2025-04-01-c19ee6afb/search.yml") { t.Errorf("got %q %s %s", spec.Version, spec.Content, spec.SourceURL) } - if (Algolia{Spec: "search"}).API() != "algolia-search" { + if (Algolia{Spec: "search"}).API() != "algolia/search-api" { t.Error("api slug") } for _, tag := range []string{"v4.0.0", "released-2025-04-01-c19ee6afb-x", "released-xx"} { diff --git a/plugins/openapi/adapter/appwrite.go b/plugins/openapi/adapter/appwrite.go index c458936..837c2cf 100644 --- a/plugins/openapi/adapter/appwrite.go +++ b/plugins/openapi/adapter/appwrite.go @@ -28,7 +28,7 @@ var appwriteMethods = []string{"get", "put", "post", "delete", "patch", "head", // Appwrite adapts Appwrite's REST API spec in appwrite/specs (BSD-3-Clause) // for the openapi plugin. The repo has one directory per server minor, // specs/.x/, and no tags or releases (checked 2026-11-19), so a tag here -// is a commit SHA: the newest minor's spec at that commit. To replay an older +// is a commit SHA: the newest minor's spec at that commit. To read an older // minor, a tag can name its directory, "1.8.x@". // // A directory holds one of two layouts: @@ -59,7 +59,7 @@ type Appwrite struct { var _ Adapter = Appwrite{} -func (Appwrite) API() string { return "appwrite" } +func (Appwrite) API() string { return "appwrite/api" } func (a Appwrite) api(path string) string { return cmp.Or(a.APIBase, "https://api.github.com") + "/repos/appwrite/specs" + path diff --git a/plugins/openapi/adapter/convex.go b/plugins/openapi/adapter/convex.go index fe0e020..75ca537 100644 --- a/plugins/openapi/adapter/convex.go +++ b/plugins/openapi/adapter/convex.go @@ -37,7 +37,7 @@ type Convex struct{} var _ Adapter = Convex{} -func (Convex) API() string { return "convex" } +func (Convex) API() string { return "convex/deployment-api" } // LatestTag is the SHA of the newest commit that changed the spec. func (Convex) LatestTag(ctx context.Context) (string, error) { diff --git a/plugins/openapi/adapter/datadog.go b/plugins/openapi/adapter/datadog.go index 8a5f9d3..c25fded 100644 --- a/plugins/openapi/adapter/datadog.go +++ b/plugins/openapi/adapter/datadog.go @@ -27,7 +27,7 @@ type Datadog struct{} var _ Adapter = Datadog{} -func (Datadog) API() string { return "datadog" } +func (Datadog) API() string { return "datadog/api" } // LatestTag asks GitHub for the client's newest release tag, e.g. "2.62.0". // Datadog has no release process of its own to ask instead: the spec has no diff --git a/plugins/openapi/adapter/elasticsearch.go b/plugins/openapi/adapter/elasticsearch.go index e14b571..288d249 100644 --- a/plugins/openapi/adapter/elasticsearch.go +++ b/plugins/openapi/adapter/elasticsearch.go @@ -5,6 +5,7 @@ import ( "encoding/json" "fmt" "regexp" + "slices" "strconv" "strings" @@ -37,7 +38,7 @@ type Elasticsearch struct{} var _ Adapter = Elasticsearch{} -func (Elasticsearch) API() string { return "elasticsearch" } +func (Elasticsearch) API() string { return "elastic/elasticsearch-api" } var ( esRelease = regexp.MustCompile(`^v(\d+)\.(\d+)\.(\d+)$`) @@ -49,9 +50,23 @@ 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) { + newest, branches, err := esMinors(ctx) + if err != nil { + return "", err + } + want := fmt.Sprintf("%d.%d", newest[0], newest[1]) + if slices.Contains(branches, want) { + return want, nil + } + return "", fmt.Errorf("elasticsearch %s is released, but elasticsearch-specification has no %s branch", want, want) +} + +// esMinors is the newest minor Elastic has released and every minor branch +// ("9.5") of elasticsearch-specification. +func esMinors(ctx context.Context) (newest [2]int, branches []string, err error) { body, err := fetch.Get(ctx, esReleasesURL, github.Headers()) if err != nil { - return "", fmt.Errorf("listing elasticsearch releases: %w", err) + return newest, nil, fmt.Errorf("listing elasticsearch releases: %w", err) } var releases []struct { Tag string `json:"tag_name"` @@ -59,9 +74,9 @@ func (Elasticsearch) LatestTag(ctx context.Context) (string, error) { Draft bool `json:"draft"` } if err := json.Unmarshal(body, &releases); err != nil { - return "", fmt.Errorf("parsing github releases: %w", err) + return newest, nil, fmt.Errorf("parsing github releases: %w", err) } - newest := [2]int{-1, -1} + newest = [2]int{-1, -1} for _, r := range releases { m := esRelease.FindStringSubmatch(r.Tag) if m == nil || r.Prerelease || r.Draft { @@ -73,26 +88,25 @@ func (Elasticsearch) LatestTag(ctx context.Context) (string, error) { } } if newest[0] < 0 { - return "", fmt.Errorf("github lists no elasticsearch release") + return newest, nil, fmt.Errorf("github lists no elasticsearch release") } body, err = fetch.Get(ctx, esBranchesURL, github.Headers()) if err != nil { - return "", fmt.Errorf("listing elasticsearch-specification branches: %w", err) + return newest, nil, fmt.Errorf("listing elasticsearch-specification branches: %w", err) } var refs []struct { Ref string `json:"ref"` } if err := json.Unmarshal(body, &refs); err != nil { - return "", fmt.Errorf("parsing github branch refs: %w", err) + return newest, nil, fmt.Errorf("parsing github branch refs: %w", err) } - want := fmt.Sprintf("%d.%d", newest[0], newest[1]) for _, r := range refs { - if strings.TrimPrefix(r.Ref, "refs/heads/") == want { - return want, nil + if b := strings.TrimPrefix(r.Ref, "refs/heads/"); esBranch.MatchString(b) { + branches = append(branches, b) } } - return "", fmt.Errorf("elasticsearch %s is released, but elasticsearch-specification has no %s branch", want, want) + return newest, branches, nil } func atoi(s string) int { diff --git a/plugins/openapi/adapter/flagsmith.go b/plugins/openapi/adapter/flagsmith.go index 1c5c182..659b30c 100644 --- a/plugins/openapi/adapter/flagsmith.go +++ b/plugins/openapi/adapter/flagsmith.go @@ -33,7 +33,7 @@ type Flagsmith struct{} var _ Adapter = Flagsmith{} -func (Flagsmith) API() string { return "flagsmith" } +func (Flagsmith) API() string { return "flagsmith/api" } // LatestTag asks GitHub for Flagsmith's newest release tag, e.g. "v2.293.0". // Flagsmith tags a release on (almost) every merge to main via release-please, diff --git a/plugins/openapi/adapter/github.go b/plugins/openapi/adapter/github.go index f8c29f6..fa9d6b7 100644 --- a/plugins/openapi/adapter/github.go +++ b/plugins/openapi/adapter/github.go @@ -32,7 +32,7 @@ type GitHub struct{} var _ Adapter = GitHub{} -func (GitHub) API() string { return "github" } +func (GitHub) API() string { return "github/rest-api" } // LatestTag asks GitHub for every API version it currently supports and // returns the newest, by string order (the dates sort correctly as text). diff --git a/plugins/openapi/adapter/gitlab.go b/plugins/openapi/adapter/gitlab.go index b3ebb94..461ddf1 100644 --- a/plugins/openapi/adapter/gitlab.go +++ b/plugins/openapi/adapter/gitlab.go @@ -50,7 +50,7 @@ type GitLab struct { var _ Adapter = GitLab{} -func (GitLab) API() string { return "gitlab" } +func (GitLab) API() string { return "gitlab/rest-api" } // LatestTag is the highest stable release tag, e.g. "v19.5.5-ee". The tags API // sorts by version, but its handling of the "-ee" suffix and of release @@ -101,7 +101,7 @@ func (g GitLab) LatestTag(ctx context.Context) (string, error) { // (checked v18.11.0-ee and v19.0.0-ee, 2026-11-15), which can't tell two // releases apart. The bare version is also what a self-managed instance // reports and what patch-it's package gate can read; it refuses "v19.0.0-ee". -// A tag that isn't a release (a branch, for a replay) is its own version. +// A tag that isn't a release (a branch, read as a version) is its own version. func (g GitLab) Fetch(ctx context.Context, tag string) (Spec, error) { url := fmt.Sprintf(cmp.Or(g.SpecURLTemplate, gitlabSpecURLTemplate), tag) body, err := fetch.Get(ctx, url, nil) diff --git a/plugins/openapi/adapter/neon.go b/plugins/openapi/adapter/neon.go index b767b2b..1de323b 100644 --- a/plugins/openapi/adapter/neon.go +++ b/plugins/openapi/adapter/neon.go @@ -32,7 +32,7 @@ type Neon struct{} var _ Adapter = Neon{} -func (Neon) API() string { return "neon" } +func (Neon) API() string { return "neon/api" } // LatestTag is the SHA of the newest commit that changed the spec. func (Neon) LatestTag(ctx context.Context) (string, error) { diff --git a/plugins/openapi/adapter/planetscale.go b/plugins/openapi/adapter/planetscale.go index 5c83d61..3d77cf9 100644 --- a/plugins/openapi/adapter/planetscale.go +++ b/plugins/openapi/adapter/planetscale.go @@ -34,7 +34,7 @@ type PlanetScale struct { var _ Adapter = PlanetScale{} -func (PlanetScale) API() string { return "planetscale" } +func (PlanetScale) API() string { return "planetscale/api" } func (p PlanetScale) api(path string) string { return cmp.Or(p.APIBase, "https://api.github.com") + "/repos/" + planetscaleRepo + path diff --git a/plugins/openapi/adapter/sentry.go b/plugins/openapi/adapter/sentry.go index 4b8bda6..9db5510 100644 --- a/plugins/openapi/adapter/sentry.go +++ b/plugins/openapi/adapter/sentry.go @@ -51,7 +51,7 @@ type Sentry struct { var _ Adapter = Sentry{} -func (Sentry) API() string { return "sentry" } +func (Sentry) API() string { return "sentry/api" } func (s Sentry) api(path string) string { return cmp.Or(s.APIBase, "https://api.github.com") + path diff --git a/plugins/openapi/adapter/stripe.go b/plugins/openapi/adapter/stripe.go index 171f736..4c94628 100644 --- a/plugins/openapi/adapter/stripe.go +++ b/plugins/openapi/adapter/stripe.go @@ -29,7 +29,7 @@ type Stripe struct{} // Compile-time check that Stripe actually satisfies Adapter. var _ Adapter = Stripe{} -func (Stripe) API() string { return "stripe" } +func (Stripe) API() string { return "stripe/api" } // LatestTag asks GitHub for Stripe's newest openapi release tag, e.g. "v2468". func (Stripe) LatestTag(ctx context.Context) (string, error) { diff --git a/plugins/openapi/adapter/supabase.go b/plugins/openapi/adapter/supabase.go index bd4ab86..fc7291d 100644 --- a/plugins/openapi/adapter/supabase.go +++ b/plugins/openapi/adapter/supabase.go @@ -31,7 +31,7 @@ type Supabase struct{} var _ Adapter = Supabase{} -func (Supabase) API() string { return "supabase" } +func (Supabase) API() string { return "supabase/management-api" } // LatestTag is the SHA of the newest commit that changed the spec. func (Supabase) LatestTag(ctx context.Context) (string, error) { diff --git a/plugins/openapi/adapter/testdata/README.md b/plugins/openapi/adapter/testdata/README.md new file mode 100644 index 0000000..d24b82e --- /dev/null +++ b/plugins/openapi/adapter/testdata/README.md @@ -0,0 +1,18 @@ +# Recorded API responses + +The version-listing tests (`versions_test.go`) read these instead of the network. Each was recorded on 2026-11-20 from the public API named, then trimmed: only the fields the adapter reads are kept, and some lists are cut to a few entries, said per file. Nothing else is changed. + +| File | Recorded from | Trimmed to | +|---|---|---| +| `versions/github-versions.json` | `https://api.github.com/versions` | whole | +| `versions/gitlab-tags-1.json` | `https://gitlab.com/api/v4/projects/gitlab-org%2Fgitlab/repository/tags?order_by=version&sort=desc&per_page=100&page=1` | all 100 tags; `name` and `commit.created_at` | +| `versions/gitlab-tags-2.json` | the same, `page=2` | 14 tags (18.10.0, 18.10.1, 18.9.x, 18.1.4); same fields | +| `versions/es-releases.json` | `https://api.github.com/repos/elastic/elasticsearch/releases?per_page=100` | all 100; `tag_name`, `prerelease`, `draft` | +| `versions/es-branches.json` | `https://api.github.com/repos/elastic/elasticsearch-specification/git/matching-refs/heads/` | the minor branches, `main` and `gh-pages` (33 of 250) | +| `versions/sentry-api-releases.json` | `https://api.github.com/repos/getsentry/sentry/releases?per_page=100&page=1` | the 19 `api@` releases; `tag_name`, `draft`, `prerelease`, `published_at`, asset names | +| `versions/sentry-schema-releases.json` | `https://api.github.com/repos/getsentry/sentry-api-schema/releases` (pages 1-4) | 2.3.2 and 2.4.0; same fields | +| `versions/algolia-refs.json` | `https://api.github.com/repos/algolia/api-clients-automation/git/matching-refs/tags/released-` | 9 of 186 tags, five of them on two days with several releases | +| `versions/algolia-commit-*.json` | `https://api.github.com/repos/algolia/api-clients-automation/commits/` | `sha` and the committer date | +| `versions/appwrite-commits.json` | `https://api.github.com/repos/appwrite/specs/commits?path=specs&per_page=100&page=1` | the 40 newest commits; `sha`, `html_url`, the committer date | + +Licenses: these are API metadata (tag names, dates, SHAs), not the projects' content. diff --git a/plugins/openapi/adapter/testdata/versions/algolia-commit-released-2024-09-18-45edcd844.json b/plugins/openapi/adapter/testdata/versions/algolia-commit-released-2024-09-18-45edcd844.json new file mode 100644 index 0000000..467081e --- /dev/null +++ b/plugins/openapi/adapter/testdata/versions/algolia-commit-released-2024-09-18-45edcd844.json @@ -0,0 +1,8 @@ +{ + "commit": { + "committer": { + "date": "2024-09-18T12:31:40Z" + } + }, + "sha": "45edcd844ff3a8f79bf3d04f7a6ee35b40e57b84" +} diff --git a/plugins/openapi/adapter/testdata/versions/algolia-commit-released-2024-09-18-cc190fae3.json b/plugins/openapi/adapter/testdata/versions/algolia-commit-released-2024-09-18-cc190fae3.json new file mode 100644 index 0000000..ae87e58 --- /dev/null +++ b/plugins/openapi/adapter/testdata/versions/algolia-commit-released-2024-09-18-cc190fae3.json @@ -0,0 +1,8 @@ +{ + "commit": { + "committer": { + "date": "2024-09-18T19:37:12Z" + } + }, + "sha": "cc190fae3ddac7acbce990f38a1110f165520011" +} diff --git a/plugins/openapi/adapter/testdata/versions/algolia-commit-released-2024-09-19-6e91dbf55.json b/plugins/openapi/adapter/testdata/versions/algolia-commit-released-2024-09-19-6e91dbf55.json new file mode 100644 index 0000000..ae645d8 --- /dev/null +++ b/plugins/openapi/adapter/testdata/versions/algolia-commit-released-2024-09-19-6e91dbf55.json @@ -0,0 +1,8 @@ +{ + "commit": { + "committer": { + "date": "2024-09-19T13:16:52Z" + } + }, + "sha": "6e91dbf555623d6a35e1491903ffbf3fdd4273f7" +} diff --git a/plugins/openapi/adapter/testdata/versions/algolia-commit-released-2024-09-19-a62c27d3b.json b/plugins/openapi/adapter/testdata/versions/algolia-commit-released-2024-09-19-a62c27d3b.json new file mode 100644 index 0000000..1ac6684 --- /dev/null +++ b/plugins/openapi/adapter/testdata/versions/algolia-commit-released-2024-09-19-a62c27d3b.json @@ -0,0 +1,8 @@ +{ + "commit": { + "committer": { + "date": "2024-09-19T10:17:21Z" + } + }, + "sha": "a62c27d3bd51ca5e26f7d0cbd60a69e0b4408c9c" +} diff --git a/plugins/openapi/adapter/testdata/versions/algolia-commit-released-2024-09-19-e47df6533.json b/plugins/openapi/adapter/testdata/versions/algolia-commit-released-2024-09-19-e47df6533.json new file mode 100644 index 0000000..41513af --- /dev/null +++ b/plugins/openapi/adapter/testdata/versions/algolia-commit-released-2024-09-19-e47df6533.json @@ -0,0 +1,8 @@ +{ + "commit": { + "committer": { + "date": "2024-09-19T19:28:05Z" + } + }, + "sha": "e47df65330ddcc3c61293ac8da7c0e89feb14948" +} diff --git a/plugins/openapi/adapter/testdata/versions/algolia-refs.json b/plugins/openapi/adapter/testdata/versions/algolia-refs.json new file mode 100644 index 0000000..f68d785 --- /dev/null +++ b/plugins/openapi/adapter/testdata/versions/algolia-refs.json @@ -0,0 +1,29 @@ +[ + { + "ref": "refs/tags/released-2023-08-22" + }, + { + "ref": "refs/tags/released-2023-08-29" + }, + { + "ref": "refs/tags/released-2024-09-18-45edcd844" + }, + { + "ref": "refs/tags/released-2024-09-18-cc190fae3" + }, + { + "ref": "refs/tags/released-2024-09-19-6e91dbf55" + }, + { + "ref": "refs/tags/released-2024-09-19-a62c27d3b" + }, + { + "ref": "refs/tags/released-2024-09-19-e47df6533" + }, + { + "ref": "refs/tags/released-2026-11-10-8d91e3d8a3" + }, + { + "ref": "refs/tags/released-2026-11-17-31c309fe2a" + } +] diff --git a/plugins/openapi/adapter/testdata/versions/appwrite-commits.json b/plugins/openapi/adapter/testdata/versions/appwrite-commits.json new file mode 100644 index 0000000..8131340 --- /dev/null +++ b/plugins/openapi/adapter/testdata/versions/appwrite-commits.json @@ -0,0 +1,42 @@ +[ +{"commit":{"committer":{"date":"2026-11-17T12:19:47Z"}},"html_url":"https://github.com/appwrite/specs/commit/529dfb64e0886acabd44f8e02fa96c5fdc7020cb","sha":"529dfb64e0886acabd44f8e02fa96c5fdc7020cb"}, +{"commit":{"committer":{"date":"2026-11-17T12:06:38Z"}},"html_url":"https://github.com/appwrite/specs/commit/946d0b0e8be2b1ea06c8591951b3df66ba33db51","sha":"946d0b0e8be2b1ea06c8591951b3df66ba33db51"}, +{"commit":{"committer":{"date":"2026-11-12T21:40:57Z"}},"html_url":"https://github.com/appwrite/specs/commit/f1c18dddc40bfabfcefc8a346583c7817f0af7c7","sha":"f1c18dddc40bfabfcefc8a346583c7817f0af7c7"}, +{"commit":{"committer":{"date":"2026-11-12T17:37:58Z"}},"html_url":"https://github.com/appwrite/specs/commit/3529c0c89cff4002f457dc1240dae84947fc23c1","sha":"3529c0c89cff4002f457dc1240dae84947fc23c1"}, +{"commit":{"committer":{"date":"2026-11-12T14:35:53Z"}},"html_url":"https://github.com/appwrite/specs/commit/4e00d85213d1884cc27abb1549f022c8b781bfaa","sha":"4e00d85213d1884cc27abb1549f022c8b781bfaa"}, +{"commit":{"committer":{"date":"2026-11-05T01:06:08Z"}},"html_url":"https://github.com/appwrite/specs/commit/218c99f7593e854ebf3089137aae4ad8bd50c48d","sha":"218c99f7593e854ebf3089137aae4ad8bd50c48d"}, +{"commit":{"committer":{"date":"2026-11-04T05:20:14Z"}},"html_url":"https://github.com/appwrite/specs/commit/5deee2847895a5f540cecb3b73035febc8ac4cba","sha":"5deee2847895a5f540cecb3b73035febc8ac4cba"}, +{"commit":{"committer":{"date":"2026-11-03T14:21:27Z"}},"html_url":"https://github.com/appwrite/specs/commit/9a50097dd538fd7663748aceed37fa05692bc5e4","sha":"9a50097dd538fd7663748aceed37fa05692bc5e4"}, +{"commit":{"committer":{"date":"2026-11-03T14:14:52Z"}},"html_url":"https://github.com/appwrite/specs/commit/90075ef836951a4d7173ec164eedafde9b37cf11","sha":"90075ef836951a4d7173ec164eedafde9b37cf11"}, +{"commit":{"committer":{"date":"2026-11-03T14:11:56Z"}},"html_url":"https://github.com/appwrite/specs/commit/64942f853d9fd2bed6c447424d12ead784824857","sha":"64942f853d9fd2bed6c447424d12ead784824857"}, +{"commit":{"committer":{"date":"2026-10-24T15:19:11Z"}},"html_url":"https://github.com/appwrite/specs/commit/b1ed34a3639a12c6763646585ec96ec7b4b5cd30","sha":"b1ed34a3639a12c6763646585ec96ec7b4b5cd30"}, +{"commit":{"committer":{"date":"2026-10-24T15:16:42Z"}},"html_url":"https://github.com/appwrite/specs/commit/7542cb07767c82d96dacb58f0590c28269ed2b58","sha":"7542cb07767c82d96dacb58f0590c28269ed2b58"}, +{"commit":{"committer":{"date":"2026-10-21T21:30:47Z"}},"html_url":"https://github.com/appwrite/specs/commit/3aba27c956bf7a3fe64605fed2f5081646ec3c52","sha":"3aba27c956bf7a3fe64605fed2f5081646ec3c52"}, +{"commit":{"committer":{"date":"2026-10-21T21:30:43Z"}},"html_url":"https://github.com/appwrite/specs/commit/eb54195bd82b1b6b4d35b873b33a9dc5e2811a5a","sha":"eb54195bd82b1b6b4d35b873b33a9dc5e2811a5a"}, +{"commit":{"committer":{"date":"2026-10-21T15:15:27Z"}},"html_url":"https://github.com/appwrite/specs/commit/177e27b44005f73e3fc455385a8f79dc3aeac897","sha":"177e27b44005f73e3fc455385a8f79dc3aeac897"}, +{"commit":{"committer":{"date":"2026-10-21T13:43:40Z"}},"html_url":"https://github.com/appwrite/specs/commit/138ae87d49b4df7122e2a4fde663d2f1bb830818","sha":"138ae87d49b4df7122e2a4fde663d2f1bb830818"}, +{"commit":{"committer":{"date":"2026-10-13T14:43:22Z"}},"html_url":"https://github.com/appwrite/specs/commit/5d0161216cc26eb898388e9c6ee51ecaae567c48","sha":"5d0161216cc26eb898388e9c6ee51ecaae567c48"}, +{"commit":{"committer":{"date":"2026-10-13T14:40:39Z"}},"html_url":"https://github.com/appwrite/specs/commit/5a3a34d5f592e1079f68dee24bee18bbcc930118","sha":"5a3a34d5f592e1079f68dee24bee18bbcc930118"}, +{"commit":{"committer":{"date":"2026-10-13T14:40:14Z"}},"html_url":"https://github.com/appwrite/specs/commit/26ab4b057d295fd42579f70b610ef27a880f485d","sha":"26ab4b057d295fd42579f70b610ef27a880f485d"}, +{"commit":{"committer":{"date":"2026-10-12T18:11:38Z"}},"html_url":"https://github.com/appwrite/specs/commit/06e6fafa4d1ae3c815843ff0b02a56e6e5582756","sha":"06e6fafa4d1ae3c815843ff0b02a56e6e5582756"}, +{"commit":{"committer":{"date":"2026-10-12T18:11:32Z"}},"html_url":"https://github.com/appwrite/specs/commit/54bfafcaa1ef8de99288d1014dc64ad1e4188d9c","sha":"54bfafcaa1ef8de99288d1014dc64ad1e4188d9c"}, +{"commit":{"committer":{"date":"2026-10-08T15:06:26Z"}},"html_url":"https://github.com/appwrite/specs/commit/98cc1a25215d3cead3a64f9bd4574a9c5b1ec87b","sha":"98cc1a25215d3cead3a64f9bd4574a9c5b1ec87b"}, +{"commit":{"committer":{"date":"2026-10-08T10:55:33Z"}},"html_url":"https://github.com/appwrite/specs/commit/fcaf861efd0186d0e53dd82df6993f90eb66bd7b","sha":"fcaf861efd0186d0e53dd82df6993f90eb66bd7b"}, +{"commit":{"committer":{"date":"2026-10-08T10:55:24Z"}},"html_url":"https://github.com/appwrite/specs/commit/0a012b5b85cf14c0f53db0da3bb49f97eab522ad","sha":"0a012b5b85cf14c0f53db0da3bb49f97eab522ad"}, +{"commit":{"committer":{"date":"2026-10-05T12:54:21Z"}},"html_url":"https://github.com/appwrite/specs/commit/275907e08299bda9c73e9cd08a75ede75444fce5","sha":"275907e08299bda9c73e9cd08a75ede75444fce5"}, +{"commit":{"committer":{"date":"2026-10-05T12:54:17Z"}},"html_url":"https://github.com/appwrite/specs/commit/20cd27f3a3d6caf923c829e880dae9d8a3d673d5","sha":"20cd27f3a3d6caf923c829e880dae9d8a3d673d5"}, +{"commit":{"committer":{"date":"2026-09-24T14:39:42Z"}},"html_url":"https://github.com/appwrite/specs/commit/96060bf70ebd673f94e349289ac5007815619be1","sha":"96060bf70ebd673f94e349289ac5007815619be1"}, +{"commit":{"committer":{"date":"2026-09-24T12:26:26Z"}},"html_url":"https://github.com/appwrite/specs/commit/fa0ac9e58511bf3a0ce4e5cdcb7d95413fcaf262","sha":"fa0ac9e58511bf3a0ce4e5cdcb7d95413fcaf262"}, +{"commit":{"committer":{"date":"2026-09-23T14:39:59Z"}},"html_url":"https://github.com/appwrite/specs/commit/af4c27c8f30e492e592a7c9ab6e83641851732d7","sha":"af4c27c8f30e492e592a7c9ab6e83641851732d7"}, +{"commit":{"committer":{"date":"2026-09-23T14:29:51Z"}},"html_url":"https://github.com/appwrite/specs/commit/9a2203ac099e272273296ddea1c89df92292975a","sha":"9a2203ac099e272273296ddea1c89df92292975a"}, +{"commit":{"committer":{"date":"2026-09-18T12:27:45Z"}},"html_url":"https://github.com/appwrite/specs/commit/29c25de5ddbfcf93b60f74e648da3b7312bc2012","sha":"29c25de5ddbfcf93b60f74e648da3b7312bc2012"}, +{"commit":{"committer":{"date":"2026-09-18T12:21:52Z"}},"html_url":"https://github.com/appwrite/specs/commit/19b780bf887c8ceb31bd4df5519e754b6202d1ce","sha":"19b780bf887c8ceb31bd4df5519e754b6202d1ce"}, +{"commit":{"committer":{"date":"2026-09-18T12:14:54Z"}},"html_url":"https://github.com/appwrite/specs/commit/623e580eae5dfaea7c62383ead066323a287c94b","sha":"623e580eae5dfaea7c62383ead066323a287c94b"}, +{"commit":{"committer":{"date":"2026-09-18T12:14:20Z"}},"html_url":"https://github.com/appwrite/specs/commit/d7fc6c4a5bd4dcd59b864bdf7485a235f4b654c3","sha":"d7fc6c4a5bd4dcd59b864bdf7485a235f4b654c3"}, +{"commit":{"committer":{"date":"2026-09-10T08:17:50Z"}},"html_url":"https://github.com/appwrite/specs/commit/592d16a6d8bedfff7da085fceceaa90affbc5056","sha":"592d16a6d8bedfff7da085fceceaa90affbc5056"}, +{"commit":{"committer":{"date":"2026-09-10T08:07:31Z"}},"html_url":"https://github.com/appwrite/specs/commit/371e49909b4deef9168e7563d96ff127d6324b71","sha":"371e49909b4deef9168e7563d96ff127d6324b71"}, +{"commit":{"committer":{"date":"2026-09-10T08:07:09Z"}},"html_url":"https://github.com/appwrite/specs/commit/0f0bd2ab63901f06c7fca107c7a95cf59d476e44","sha":"0f0bd2ab63901f06c7fca107c7a95cf59d476e44"}, +{"commit":{"committer":{"date":"2026-09-08T11:08:25Z"}},"html_url":"https://github.com/appwrite/specs/commit/56f42236ccdf7621019020e6224279d707d6f848","sha":"56f42236ccdf7621019020e6224279d707d6f848"}, +{"commit":{"committer":{"date":"2026-09-08T11:07:53Z"}},"html_url":"https://github.com/appwrite/specs/commit/3adab28615a52fb64641097c6d2cb266e9b650e6","sha":"3adab28615a52fb64641097c6d2cb266e9b650e6"}, +{"commit":{"committer":{"date":"2026-09-08T11:07:49Z"}},"html_url":"https://github.com/appwrite/specs/commit/2248bd24e9c4ab571694d3d3ac5dcf323263a63e","sha":"2248bd24e9c4ab571694d3d3ac5dcf323263a63e"} +] diff --git a/plugins/openapi/adapter/testdata/versions/es-branches.json b/plugins/openapi/adapter/testdata/versions/es-branches.json new file mode 100644 index 0000000..60832dc --- /dev/null +++ b/plugins/openapi/adapter/testdata/versions/es-branches.json @@ -0,0 +1,101 @@ +[ + { + "ref": "refs/heads/7.14" + }, + { + "ref": "refs/heads/7.15" + }, + { + "ref": "refs/heads/7.16" + }, + { + "ref": "refs/heads/7.17" + }, + { + "ref": "refs/heads/8.0" + }, + { + "ref": "refs/heads/8.1" + }, + { + "ref": "refs/heads/8.10" + }, + { + "ref": "refs/heads/8.11" + }, + { + "ref": "refs/heads/8.12" + }, + { + "ref": "refs/heads/8.13" + }, + { + "ref": "refs/heads/8.14" + }, + { + "ref": "refs/heads/8.15" + }, + { + "ref": "refs/heads/8.16" + }, + { + "ref": "refs/heads/8.17" + }, + { + "ref": "refs/heads/8.18" + }, + { + "ref": "refs/heads/8.19" + }, + { + "ref": "refs/heads/8.2" + }, + { + "ref": "refs/heads/8.3" + }, + { + "ref": "refs/heads/8.4" + }, + { + "ref": "refs/heads/8.5" + }, + { + "ref": "refs/heads/8.6" + }, + { + "ref": "refs/heads/8.7" + }, + { + "ref": "refs/heads/8.8" + }, + { + "ref": "refs/heads/8.9" + }, + { + "ref": "refs/heads/9.0" + }, + { + "ref": "refs/heads/9.1" + }, + { + "ref": "refs/heads/9.2" + }, + { + "ref": "refs/heads/9.3" + }, + { + "ref": "refs/heads/9.4" + }, + { + "ref": "refs/heads/9.5" + }, + { + "ref": "refs/heads/9.6" + }, + { + "ref": "refs/heads/gh-pages" + }, + { + "ref": "refs/heads/main" + } +] diff --git a/plugins/openapi/adapter/testdata/versions/es-releases.json b/plugins/openapi/adapter/testdata/versions/es-releases.json new file mode 100644 index 0000000..42f6bcc --- /dev/null +++ b/plugins/openapi/adapter/testdata/versions/es-releases.json @@ -0,0 +1,502 @@ +[ + { + "draft": false, + "prerelease": false, + "tag_name": "v8.19.25" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.5.6" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.4.9" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.19.24" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.5.5" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.4.8" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.19.23" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.19.22" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.5.4" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.4.7" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.5.3" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.4.6" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.19.21" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.5.2" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.5.1" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.4.5" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.19.20" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.5.0" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.4.4" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.3.8" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.19.19" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.19.18" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.3.7" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.4.3" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.19.17" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.3.6" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.4.2" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.3.5" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.19.16" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.4.1" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.4.0" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.19.15" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.3.4" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.2.8" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.19.14" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.3.3" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.3.2" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.2.7" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.19.13" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.3.1" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.2.6" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.19.12" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.3.0" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.2.5" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.19.11" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.1.10" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.19.10" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.2.4" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.1.9" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.19.9" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.2.3" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.2.2" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.1.8" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.19.8" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.2.1" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.1.7" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.19.7" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.2.0" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.1.6" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.19.6" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.19.5" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.1.5" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.0.8" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.18.8" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.1.4" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.19.4" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.0.7" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.18.7" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.19.3" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.18.6" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.1.3" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.0.6" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.1.2" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.19.2" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.0.5" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.19.1" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.18.5" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.17.10" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.1.1" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.1.0" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.19.0" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.0.4" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.18.4" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.17.9" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.0.3" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.18.3" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v7.17.29" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.17.8" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.0.2" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.18.2" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.17.7" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.0.1" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.18.1" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.17.6" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.18.0" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.17.5" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v9.0.0" + }, + { + "draft": false, + "prerelease": true, + "tag_name": "v9.0.0-rc1" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.17.4" + }, + { + "draft": false, + "prerelease": false, + "tag_name": "v8.16.6" + } +] diff --git a/plugins/openapi/adapter/testdata/versions/github-versions.json b/plugins/openapi/adapter/testdata/versions/github-versions.json new file mode 100644 index 0000000..1ed70f8 --- /dev/null +++ b/plugins/openapi/adapter/testdata/versions/github-versions.json @@ -0,0 +1 @@ +["2026-03-10","2022-11-28"] \ No newline at end of file diff --git a/plugins/openapi/adapter/testdata/versions/gitlab-tags-1.json b/plugins/openapi/adapter/testdata/versions/gitlab-tags-1.json new file mode 100644 index 0000000..dd11e78 --- /dev/null +++ b/plugins/openapi/adapter/testdata/versions/gitlab-tags-1.json @@ -0,0 +1,102 @@ +[ +{"name":"v19.6.1-ee","commit":{"created_at":"2026-11-19T22:47:46.000+00:00"}}, +{"name":"v19.6.0-rc43-ee","commit":{"created_at":"2026-11-17T15:41:23.000+00:00"}}, +{"name":"v19.6.0-rc42-ee","commit":{"created_at":"2026-11-17T09:18:16.000+00:00"}}, +{"name":"v19.6.0-ee","commit":{"created_at":"2026-11-18T17:40:45.000+00:00"}}, +{"name":"v19.5.8-ee","commit":{"created_at":"2026-11-19T21:37:02.000+00:00"}}, +{"name":"v19.5.6-ee","commit":{"created_at":"2026-11-16T15:34:18.000+00:00"}}, +{"name":"v19.5.5-ee","commit":{"created_at":"2026-11-11T04:11:12.000+00:00"}}, +{"name":"v19.5.4-ee","commit":{"created_at":"2026-11-06T15:44:23.000+00:00"}}, +{"name":"v19.5.3-ee","commit":{"created_at":"2026-10-28T05:04:29.000+00:00"}}, +{"name":"v19.5.2-ee","commit":{"created_at":"2026-10-27T09:34:33.000+00:00"}}, +{"name":"v19.5.1-ee","commit":{"created_at":"2026-10-20T23:00:49.000+00:00"}}, +{"name":"v19.5.0-rc43-ee","commit":{"created_at":"2026-10-14T19:43:39.000+00:00"}}, +{"name":"v19.5.0-rc42-ee","commit":{"created_at":"2026-10-13T12:08:07.000+00:00"}}, +{"name":"v19.5.0-ee","commit":{"created_at":"2026-10-15T00:37:08.000+00:00"}}, +{"name":"v19.4.10-ee","commit":{"created_at":"2026-11-19T21:52:01.000+00:00"}}, +{"name":"v19.4.8-ee","commit":{"created_at":"2026-11-16T15:51:20.000+00:00"}}, +{"name":"v19.4.7-ee","commit":{"created_at":"2026-11-11T04:21:19.000+00:00"}}, +{"name":"v19.4.6-ee","commit":{"created_at":"2026-11-06T15:56:03.000+00:00"}}, +{"name":"v19.4.5-ee","commit":{"created_at":"2026-10-28T05:14:24.000+00:00"}}, +{"name":"v19.4.4-ee","commit":{"created_at":"2026-10-27T09:35:49.000+00:00"}}, +{"name":"v19.4.3-ee","commit":{"created_at":"2026-10-20T23:07:57.000+00:00"}}, +{"name":"v19.4.2-ee","commit":{"created_at":"2026-10-07T14:19:10.000+00:00"}}, +{"name":"v19.4.1-ee","commit":{"created_at":"2026-09-22T11:59:12.000+00:00"}}, +{"name":"v19.4.0-rc44-ee","commit":{"created_at":"2026-09-16T05:33:49.000+00:00"}}, +{"name":"v19.4.0-rc43-ee","commit":{"created_at":"2026-09-15T12:46:19.000+00:00"}}, +{"name":"v19.4.0-rc42-ee","commit":{"created_at":"2026-09-15T02:05:20.000+00:00"}}, +{"name":"v19.4.0-ee","commit":{"created_at":"2026-09-16T15:51:13.000+00:00"}}, +{"name":"v19.3.9-ee","commit":{"created_at":"2026-11-16T16:02:35.000+00:00"}}, +{"name":"v19.3.8-ee","commit":{"created_at":"2026-11-06T16:19:00.000+00:00"}}, +{"name":"v19.3.7-ee","commit":{"created_at":"2026-10-27T09:41:55.000+00:00"}}, +{"name":"v19.3.6-ee","commit":{"created_at":"2026-10-20T23:15:49.000+00:00"}}, +{"name":"v19.3.5-ee","commit":{"created_at":"2026-10-12T09:38:10.000+00:00"}}, +{"name":"v19.3.4-ee","commit":{"created_at":"2026-10-07T14:32:16.000+00:00"}}, +{"name":"v19.3.3-ee","commit":{"created_at":"2026-09-22T12:07:51.000+00:00"}}, +{"name":"v19.3.2-ee","commit":{"created_at":"2026-09-10T08:20:41.000+00:00"}}, +{"name":"v19.3.1-ee","commit":{"created_at":"2026-08-25T08:42:17.000+00:00"}}, +{"name":"v19.3.0-rc44-ee","commit":{"created_at":"2026-08-19T18:21:05.000+00:00"}}, +{"name":"v19.3.0-rc43-ee","commit":{"created_at":"2026-08-18T19:52:52.000+00:00"}}, +{"name":"v19.3.0-rc42-ee","commit":{"created_at":"2026-08-18T19:35:00.000+00:00"}}, +{"name":"v19.3.0-ee","commit":{"created_at":"2026-08-20T01:16:27.000+00:00"}}, +{"name":"v19.2.10-ee","commit":{"created_at":"2026-10-28T15:03:32.000+00:00"}}, +{"name":"v19.2.9-ee","commit":{"created_at":"2026-10-20T17:18:17.000+00:00"}}, +{"name":"v19.2.8-ee","commit":{"created_at":"2026-10-07T14:40:40.000+00:00"}}, +{"name":"v19.2.7-ee","commit":{"created_at":"2026-09-22T12:16:30.000+00:00"}}, +{"name":"v19.2.6-ee","commit":{"created_at":"2026-09-10T08:29:18.000+00:00"}}, +{"name":"v19.2.5-ee","commit":{"created_at":"2026-08-25T09:20:04.000+00:00"}}, +{"name":"v19.2.4-ee","commit":{"created_at":"2026-08-14T18:02:15.000+00:00"}}, +{"name":"v19.2.2-ee","commit":{"created_at":"2026-08-11T23:49:23.000+00:00"}}, +{"name":"v19.2.1-ee","commit":{"created_at":"2026-07-29T01:07:58.000+00:00"}}, +{"name":"v19.2.0-rc44-ee","commit":{"created_at":"2026-07-15T11:59:57.000+00:00"}}, +{"name":"v19.2.0-rc43-ee","commit":{"created_at":"2026-07-14T08:15:21.000+00:00"}}, +{"name":"v19.2.0-rc42-ee","commit":{"created_at":"2026-07-14T07:47:00.000+00:00"}}, +{"name":"v19.2.0-ee","commit":{"created_at":"2026-07-15T20:06:11.000+00:00"}}, +{"name":"v19.1.10-ee","commit":{"created_at":"2026-10-28T15:04:27.000+00:00"}}, +{"name":"v19.1.9-ee","commit":{"created_at":"2026-10-20T17:47:42.000+00:00"}}, +{"name":"v19.1.8-ee","commit":{"created_at":"2026-09-10T08:39:07.000+00:00"}}, +{"name":"v19.1.7-ee","commit":{"created_at":"2026-08-25T09:46:12.000+00:00"}}, +{"name":"v19.1.6-ee","commit":{"created_at":"2026-08-14T17:44:15.000+00:00"}}, +{"name":"v19.1.4-ee","commit":{"created_at":"2026-08-12T00:53:23.000+00:00"}}, +{"name":"v19.1.3-ee","commit":{"created_at":"2026-07-29T01:14:45.000+00:00"}}, +{"name":"v19.1.2-ee","commit":{"created_at":"2026-07-07T09:07:17.000+00:00"}}, +{"name":"v19.1.1-ee","commit":{"created_at":"2026-06-23T15:10:23.000+00:00"}}, +{"name":"v19.1.0-rc43-ee","commit":{"created_at":"2026-06-17T04:05:32.000+00:00"}}, +{"name":"v19.1.0-rc42-ee","commit":{"created_at":"2026-06-16T03:50:35.000+00:00"}}, +{"name":"v19.1.0-ee","commit":{"created_at":"2026-06-17T09:24:55.000+00:00"}}, +{"name":"v19.0.11-ee","commit":{"created_at":"2026-10-28T15:04:31.000+00:00"}}, +{"name":"v19.0.10-ee","commit":{"created_at":"2026-10-20T18:55:09.000+00:00"}}, +{"name":"v19.0.9-ee","commit":{"created_at":"2026-09-22T09:18:37.000+00:00"}}, +{"name":"v19.0.8-ee","commit":{"created_at":"2026-08-14T17:35:10.000+00:00"}}, +{"name":"v19.0.6-ee","commit":{"created_at":"2026-08-12T01:01:52.000+00:00"}}, +{"name":"v19.0.5-ee","commit":{"created_at":"2026-07-29T01:22:07.000+00:00"}}, +{"name":"v19.0.4-ee","commit":{"created_at":"2026-07-07T09:16:20.000+00:00"}}, +{"name":"v19.0.3-ee","commit":{"created_at":"2026-06-23T15:19:18.000+00:00"}}, +{"name":"v19.0.2-ee","commit":{"created_at":"2026-06-10T02:43:17.000+00:00"}}, +{"name":"v19.0.1-ee","commit":{"created_at":"2026-05-26T23:13:26.000+00:00"}}, +{"name":"v19.0.0-rc43-ee","commit":{"created_at":"2026-05-20T13:38:20.000+00:00"}}, +{"name":"v19.0.0-rc42-ee","commit":{"created_at":"2026-05-19T02:55:01.000+00:00"}}, +{"name":"v19.0.0-ee","commit":{"created_at":"2026-05-21T00:28:28.000+00:00"}}, +{"name":"v18.11.14-ee","commit":{"created_at":"2026-10-27T09:42:28.000+00:00"}}, +{"name":"v18.11.13-ee","commit":{"created_at":"2026-10-20T17:32:08.000+00:00"}}, +{"name":"v18.11.12-ee","commit":{"created_at":"2026-09-22T09:11:39.000+00:00"}}, +{"name":"v18.11.11-ee","commit":{"created_at":"2026-08-14T17:24:21.000+00:00"}}, +{"name":"v18.11.9-ee","commit":{"created_at":"2026-08-06T04:01:12.000+00:00"}}, +{"name":"v18.11.8-ee","commit":{"created_at":"2026-08-03T08:57:50.000+00:00"}}, +{"name":"v18.11.7-ee","commit":{"created_at":"2026-07-07T09:22:51.000+00:00"}}, +{"name":"v18.11.6-ee","commit":{"created_at":"2026-06-23T15:27:04.000+00:00"}}, +{"name":"v18.11.5-ee","commit":{"created_at":"2026-06-10T02:49:43.000+00:00"}}, +{"name":"v18.11.4-ee","commit":{"created_at":"2026-05-26T23:20:09.000+00:00"}}, +{"name":"v18.11.3-ee","commit":{"created_at":"2026-05-13T10:30:07.000+00:00"}}, +{"name":"v18.11.2-ee","commit":{"created_at":"2026-04-28T16:29:21.000+00:00"}}, +{"name":"v18.11.1-ee","commit":{"created_at":"2026-04-21T13:40:54.000+00:00"}}, +{"name":"v18.11.0-rc43-ee","commit":{"created_at":"2026-04-15T12:17:09.000+00:00"}}, +{"name":"v18.11.0-rc42-ee","commit":{"created_at":"2026-04-14T15:48:21.000+00:00"}}, +{"name":"v18.11.0-ee","commit":{"created_at":"2026-04-15T21:41:05.000+00:00"}}, +{"name":"v18.10.8-ee","commit":{"created_at":"2026-06-10T02:56:44.000+00:00"}}, +{"name":"v18.10.7-ee","commit":{"created_at":"2026-05-26T23:26:31.000+00:00"}}, +{"name":"v18.10.6-ee","commit":{"created_at":"2026-05-13T10:36:35.000+00:00"}}, +{"name":"v18.10.5-ee","commit":{"created_at":"2026-04-28T16:48:26.000+00:00"}}, +{"name":"v18.10.4-ee","commit":{"created_at":"2026-04-21T13:51:03.000+00:00"}}, +{"name":"v18.10.3-ee","commit":{"created_at":"2026-04-07T12:30:23.000+00:00"}} +] diff --git a/plugins/openapi/adapter/testdata/versions/gitlab-tags-2.json b/plugins/openapi/adapter/testdata/versions/gitlab-tags-2.json new file mode 100644 index 0000000..6280b39 --- /dev/null +++ b/plugins/openapi/adapter/testdata/versions/gitlab-tags-2.json @@ -0,0 +1,86 @@ +[ + { + "name": "v18.10.1-ee", + "commit": { + "created_at": "2026-03-24T16:07:05.000+00:00" + } + }, + { + "name": "v18.10.0-ee", + "commit": { + "created_at": "2026-03-18T13:35:57.000+00:00" + } + }, + { + "name": "v18.9.8-ee", + "commit": { + "created_at": "2026-05-25T20:33:16.000+00:00" + } + }, + { + "name": "v18.9.7-ee", + "commit": { + "created_at": "2026-05-13T10:41:30.000+00:00" + } + }, + { + "name": "v18.9.6-ee", + "commit": { + "created_at": "2026-04-21T13:56:40.000+00:00" + } + }, + { + "name": "v18.9.5-ee", + "commit": { + "created_at": "2026-04-07T12:41:16.000+00:00" + } + }, + { + "name": "v18.9.4-ee", + "commit": { + "created_at": "2026-03-31T13:57:04.000+00:00" + } + }, + { + "name": "v18.9.3-ee", + "commit": { + "created_at": "2026-03-24T16:13:31.000+00:00" + } + }, + { + "name": "v18.9.2-ee", + "commit": { + "created_at": "2026-03-10T17:49:47.000+00:00" + } + }, + { + "name": "v18.9.1-ee", + "commit": { + "created_at": "2026-02-24T20:32:28.000+00:00" + } + }, + { + "name": "v18.9.0-rc43-ee", + "commit": { + "created_at": "2026-02-18T11:31:27.000+00:00" + } + }, + { + "name": "v18.9.0-rc42-ee", + "commit": { + "created_at": "2026-02-17T08:22:20.000+00:00" + } + }, + { + "name": "v18.9.0-ee", + "commit": { + "created_at": "2026-02-18T17:07:38.000+00:00" + } + }, + { + "name": "v18.1.4-ee", + "commit": { + "created_at": "2025-08-12T12:44:06.000+00:00" + } + } +] diff --git a/plugins/openapi/adapter/testdata/versions/sentry-api-releases.json b/plugins/openapi/adapter/testdata/versions/sentry-api-releases.json new file mode 100644 index 0000000..7adc415 --- /dev/null +++ b/plugins/openapi/adapter/testdata/versions/sentry-api-releases.json @@ -0,0 +1,382 @@ +[ + { + "assets": [ + { + "name": "api_ownership_stats_dont_modify.json" + }, + { + "name": "openapi-derefed.json" + }, + { + "name": "rpc_method_schema.json" + }, + { + "name": "sentry-api-2.16.0.tgz" + } + ], + "draft": false, + "prerelease": false, + "published_at": "2026-11-18T20:55:52Z", + "tag_name": "api@2.16.0" + }, + { + "assets": [ + { + "name": "api_ownership_stats_dont_modify.json" + }, + { + "name": "openapi-derefed.json" + }, + { + "name": "rpc_method_schema.json" + }, + { + "name": "sentry-api-2.15.0.tgz" + } + ], + "draft": false, + "prerelease": false, + "published_at": "2026-11-18T18:56:35Z", + "tag_name": "api@2.15.0" + }, + { + "assets": [ + { + "name": "api_ownership_stats_dont_modify.json" + }, + { + "name": "openapi-derefed.json" + }, + { + "name": "rpc_method_schema.json" + }, + { + "name": "sentry-api-2.14.2.tgz" + } + ], + "draft": false, + "prerelease": false, + "published_at": "2026-11-18T18:38:46Z", + "tag_name": "api@2.14.2" + }, + { + "assets": [ + { + "name": "api_ownership_stats_dont_modify.json" + }, + { + "name": "openapi-derefed.json" + }, + { + "name": "rpc_method_schema.json" + }, + { + "name": "sentry-api-2.14.1.tgz" + } + ], + "draft": false, + "prerelease": false, + "published_at": "2026-11-18T18:30:53Z", + "tag_name": "api@2.14.1" + }, + { + "assets": [ + { + "name": "api_ownership_stats_dont_modify.json" + }, + { + "name": "openapi-derefed.json" + }, + { + "name": "rpc_method_schema.json" + }, + { + "name": "sentry-api-2.14.0.tgz" + } + ], + "draft": false, + "prerelease": false, + "published_at": "2026-11-18T12:42:27Z", + "tag_name": "api@2.14.0" + }, + { + "assets": [ + { + "name": "api_ownership_stats_dont_modify.json" + }, + { + "name": "openapi-derefed.json" + }, + { + "name": "rpc_method_schema.json" + }, + { + "name": "sentry-api-2.13.0.tgz" + } + ], + "draft": false, + "prerelease": false, + "published_at": "2026-11-18T09:34:28Z", + "tag_name": "api@2.13.0" + }, + { + "assets": [ + { + "name": "api_ownership_stats_dont_modify.json" + }, + { + "name": "openapi-derefed.json" + }, + { + "name": "rpc_method_schema.json" + }, + { + "name": "sentry-api-2.9.0.tgz" + } + ], + "draft": false, + "prerelease": false, + "published_at": "2026-11-17T16:54:56Z", + "tag_name": "api@2.9.0" + }, + { + "assets": [ + { + "name": "api_ownership_stats_dont_modify.json" + }, + { + "name": "openapi-derefed.json" + }, + { + "name": "rpc_method_schema.json" + }, + { + "name": "sentry-api-2.8.0.tgz" + } + ], + "draft": false, + "prerelease": false, + "published_at": "2026-11-17T16:04:08Z", + "tag_name": "api@2.8.0" + }, + { + "assets": [ + { + "name": "api_ownership_stats_dont_modify.json" + }, + { + "name": "openapi-derefed.json" + }, + { + "name": "rpc_method_schema.json" + }, + { + "name": "sentry-api-2.12.0.tgz" + } + ], + "draft": false, + "prerelease": false, + "published_at": "2026-11-17T23:31:03Z", + "tag_name": "api@2.12.0" + }, + { + "assets": [ + { + "name": "api_ownership_stats_dont_modify.json" + }, + { + "name": "openapi-derefed.json" + }, + { + "name": "rpc_method_schema.json" + }, + { + "name": "sentry-api-2.11.0.tgz" + } + ], + "draft": false, + "prerelease": false, + "published_at": "2026-11-17T22:14:24Z", + "tag_name": "api@2.11.0" + }, + { + "assets": [ + { + "name": "api_ownership_stats_dont_modify.json" + }, + { + "name": "openapi-derefed.json" + }, + { + "name": "rpc_method_schema.json" + }, + { + "name": "sentry-api-2.10.1.tgz" + } + ], + "draft": false, + "prerelease": false, + "published_at": "2026-11-17T20:10:08Z", + "tag_name": "api@2.10.1" + }, + { + "assets": [ + { + "name": "api_ownership_stats_dont_modify.json" + }, + { + "name": "openapi-derefed.json" + }, + { + "name": "rpc_method_schema.json" + }, + { + "name": "sentry-api-2.10.0.tgz" + } + ], + "draft": false, + "prerelease": false, + "published_at": "2026-11-17T17:59:39Z", + "tag_name": "api@2.10.0" + }, + { + "assets": [ + { + "name": "api_ownership_stats_dont_modify.json" + }, + { + "name": "openapi-derefed.json" + }, + { + "name": "rpc_method_schema.json" + }, + { + "name": "sentry-api-2.7.0.tgz" + } + ], + "draft": false, + "prerelease": false, + "published_at": "2026-11-16T13:56:34Z", + "tag_name": "api@2.7.0" + }, + { + "assets": [ + { + "name": "api_ownership_stats_dont_modify.json" + }, + { + "name": "openapi-derefed.json" + }, + { + "name": "rpc_method_schema.json" + }, + { + "name": "sentry-api-2.6.1.tgz" + } + ], + "draft": false, + "prerelease": false, + "published_at": "2026-11-16T13:48:10Z", + "tag_name": "api@2.6.1" + }, + { + "assets": [ + { + "name": "api_ownership_stats_dont_modify.json" + }, + { + "name": "openapi-derefed.json" + }, + { + "name": "rpc_method_schema.json" + }, + { + "name": "sentry-api-2.6.0.tgz" + } + ], + "draft": false, + "prerelease": false, + "published_at": "2026-11-16T13:38:47Z", + "tag_name": "api@2.6.0" + }, + { + "assets": [ + { + "name": "api_ownership_stats_dont_modify.json" + }, + { + "name": "openapi-derefed.json" + }, + { + "name": "rpc_method_schema.json" + }, + { + "name": "sentry-api-2.5.3.tgz" + } + ], + "draft": false, + "prerelease": false, + "published_at": "2026-11-16T13:30:57Z", + "tag_name": "api@2.5.3" + }, + { + "assets": [ + { + "name": "api_ownership_stats_dont_modify.json" + }, + { + "name": "openapi-derefed.json" + }, + { + "name": "rpc_method_schema.json" + }, + { + "name": "sentry-api-2.5.2.tgz" + } + ], + "draft": false, + "prerelease": false, + "published_at": "2026-11-16T13:08:55Z", + "tag_name": "api@2.5.2" + }, + { + "assets": [ + { + "name": "api_ownership_stats_dont_modify.json" + }, + { + "name": "openapi-derefed.json" + }, + { + "name": "rpc_method_schema.json" + }, + { + "name": "sentry-api-2.5.1.tgz" + } + ], + "draft": false, + "prerelease": false, + "published_at": "2026-11-16T11:13:34Z", + "tag_name": "api@2.5.1" + }, + { + "assets": [ + { + "name": "api_ownership_stats_dont_modify.json" + }, + { + "name": "openapi-derefed.json" + }, + { + "name": "rpc_method_schema.json" + }, + { + "name": "sentry-api-2.5.0.tgz" + } + ], + "draft": false, + "prerelease": false, + "published_at": "2026-11-14T15:29:13Z", + "tag_name": "api@2.5.0" + } +] diff --git a/plugins/openapi/adapter/testdata/versions/sentry-schema-releases.json b/plugins/openapi/adapter/testdata/versions/sentry-schema-releases.json new file mode 100644 index 0000000..acf2dc1 --- /dev/null +++ b/plugins/openapi/adapter/testdata/versions/sentry-schema-releases.json @@ -0,0 +1,14 @@ +[ + { + "draft": false, + "prerelease": false, + "published_at": "2026-11-14T01:22:13Z", + "tag_name": "2.4.0" + }, + { + "draft": false, + "prerelease": false, + "published_at": "2026-11-14T00:30:35Z", + "tag_name": "2.3.2" + } +] diff --git a/plugins/openapi/adapter/vercel.go b/plugins/openapi/adapter/vercel.go index ae0d5e1..7d3afb3 100644 --- a/plugins/openapi/adapter/vercel.go +++ b/plugins/openapi/adapter/vercel.go @@ -27,7 +27,7 @@ type Vercel struct{} var _ Adapter = Vercel{} -func (Vercel) API() string { return "vercel" } +func (Vercel) API() string { return "vercel/api" } // LatestTag asks GitHub for vercel/sdk's newest release tag, e.g. "v1.28.65". // The canary tags (v14.0.0-canary.9) aren't releases, so releases/latest never diff --git a/plugins/openapi/adapter/versions.go b/plugins/openapi/adapter/versions.go index 9e6238e..dd2f0af 100644 --- a/plugins/openapi/adapter/versions.go +++ b/plugins/openapi/adapter/versions.go @@ -1,19 +1,26 @@ package adapter import ( + "cmp" "context" + "encoding/json" + "fmt" + "slices" "strings" + "time" + "github.com/patch-it-dev/patch-it-plugins/core/fetch" "github.com/patch-it-dev/patch-it-plugins/core/github" "github.com/patch-it-dev/patch-it-plugins/core/plugin" "github.com/patch-it-dev/patch-it-plugins/core/versions" ) -// Every version of each spec that can be listed, oldest first (Lister): the -// repo's releases for the adapters whose LatestTag is releases/latest, the -// commits that changed the spec for those that follow a file. The others -// (GitHub's dated versions, GitLab, Elasticsearch, Sentry, Algolia, Appwrite) -// are read at LatestTag only, for now. +// Every version of each spec, oldest first (Lister): the repo's releases for +// the adapters whose LatestTag is releases/latest, the commits that changed +// the spec for those that follow a file, and each other adapter's own +// listing (GitHub's dated versions, GitLab's release tags, Elasticsearch's +// released minors, Sentry's releases, Algolia's release tags, Appwrite's +// spec commits). Every adapter is a Lister. func releases(ctx context.Context, repo string, keep func(string) bool) ([]plugin.Version, error) { return versions.GitHubReleases(ctx, github.Get, repo, keep) @@ -73,3 +80,192 @@ var ( _ Lister = Convex{} _ Lister = PlanetScale{} ) + +// Versions are every API version GitHub supports, oldest first: each is a +// spec file of its own, and what a client sends as X-GitHub-Api-Version. +// GitHub publishes no spec for a version it no longer supports. +func (GitHub) Versions(ctx context.Context) ([]plugin.Version, error) { + body, err := fetch.Get(ctx, githubVersionsURL, github.Headers()) + if err != nil { + return nil, fmt.Errorf("looking up github's supported api versions: %w", err) + } + var ids []string + if err := json.Unmarshal(body, &ids); err != nil { + return nil, fmt.Errorf("parsing github versions response: %w", err) + } + slices.Sort(ids) + var out []plugin.Version + for _, id := range ids { + released, _ := time.Parse(time.DateOnly, id) + out = append(out, plugin.Version{ID: id, Released: released, Ref: id, URL: "https://docs.github.com/rest/about-the-rest-api/api-versions"}) + } + return out, nil +} + +// gitlabFirstSpec is the first release whose tag carries openapi_v3.yaml. +var gitlabFirstSpec = [3]int{18, 10, 0} + +// Versions are every stable GitLab release with the OpenAPI 3 spec +// (v18.10.0-ee on), oldest first by version: patch releases of an older +// minor (18.11.14) sit before the next minor's first release. The tags +// listing is read page by page, newest version first, until it passes +// v18.10.0-ee. +func (g GitLab) Versions(ctx context.Context) ([]plugin.Version, error) { + type tag struct { + Name string `json:"name"` + Commit struct { + Created time.Time `json:"created_at"` + } `json:"commit"` + } + var out []plugin.Version + for page := 1; page <= versions.MaxPages; page++ { + body, err := fetch.Get(ctx, fmt.Sprintf("%s&page=%d", cmp.Or(g.TagsURL, gitlabTagsURL), page), nil) + if err != nil { + return nil, fmt.Errorf("listing gitlab's tags: %w", err) + } + var tags []tag + if err := json.Unmarshal(body, &tags); err != nil { + return nil, fmt.Errorf("parsing gitlab tags response: %w", err) + } + older := false + for _, t := range tags { + m := gitlabRelease.FindStringSubmatch(t.Name) + if m == nil { + continue + } + v := [3]int{atoi(m[1]), atoi(m[2]), atoi(m[3])} + if slices.Compare(v[:], gitlabFirstSpec[:]) < 0 { + older = true + continue + } + out = append(out, plugin.Version{ID: gitlabVersion(t.Name), Released: t.Commit.Created.UTC(), Ref: t.Name, + URL: "https://gitlab.com/gitlab-org/gitlab/-/tags/" + t.Name}) + } + if older || len(tags) < 100 { + break + } + } + slices.SortStableFunc(out, func(a, b plugin.Version) int { return versions.Compare(a.ID, b.ID) }) + return out, nil +} + +// esFirstSpec is the first minor whose branch has the OpenAPI output. +var esFirstSpec = [2]int{8, 14} + +// Versions are every released minor with the OpenAPI output (8.14 on), its +// branch the ref: up to the newest minor Elastic has released (LatestTag), +// never the next, unreleased one. +func (e Elasticsearch) Versions(ctx context.Context) ([]plugin.Version, error) { + newest, branches, err := esMinors(ctx) + if err != nil { + return nil, err + } + var out []plugin.Version + for _, b := range branches { + m := esBranch.FindStringSubmatch(b) + v := [2]int{atoi(m[1]), atoi(m[2])} + if slices.Compare(v[:], esFirstSpec[:]) < 0 || slices.Compare(v[:], newest[:]) > 0 { + continue + } + out = append(out, plugin.Version{ID: b + ".0", Ref: b, URL: "https://github.com/elastic/elasticsearch-specification/tree/" + b}) + } + slices.SortStableFunc(out, func(a, b plugin.Version) int { return versions.Compare(a.ID, b.ID) }) + return out, nil +} + +// Versions are every release of the spec, oldest first by date: the +// getsentry/sentry-api-schema release tags (0.1.0 to 2.4.0, the archived +// repo) and then getsentry/sentry's api@X.Y.Z releases with the spec +// attached. The ID is the release's date, as Fetch's Version. The schema +// repo's commits before its first tag aren't listed; Fetch still reads one +// by its SHA. +func (s Sentry) Versions(ctx context.Context) ([]plugin.Version, error) { + var out []plugin.Version + for _, src := range []struct { + repo string + keep func(sentryReleaseInfo) bool + }{ + {"getsentry/sentry-api-schema", func(r sentryReleaseInfo) bool { return sentrySchemaTag.MatchString(r.Tag) }}, + {"getsentry/sentry", func(r sentryReleaseInfo) bool { return sentryRelease.MatchString(r.Tag) && r.hasSpec() }}, + } { + rs, err := versions.GitHubPages[sentryReleaseInfo](ctx, github.Get, s.api("/repos/"+src.repo+"/releases")) + if err != nil { + return nil, fmt.Errorf("listing %s's releases: %w", src.repo, err) + } + for _, r := range rs { + if r.Draft || r.Prerelease || !src.keep(r) { + continue + } + at := r.PublishedAt.UTC() + out = append(out, plugin.Version{ID: at.Format(time.DateOnly), Released: at, Ref: r.Tag, + URL: "https://github.com/" + src.repo + "/releases/tag/" + strings.ReplaceAll(r.Tag, "@", "%40")}) + } + } + slices.SortStableFunc(out, func(a, b plugin.Version) int { return a.Released.Compare(b.Released) }) + return out, nil +} + +// Versions are every release tag, oldest first. A day with several releases +// is ordered by each tag's commit date (LatestTag's rule), one lookup per +// tag on such a day only. +func (a Algolia) Versions(ctx context.Context) ([]plugin.Version, error) { + tags, err := algoliaTags(ctx) + if err != nil { + return nil, err + } + days := map[string]int{} + for _, t := range tags { + days[algoliaTag.FindStringSubmatch(t)[1]]++ + } + var out []plugin.Version + for _, t := range tags { + day := algoliaTag.FindStringSubmatch(t)[1] + released, _ := time.Parse(time.DateOnly, day) + if days[day] > 1 { + if released, err = algoliaCommitDate(ctx, t); err != nil { + return nil, err + } + } + out = append(out, plugin.Version{ID: day, Released: released.UTC(), Ref: t, + URL: "https://github.com/algolia/api-clients-automation/releases/tag/" + t}) + } + slices.SortStableFunc(out, func(a, b plugin.Version) int { return a.Released.Compare(b.Released) }) + return out, nil +} + +// Versions are the commits on appwrite/specs' default branch that changed +// specs/, oldest first: the ID is the commit's date (Fetch's Version), the +// Ref its SHA, read at the newest minor's directory. +func (a Appwrite) Versions(ctx context.Context) ([]plugin.Version, error) { + cs, err := versions.GitHubPages[struct { + SHA string `json:"sha"` + URL string `json:"html_url"` + Commit struct { + Committer struct { + Date time.Time `json:"date"` + } `json:"committer"` + } `json:"commit"` + }](ctx, github.Get, a.api("/commits?path=specs")) + if err != nil { + return nil, fmt.Errorf("listing the commits that changed appwrite's specs: %w", err) + } + var out []plugin.Version + for _, c := range cs { + if !appwriteCommit.MatchString(c.SHA) || c.Commit.Committer.Date.IsZero() { + continue + } + at := c.Commit.Committer.Date.UTC() + out = append(out, plugin.Version{ID: at.Format(time.DateOnly), Released: at, Ref: c.SHA, URL: c.URL}) + } + slices.SortStableFunc(out, func(a, b plugin.Version) int { return a.Released.Compare(b.Released) }) + return out, nil +} + +var ( + _ Lister = GitHub{} + _ Lister = GitLab{} + _ Lister = Elasticsearch{} + _ Lister = Sentry{} + _ Lister = Algolia{} + _ Lister = Appwrite{} +) diff --git a/plugins/openapi/adapter/versions_test.go b/plugins/openapi/adapter/versions_test.go new file mode 100644 index 0000000..98f10e5 --- /dev/null +++ b/plugins/openapi/adapter/versions_test.go @@ -0,0 +1,169 @@ +package adapter + +import ( + "context" + "net/http" + "net/http/httptest" + "os" + "slices" + "strings" + "testing" + + "github.com/patch-it-dev/patch-it-plugins/core/plugin" +) + +// recorded serves saved API responses (testdata/versions/, recorded +// 2026-11-20 and trimmed: testdata/README.md) by request path and query; +// any other request fails the test. +func recorded(t *testing.T, files map[string]string) *httptest.Server { + t.Helper() + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + key := r.URL.Path + if r.URL.RawQuery != "" { + key += "?" + r.URL.RawQuery + } + file, ok := files[key] + if !ok { + t.Errorf("unexpected request %s", key) + http.NotFound(w, r) + return + } + b, err := os.ReadFile("testdata/versions/" + file) + if err != nil { + t.Error(err) + } + w.Write(b) + })) + t.Cleanup(srv.Close) + return srv +} + +func ids(vs []plugin.Version) string { + var out []string + for _, v := range vs { + out = append(out, v.ID+"@"+v.Ref) + } + return strings.Join(out, " ") +} + +func TestGitHubListsEverySupportedVersion(t *testing.T) { + srv := recorded(t, map[string]string{"/versions": "github-versions.json"}) + old := githubVersionsURL + githubVersionsURL = srv.URL + "/versions" + t.Cleanup(func() { githubVersionsURL = old }) + vs, err := GitHub{}.Versions(context.Background()) + if err != nil { + t.Fatal(err) + } + if got := ids(vs); got != "2022-11-28@2022-11-28 2026-03-10@2026-03-10" { + t.Errorf("versions %s", got) + } +} + +// Every stable release from v18.10.0-ee (the first with openapi_v3.yaml), in +// version order, release candidates left out; the listing is read a second +// page, and no further once it passes v18.10.0-ee. +func TestGitLabListsEveryReleaseWithTheSpec(t *testing.T) { + srv := recorded(t, map[string]string{ + "/tags?order_by=version&sort=desc&per_page=100&page=1": "gitlab-tags-1.json", + "/tags?order_by=version&sort=desc&per_page=100&page=2": "gitlab-tags-2.json", + }) + vs, err := GitLab{TagsURL: srv.URL + "/tags?order_by=version&sort=desc&per_page=100"}.Versions(context.Background()) + if err != nil { + t.Fatal(err) + } + if vs[0].ID != "18.10.0" || vs[0].Ref != "v18.10.0-ee" || vs[len(vs)-1].ID != "19.6.1" { + t.Errorf("first %v, last %v", vs[0], vs[len(vs)-1]) + } + seen := map[string]bool{} + for _, v := range vs { + if strings.Contains(v.Ref, "rc") || v.Released.IsZero() || seen[v.ID] { + t.Errorf("version %v", v) + } + seen[v.ID] = true + } + at := func(id string) int { return slices.IndexFunc(vs, func(v plugin.Version) bool { return v.ID == id }) } + if !(at("18.11.14") < at("19.0.0") && at("19.0.0") < at("19.6.0") && at("18.10.1") > at("18.10.0")) { + t.Errorf("not in version order: %s", ids(vs)) + } +} + +// Every released minor from 8.14 (the first with the OpenAPI output) to the +// newest released one, 9.5: not 9.6, the next minor's branch. +func TestElasticsearchListsEveryReleasedMinor(t *testing.T) { + srv := recorded(t, map[string]string{"/releases": "es-releases.json", "/branches": "es-branches.json"}) + a, b := esReleasesURL, esBranchesURL + esReleasesURL, esBranchesURL = srv.URL+"/releases", srv.URL+"/branches" + t.Cleanup(func() { esReleasesURL, esBranchesURL = a, b }) + vs, err := Elasticsearch{}.Versions(context.Background()) + if err != nil { + t.Fatal(err) + } + want := "8.14.0@8.14 8.15.0@8.15 8.16.0@8.16 8.17.0@8.17 8.18.0@8.18 8.19.0@8.19 9.0.0@9.0 9.1.0@9.1 9.2.0@9.2 9.3.0@9.3 9.4.0@9.4 9.5.0@9.5" + if got := ids(vs); got != want { + t.Errorf("versions\n %s\nwant\n %s", got, want) + } +} + +// The archived schema repo's tags, then getsentry/sentry's api@ releases, +// by date; the IDs are dates, as Fetch's Version. +func TestSentryListsBothRepos(t *testing.T) { + srv := recorded(t, map[string]string{ + "/repos/getsentry/sentry-api-schema/releases?per_page=100&page=1": "sentry-schema-releases.json", + "/repos/getsentry/sentry/releases?per_page=100&page=1": "sentry-api-releases.json", + }) + vs, err := Sentry{APIBase: srv.URL}.Versions(context.Background()) + if err != nil { + t.Fatal(err) + } + if len(vs) != 21 || vs[0].Ref != "2.3.2" || vs[1].Ref != "2.4.0" || vs[2].Ref != "api@2.5.0" || vs[len(vs)-1].Ref != "api@2.16.0" { + t.Fatalf("versions %s", ids(vs)) + } + for i := 1; i < len(vs); i++ { + if vs[i].Released.Before(vs[i-1].Released) || vs[i].ID != vs[i].Released.Format("2006-01-02") { + t.Errorf("%v after %v", vs[i], vs[i-1]) + } + } +} + +// Every release tag, oldest first; the five tags of 2024-09-18 and -19 are +// ordered by their commits' dates, not their names. +func TestAlgoliaListsEveryReleaseTag(t *testing.T) { + files := map[string]string{"/refs": "algolia-refs.json"} + for _, tag := range []string{"2024-09-18-45edcd844", "2024-09-18-cc190fae3", "2024-09-19-6e91dbf55", "2024-09-19-a62c27d3b", "2024-09-19-e47df6533"} { + files["/commits/released-"+tag] = "algolia-commit-released-" + tag + ".json" + } + srv := recorded(t, files) + a, b := algoliaRefsURL, algoliaCommitURL + algoliaRefsURL, algoliaCommitURL = srv.URL+"/refs", srv.URL+"/commits/%s" + t.Cleanup(func() { algoliaRefsURL, algoliaCommitURL = a, b }) + vs, err := Algolia{Spec: "search"}.Versions(context.Background()) + if err != nil { + t.Fatal(err) + } + var refs []string + for _, v := range vs { + refs = append(refs, strings.TrimPrefix(v.Ref, "released-")) + } + want := "2023-08-22 2023-08-29 2024-09-18-45edcd844 2024-09-18-cc190fae3 2024-09-19-a62c27d3b 2024-09-19-6e91dbf55 2024-09-19-e47df6533 2026-11-10-8d91e3d8a3 2026-11-17-31c309fe2a" + if got := strings.Join(refs, " "); got != want { + t.Errorf("refs\n %s\nwant\n %s", got, want) + } +} + +// Every commit that changed specs/, oldest first, dated. +func TestAppwriteListsEverySpecCommit(t *testing.T) { + srv := recorded(t, map[string]string{"/repos/appwrite/specs/commits?path=specs&per_page=100&page=1": "appwrite-commits.json"}) + vs, err := Appwrite{APIBase: srv.URL}.Versions(context.Background()) + if err != nil { + t.Fatal(err) + } + if len(vs) != 40 { + t.Fatalf("%d versions, want 40", len(vs)) + } + for i := 1; i < len(vs); i++ { + if vs[i].Released.Before(vs[i-1].Released) || len(vs[i].Ref) != 40 { + t.Errorf("%v after %v", vs[i], vs[i-1]) + } + } +} diff --git a/plugins/openapi/algolia_test.go b/plugins/openapi/algolia_test.go index 6689e85..edc34ef 100644 --- a/plugins/openapi/algolia_test.go +++ b/plugins/openapi/algolia_test.go @@ -20,10 +20,10 @@ import ( // from YAML to JSON like adapter.Algolia.Fetch, and cited by the real URL. type fakeAlgoliaAdapter struct{ spec string } -func (f fakeAlgoliaAdapter) API() string { return "algolia-" + f.spec } +func (f fakeAlgoliaAdapter) API() string { return "algolia/" + f.spec + "-api" } func (fakeAlgoliaAdapter) LatestTag(context.Context) (string, error) { - return "", fmt.Errorf("replay only") + return "", fmt.Errorf("pairs only") } func (f fakeAlgoliaAdapter) Fetch(_ context.Context, tag string) (adapter.Spec, error) { @@ -76,8 +76,8 @@ func TestAlgoliaGolden(t *testing.T) { t.Run(c.spec, func(t *testing.T) { ctx := context.Background() s := openStore(t) - if rejected, err := kittest.Replay(ctx, vercelEnv(s), s, algoliaPlugin(c.spec), c.from, c.to); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, algoliaPlugin(c.spec), c.from, c.to); err != nil || rejected { + t.Fatalf("pair: rejected=%v err=%v", rejected, err) } events := kittest.Stored(t, s) if len(events) != c.ops { @@ -113,8 +113,8 @@ func TestAlgoliaDropsRemovalsThatWerentDeprecated(t *testing.T) { ctx := context.Background() const from, to = "released-2024-09-18-cc190fae3", "released-2024-09-19-a62c27d3b" s := openStore(t) - if rejected, err := kittest.Replay(ctx, vercelEnv(s), s, algoliaPlugin("ingestion"), from, to); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, algoliaPlugin("ingestion"), from, to); err != nil || rejected { + t.Fatalf("pair: rejected=%v err=%v", rejected, err) } if events := kittest.Stored(t, s); len(events) != 0 { t.Fatalf("%d events, want none", len(events)) @@ -122,7 +122,7 @@ func TestAlgoliaDropsRemovalsThatWerentDeprecated(t *testing.T) { s = openStore(t) p := algoliaPlugin("ingestion") p.Keep = nil - if _, err := kittest.Replay(ctx, vercelEnv(s), s, p, from, to); err != nil { + if _, err := kittest.Pair(ctx, vercelEnv(s), s, p, from, to); err != nil { t.Fatal(err) } var removed int @@ -165,8 +165,8 @@ func TestAlgoliaRecommendCustomRequestMoveIsNoEvent(t *testing.T) { ctx := context.Background() const from, to = "released-2024-03-19-2eac6f410", "released-2024-03-25-30207fcd0" s := openStore(t) - if rejected, err := kittest.Replay(ctx, vercelEnv(s), s, algoliaPlugin("recommend"), from, to); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, algoliaPlugin("recommend"), from, to); err != nil || rejected { + t.Fatalf("pair: rejected=%v err=%v", rejected, err) } if events := kittest.Stored(t, s); len(events) != 0 { t.Fatalf("%d events, want none", len(events)) @@ -174,7 +174,7 @@ func TestAlgoliaRecommendCustomRequestMoveIsNoEvent(t *testing.T) { s = openStore(t) p := algoliaPlugin("recommend") p.Keep = nil - if _, err := kittest.Replay(ctx, vercelEnv(s), s, p, from, to); err != nil { + if _, err := kittest.Pair(ctx, vercelEnv(s), s, p, from, to); err != nil { t.Fatal(err) } var removed int diff --git a/plugins/openapi/appwrite_test.go b/plugins/openapi/appwrite_test.go index 04f84cc..047200d 100644 --- a/plugins/openapi/appwrite_test.go +++ b/plugins/openapi/appwrite_test.go @@ -98,11 +98,11 @@ func appwritePlugin(t *testing.T) (Plugin, string) { return Plugin{Adapter: a, Diff: appwriteDiff, Keep: appwriteKeep}, srv.URL + "/raw/appwrite/specs" } -func replayAppwrite(t *testing.T, p Plugin, from, to string) []event.EventV2 { +func pairAppwrite(t *testing.T, p Plugin, from, to string) []event.Event { t.Helper() s := openStore(t) - if rejected, err := kittest.Replay(context.Background(), vercelEnv(s), s, p, from, to); err != nil || rejected { - t.Fatalf("replay %s -> %s: rejected=%v err=%v", from, to, rejected, err) + if rejected, err := kittest.Pair(context.Background(), vercelEnv(s), s, p, from, to); err != nil || rejected { + t.Fatalf("pair %s -> %s: rejected=%v err=%v", from, to, rejected, err) } return kittest.Stored(t, s) } @@ -122,7 +122,7 @@ func TestAppwriteRegistersItself(t *testing.T) { // quotes x-appwrite.deprecated in the file as published. func TestAppwriteGolden(t *testing.T) { p, base := appwritePlugin(t) - events := replayAppwrite(t, p, appwrite19Old, appwrite19New) + events := pairAppwrite(t, p, appwrite19Old, appwrite19New) if len(events) != 14 { t.Fatalf("%d events, want 14", len(events)) } @@ -153,14 +153,14 @@ func TestAppwriteGolden(t *testing.T) { // day. As the adapter reads it, 13 removals; no event: removals never are. func TestAppwriteDropsRemovals(t *testing.T) { p, _ := appwritePlugin(t) - if events := replayAppwrite(t, p, appwrite24Old, appwrite24New); len(events) != 0 { + if events := pairAppwrite(t, p, appwrite24Old, appwrite24New); len(events) != 0 { t.Fatalf("%d events, want none: %s", len(events), events[0].Subject.Operation) } // Unfiltered, the same pair reports the 13 removals. p.Keep = nil var removed int - for _, e := range replayAppwrite(t, p, appwrite24Old, appwrite24New) { - if e.ChangeType == event.ChangeTypeBreaking && e.Subject.Kind == event.AffectedKindOperation { + for _, e := range pairAppwrite(t, p, appwrite24Old, appwrite24New) { + if e.ChangeType == event.ChangeTypeBreaking && e.Subject.Kind == event.KindOperation { removed++ } } @@ -180,11 +180,11 @@ func TestAppwriteDropsRemovals(t *testing.T) { // flag, 21. func TestAppwriteDropsSDKMethodRenames(t *testing.T) { p, _ := appwritePlugin(t) - if events := replayAppwrite(t, p, "1.7.x@"+appwrite18, appwrite18); len(events) != 0 { + if events := pairAppwrite(t, p, "1.7.x@"+appwrite18, appwrite18); len(events) != 0 { t.Fatalf("%d events, want none: %s", len(events), events[0].Subject.Operation) } p.Diff.FlagNotDeprecation = nil - events := replayAppwrite(t, p, "1.7.x@"+appwrite18, appwrite18) + events := pairAppwrite(t, p, "1.7.x@"+appwrite18, appwrite18) if len(events) != 21 { t.Fatalf("every flag read: %d events, want 21", len(events)) } diff --git a/plugins/openapi/convex_test.go b/plugins/openapi/convex_test.go index 21c7613..098d8ca 100644 --- a/plugins/openapi/convex_test.go +++ b/plugins/openapi/convex_test.go @@ -26,7 +26,7 @@ var convexCommits = map[string][2]string{ // copied from, as adapter.Convex.Fetch cites it. type fakeConvexAdapter struct{ latest string } -func (fakeConvexAdapter) API() string { return "convex" } +func (fakeConvexAdapter) API() string { return "convex/deployment-api" } func (f fakeConvexAdapter) LatestTag(context.Context) (string, error) { return f.latest, nil } @@ -84,8 +84,8 @@ var convexReplacements = map[string]string{ func TestConvexGolden(t *testing.T) { ctx := context.Background() s := openStore(t) - if rejected, err := kittest.Replay(ctx, vercelEnv(s), s, convexPlugin(""), "f35879bb", "5e5159cb"); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, convexPlugin(""), "f35879bb", "5e5159cb"); err != nil || rejected { + t.Fatalf("pair: rejected=%v err=%v", rejected, err) } events := kittest.Stored(t, s) if len(events) != len(convexReplacements) { @@ -137,8 +137,8 @@ func TestConvexGolden(t *testing.T) { func TestConvexDropsPropertyChangesThatWerentDeprecations(t *testing.T) { ctx := context.Background() s := openStore(t) - if rejected, err := kittest.Replay(ctx, vercelEnv(s), s, convexPlugin(""), "3f6edf7a", "3ead9091"); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, convexPlugin(""), "3f6edf7a", "3ead9091"); err != nil || rejected { + t.Fatalf("pair: rejected=%v err=%v", rejected, err) } if events := kittest.Stored(t, s); len(events) != 0 { t.Fatalf("stored %d events, want none", len(events)) @@ -148,7 +148,7 @@ func TestConvexDropsPropertyChangesThatWerentDeprecations(t *testing.T) { s = openStore(t) p := convexPlugin("") p.Keep = nil - if _, err := kittest.Replay(ctx, vercelEnv(s), s, p, "3f6edf7a", "3ead9091"); err != nil { + if _, err := kittest.Pair(ctx, vercelEnv(s), s, p, "3f6edf7a", "3ead9091"); err != nil { t.Fatal(err) } unfiltered := kittest.Stored(t, s) diff --git a/plugins/openapi/datadog_test.go b/plugins/openapi/datadog_test.go index 908ba5c..fa486e5 100644 --- a/plugins/openapi/datadog_test.go +++ b/plugins/openapi/datadog_test.go @@ -16,7 +16,7 @@ import ( // YAML to JSON the same way adapter.Datadog.Fetch does. type fakeDatadogAdapter struct{} -func (fakeDatadogAdapter) API() string { return "datadog" } +func (fakeDatadogAdapter) API() string { return "datadog/api" } func (fakeDatadogAdapter) LatestTag(context.Context) (string, error) { return "2.61.0", nil } @@ -38,20 +38,20 @@ func (fakeDatadogAdapter) Fetch(_ context.Context, tag string) (adapter.Spec, er return adapter.Spec{Content: content, Version: tag, SourceURL: sourceURL}, nil } -// The golden test and the replay fixture in one: testdata/datadog-2.60.0.yaml +// The golden test and the pair fixture in one: testdata/datadog-2.60.0.yaml // and datadog-2.61.0.yaml are real, trimmed excerpts of // datadog-api-client-python's bundled spec at those two tags (checked // 2026-11-13). Between them, PR #4045 removed queried_tags_window_seconds and // related_asset_tags from TagIndexingRuleDynamicTags — a real historical // breaking change, not an invented one. This is the pair -// the plugin's Replay from 2.60.0 to 2.61.0 recreates. -func TestDatadogReplayRecreatesTheRealPropertyRemoval(t *testing.T) { +// the pair 2.60.0 → 2.61.0 recreates. +func TestDatadogPairRecreatesTheRealPropertyRemoval(t *testing.T) { ctx := context.Background() s := openStore(t) - rejected, err := replayWith(ctx, s, Plugin{Adapter: fakeDatadogAdapter{}}, "2.60.0", "2.61.0") + rejected, err := pairWith(ctx, s, Plugin{Adapter: fakeDatadogAdapter{}}, "2.60.0", "2.61.0") if err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + t.Fatalf("pair: rejected=%v err=%v", rejected, err) } events, err := s.All() @@ -78,8 +78,8 @@ func TestDatadogReplayRecreatesTheRealPropertyRemoval(t *testing.T) { // Acceptance criteria: every event carries source_url and a non-empty // source_excerpt, and is placed on the real tags, not stand-ins. for _, e := range events { - if e.API != "datadog" || e.Version != "2.61.0" || e.PreviousVersion != "2.60.0" { - t.Errorf("event %s: api=%s version=%s previous_version=%s, want datadog 2.61.0 from 2.60.0", + if e.API != "datadog/api" || e.Version != "2.61.0" || e.PreviousVersion != "2.60.0" { + t.Errorf("event %s: api=%s version=%s previous_version=%s, want datadog/api 2.61.0 from 2.60.0", e.Subject.Property, e.API, e.Version, e.PreviousVersion) } if e.SourceURL == "" || e.SourceExcerpt == "" { @@ -87,11 +87,11 @@ func TestDatadogReplayRecreatesTheRealPropertyRemoval(t *testing.T) { } } - // Replaying the same pair again must not duplicate the events. - if _, err := replayWith(ctx, s, Plugin{Adapter: fakeDatadogAdapter{}}, "2.60.0", "2.61.0"); err != nil { - t.Fatalf("second replay: %v", err) + // Reading the same pair again must not duplicate the events. + if _, err := pairWith(ctx, s, Plugin{Adapter: fakeDatadogAdapter{}}, "2.60.0", "2.61.0"); err != nil { + t.Fatalf("second read of the pair: %v", err) } if again, _ := s.All(); len(again) != len(events) { - t.Errorf("repeating the replay added events: %d -> %d", len(events), len(again)) + t.Errorf("reading the pair again added events: %d -> %d", len(events), len(again)) } } diff --git a/plugins/openapi/elasticsearch_test.go b/plugins/openapi/elasticsearch_test.go index 402ad23..10ec11a 100644 --- a/plugins/openapi/elasticsearch_test.go +++ b/plugins/openapi/elasticsearch_test.go @@ -24,9 +24,9 @@ var esHeads = map[string]string{ type fakeESAdapter struct{} -func (fakeESAdapter) API() string { return "elasticsearch" } +func (fakeESAdapter) API() string { return "elastic/elasticsearch-api" } -func (fakeESAdapter) LatestTag(context.Context) (string, error) { return "", fmt.Errorf("replay only") } +func (fakeESAdapter) LatestTag(context.Context) (string, error) { return "", fmt.Errorf("pairs only") } func (fakeESAdapter) Fetch(_ context.Context, branch string) (adapter.Spec, error) { if _, ok := esHeads[branch]; !ok { @@ -71,8 +71,8 @@ func TestElasticsearchNoRemovalWithinAMinor(t *testing.T) { s := openStore(t) p := esPlugin() p.Adapter = sameMinor{} - if rejected, err := kittest.Replay(ctx, vercelEnv(s), s, p, "8.19", "9.0"); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, p, "8.19", "9.0"); err != nil || rejected { + t.Fatalf("pair: rejected=%v err=%v", rejected, err) } n := map[event.ChangeType]int{} for _, e := range kittest.Stored(t, s) { @@ -92,8 +92,8 @@ func TestElasticsearchNoRemovalWithinAMinor(t *testing.T) { func TestElasticsearchGolden(t *testing.T) { ctx := context.Background() s := openStore(t) - if rejected, err := kittest.Replay(ctx, vercelEnv(s), s, esPlugin(), "8.19", "9.0"); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, esPlugin(), "8.19", "9.0"); err != nil || rejected { + t.Fatalf("pair: rejected=%v err=%v", rejected, err) } events := kittest.Stored(t, s) byType := map[event.ChangeType][]string{} @@ -142,8 +142,8 @@ func TestElasticsearchGolden(t *testing.T) { func TestElasticsearchDropsUndeprecatedRemovals(t *testing.T) { ctx := context.Background() s := openStore(t) - if rejected, err := kittest.Replay(ctx, vercelEnv(s), s, esPlugin(), "9.1", "9.2"); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, esPlugin(), "9.1", "9.2"); err != nil || rejected { + t.Fatalf("pair: rejected=%v err=%v", rejected, err) } if events := kittest.Stored(t, s); len(events) != 0 { t.Fatalf("%d events, want none", len(events)) @@ -151,7 +151,7 @@ func TestElasticsearchDropsUndeprecatedRemovals(t *testing.T) { s = openStore(t) p := esPlugin() p.Keep = nil - if _, err := kittest.Replay(ctx, vercelEnv(s), s, p, "9.1", "9.2"); err != nil { + if _, err := kittest.Pair(ctx, vercelEnv(s), s, p, "9.1", "9.2"); err != nil { t.Fatal(err) } var removed int diff --git a/plugins/openapi/flagsmith_test.go b/plugins/openapi/flagsmith_test.go index eaea1df..1b91b06 100644 --- a/plugins/openapi/flagsmith_test.go +++ b/plugins/openapi/flagsmith_test.go @@ -44,7 +44,7 @@ func TestFlagsmithRegistersItself(t *testing.T) { // trimmed from Version the same way adapter.Flagsmith.Fetch does. type fakeFlagsmithAdapter struct{} -func (fakeFlagsmithAdapter) API() string { return "flagsmith" } +func (fakeFlagsmithAdapter) API() string { return "flagsmith/api" } func (fakeFlagsmithAdapter) LatestTag(context.Context) (string, error) { return "v2.287.0", nil } @@ -72,15 +72,15 @@ func (fakeFlagsmithAdapter) Fetch(_ context.Context, tag string) (adapter.Spec, }, nil } -// The golden test and the replay fixture: the real removal of the three +// The golden test and the pair fixture: the real removal of the three // experimental flag-update endpoints between v2.286.0 and v2.287.0. func TestFlagsmithGolden(t *testing.T) { ctx := context.Background() env := kittest.Env(t, nil) sink := env.Baselines.(kittest.Sink) p := Plugin{Adapter: fakeFlagsmithAdapter{}, Keep: requestSide} - if rejected, err := kittest.Replay(ctx, env, sink, p, "v2.286.0", "v2.287.0"); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + if rejected, err := kittest.Pair(ctx, env, sink, p, "v2.286.0", "v2.287.0"); err != nil || rejected { + t.Fatalf("pair: rejected=%v err=%v", rejected, err) } kittest.Golden(t, "testdata/golden/flagsmith.json", kittest.Stored(t, sink)) } @@ -92,8 +92,8 @@ func TestFlagsmithDropsADescriptionOnlyChange(t *testing.T) { env := kittest.Env(t, nil) sink := env.Baselines.(kittest.Sink) p := Plugin{Adapter: fakeFlagsmithAdapter{}, Keep: requestSide} - if rejected, err := kittest.Replay(ctx, env, sink, p, "c3ef832", "f504f16"); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + if rejected, err := kittest.Pair(ctx, env, sink, p, "c3ef832", "f504f16"); err != nil || rejected { + t.Fatalf("pair: rejected=%v err=%v", rejected, err) } if got := kittest.Stored(t, sink); len(got) != 0 { t.Errorf("%d events from a description-only change, want none", len(got)) diff --git a/plugins/openapi/github_test.go b/plugins/openapi/github_test.go index 4496f7a..9239b88 100644 --- a/plugins/openapi/github_test.go +++ b/plugins/openapi/github_test.go @@ -14,7 +14,7 @@ import ( // Datadog's, github's spec is already JSON, so there's no conversion step. type fakeGitHubAdapter struct{} -func (fakeGitHubAdapter) API() string { return "github" } +func (fakeGitHubAdapter) API() string { return "github/rest-api" } func (fakeGitHubAdapter) LatestTag(context.Context) (string, error) { return "2026-03-10", nil } @@ -28,21 +28,21 @@ func (fakeGitHubAdapter) Fetch(_ context.Context, tag string) (adapter.Spec, err return adapter.Spec{Content: body, Version: tag, SourceURL: sourceURL}, nil } -// The golden test and the replay fixture in one: testdata/github-2022-11-28.json +// The golden test and the pair fixture in one: testdata/github-2022-11-28.json // and github-2026-03-10.json are real, trimmed excerpts of github's own bundled // REST API description at those two dated API versions (checked 2026-11-14). // Between them, GitHub's documented breaking change for 2026-03-10 ("Remove // deprecated rate property from rate limit endpoint") dropped the required // `rate` property from the `rate-limit-overview` schema — a real historical // breaking change, not an invented one. This is the pair -// the plugin's Replay from 2022-11-28 to 2026-03-10 recreates. -func TestGitHubReplayRecreatesTheRealPropertyRemoval(t *testing.T) { +// the pair 2022-11-28 → 2026-03-10 recreates. +func TestGitHubPairRecreatesTheRealPropertyRemoval(t *testing.T) { ctx := context.Background() s := openStore(t) - rejected, err := replayWith(ctx, s, Plugin{Adapter: fakeGitHubAdapter{}}, "2022-11-28", "2026-03-10") + rejected, err := pairWith(ctx, s, Plugin{Adapter: fakeGitHubAdapter{}}, "2022-11-28", "2026-03-10") if err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + t.Fatalf("pair: rejected=%v err=%v", rejected, err) } events, err := s.All() @@ -59,19 +59,19 @@ func TestGitHubReplayRecreatesTheRealPropertyRemoval(t *testing.T) { // Acceptance criteria: the event carries source_url and a non-empty // source_excerpt, and is placed on the real dated versions, not stand-ins. - if e.API != "github" || e.Version != "2026-03-10" || e.PreviousVersion != "2022-11-28" { - t.Errorf("event %s: api=%s version=%s previous_version=%s, want github 2026-03-10 from 2022-11-28", + if e.API != "github/rest-api" || e.Version != "2026-03-10" || e.PreviousVersion != "2022-11-28" { + t.Errorf("event %s: api=%s version=%s previous_version=%s, want github/rest-api 2026-03-10 from 2022-11-28", e.Subject.Property, e.API, e.Version, e.PreviousVersion) } if e.SourceURL == "" || e.SourceExcerpt == "" { t.Errorf("event %s: missing provenance", e.Subject.Property) } - // Replaying the same pair again must not duplicate the event. - if _, err := replayWith(ctx, s, Plugin{Adapter: fakeGitHubAdapter{}}, "2022-11-28", "2026-03-10"); err != nil { - t.Fatalf("second replay: %v", err) + // Reading the same pair again must not duplicate the event. + if _, err := pairWith(ctx, s, Plugin{Adapter: fakeGitHubAdapter{}}, "2022-11-28", "2026-03-10"); err != nil { + t.Fatalf("second read of the pair: %v", err) } if again, _ := s.All(); len(again) != len(events) { - t.Errorf("repeating the replay added events: %d -> %d", len(events), len(again)) + t.Errorf("reading the pair again added events: %d -> %d", len(events), len(again)) } } diff --git a/plugins/openapi/gitlab_test.go b/plugins/openapi/gitlab_test.go index a61851f..cafdd13 100644 --- a/plugins/openapi/gitlab_test.go +++ b/plugins/openapi/gitlab_test.go @@ -24,7 +24,7 @@ func gitlabPlugin(t *testing.T) (Plugin, string) { return Plugin{Adapter: adapter.GitLab{SpecURLTemplate: tmpl}, Keep: requestSide}, tmpl } -// The golden test and the replay fixture in one: testdata/gitlab-v18.11.0-ee.yaml +// The golden test and the pair fixture in one: testdata/gitlab-v18.11.0-ee.yaml // and gitlab-v19.0.0-ee.yaml are trimmed, unedited excerpts of GitLab's // OpenAPI spec at those two tags (checked 2026-11-15). GitLab 19.0 removed app // passwords from the Bitbucket Cloud import API ("Using app passwords with @@ -32,19 +32,19 @@ func gitlabPlugin(t *testing.T) (Plugin, string) { // docs.gitlab.com/update/deprecations): bitbucket_username and // bitbucket_app_password are gone from POST /api/v4/import/bitbucket, and // bitbucket_email and bitbucket_api_token became required. This is the pair -// the plugin's Replay from v18.11.0-ee to v19.0.0-ee recreates. +// the pair v18.11.0-ee → v19.0.0-ee recreates. // // The excerpts also keep APIEntitiesBadge, whose id went from the generator's // default "string" to "integer" in the same release while the API kept // returning the same JSON: the response-side noise requestSide drops. -func TestGitLabReplayRecreatesTheBitbucketAppPasswordRemoval(t *testing.T) { +func TestGitLabPairRecreatesTheBitbucketAppPasswordRemoval(t *testing.T) { ctx := context.Background() s := openStore(t) p, tmpl := gitlabPlugin(t) - rejected, err := replayWith(ctx, s, p, "v18.11.0-ee", "v19.0.0-ee") + rejected, err := pairWith(ctx, s, p, "v18.11.0-ee", "v19.0.0-ee") if err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + t.Fatalf("pair: rejected=%v err=%v", rejected, err) } events, err := s.All() if err != nil { @@ -84,7 +84,7 @@ func TestGitLabReplayRecreatesTheBitbucketAppPasswordRemoval(t *testing.T) { t.Errorf("unexpected event: %s", e.Description) continue } - if e.API != "gitlab" || e.Version != "19.0.0" || e.PreviousVersion != "18.11.0" { + if e.API != "gitlab/rest-api" || e.Version != "19.0.0" || e.PreviousVersion != "18.11.0" { t.Errorf("%s: api=%s version=%s previous=%s", e.Subject.Property, e.API, e.Version, e.PreviousVersion) } if string(e.ChangeType) != "breaking" || !e.Breaking { @@ -110,12 +110,12 @@ func TestGitLabReplayRecreatesTheBitbucketAppPasswordRemoval(t *testing.T) { } } - // Replaying the same pair again must not duplicate the events. - if _, err := replayWith(ctx, s, p, "v18.11.0-ee", "v19.0.0-ee"); err != nil { - t.Fatalf("second replay: %v", err) + // Reading the same pair again must not duplicate the events. + if _, err := pairWith(ctx, s, p, "v18.11.0-ee", "v19.0.0-ee"); err != nil { + t.Fatalf("second read of the pair: %v", err) } if again, _ := s.All(); len(again) != len(events) { - t.Errorf("repeating the replay added events: %d -> %d", len(events), len(again)) + t.Errorf("reading the pair again added events: %d -> %d", len(events), len(again)) } } @@ -127,8 +127,8 @@ func TestGitLabResponseSideNoiseIsWhatTheFilterDrops(t *testing.T) { p, _ := gitlabPlugin(t) p.Keep = nil - if _, err := replayWith(ctx, s, p, "v18.11.0-ee", "v19.0.0-ee"); err != nil { - t.Fatalf("replay: %v", err) + if _, err := pairWith(ctx, s, p, "v18.11.0-ee", "v19.0.0-ee"); err != nil { + t.Fatalf("pair: %v", err) } events, _ := s.All() var badge bool @@ -138,7 +138,7 @@ func TestGitLabResponseSideNoiseIsWhatTheFilterDrops(t *testing.T) { } } if !badge { - t.Error("unfiltered replay has no APIEntitiesBadge.id event; the fixture no longer shows what requestSide is for") + t.Error("unfiltered pair has no APIEntitiesBadge.id event; the fixture no longer shows what requestSide is for") } } diff --git a/plugins/openapi/neon_test.go b/plugins/openapi/neon_test.go index ac726f6..09ed7e0 100644 --- a/plugins/openapi/neon_test.go +++ b/plugins/openapi/neon_test.go @@ -30,7 +30,7 @@ var neonCommits = map[string][2]string{ // copied from and reshaped, as adapter.Neon.Fetch cites and reshapes it. type fakeNeonAdapter struct{ latest string } -func (fakeNeonAdapter) API() string { return "neon" } +func (fakeNeonAdapter) API() string { return "neon/api" } func (f fakeNeonAdapter) LatestTag(context.Context) (string, error) { return f.latest, nil } @@ -67,7 +67,7 @@ func neonPlugin(a adapter.Adapter) Plugin { return Plugin{Adapter: a, Diff: neonDiff, Keep: neonKeep} } -// The golden test, the replay fixture: the one operation Neon deprecated in +// The golden test, the pair fixture: the one operation Neon deprecated in // neon-pkgs's copy of the spec. On 2026-08-23 POST // /projects/{project_id}/branches/{branch_id}/auth/send_test_email (beta) // gained the flag, an x-sunset of 2027-02-28 and "Deprecated: to test a @@ -77,8 +77,8 @@ func neonPlugin(a adapter.Adapter) Plugin { func TestNeonGolden(t *testing.T) { ctx := context.Background() s := openStore(t) - if rejected, err := kittest.Replay(ctx, vercelEnv(s), s, neonPlugin(fakeNeonAdapter{}), "5c57d009", "93b93dc9"); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, neonPlugin(fakeNeonAdapter{}), "5c57d009", "93b93dc9"); err != nil || rejected { + t.Fatalf("pair: rejected=%v err=%v", rejected, err) } events := kittest.Stored(t, s) if len(events) != 1 { @@ -117,8 +117,8 @@ func TestNeonGolden(t *testing.T) { func TestNeonDropsRemovalsThatWerentDeprecated(t *testing.T) { ctx := context.Background() s := openStore(t) - if rejected, err := kittest.Replay(ctx, vercelEnv(s), s, neonPlugin(fakeNeonAdapter{}), "4c6b3be4", "4497de89"); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, neonPlugin(fakeNeonAdapter{}), "4c6b3be4", "4497de89"); err != nil || rejected { + t.Fatalf("pair: rejected=%v err=%v", rejected, err) } if events := kittest.Stored(t, s); len(events) != 0 { t.Fatalf("stored %d events, want none", len(events)) @@ -127,7 +127,7 @@ func TestNeonDropsRemovalsThatWerentDeprecated(t *testing.T) { s = openStore(t) p := neonPlugin(fakeNeonAdapter{}) p.Keep = nil - if _, err := kittest.Replay(ctx, vercelEnv(s), s, p, "4c6b3be4", "4497de89"); err != nil { + if _, err := kittest.Pair(ctx, vercelEnv(s), s, p, "4c6b3be4", "4497de89"); err != nil { t.Fatal(err) } var removals []string @@ -152,7 +152,7 @@ func TestNeonDropsRemovalsThatWerentDeprecated(t *testing.T) { // /consumption_history/account` endpoint has been removed." type neonAPIClient struct{} -func (neonAPIClient) API() string { return "neon" } +func (neonAPIClient) API() string { return "neon/api" } func (neonAPIClient) LatestTag(context.Context) (string, error) { return "2.7.3", nil } @@ -178,8 +178,8 @@ func (neonAPIClient) Fetch(_ context.Context, version string) (adapter.Spec, err func TestNeonKeepsTheRemovalOfADeprecatedOperation(t *testing.T) { ctx := context.Background() s := openStore(t) - if rejected, err := kittest.Replay(ctx, vercelEnv(s), s, neonPlugin(neonAPIClient{}), "2.7.2", "2.7.3"); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, neonPlugin(neonAPIClient{}), "2.7.2", "2.7.3"); err != nil || rejected { + t.Fatalf("pair: rejected=%v err=%v", rejected, err) } events := kittest.Stored(t, s) if len(events) != 1 { diff --git a/plugins/openapi/openapi.go b/plugins/openapi/openapi.go index 61eeda4..cdae1f6 100644 --- a/plugins/openapi/openapi.go +++ b/plugins/openapi/openapi.go @@ -3,7 +3,8 @@ // Algolia, Elasticsearch, Sentry, Neon, Convex, PlanetScale, Appwrite): fetch // the newest spec, diff it against the last one seen, normalize the changes // into events, and attach migration hints from the API's changelog when it -// has one. It can also replay two given releases. +// has one. Every release is listed and each consecutive pair diffed +// (ListVersions, ReadAt, Extract). package openapi import ( @@ -14,7 +15,6 @@ import ( "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" @@ -25,9 +25,10 @@ func init() { ID: "stripe", Name: "Stripe", Category: plugin.CategoryPayments, Homepage: "https://stripe.com", Sources: []plugin.Source{{ ID: "api", Layer: plugin.LayerAPI, Page: "providers/stripe.md", - Watches: "REST API changes between OpenAPI spec releases (removed and renamed endpoints, parameters and fields), with migration hints from Stripe's API changelog", - URLs: []string{"https://github.com/stripe/openapi"}, - Plugin: Plugin{Adapter: adapter.Stripe{}, Hints: hint.Stripe{}}, + Watches: "REST API changes between OpenAPI spec releases (removed and renamed endpoints, parameters and fields), with migration hints from Stripe's API changelog", + URLs: []string{"https://github.com/stripe/openapi"}, + Packages: []string{"pypi:stripe", "npm:stripe"}, + Plugin: Plugin{Adapter: adapter.Stripe{}, Hints: hint.Stripe{}}, }}, }) // No Hints yet: Datadog's changelog isn't Stripe's per-parameter table @@ -36,9 +37,10 @@ func init() { ID: "datadog", Name: "Datadog", Category: plugin.CategoryMonitoring, Homepage: "https://www.datadoghq.com", Sources: []plugin.Source{{ ID: "api", Layer: plugin.LayerAPI, Page: "providers/datadog.md", - Watches: "API v2 changes between OpenAPI spec releases", - URLs: []string{"https://github.com/DataDog/datadog-api-client-python"}, - Plugin: Plugin{Adapter: adapter.Datadog{}}, + Watches: "API v2 changes between OpenAPI spec releases", + URLs: []string{"https://github.com/DataDog/datadog-api-client-python"}, + Packages: []string{"pypi:datadog-api-client", "npm:@datadog/datadog-api-client"}, + Plugin: Plugin{Adapter: adapter.Datadog{}}, }}, }) // No Hints: GitLab's deprecations are prose per feature, not a changelog @@ -54,7 +56,7 @@ func init() { }) // No Hints yet: GitHub's per-version CHANGELOG.md is prose with no table // at all, so there's nothing for hint.Source to key on. (GitHub's Actions - // source is registered by plugins/feed.) + // source is registered by plugins/notices.) plugin.RegisterProvider(plugin.Provider{ ID: "github", Name: "GitHub", Category: plugin.CategoryDevTools, Homepage: "https://github.com", Sources: []plugin.Source{{ @@ -70,9 +72,10 @@ func init() { ID: "vercel", Name: "Vercel", Category: plugin.CategoryHosting, Homepage: "https://vercel.com", Sources: []plugin.Source{{ ID: "api", Layer: plugin.LayerAPI, Page: "providers/vercel.md", - Watches: "REST API operations deprecated, and deprecated operations removed, between SDK releases of the spec", - URLs: []string{"https://github.com/vercel/sdk"}, - Plugin: Plugin{Adapter: adapter.Vercel{}, Diff: vercelDiff, Keep: vercelKeep}, + Watches: "REST API operations deprecated, and deprecated operations removed, between SDK releases of the spec", + URLs: []string{"https://github.com/vercel/sdk"}, + Packages: []string{"npm:@vercel/sdk"}, + Plugin: Plugin{Adapter: adapter.Vercel{}, Diff: vercelDiff, Keep: vercelKeep}, }}, }) // No Hints: Supabase's changelog is platform news, not keyed by @@ -92,9 +95,10 @@ func init() { for _, spec := range []struct{ name, title string }{{"search", "Search"}, {"ingestion", "Ingestion"}, {"recommend", "Recommend"}} { algolia.Sources = append(algolia.Sources, plugin.Source{ ID: spec.name + "-api", Layer: plugin.LayerAPI, Page: "providers/algolia.md", - Watches: spec.title + " API operations deprecated, and deprecated operations removed, between releases of the spec", - URLs: []string{"https://github.com/algolia/api-clients-automation", "https://github.com/algolia/api-clients-automation/blob/main/specs/bundled/" + spec.name + ".yml"}, - Plugin: Plugin{Adapter: adapter.Algolia{Spec: spec.name}, Diff: algoliaDiff, Keep: algoliaKeep}, + Watches: spec.title + " API operations deprecated, and deprecated operations removed, between releases of the spec", + URLs: []string{"https://github.com/algolia/api-clients-automation", "https://github.com/algolia/api-clients-automation/blob/main/specs/bundled/" + spec.name + ".yml"}, + Packages: []string{"pypi:algoliasearch", "npm:algoliasearch"}, + Plugin: Plugin{Adapter: adapter.Algolia{Spec: spec.name}, Diff: algoliaDiff, Keep: algoliaKeep}, }) } plugin.RegisterProvider(algolia) @@ -104,9 +108,10 @@ func init() { ID: "elastic", Name: "Elastic", Category: plugin.CategorySearch, Homepage: "https://www.elastic.co", Sources: []plugin.Source{{ ID: "elasticsearch-api", Layer: plugin.LayerAPI, Page: "providers/elasticsearch.md", - Watches: "Elasticsearch REST API operations deprecated, and deprecated operations removed, between released minor versions of the spec", - URLs: []string{"https://github.com/elastic/elasticsearch-specification"}, - Plugin: Plugin{Adapter: adapter.Elasticsearch{}, Diff: elasticsearchDiff, Keep: elasticsearchKeep, RemovalsNeedANewVersion: true}, + Watches: "Elasticsearch REST API operations deprecated, and deprecated operations removed, between released minor versions of the spec", + URLs: []string{"https://github.com/elastic/elasticsearch-specification"}, + Packages: []string{"pypi:elasticsearch", "npm:@elastic/elasticsearch"}, + Plugin: Plugin{Adapter: adapter.Elasticsearch{}, Diff: elasticsearchDiff, Keep: elasticsearchKeep, RemovalsNeedANewVersion: true}, }}, }) // No Hints: Sentry's changelog is product news, not keyed by operation. @@ -127,9 +132,10 @@ func init() { ID: "neon", Name: "Neon", Category: plugin.CategoryDatabases, Homepage: "https://neon.com", Sources: []plugin.Source{{ ID: "api", Layer: plugin.LayerAPI, Page: "providers/neon.md", - Watches: "Neon API operations deprecated, and deprecated operations removed, between commits of the spec", - URLs: []string{"https://github.com/neondatabase/neon-pkgs"}, - Plugin: Plugin{Adapter: adapter.Neon{}, Diff: neonDiff, Keep: neonKeep}, + Watches: "Neon API operations deprecated, and deprecated operations removed, between commits of the spec", + URLs: []string{"https://github.com/neondatabase/neon-pkgs"}, + Packages: []string{"npm:@neondatabase/api-client"}, + Plugin: Plugin{Adapter: adapter.Neon{}, Diff: neonDiff, Keep: neonKeep}, }}, }) // No Hints: Convex has no API changelog; its news feed is product news. @@ -162,9 +168,10 @@ func init() { ID: "appwrite", Name: "Appwrite", Category: plugin.CategoryHosting, Homepage: "https://appwrite.io", Sources: []plugin.Source{{ ID: "api", Layer: plugin.LayerAPI, Page: "providers/appwrite.md", - Watches: "REST API operations a server SDK calls that are deprecated between commits of the spec, SDK method renames left out", - URLs: []string{"https://github.com/appwrite/specs"}, - Plugin: Plugin{Adapter: adapter.Appwrite{}, Diff: appwriteDiff, Keep: appwriteKeep}, + Watches: "REST API operations a server SDK calls that are deprecated between commits of the spec, SDK method renames left out", + URLs: []string{"https://github.com/appwrite/specs"}, + Packages: []string{"pypi:appwrite", "npm:node-appwrite"}, + Plugin: Plugin{Adapter: adapter.Appwrite{}, Diff: appwriteDiff, Keep: appwriteKeep}, }}, }) // No Hints: Flagsmith's release notes are product news, not keyed by @@ -243,32 +250,7 @@ func (p Plugin) Run(ctx context.Context, env plugin.Env) (plugin.Result, error) return plugin.Result{}, err } res.Label = tag - res.Baselines = []plugin.Spec{plugin.Baseline(a.API(), to.Version.ID, tag, to.SourceURL, to.Content, false, env.Now())} - return res, nil -} - -// Replay diffs two given releases. Both specs are saved marked as replays, so -// the normal-run baseline never moves; the events are stored like any others: -// that's how a historical change becomes something the feed can serve. -func (p Plugin) Replay(ctx context.Context, env plugin.Env, from, to string) (plugin.Result, error) { - old, err := p.ReadAt(ctx, env, plugin.Version{ID: from, Ref: from}) - if err != nil { - return plugin.Result{}, err - } - next, err := p.ReadAt(ctx, env, plugin.Version{ID: to, Ref: to}) - if err != nil { - return plugin.Result{}, err - } - res, err := p.Extract(ctx, env, old, next) - if err != nil { - return plugin.Result{}, err - } - now := env.Now() - res.Label = to - res.Baselines = []plugin.Spec{ - plugin.Baseline(p.Adapter.API(), old.Version.ID, from, old.SourceURL, old.Content, true, now), - plugin.Baseline(p.Adapter.API(), next.Version.ID, to, next.SourceURL, next.Content, true, now), - } + res.Baselines = []plugin.Spec{plugin.Baseline(a.API(), to.Version.ID, tag, to.SourceURL, to.Content, env.Now())} return res, nil } @@ -319,15 +301,14 @@ func (p Plugin) Extract(ctx context.Context, env plugin.Env, from, to plugin.Sna DetectedAt: env.Now().UTC(), }) p.attachHints(ctx, to.Version.ID, events) - converted, invalid := migrate.Fresh(events) - return plugin.Result{Label: to.Version.Ref, Events: converted, Rejected: append(errs, invalid...)}, nil + return plugin.Result{Label: to.Version.Ref, Events: events, Rejected: errs}, nil } var _ plugin.Versioned = Plugin{} // events diffs two parsed specs into events, applying Keep, and pointing each // event's source_pointer into the published file when the adapter reshaped it. -func (p Plugin) events(oldParsed, newParsed *diff.Spec, oldContent, newContent []byte, src normalize.Source) ([]event.ChangeEvent, []error) { +func (p Plugin) events(oldParsed, newParsed *diff.Spec, oldContent, newContent []byte, src normalize.Source) ([]event.Event, []error) { changes := diff.ChangesWith(oldParsed, newParsed, p.Diff) if p.Keep != nil { kept := changes[:0:0] @@ -373,7 +354,7 @@ func (p Plugin) events(oldParsed, newParsed *diff.Spec, oldContent, newContent [ // attachHints looks the events up in the API's changelog for their version. // Never fails the run: a hint is help for the fix, not provenance for the event. -func (p Plugin) attachHints(ctx context.Context, version string, events []event.ChangeEvent) { +func (p Plugin) attachHints(ctx context.Context, version string, events []event.Event) { if p.Hints == nil || len(events) == 0 { return } diff --git a/plugins/openapi/openapi_test.go b/plugins/openapi/openapi_test.go index d76c60c..ec60e9d 100644 --- a/plugins/openapi/openapi_test.go +++ b/plugins/openapi/openapi_test.go @@ -43,12 +43,12 @@ func ingest(ctx context.Context, s *kittest.Mem, a adapter.Adapter) (bool, error return kittest.Run(ctx, env(s), s, newPlugin(a, noChangelog)) } -func replay(ctx context.Context, s *kittest.Mem, a adapter.Adapter, from, to string) (bool, error) { - return replayWith(ctx, s, newPlugin(a, noChangelog), from, to) +func pair(ctx context.Context, s *kittest.Mem, a adapter.Adapter, from, to string) (bool, error) { + return pairWith(ctx, s, newPlugin(a, noChangelog), from, to) } -func replayWith(ctx context.Context, s *kittest.Mem, p Plugin, from, to string) (bool, error) { - return kittest.Replay(ctx, env(s), s, p, from, to) +func pairWith(ctx context.Context, s *kittest.Mem, p Plugin, from, to string) (bool, error) { + return kittest.Pair(ctx, env(s), s, p, from, to) } // fakeAdapter serves specs from memory, one per tag, so the whole ingest flow @@ -58,7 +58,7 @@ type fakeAdapter struct { specs map[string]string // tag -> spec JSON } -func (fakeAdapter) API() string { return "stripe" } +func (fakeAdapter) API() string { return "stripe/api" } func (f fakeAdapter) LatestTag(context.Context) (string, error) { return f.latest, nil } @@ -131,7 +131,7 @@ func TestIngestStoresTheEventsItFinds(t *testing.T) { } // The baseline moved to v2 only after the events were safely stored. - last, _ := s.LastSpec("stripe") + last, _ := s.LastSpec("stripe/api") if last == nil || last.Version != "version-v2" { t.Errorf("baseline after the second run = %+v, want version-v2", last) } @@ -145,29 +145,29 @@ func TestIngestStoresTheEventsItFinds(t *testing.T) { } } -// Replay (--from/--to) is how the demo change gets recreated: it must store the -// events, and it must never move the normal-run baseline. -func TestReplayStoresEventsWithoutMovingTheBaseline(t *testing.T) { +// A version pair (ReadAt both sides, Extract) stores its events and no +// baseline: a backfill never moves what the next run compares with. +func TestAPairStoresEventsAndNoBaseline(t *testing.T) { ctx := context.Background() s := openStore(t) - if _, err := replay(ctx, s, fakeAdapter{specs: specs}, "v1", "v2"); err != nil { - t.Fatalf("replay: %v", err) + if _, err := pair(ctx, s, fakeAdapter{specs: specs}, "v1", "v2"); err != nil { + t.Fatalf("pair: %v", err) } if got := storedEvents(t, s); len(got) != 2 { - t.Errorf("replay stored %d events, want 2: %v", len(got), got) + t.Errorf("the pair stored %d events, want 2: %v", len(got), got) } - if last, _ := s.LastSpec("stripe"); last != nil { - t.Errorf("replay moved the baseline to %s; replays must never set it", last.Version) + if last, _ := s.LastSpec("stripe/api"); last != nil { + t.Errorf("the pair set a baseline (%s); Extract returns none", last.Version) } - // Replaying the same pair again stores nothing new. + // Reading the same pair again stores nothing new. before := len(storedEvents(t, s)) - if _, err := replay(ctx, s, fakeAdapter{specs: specs}, "v1", "v2"); err != nil { - t.Fatalf("second replay: %v", err) + if _, err := pair(ctx, s, fakeAdapter{specs: specs}, "v1", "v2"); err != nil { + t.Fatalf("second read of the pair: %v", err) } if after := len(storedEvents(t, s)); after != before { - t.Errorf("repeating a replay added events: %d -> %d", before, after) + t.Errorf("reading the pair again added events: %d -> %d", before, after) } } @@ -176,8 +176,8 @@ func TestReplayStoresEventsWithoutMovingTheBaseline(t *testing.T) { func TestIngestStoresEventsWhenTheChangelogIsUnreachable(t *testing.T) { ctx := context.Background() s := openStore(t) - if _, err := replay(ctx, s, fakeAdapter{specs: specs}, "v1", "v2"); err != nil { - t.Fatalf("replay: %v", err) + if _, err := pair(ctx, s, fakeAdapter{specs: specs}, "v1", "v2"); err != nil { + t.Fatalf("pair: %v", err) } events, _ := s.All() if len(events) != 2 { @@ -186,7 +186,7 @@ func TestIngestStoresEventsWhenTheChangelogIsUnreachable(t *testing.T) { } // With a changelog, the entry's text and link become the event's migration hint. -func TestReplayAttachesMigrationHintsFromTheChangelog(t *testing.T) { +func TestAPairAttachesMigrationHintsFromTheChangelog(t *testing.T) { withHints := fakeHints{entries: []hint.Entry{{ Title: "Removes the charges attribute from the PaymentIntent object", URL: "https://docs.stripe.com/changelog/2022-11-15/removes-charges-attribute-paymentintent", @@ -196,11 +196,11 @@ func TestReplayAttachesMigrationHintsFromTheChangelog(t *testing.T) { ctx := context.Background() s := openStore(t) - if _, err := replayWith(ctx, s, newPlugin(fakeAdapter{specs: specs}, withHints), "v1", "v2"); err != nil { - t.Fatalf("replay: %v", err) + if _, err := pairWith(ctx, s, newPlugin(fakeAdapter{specs: specs}, withHints), "v1", "v2"); err != nil { + t.Fatalf("pair: %v", err) } events, _ := s.All() - var removed *event.EventV2 + var removed *event.Event for i := range events { if events[i].Subject.Property == "charges" { removed = &events[i] diff --git a/plugins/openapi/planetscale_test.go b/plugins/openapi/planetscale_test.go index ecf51f3..0da3651 100644 --- a/plugins/openapi/planetscale_test.go +++ b/plugins/openapi/planetscale_test.go @@ -56,11 +56,11 @@ func planetscalePlugin(t *testing.T) (Plugin, string) { return Plugin{Adapter: a, Diff: planetscaleDiff, Keep: planetscaleKeep}, srv.URL + "/raw" + repo } -func replayPlanetScale(t *testing.T, p Plugin, from, to string) []event.EventV2 { +func pairPlanetScale(t *testing.T, p Plugin, from, to string) []event.Event { t.Helper() s := openStore(t) - if rejected, err := kittest.Replay(context.Background(), vercelEnv(s), s, p, from, to); err != nil || rejected { - t.Fatalf("replay %s -> %s: rejected=%v err=%v", from, to, rejected, err) + if rejected, err := kittest.Pair(context.Background(), vercelEnv(s), s, p, from, to); err != nil || rejected { + t.Fatalf("pair %s -> %s: rejected=%v err=%v", from, to, rejected, err) } return kittest.Stored(t, s) } @@ -74,7 +74,7 @@ func replayPlanetScale(t *testing.T, p Plugin, from, to string) []event.EventV2 func TestPlanetScaleGolden(t *testing.T) { p, base := planetscalePlugin(t) const from, to = "e631095aa649a6797578a1d51d861b91e0568aa1", "fc13e09d0c18b893aabd3e02d175d13957bba677" - events := replayPlanetScale(t, p, from, to) + events := pairPlanetScale(t, p, from, to) const branch = "/v1/organizations/{organization}/databases/{database}/branches/{branch}" want := map[string]bool{ "GET " + branch + "/bouncers/{bouncer}/resizes": true, @@ -127,13 +127,13 @@ func TestPlanetScaleGolden(t *testing.T) { func TestPlanetScaleDropsRemovalsThatWerentDeprecated(t *testing.T) { p, _ := planetscalePlugin(t) const from, to = "b49c354080667638b79781801f0517ae07bc55b8", "f6d6ad4d3929f6c1ef021eb13c1541ba31f72107" - if events := replayPlanetScale(t, p, from, to); len(events) != 0 { + if events := pairPlanetScale(t, p, from, to); len(events) != 0 { t.Fatalf("%d events, want none: %s", len(events), events[0].Description) } p.Keep = nil var removed []string - for _, e := range replayPlanetScale(t, p, from, to) { - if e.Breaking && e.Subject.Kind == event.AffectedKindOperation && strings.HasSuffix(e.Description, " removed.") { + for _, e := range pairPlanetScale(t, p, from, to) { + if e.Breaking && e.Subject.Kind == event.KindOperation && strings.HasSuffix(e.Description, " removed.") { removed = append(removed, e.Subject.Operation) } } diff --git a/plugins/openapi/sentry_test.go b/plugins/openapi/sentry_test.go index c435b28..80b8b0c 100644 --- a/plugins/openapi/sentry_test.go +++ b/plugins/openapi/sentry_test.go @@ -80,12 +80,12 @@ func sentryPlugin(t *testing.T) (Plugin, string) { return Plugin{Adapter: a, Diff: sentryDiff, Keep: sentryKeep}, srv.URL + "/raw/getsentry/sentry-api-schema" } -func replaySentry(t *testing.T, p Plugin, pairs ...[2]string) []event.EventV2 { +func pairSentry(t *testing.T, p Plugin, pairs ...[2]string) []event.Event { t.Helper() s := openStore(t) for _, pair := range pairs { - if rejected, err := kittest.Replay(context.Background(), vercelEnv(s), s, p, pair[0], pair[1]); err != nil || rejected { - t.Fatalf("replay %s -> %s: rejected=%v err=%v", pair[0], pair[1], rejected, err) + if rejected, err := kittest.Pair(context.Background(), vercelEnv(s), s, p, pair[0], pair[1]); err != nil || rejected { + t.Fatalf("pair %s -> %s: rejected=%v err=%v", pair[0], pair[1], rejected, err) } } return kittest.Stored(t, s) @@ -105,7 +105,7 @@ func replaySentry(t *testing.T, p Plugin, pairs ...[2]string) []event.EventV2 { // Each event cites the description, in the commit's file. func TestSentryGolden(t *testing.T) { p, base := sentryPlugin(t) - events := replaySentry(t, p, + events := pairSentry(t, p, [2]string{"ead7f0cf9ccb8ac817105ac11bb94fe316fcb337", "4650a66a859e015cccef2c171b115633321768e9"}, [2]string{"d64149d65723484ca4d34c956ad017a66e1a4e07", "c2f638f601baadcb055aec4ca3c2ba9f2654c087"}, [2]string{"47231e6180b34f222ed462b1d0cb3cdb951cc4e7", "1da1f31fac696201b1a7d20046fc199c8b1324b6"}, @@ -152,11 +152,11 @@ func TestSentryGolden(t *testing.T) { // date both deprecations 2026-06-16. func TestSentryFlagAfterWordsIsNotNew(t *testing.T) { p, _ := sentryPlugin(t) - if events := replaySentry(t, p, [2]string{"0.223.0", "0.224.0"}); len(events) != 0 { + if events := pairSentry(t, p, [2]string{"0.223.0", "0.224.0"}); len(events) != 0 { t.Fatalf("%d events, want none", len(events)) } p.Diff.DeprecatedDescription = nil - events := replaySentry(t, p, [2]string{"0.223.0", "0.224.0"}) + events := pairSentry(t, p, [2]string{"0.223.0", "0.224.0"}) var ops []string for _, e := range events { if strings.HasSuffix(e.SourcePointer, "/description") || !strings.Contains(e.SourceExcerpt, `"deprecated":true`) { @@ -173,8 +173,8 @@ func TestSentryFlagAfterWordsIsNotNew(t *testing.T) { // moving /api/0 into the paths. type rawSentry struct{} -func (rawSentry) API() string { return "sentry" } -func (rawSentry) LatestTag(context.Context) (string, error) { return "", fmt.Errorf("replay only") } +func (rawSentry) API() string { return "sentry/api" } +func (rawSentry) LatestTag(context.Context) (string, error) { return "", fmt.Errorf("pairs only") } func (rawSentry) Fetch(_ context.Context, tag string) (adapter.Spec, error) { body, err := os.ReadFile(sentryFile(tag)) return adapter.Spec{Content: body, Version: sentryTags[tag][:10], SourceURL: "https://example.invalid/" + tag}, err @@ -187,15 +187,15 @@ func (rawSentry) Fetch(_ context.Context, tag string) (adapter.Spec, error) { // rule that kept removals of deprecated operations would report it shut down. func TestSentryBasePathMoveIsNoChange(t *testing.T) { p, base := sentryPlugin(t) - if events := replaySentry(t, p, [2]string{"2.0.1", "2.1.0"}); len(events) != 0 { + if events := pairSentry(t, p, [2]string{"2.0.1", "2.1.0"}); len(events) != 0 { t.Fatalf("%d events, want none", len(events)) } // Unfiltered, what the move leaves is a few property changes, and every // pointer names a node in the file as published, without /api/0. p.Keep = nil - for _, e := range replaySentry(t, p, [2]string{"2.0.1", "2.1.0"}) { - if e.ChangeType == event.ChangeTypeBreaking && e.Subject.Kind == event.AffectedKindOperation { + for _, e := range pairSentry(t, p, [2]string{"2.0.1", "2.1.0"}) { + if e.ChangeType == event.ChangeTypeBreaking && e.Subject.Kind == event.KindOperation { t.Errorf("unfiltered: %s %s", e.ChangeType, e.Subject.Operation) } ref := strings.TrimSuffix(strings.TrimPrefix(e.SourceURL, base+"/"), "/openapi-derefed.json") @@ -207,8 +207,8 @@ func TestSentryBasePathMoveIsNoChange(t *testing.T) { // As published: every operation of 2.0.1 removed. raw := Plugin{Adapter: rawSentry{}, Diff: sentryDiff} var removed []string - for _, e := range replaySentry(t, raw, [2]string{"2.0.1", "2.1.0"}) { - if e.ChangeType == event.ChangeTypeBreaking && e.Subject.Kind == event.AffectedKindOperation { + for _, e := range pairSentry(t, raw, [2]string{"2.0.1", "2.1.0"}) { + if e.ChangeType == event.ChangeTypeBreaking && e.Subject.Kind == event.KindOperation { removed = append(removed, e.Subject.Operation) } } @@ -216,7 +216,7 @@ func TestSentryBasePathMoveIsNoChange(t *testing.T) { t.Errorf("as published: removed %v, want the 5 operations of the saved 2.0.1", removed) } raw.Keep = deprecationsOnly(sentryDiff) - events := replaySentry(t, raw, [2]string{"2.0.1", "2.1.0"}) + events := pairSentry(t, raw, [2]string{"2.0.1", "2.1.0"}) if len(events) != 1 || events[0].Subject.Operation != "GET /api/0/projects/{organization_id_or_slug}/{project_id_or_slug}/issues/" || !events[0].Breaking { t.Errorf("as published, removals of deprecated operations: %d events, want GET .../issues/ removed", len(events)) } @@ -234,12 +234,12 @@ func TestSentryDeprecationWordsThatArentDeprecations(t *testing.T) { {"e8ec23b4c9601dea2d51205983ec1d7b89550b85", "1ef7f21a0501fae9490d69e3ae29f0d5acbfb61c"}, } p, _ := sentryPlugin(t) - if events := replaySentry(t, p, pairs...); len(events) != 0 { + if events := pairSentry(t, p, pairs...); len(events) != 0 { t.Fatalf("%d events, want none: %v", len(events), events[0].Subject.Operation) } loose := regexp.MustCompile(`(?i)deprecat`) p.Diff.DeprecatedDescription = loose.MatchString - if events := replaySentry(t, p, pairs...); len(events) != 2 { + if events := pairSentry(t, p, pairs...); len(events) != 2 { t.Errorf("matching %q: %d events, want the 2 wrong ones", loose, len(events)) } } diff --git a/plugins/openapi/supabase_test.go b/plugins/openapi/supabase_test.go index a9ae173..d2497ad 100644 --- a/plugins/openapi/supabase_test.go +++ b/plugins/openapi/supabase_test.go @@ -31,7 +31,7 @@ var supabaseCommits = map[string][2]string{ // copied from, as adapter.Supabase.Fetch cites it. type fakeSupabaseAdapter struct{ latest string } -func (fakeSupabaseAdapter) API() string { return "supabase" } +func (fakeSupabaseAdapter) API() string { return "supabase/management-api" } func (f fakeSupabaseAdapter) LatestTag(context.Context) (string, error) { return f.latest, nil } @@ -62,7 +62,7 @@ func supabasePlugin(latest string) Plugin { // Management API spec's history. On 2025-02-19, POST // /v1/projects/{ref}/functions ("This endpoint is deprecated - use the deploy // endpoint."), here as a daily ingest. On 2026-06-29, GET -// /v1/projects/{ref}/analytics/endpoints/logs.all, the replay fixture: the +// /v1/projects/{ref}/analytics/endpoints/logs.all, the pair fixture: the // flag alone, no reason yet. (On 2026-09-30 its description became "This // endpoint has been removed and always responds with `410 Gone`", with the // operation still in the spec: a change of words, which no diff sees.) @@ -75,8 +75,8 @@ func TestSupabaseGolden(t *testing.T) { t.Fatalf("run %s: rejected=%v err=%v", tag, rejected, err) } } - if rejected, err := kittest.Replay(ctx, env, s, supabasePlugin(""), "693bdc38", "eb21ae25"); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + if rejected, err := kittest.Pair(ctx, env, s, supabasePlugin(""), "693bdc38", "eb21ae25"); err != nil || rejected { + t.Fatalf("pair: rejected=%v err=%v", rejected, err) } events := kittest.Stored(t, s) @@ -123,8 +123,8 @@ func TestSupabaseGolden(t *testing.T) { func TestSupabaseDropsRemovalsThatWerentDeprecated(t *testing.T) { ctx := context.Background() s := openStore(t) - if rejected, err := kittest.Replay(ctx, vercelEnv(s), s, supabasePlugin(""), "8aef4a08", "90b71e3e"); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, supabasePlugin(""), "8aef4a08", "90b71e3e"); err != nil || rejected { + t.Fatalf("pair: rejected=%v err=%v", rejected, err) } if events := kittest.Stored(t, s); len(events) != 0 { t.Fatalf("stored %d events, want none", len(events)) @@ -133,7 +133,7 @@ func TestSupabaseDropsRemovalsThatWerentDeprecated(t *testing.T) { s = openStore(t) p := supabasePlugin("") p.Keep = nil - if _, err := kittest.Replay(ctx, vercelEnv(s), s, p, "8aef4a08", "90b71e3e"); err != nil { + if _, err := kittest.Pair(ctx, vercelEnv(s), s, p, "8aef4a08", "90b71e3e"); err != nil { t.Fatal(err) } var removals int @@ -155,7 +155,7 @@ func TestSupabaseBranchParameterRenameIsNoChange(t *testing.T) { s := openStore(t) p := supabasePlugin("") p.Keep = nil // even unfiltered: the operations are paired, not removed - if _, err := kittest.Replay(ctx, vercelEnv(s), s, p, "de806266", "a5fc0527"); err != nil { + if _, err := kittest.Pair(ctx, vercelEnv(s), s, p, "de806266", "a5fc0527"); err != nil { t.Fatal(err) } for _, e := range kittest.Stored(t, s) { @@ -165,7 +165,7 @@ func TestSupabaseBranchParameterRenameIsNoChange(t *testing.T) { } s = openStore(t) p.Diff.PathTemplates = false - if _, err := kittest.Replay(ctx, vercelEnv(s), s, p, "de806266", "a5fc0527"); err != nil { + if _, err := kittest.Pair(ctx, vercelEnv(s), s, p, "de806266", "a5fc0527"); err != nil { t.Fatal(err) } var removed int diff --git a/plugins/openapi/testdata/golden/algolia-ingestion.json b/plugins/openapi/testdata/golden/algolia-ingestion.json index 5804ed9..388f55b 100644 --- a/plugins/openapi/testdata/golden/algolia-ingestion.json +++ b/plugins/openapi/testdata/golden/algolia-ingestion.json @@ -1,8 +1,8 @@ [ { "id": 1, - "fingerprint": "sha256:1e7a1a853da5f0cb442587af95ab66fcc9a20308d4295dfb287805399c7c41e7", - "api": "algolia-ingestion", + "fingerprint": "sha256:eb14278aa4735854c8fd3f33ffe3e5eb43d6e81f720547c68cf55f91f2eb51b8", + "api": "algolia/ingestion-api", "version": "2025-01-22", "previous_version": "2025-01-07", "change_type": "deprecation", @@ -22,8 +22,8 @@ }, { "id": 2, - "fingerprint": "sha256:17ec64b06df87ecb1eecafcb16e9e382db116527edca15062f451c572745f3ae", - "api": "algolia-ingestion", + "fingerprint": "sha256:d6fbe2c5b1ed2baf0b7131551b5656fd7aed8b91490c6f4126fd4a42c9731478", + "api": "algolia/ingestion-api", "version": "2025-01-22", "previous_version": "2025-01-07", "change_type": "deprecation", @@ -43,8 +43,8 @@ }, { "id": 3, - "fingerprint": "sha256:4e9f82a0c9e7cabbc050af7fd66c4d4e71a90c18a695f1f8464d93cf7be864db", - "api": "algolia-ingestion", + "fingerprint": "sha256:8e673e76d54e5b20644e0787cbf23af273057f0bf044f7cd29081d546ec2c96c", + "api": "algolia/ingestion-api", "version": "2025-01-22", "previous_version": "2025-01-07", "change_type": "deprecation", @@ -64,8 +64,8 @@ }, { "id": 4, - "fingerprint": "sha256:df4563501aec2e6b427964f1ee51f9881e432fc2eed2c343953d78f43d79f317", - "api": "algolia-ingestion", + "fingerprint": "sha256:00482b2527330636337a1fa3e5f5319458f1ff185282d9d2d89b88fb71eea14d", + "api": "algolia/ingestion-api", "version": "2025-01-22", "previous_version": "2025-01-07", "change_type": "deprecation", @@ -85,8 +85,8 @@ }, { "id": 5, - "fingerprint": "sha256:f53f0abf4924f3abed31f2d0d50b71e30c77295dc2b2a4fcfc426aeb64b3cf4e", - "api": "algolia-ingestion", + "fingerprint": "sha256:9137e456a4e6480c5115bc5cabd4c07d3e8b90a4dc3bff54511c1cd20e93ead5", + "api": "algolia/ingestion-api", "version": "2025-01-22", "previous_version": "2025-01-07", "change_type": "deprecation", @@ -106,8 +106,8 @@ }, { "id": 6, - "fingerprint": "sha256:7dc53327e9239847c43e0d1fc140670139b4b755711875cc00b2d0126973cf69", - "api": "algolia-ingestion", + "fingerprint": "sha256:2d0c4fd84ef9e0c4956b0572939c915ab7be8075ab296fe585b307fa65a7dee0", + "api": "algolia/ingestion-api", "version": "2025-01-22", "previous_version": "2025-01-07", "change_type": "deprecation", @@ -127,8 +127,8 @@ }, { "id": 7, - "fingerprint": "sha256:fbb43f00dfdd75418da24e766a926b0e48b824e8b6a000340a3a82ed87ec654f", - "api": "algolia-ingestion", + "fingerprint": "sha256:b991f89f474625d83ef1733ba29bab9c9d63c6520a5e969610a1f7a06f3ae014", + "api": "algolia/ingestion-api", "version": "2025-01-22", "previous_version": "2025-01-07", "change_type": "deprecation", @@ -148,8 +148,8 @@ }, { "id": 8, - "fingerprint": "sha256:cefabf61328b95d67f3187e183dae0b8d54407d98b09b0d018e15f6b3d5f0d69", - "api": "algolia-ingestion", + "fingerprint": "sha256:dd4793d02c7b15e0a8469cd996a78d26e79a73684f2f620936a324c7da5761ca", + "api": "algolia/ingestion-api", "version": "2025-01-22", "previous_version": "2025-01-07", "change_type": "deprecation", diff --git a/plugins/openapi/testdata/golden/algolia-search.json b/plugins/openapi/testdata/golden/algolia-search.json index 584aed1..1457fb8 100644 --- a/plugins/openapi/testdata/golden/algolia-search.json +++ b/plugins/openapi/testdata/golden/algolia-search.json @@ -1,8 +1,8 @@ [ { "id": 1, - "fingerprint": "sha256:98c98629cbe46426329ba9fb60630c8bcc4194b191545aa008011f07252b5f5b", - "api": "algolia-search", + "fingerprint": "sha256:185305649ae5f0070c023dbd84d3b8fa2fd69b0b9396e9bcf6ab865030bbff54", + "api": "algolia/search-api", "version": "2025-04-01", "previous_version": "2025-03-25", "change_type": "deprecation", @@ -22,8 +22,8 @@ }, { "id": 2, - "fingerprint": "sha256:300b57a1485499d6a5fe3ff47e73b3dae695e2354ce20af1984db2345eb85334", - "api": "algolia-search", + "fingerprint": "sha256:2abd5794c049ff2047ac323f87f07289957eaa94026f57230857e3da4e0b4d9c", + "api": "algolia/search-api", "version": "2025-04-01", "previous_version": "2025-03-25", "change_type": "deprecation", @@ -43,8 +43,8 @@ }, { "id": 3, - "fingerprint": "sha256:cef12aebf4a4a83fccea8645a0cf33c1d26468c547db8f103763278e78d38bca", - "api": "algolia-search", + "fingerprint": "sha256:10eb98743283aa78f98c179d431384a36df1f5e383cc427087c65ce25082532f", + "api": "algolia/search-api", "version": "2025-04-01", "previous_version": "2025-03-25", "change_type": "deprecation", @@ -64,8 +64,8 @@ }, { "id": 4, - "fingerprint": "sha256:3e264c501d2346c87750b601f3ec19cd16db54f253ebac636d2d4575f754cb76", - "api": "algolia-search", + "fingerprint": "sha256:aba31879e97ea5de446ccdecdd94cfe51c9d939574f169f67d0264debd2b0dd1", + "api": "algolia/search-api", "version": "2025-04-01", "previous_version": "2025-03-25", "change_type": "deprecation", @@ -85,8 +85,8 @@ }, { "id": 5, - "fingerprint": "sha256:3be2d780b21e3a2cac8cfc73c48a91171e7b77335c19d87f400d9c8618dd6e04", - "api": "algolia-search", + "fingerprint": "sha256:89631e91da5c783ab2b68d6c400a225118eaf31e4977caf323fd97633825092c", + "api": "algolia/search-api", "version": "2025-04-01", "previous_version": "2025-03-25", "change_type": "deprecation", @@ -106,8 +106,8 @@ }, { "id": 6, - "fingerprint": "sha256:9ef87419d739219194a79e3ba13a5c06c59d1ff0a6452a04c8a6200af27f87d5", - "api": "algolia-search", + "fingerprint": "sha256:65043d5a11f9527a38ff560bd15771a2417670c3dd2d7e8631c0f5bd4fab926e", + "api": "algolia/search-api", "version": "2025-04-01", "previous_version": "2025-03-25", "change_type": "deprecation", @@ -127,8 +127,8 @@ }, { "id": 7, - "fingerprint": "sha256:933c2581c2ee22647cfc56e69694b562523e91658f8f80d14845f1d201921fdb", - "api": "algolia-search", + "fingerprint": "sha256:beefe5487e2bae8dc4017249ce0580e1a0570a403466e9b700f98b10b594d184", + "api": "algolia/search-api", "version": "2025-04-01", "previous_version": "2025-03-25", "change_type": "deprecation", @@ -148,8 +148,8 @@ }, { "id": 8, - "fingerprint": "sha256:86c3bf5e28959fbc84b0258d5df3824066ef30c2f1f87fb50070cf4d1f29736f", - "api": "algolia-search", + "fingerprint": "sha256:2b249c86f444ddda89abd95f7f78fc38b42df4f605c7fb7f298f37fc49bf4dd5", + "api": "algolia/search-api", "version": "2025-04-01", "previous_version": "2025-03-25", "change_type": "deprecation", @@ -169,8 +169,8 @@ }, { "id": 9, - "fingerprint": "sha256:590237cb63bae5005e8bcbcf50ee7e4e15a1fd2ec1b324788bc960e493a87b8a", - "api": "algolia-search", + "fingerprint": "sha256:5b72de487e9077705f70e2ef2836ae72347896671c162b7f0e35812b71272850", + "api": "algolia/search-api", "version": "2025-04-01", "previous_version": "2025-03-25", "change_type": "deprecation", diff --git a/plugins/openapi/testdata/golden/appwrite.json b/plugins/openapi/testdata/golden/appwrite.json index 71b51fd..6c96c91 100644 --- a/plugins/openapi/testdata/golden/appwrite.json +++ b/plugins/openapi/testdata/golden/appwrite.json @@ -1,8 +1,8 @@ [ { "id": 1, - "fingerprint": "sha256:d55bc2bc9326f99d1fb45d532acdaf3a9b3f607f00517726904566a275111aca", - "api": "appwrite", + "fingerprint": "sha256:ea7af6c4ce0ac5f78892593033526fd049b9dba84678559c95df62268c0bc143", + "api": "appwrite/api", "version": "2026-06-24", "previous_version": "2026-06-19", "change_type": "deprecation", @@ -22,8 +22,8 @@ }, { "id": 2, - "fingerprint": "sha256:54a92731e12a45f62ae7ca006da55acd8d0aeb850b717d0e91dcac6076805c97", - "api": "appwrite", + "fingerprint": "sha256:9aa750c05754b5e4d77e8532451916c43d59030fe5b1d4185e4298ec266c8d7a", + "api": "appwrite/api", "version": "2026-06-24", "previous_version": "2026-06-19", "change_type": "deprecation", @@ -43,8 +43,8 @@ }, { "id": 3, - "fingerprint": "sha256:1fa27c9a4c57ac607e966fab080b49ea80f21a8e7dce74c5befee3bb49170d1f", - "api": "appwrite", + "fingerprint": "sha256:ed8a5adc8dd491e36fe308d44039febe9e44f77c6d47a71ed7edd95566bbf803", + "api": "appwrite/api", "version": "2026-06-24", "previous_version": "2026-06-19", "change_type": "deprecation", @@ -64,8 +64,8 @@ }, { "id": 4, - "fingerprint": "sha256:6f4405889f51845aba9cd28d5a7178aecb016418b38da5f743acace34214a2ba", - "api": "appwrite", + "fingerprint": "sha256:b51c68833b56e4e1c8442fc7e966e85a861a363dc6a68569911d9561e7cc0608", + "api": "appwrite/api", "version": "2026-06-24", "previous_version": "2026-06-19", "change_type": "deprecation", @@ -85,8 +85,8 @@ }, { "id": 5, - "fingerprint": "sha256:1fb114ac9b3bf37942cc8a7bb25fb1f9b002fa8915cb9404358186f04ec70a0c", - "api": "appwrite", + "fingerprint": "sha256:45f6a512d1b968c8a1b7ddb488391ee2b7cbcd30455bfdb642393b3fa5a0cf96", + "api": "appwrite/api", "version": "2026-06-24", "previous_version": "2026-06-19", "change_type": "deprecation", @@ -106,8 +106,8 @@ }, { "id": 6, - "fingerprint": "sha256:c2e616df4c77d3282681a23974037061c1c4e7a80a3416d4c0111f1b411e69af", - "api": "appwrite", + "fingerprint": "sha256:3743d82a53dccfe87925bbd535a5912c06a0aeaf22671d8420d7eb3d91894166", + "api": "appwrite/api", "version": "2026-06-24", "previous_version": "2026-06-19", "change_type": "deprecation", @@ -127,8 +127,8 @@ }, { "id": 7, - "fingerprint": "sha256:e6990fcd55e828bece8dff3875ec79f1ef8a413c7571100ba7ed945fe9e1c539", - "api": "appwrite", + "fingerprint": "sha256:336e841ee77ca88bd25892dff4e73695b80040fef648dd950d67ba359220b1a1", + "api": "appwrite/api", "version": "2026-06-24", "previous_version": "2026-06-19", "change_type": "deprecation", @@ -148,8 +148,8 @@ }, { "id": 8, - "fingerprint": "sha256:8a80864146f1af2386381acaaef299815f7563119c5679a546a432ffb3907eda", - "api": "appwrite", + "fingerprint": "sha256:401e0496b4fedc6207569d1f157a590412f9d3007535d2fe2d4f091f4af727cf", + "api": "appwrite/api", "version": "2026-06-24", "previous_version": "2026-06-19", "change_type": "deprecation", @@ -169,8 +169,8 @@ }, { "id": 9, - "fingerprint": "sha256:4b28a490587c56b3f30f5b3844c446c6d60478ed97a50ce493008d6029fd227d", - "api": "appwrite", + "fingerprint": "sha256:10a2398eeb480ab3fd425040d9f435ba8bce60e3da7a770ed2ac338276eccab9", + "api": "appwrite/api", "version": "2026-06-24", "previous_version": "2026-06-19", "change_type": "deprecation", @@ -190,8 +190,8 @@ }, { "id": 10, - "fingerprint": "sha256:e9c2b62e2a2bccb4bd59086afa866d78677672411a2b6920f985dc4113114cfd", - "api": "appwrite", + "fingerprint": "sha256:a6cf84f00941198ec439e57f2a9c4a3344ab0eb343a683844ea51a726d663d26", + "api": "appwrite/api", "version": "2026-06-24", "previous_version": "2026-06-19", "change_type": "deprecation", @@ -211,8 +211,8 @@ }, { "id": 11, - "fingerprint": "sha256:e92c6dfc51cf7a10d88b4f5dc3896e3dd868de37aab652c41a314069efbb78a2", - "api": "appwrite", + "fingerprint": "sha256:924d1a10c8c836c00fd7a914f97a5452f25e44d1e62c3707ebefce3946ae325a", + "api": "appwrite/api", "version": "2026-06-24", "previous_version": "2026-06-19", "change_type": "deprecation", @@ -232,8 +232,8 @@ }, { "id": 12, - "fingerprint": "sha256:c6bba24ed542441ae24f495755a312c0580f8ba53decb9d6081b891ba111eaac", - "api": "appwrite", + "fingerprint": "sha256:e8b38a262b69d595c0ec9a0f557680d278e5831b8b85cd6270a21b401297a2cc", + "api": "appwrite/api", "version": "2026-06-24", "previous_version": "2026-06-19", "change_type": "deprecation", @@ -253,8 +253,8 @@ }, { "id": 13, - "fingerprint": "sha256:6f3460c2f466b54ae261e54c7cffecfc0528a63f5f735e15e95bdda6458fcc10", - "api": "appwrite", + "fingerprint": "sha256:3c9ef0414441ad96b68e3611ba21a866c848303105c6957377fa49dd3233774f", + "api": "appwrite/api", "version": "2026-06-24", "previous_version": "2026-06-19", "change_type": "deprecation", @@ -274,8 +274,8 @@ }, { "id": 14, - "fingerprint": "sha256:f930964ce5dc6078a8405d9b9d6472e739f13457be24e46b0f5b54e48e1b780d", - "api": "appwrite", + "fingerprint": "sha256:666d6159ed9b9d2464b84233bc13a470b3d5539f675a9a6d842b17c9906d9f9b", + "api": "appwrite/api", "version": "2026-06-24", "previous_version": "2026-06-19", "change_type": "deprecation", diff --git a/plugins/openapi/testdata/golden/convex.json b/plugins/openapi/testdata/golden/convex.json index e5aa4d8..fbb46cc 100644 --- a/plugins/openapi/testdata/golden/convex.json +++ b/plugins/openapi/testdata/golden/convex.json @@ -1,8 +1,8 @@ [ { "id": 1, - "fingerprint": "sha256:3009cdf0f6116b14f13ec28bd6eca6aa3be6eabe66d34fb5db7454881671f770", - "api": "convex", + "fingerprint": "sha256:93a0aa0792cb89fc4d14ab40c6ef6dcfdfbdd333393c1f4721ab4b60603309e6", + "api": "convex/deployment-api", "version": "2026-11-05", "previous_version": "2026-10-30", "change_type": "deprecation", @@ -22,8 +22,8 @@ }, { "id": 2, - "fingerprint": "sha256:a42a45fdc091e8fe2b4e151c38e131c3195f846cd26148ddc5db8d9d02b6cbac", - "api": "convex", + "fingerprint": "sha256:175e34aab0307fe16078ddc521e19db2b1134e4e7fd666a6000b4aab02069eb9", + "api": "convex/deployment-api", "version": "2026-11-05", "previous_version": "2026-10-30", "change_type": "deprecation", @@ -43,8 +43,8 @@ }, { "id": 3, - "fingerprint": "sha256:930075f543a07bd23b16f582788fd8b8c079dc4bc2d3d6cd43c2acd583a995da", - "api": "convex", + "fingerprint": "sha256:190e855c8c48bbce6697171cd6e05be6ffe713c69e2ff89f469647a4c4e53abb", + "api": "convex/deployment-api", "version": "2026-11-05", "previous_version": "2026-10-30", "change_type": "deprecation", @@ -64,8 +64,8 @@ }, { "id": 4, - "fingerprint": "sha256:f5a5c1ee8bb1ce5a406d952df079517005f92e83a2c09729e782ebf7e892af71", - "api": "convex", + "fingerprint": "sha256:187282ee12aefa2a977e85b647db8b327e008be175b5ede9416badb4810972ea", + "api": "convex/deployment-api", "version": "2026-11-05", "previous_version": "2026-10-30", "change_type": "deprecation", @@ -85,8 +85,8 @@ }, { "id": 5, - "fingerprint": "sha256:be79bb14968226260e9856e3ec45a8e3ad5795f6ee67be1a380e59f1acc8ab92", - "api": "convex", + "fingerprint": "sha256:db13f14c31d4173ecb76578f5ce0a352d890a678b940333b5b548d516c14c357", + "api": "convex/deployment-api", "version": "2026-11-05", "previous_version": "2026-10-30", "change_type": "deprecation", @@ -106,8 +106,8 @@ }, { "id": 6, - "fingerprint": "sha256:942f605d4201eddbb6b6b98d66dd306b6154248fca40225b5586aba1da633610", - "api": "convex", + "fingerprint": "sha256:94eaf5379beef172438857103486580fbb6952b2df56268b2887a6735b285160", + "api": "convex/deployment-api", "version": "2026-11-05", "previous_version": "2026-10-30", "change_type": "deprecation", diff --git a/plugins/openapi/testdata/golden/elasticsearch.json b/plugins/openapi/testdata/golden/elasticsearch.json index 33941d9..e2c825a 100644 --- a/plugins/openapi/testdata/golden/elasticsearch.json +++ b/plugins/openapi/testdata/golden/elasticsearch.json @@ -1,8 +1,8 @@ [ { "id": 1, - "fingerprint": "sha256:e6f9a24b6c0707867db8194dcf23dd20fe851e359236a9567c741e60daa220af", - "api": "elasticsearch", + "fingerprint": "sha256:9a7edf6e9f3b40c20d4e303d0ce42472b9c1c66e5125936f35e60b6f5255759f", + "api": "elastic/elasticsearch-api", "version": "9.0.0", "previous_version": "8.19.0", "change_type": "deprecation", @@ -22,8 +22,8 @@ }, { "id": 2, - "fingerprint": "sha256:914a686914eb233286a5ea281f284296892936c059d663d7786bf7972c3e6ae8", - "api": "elasticsearch", + "fingerprint": "sha256:89077715c1d3fdf2e229be46735a4d52bd3a9553d0531aa4ae56a073844c3770", + "api": "elastic/elasticsearch-api", "version": "9.0.0", "previous_version": "8.19.0", "change_type": "deprecation", @@ -43,8 +43,8 @@ }, { "id": 3, - "fingerprint": "sha256:ac4eb6548c39460a5ecce3f0c8c80aa59b458713afc81c081d126915c5ca116d", - "api": "elasticsearch", + "fingerprint": "sha256:72e6f44c763a9142fc69cf2328a5bff614ea2bb795a01b16f553b857230daecc", + "api": "elastic/elasticsearch-api", "version": "9.0.0", "previous_version": "8.19.0", "change_type": "deprecation", @@ -64,8 +64,8 @@ }, { "id": 4, - "fingerprint": "sha256:58610ad6c67e990ade54c586ad0cb021c4dcbb876454bb06a916f483b819e4bc", - "api": "elasticsearch", + "fingerprint": "sha256:6850c9d36ef120c4172c027d16743ced30b082c38a50f409adc5d41527aeba36", + "api": "elastic/elasticsearch-api", "version": "9.0.0", "previous_version": "8.19.0", "change_type": "deprecation", @@ -85,8 +85,8 @@ }, { "id": 5, - "fingerprint": "sha256:cf1e119d61e7a9acd402b6547a3854f956ca26b905ac6f6fe288d198f2894a6f", - "api": "elasticsearch", + "fingerprint": "sha256:6a472cf6cc4004690bee910738bc1717984e9689e71f6acd2a99a39e3fc6f502", + "api": "elastic/elasticsearch-api", "version": "9.0.0", "previous_version": "8.19.0", "change_type": "deprecation", @@ -106,8 +106,8 @@ }, { "id": 6, - "fingerprint": "sha256:245db5b4444fca5f4b864b5088d433ece32370538217d21dacc48d5cbb245eac", - "api": "elasticsearch", + "fingerprint": "sha256:dd5715bb59c4c9deb13f36a7bc80822410401c95aebddf6a9878755bd1b5d846", + "api": "elastic/elasticsearch-api", "version": "9.0.0", "previous_version": "8.19.0", "change_type": "breaking", @@ -127,8 +127,8 @@ }, { "id": 7, - "fingerprint": "sha256:e1850b21011cbdf095b88fbdbe1eaa522be2fab47912258bc06742f96bbbe44c", - "api": "elasticsearch", + "fingerprint": "sha256:351fc1a569c8a06f7b95de00e5f2b6cf521fa477ca0f16ac686d5bed1a0f0dac", + "api": "elastic/elasticsearch-api", "version": "9.0.0", "previous_version": "8.19.0", "change_type": "breaking", @@ -148,8 +148,8 @@ }, { "id": 8, - "fingerprint": "sha256:eaae479ba14d5d2779649052f53e9c9f2987b4cd01b284e94e7a5cf177f8514c", - "api": "elasticsearch", + "fingerprint": "sha256:bb11ba82db2c21bec5693520ed31045a19adfa7e36be55c2ab2f7f155df33d9c", + "api": "elastic/elasticsearch-api", "version": "9.0.0", "previous_version": "8.19.0", "change_type": "breaking", diff --git a/plugins/openapi/testdata/golden/flagsmith.json b/plugins/openapi/testdata/golden/flagsmith.json index 0eccaac..9dda769 100644 --- a/plugins/openapi/testdata/golden/flagsmith.json +++ b/plugins/openapi/testdata/golden/flagsmith.json @@ -1,8 +1,8 @@ [ { "id": 1, - "fingerprint": "sha256:9d8954a4311788d780d04796043dc3382369ea6856663403d91e0622ee46440b", - "api": "flagsmith", + "fingerprint": "sha256:6ce1b7cd44dbaf3c520bfffef67a4c7dac7eb7f4c0417d22bcf08ec6ae607785", + "api": "flagsmith/api", "version": "2.287.0", "previous_version": "2.286.0", "change_type": "breaking", @@ -22,8 +22,8 @@ }, { "id": 2, - "fingerprint": "sha256:679f551f2accf69eb0af557218cc8c0ae617589fea24835cc12b9358e4b4b644", - "api": "flagsmith", + "fingerprint": "sha256:bd7cf93e078745edc76b9b1ef7a984132dc6a5216bb46e89ed8a2ffe8526f3ef", + "api": "flagsmith/api", "version": "2.287.0", "previous_version": "2.286.0", "change_type": "breaking", @@ -43,8 +43,8 @@ }, { "id": 3, - "fingerprint": "sha256:f787d4463ba4f53083c9ebf3e686f3668606c61d8501c4256ebc4ad87a444668", - "api": "flagsmith", + "fingerprint": "sha256:05c83c262388466286bbb1b75ce4e063962258b70aa30a67d67c67a727989323", + "api": "flagsmith/api", "version": "2.287.0", "previous_version": "2.286.0", "change_type": "breaking", diff --git a/plugins/openapi/testdata/golden/neon.json b/plugins/openapi/testdata/golden/neon.json index e37eeec..08a5c1e 100644 --- a/plugins/openapi/testdata/golden/neon.json +++ b/plugins/openapi/testdata/golden/neon.json @@ -1,8 +1,8 @@ [ { "id": 1, - "fingerprint": "sha256:ddffac6cdf8e522e71a5059177f72c13d0f91fdcfcbaab724df5a0aa14666f9c", - "api": "neon", + "fingerprint": "sha256:50fac21d2215fb2ff00b13fe54d7d0bcbb21769dedc49d0db8ab8e2f25844828", + "api": "neon/api", "version": "2026-08-23", "previous_version": "2026-08-17", "change_type": "deprecation", diff --git a/plugins/openapi/testdata/golden/planetscale.json b/plugins/openapi/testdata/golden/planetscale.json index 0d6f791..7ca141b 100644 --- a/plugins/openapi/testdata/golden/planetscale.json +++ b/plugins/openapi/testdata/golden/planetscale.json @@ -1,8 +1,8 @@ [ { "id": 1, - "fingerprint": "sha256:12edd932544ab7968b2ad2cd824f69cb0c14e258cbc923ac87feed5880eaaa78", - "api": "planetscale", + "fingerprint": "sha256:a4087965f42c9adeebfca1fce9db2fcc702fac2032be5becb97e084e058725a8", + "api": "planetscale/api", "version": "2026-11-09", "previous_version": "2026-10-23", "change_type": "deprecation", @@ -22,8 +22,8 @@ }, { "id": 2, - "fingerprint": "sha256:9d65c2b858a48c37c43fc2d4cdcf41b581ecab8ad3aa5f598ea4e85542d606b9", - "api": "planetscale", + "fingerprint": "sha256:a0e317945d1c458b22634689ab4613d532123c479b9b89cb5255c35fae24d635", + "api": "planetscale/api", "version": "2026-11-09", "previous_version": "2026-10-23", "change_type": "deprecation", @@ -43,8 +43,8 @@ }, { "id": 3, - "fingerprint": "sha256:51bee34c435105c87184ba87b0b57fae2195ff2212833d6630c41150b7d8d011", - "api": "planetscale", + "fingerprint": "sha256:c35e7b205fe4211446cbbf0900597be4f3930c66eb5436f42a4808aa9b024c65", + "api": "planetscale/api", "version": "2026-11-09", "previous_version": "2026-10-23", "change_type": "deprecation", @@ -64,8 +64,8 @@ }, { "id": 4, - "fingerprint": "sha256:414d4e35218966651f9ebb9baa9bef90d1a26dbb1722e53ec01b559ed6e1bd57", - "api": "planetscale", + "fingerprint": "sha256:e4a98b2e24ca8682268a2dd9bf628575f0437a8e562fe0a85f72335e09f8545a", + "api": "planetscale/api", "version": "2026-11-09", "previous_version": "2026-10-23", "change_type": "deprecation", @@ -85,8 +85,8 @@ }, { "id": 5, - "fingerprint": "sha256:542446b844dd8fc039e8148a9fbe9160f61e1b239e9889eb97227613d193f65c", - "api": "planetscale", + "fingerprint": "sha256:f63159b51e042b49e72a3209e0b5851ad836cfb5925e4380c23770b8f1b562fd", + "api": "planetscale/api", "version": "2026-11-09", "previous_version": "2026-10-23", "change_type": "deprecation", diff --git a/plugins/openapi/testdata/golden/sentry.json b/plugins/openapi/testdata/golden/sentry.json index e9c4f60..c755e62 100644 --- a/plugins/openapi/testdata/golden/sentry.json +++ b/plugins/openapi/testdata/golden/sentry.json @@ -1,8 +1,8 @@ [ { "id": 1, - "fingerprint": "sha256:2efa45f20c4794cb83d70cc75a4a098f03002e8ca698ae69be2f0a032fba4d43", - "api": "sentry", + "fingerprint": "sha256:2c581bcf2a003ab8ce3564a8fa559f444388a64ed2a5dc0da2e7440400417047", + "api": "sentry/api", "version": "2024-07-31", "previous_version": "2024-07-31", "change_type": "deprecation", @@ -22,8 +22,8 @@ }, { "id": 2, - "fingerprint": "sha256:c9d7575990702109c5fe20bb8a1cf67654789f4e4a0977b4eb4d540093015e15", - "api": "sentry", + "fingerprint": "sha256:3cd6e034c9602e808d72897f85568aa4c6f3427840a9f55e3a819ec84f2c24e3", + "api": "sentry/api", "version": "2025-07-25", "previous_version": "2025-07-25", "change_type": "deprecation", @@ -43,8 +43,8 @@ }, { "id": 3, - "fingerprint": "sha256:6fc16106a310cfe991afc1001b20127813897fb5ae8a495c6b35f3877f844e73", - "api": "sentry", + "fingerprint": "sha256:b10b4122b9cf5bb7cf73b726128cfb8325227dd9e252b529595eb8419fcd3a17", + "api": "sentry/api", "version": "2026-01-22", "previous_version": "2026-01-21", "change_type": "deprecation", @@ -64,8 +64,8 @@ }, { "id": 4, - "fingerprint": "sha256:c2eb3298f4f871a01f9b5bf7b99e3731aa0328acc1f654b68308844bc8d9cdc7", - "api": "sentry", + "fingerprint": "sha256:9a1a370124284bb32f1ade8af8dc022ef9719a7adc5ade39a71f607848aea43b", + "api": "sentry/api", "version": "2026-01-22", "previous_version": "2026-01-21", "change_type": "deprecation", @@ -85,8 +85,8 @@ }, { "id": 5, - "fingerprint": "sha256:7c4f21e09fe00c30d1239b95e167e7739e81ad21e7ede0234ae837277f60b590", - "api": "sentry", + "fingerprint": "sha256:360f32fc9198150194657ac504e030a86f246677364104b5cdf65175934a1d5d", + "api": "sentry/api", "version": "2026-01-22", "previous_version": "2026-01-21", "change_type": "deprecation", @@ -106,8 +106,8 @@ }, { "id": 6, - "fingerprint": "sha256:5d93def1bfa9db7da29d9446fd4f5944df489f55033d585f951a2e4925afd4da", - "api": "sentry", + "fingerprint": "sha256:d585c8aff07f53c61f686e437d99447ce5d68254eef0f3527d38090d2103d1d8", + "api": "sentry/api", "version": "2026-01-22", "previous_version": "2026-01-21", "change_type": "deprecation", @@ -127,8 +127,8 @@ }, { "id": 7, - "fingerprint": "sha256:90402d61a2a48a93c0c095061b6dc457e189a52d4e5d84b68953d49b16c0c052", - "api": "sentry", + "fingerprint": "sha256:49151a031811fac3d401cc2ae9df3b29c92f25a1c768941f64b9db48fe933c38", + "api": "sentry/api", "version": "2026-01-22", "previous_version": "2026-01-21", "change_type": "deprecation", @@ -148,8 +148,8 @@ }, { "id": 8, - "fingerprint": "sha256:2f145e0f7dab69af5b768ce70659ca1bc83c0adcbc3d82e0d4c8282c70c4cded", - "api": "sentry", + "fingerprint": "sha256:1e0a6193b9d4ee311207fff20af8ee2a22ad6d55a066af49fa82876a7cb91d97", + "api": "sentry/api", "version": "2026-01-22", "previous_version": "2026-01-21", "change_type": "deprecation", @@ -169,8 +169,8 @@ }, { "id": 9, - "fingerprint": "sha256:9530af56a60f90dc66ad010d23cfbe27c1e4995ca7abaf025069e9a8a979c813", - "api": "sentry", + "fingerprint": "sha256:10b62873f4ac22a29ac7384ccc9bdb308c3bb070adc6cc3e4e21afe759ebade0", + "api": "sentry/api", "version": "2026-01-22", "previous_version": "2026-01-21", "change_type": "deprecation", @@ -190,8 +190,8 @@ }, { "id": 10, - "fingerprint": "sha256:c4b2385ae7d1452194f50e65e09c90b5a370c23741e45655c2aef541b65aa70c", - "api": "sentry", + "fingerprint": "sha256:229b405e49905a7c71fc58eaff80f860bdce47abbeb9bd766301879094c31e17", + "api": "sentry/api", "version": "2026-01-22", "previous_version": "2026-01-21", "change_type": "deprecation", @@ -211,8 +211,8 @@ }, { "id": 11, - "fingerprint": "sha256:67cdb8021716e9e3bdd7fbe696b87099b0301943cba1cf66b5a8973e4db45fbb", - "api": "sentry", + "fingerprint": "sha256:1e5db27221e10250eb64354e1c204c1120cd14dbef5bf7661f063d0aab0bbe71", + "api": "sentry/api", "version": "2026-01-22", "previous_version": "2026-01-21", "change_type": "deprecation", @@ -232,8 +232,8 @@ }, { "id": 12, - "fingerprint": "sha256:4857ec490742153cbb2fc9d7acfdfe63f5fc5c1cb45f4df2a8d9c6a8de9ca484", - "api": "sentry", + "fingerprint": "sha256:c2c1b2a44827fbc07afe0ddf1c6cbd7fae8c39d513508c68853ec8a7a8f6988d", + "api": "sentry/api", "version": "2026-01-22", "previous_version": "2026-01-21", "change_type": "deprecation", diff --git a/plugins/openapi/testdata/golden/supabase.json b/plugins/openapi/testdata/golden/supabase.json index dbe6909..2719393 100644 --- a/plugins/openapi/testdata/golden/supabase.json +++ b/plugins/openapi/testdata/golden/supabase.json @@ -1,8 +1,8 @@ [ { "id": 1, - "fingerprint": "sha256:880606fe624faa3f49480e13588a19e93562091d5a8f40c2a097f36fb329a604", - "api": "supabase", + "fingerprint": "sha256:fd6a1208f9f1047d9eaeff41188fbfda52dd7a2d5a67c05a7989a0a17ac1eb6f", + "api": "supabase/management-api", "version": "2025-02-19", "previous_version": "2025-02-10", "change_type": "deprecation", @@ -22,8 +22,8 @@ }, { "id": 2, - "fingerprint": "sha256:9cdc7164ed43b50e19c232e8af7f43c3fbfe87aa18b96bf5e62d7e59ee47c7b0", - "api": "supabase", + "fingerprint": "sha256:06a8a5322e8f622bc5e0841866ddb7d9d2c195f8b5137c9a5c7e2f49d3f7f7b2", + "api": "supabase/management-api", "version": "2026-06-29", "previous_version": "2026-06-22", "change_type": "deprecation", diff --git a/plugins/openapi/testdata/golden/vercel.json b/plugins/openapi/testdata/golden/vercel.json index 9c1a600..9731195 100644 --- a/plugins/openapi/testdata/golden/vercel.json +++ b/plugins/openapi/testdata/golden/vercel.json @@ -1,8 +1,8 @@ [ { "id": 1, - "fingerprint": "sha256:3ed13a96aa00836818e55222cab3da2dfa8a26582d5498f1af05c31f5d6f4069", - "api": "vercel", + "fingerprint": "sha256:ff56553007ba92c7da01fd7b944f1989a2a08ddd78f67e4d61757f507b93ca91", + "api": "vercel/api", "version": "1.13.5", "previous_version": "1.13.4", "change_type": "deprecation", @@ -22,8 +22,8 @@ }, { "id": 2, - "fingerprint": "sha256:9063f28da001671b78c5c0095cc412ca28c892e2a0e87b8a26c15b954530cea4", - "api": "vercel", + "fingerprint": "sha256:bbc8995e4907e383935c8eb7eda04a71b49975160a4c2cfa67ca296011a5e48c", + "api": "vercel/api", "version": "1.13.5", "previous_version": "1.13.4", "change_type": "deprecation", @@ -43,8 +43,8 @@ }, { "id": 3, - "fingerprint": "sha256:13194122725cea31972cf361d8bf98a8f41aedb308e10a721fe800145f2afe51", - "api": "vercel", + "fingerprint": "sha256:350f494abf46acc4721581386836895b85a3fab5cb1b285405ba8094d7e9ddf8", + "api": "vercel/api", "version": "1.13.5", "previous_version": "1.13.4", "change_type": "deprecation", @@ -64,8 +64,8 @@ }, { "id": 4, - "fingerprint": "sha256:3230007e27b6de1ffbd000649cdd3e34ac9a31da35a9c650cdb573b5d8f939d6", - "api": "vercel", + "fingerprint": "sha256:e36c66e4c03dd109d47cfe6cc67a8f8809b46f23afa1ab9133b6270c0f7bf34d", + "api": "vercel/api", "version": "1.13.5", "previous_version": "1.13.4", "change_type": "deprecation", @@ -85,8 +85,8 @@ }, { "id": 5, - "fingerprint": "sha256:4f1bb30450488badb2c18e52b206ebdd7c5b1265e2e13508351e4bf99d945d05", - "api": "vercel", + "fingerprint": "sha256:3abdd335e32e5c60ebe66fcbc7fc418a6c58c76f5402907977f1ada184f96733", + "api": "vercel/api", "version": "1.18.7", "previous_version": "1.18.6", "change_type": "breaking", @@ -106,8 +106,8 @@ }, { "id": 6, - "fingerprint": "sha256:ab1fee5e9b4b891417f2c62350ae005c7e15241d877b242dfc437764201915ac", - "api": "vercel", + "fingerprint": "sha256:f982f8524edab06d1447ca7c478e0b4e153914e8f1d7a3781762e37338f3d895", + "api": "vercel/api", "version": "1.18.7", "previous_version": "1.18.6", "change_type": "breaking", diff --git a/plugins/openapi/vercel_test.go b/plugins/openapi/vercel_test.go index 2c1e357..9f76e86 100644 --- a/plugins/openapi/vercel_test.go +++ b/plugins/openapi/vercel_test.go @@ -21,7 +21,7 @@ import ( // real URL each one was copied from, the way adapter.Vercel.Fetch cites it. type fakeVercelAdapter struct{ latest string } -func (fakeVercelAdapter) API() string { return "vercel" } +func (fakeVercelAdapter) API() string { return "vercel/api" } func (f fakeVercelAdapter) LatestTag(context.Context) (string, error) { return f.latest, nil } @@ -58,7 +58,7 @@ func vercelEnv(s *kittest.Mem) plugin.Env { // Domains API is now deprecated. ... Sunset date: 2025-11-09." // (vercel.com/changelog/new-domains-registrar-api-for-domain-search-pricing-purchase-and-management). // v1.18.7 (2026-01-09) removed two of them; both now answer "This endpoint has -// been sunsetted on November 9, 2025." The second pair is the replay fixture: +// been sunsetted on November 9, 2025." The second pair is the pair fixture: // one real historical breaking change. The same release added the five // /v1/connect/networks operations, which the filter drops, saved here as one. func TestVercelGolden(t *testing.T) { @@ -72,9 +72,9 @@ func TestVercelGolden(t *testing.T) { t.Fatalf("run %s: rejected=%v err=%v", tag, rejected, err) } } - // The removal, replayed. - if rejected, err := kittest.Replay(ctx, env, s, vercelPlugin(""), "v1.18.6", "v1.18.7"); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + // The removal, as a pair. + if rejected, err := kittest.Pair(ctx, env, s, vercelPlugin(""), "v1.18.6", "v1.18.7"); err != nil || rejected { + t.Fatalf("pair: rejected=%v err=%v", rejected, err) } events := kittest.Stored(t, s) @@ -116,12 +116,12 @@ func TestVercelGolden(t *testing.T) { kittest.Golden(t, "testdata/golden/vercel.json", events) - // Replaying the same pair again must not duplicate the events. - if _, err := kittest.Replay(ctx, env, s, vercelPlugin(""), "v1.18.6", "v1.18.7"); err != nil { - t.Fatalf("second replay: %v", err) + // Reading the same pair again must not duplicate the events. + if _, err := kittest.Pair(ctx, env, s, vercelPlugin(""), "v1.18.6", "v1.18.7"); err != nil { + t.Fatalf("second read of the pair: %v", err) } if again := kittest.Stored(t, s); len(again) != len(events) { - t.Errorf("repeating the replay added events: %d -> %d", len(events), len(again)) + t.Errorf("reading the pair again added events: %d -> %d", len(events), len(again)) } } @@ -129,7 +129,7 @@ func TestVercelGolden(t *testing.T) { func TestVercelSummaryDeprecationQuotesTheSummary(t *testing.T) { ctx := context.Background() s := openStore(t) - if _, err := kittest.Replay(ctx, vercelEnv(s), s, vercelPlugin(""), "v1.13.4", "v1.13.5"); err != nil { + if _, err := kittest.Pair(ctx, vercelEnv(s), s, vercelPlugin(""), "v1.13.4", "v1.13.5"); err != nil { t.Fatal(err) } for _, e := range kittest.Stored(t, s) { @@ -153,8 +153,8 @@ func TestVercelSummaryDeprecationQuotesTheSummary(t *testing.T) { func TestVercelDropsRemovalsThatWerentDeprecated(t *testing.T) { ctx := context.Background() s := openStore(t) - if rejected, err := kittest.Replay(ctx, vercelEnv(s), s, vercelPlugin(""), "v1.6.2", "v1.6.3"); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, vercelPlugin(""), "v1.6.2", "v1.6.3"); err != nil || rejected { + t.Fatalf("pair: rejected=%v err=%v", rejected, err) } if events := kittest.Stored(t, s); len(events) != 0 { for _, e := range events { @@ -168,7 +168,7 @@ func TestVercelDropsRemovalsThatWerentDeprecated(t *testing.T) { s = openStore(t) p := vercelPlugin("") p.Keep = nil - if _, err := kittest.Replay(ctx, vercelEnv(s), s, p, "v1.6.2", "v1.6.3"); err != nil { + if _, err := kittest.Pair(ctx, vercelEnv(s), s, p, "v1.6.2", "v1.6.3"); err != nil { t.Fatal(err) } var removals int @@ -178,7 +178,7 @@ func TestVercelDropsRemovalsThatWerentDeprecated(t *testing.T) { } } if removals == 0 { - t.Error("unfiltered replay removes no /v1/log-drains operation; the fixture no longer shows the noise") + t.Error("unfiltered pair removes no /v1/log-drains operation; the fixture no longer shows the noise") } } @@ -188,8 +188,8 @@ func TestVercelDropsRemovalsThatWerentDeprecated(t *testing.T) { func TestVercelPathParameterRenameIsNoChange(t *testing.T) { ctx := context.Background() s := openStore(t) - if rejected, err := kittest.Replay(ctx, vercelEnv(s), s, vercelPlugin(""), "v1.28.64", "v1.28.65"); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, vercelPlugin(""), "v1.28.64", "v1.28.65"); err != nil || rejected { + t.Fatalf("pair: rejected=%v err=%v", rejected, err) } if events := kittest.Stored(t, s); len(events) != 0 { for _, e := range events { @@ -202,7 +202,7 @@ func TestVercelPathParameterRenameIsNoChange(t *testing.T) { s = openStore(t) p := vercelPlugin("") p.Diff.PathTemplates = false - if _, err := kittest.Replay(ctx, vercelEnv(s), s, p, "v1.28.64", "v1.28.65"); err != nil { + if _, err := kittest.Pair(ctx, vercelEnv(s), s, p, "v1.28.64", "v1.28.65"); err != nil { t.Fatal(err) } events := kittest.Stored(t, s) diff --git a/plugins/removedmembers/golden_test.go b/plugins/removedmembers/golden_test.go deleted file mode 100644 index ac62dbd..0000000 --- a/plugins/removedmembers/golden_test.go +++ /dev/null @@ -1,15 +0,0 @@ -package removedmembers - -import ( - "testing" - - "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. -func TestGolden(t *testing.T) { - got := kittest.Ingest(t, Plugin{Guide: NumPy2}, kittest.Pages{ - NumPy2.URL(): "testdata/numpy_2_0_migration_guide-v2.0.0.rst", - }) - kittest.Golden(t, "testdata/golden/numpy-2.0.0.json", got) -} diff --git a/plugins/removedmembers/registered_test.go b/plugins/removedmembers/registered_test.go deleted file mode 100644 index 20af0b9..0000000 --- a/plugins/removedmembers/registered_test.go +++ /dev/null @@ -1,11 +0,0 @@ -package removedmembers - -import ( - "testing" - - "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" -) - -func TestRegistersItself(t *testing.T) { - kittest.Registered(t, Plugin{Guide: NumPy2}) -} diff --git a/plugins/retirements/retirements.go b/plugins/retirements/retirements.go deleted file mode 100644 index d4d200a..0000000 --- a/plugins/retirements/retirements.go +++ /dev/null @@ -1,92 +0,0 @@ -// Package retirements is the source plugin for a model provider's deprecations -// page (OpenAI, Anthropic): every retired model becomes an event. There is no -// spec to diff: the page is read as it is now, and the events cite a Wayback -// Machine snapshot of it, never the live page (kit/). -package retirements - -import ( - "context" - "fmt" - "log" - - "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() { - plugin.RegisterProvider(plugin.Provider{ - ID: "openai", Name: "OpenAI", Category: plugin.CategoryAI, Homepage: "https://openai.com", - Sources: []plugin.Source{{ - ID: "models", Layer: plugin.LayerAIModels, Page: "providers/openai-models.md", - Watches: "Model deprecations and shutdown dates (Chat Completions and Responses text models)", - URLs: []string{"https://developers.openai.com/api/docs/deprecations"}, - Plugin: Plugin{Page: retire.OpenAI, Archiver: kit.Wayback{}}, - }}, - }) - plugin.RegisterProvider(plugin.Provider{ - ID: "anthropic", Name: "Anthropic", Category: plugin.CategoryAI, Homepage: "https://www.anthropic.com", - Sources: []plugin.Source{{ - ID: "models", Layer: plugin.LayerAIModels, Page: "providers/anthropic-models.md", - Watches: "Model deprecations and retirement dates (Messages API models)", - URLs: []string{"https://platform.claude.com/docs/en/about-claude/model-deprecations"}, - Plugin: Plugin{Page: retire.Anthropic, Archiver: kit.Wayback{}}, - }}, - }) -} - -// Plugin reads one provider's page. -type Plugin struct { - Page retire.Page - Archiver kit.Archiver -} - -func (p Plugin) Name() string { return p.Page.API } - -// Run stores an event for every retired model on the page. The events are read -// from the snapshot itself, so every excerpt is on the page it cites; a -// snapshot that doesn't hold what the live page says (the page changed in -// between) stores nothing this run. An unchanged page since the last run costs -// one GET and no snapshot. -func (p Plugin) Run(ctx context.Context, env plugin.Env) (plugin.Result, error) { - live, err := env.Get(ctx, p.Page.URL) - if err != nil { - return plugin.Result{}, fmt.Errorf("fetching %s: %w", p.Page.URL, err) - } - hash := plugin.SHA256(live) - last, same, err := kit.Unchanged(env, p.Page.API, live) - if err != nil { - return plugin.Result{}, err - } - if same { - log.Printf("%s: no change since %s", p.Page.API, last.SourceURL) - return plugin.Result{}, nil - } - want, err := retire.Parse(live, p.Page.Keep) - if err != nil { - return plugin.Result{}, fmt.Errorf("reading %s: %w", p.Page.URL, err) - } - // A provider renaming a column makes its table unreadable, and the run would - // quietly read fewer retirements. Past retirements stay on both pages, so a - // real drop is rare: fail loudly instead of storing a partial list. - if last != nil { - if before, err := retire.Parse(last.Content, p.Page.Keep); err == nil && len(want)*10 < len(before)*9 { - return plugin.Result{}, fmt.Errorf("%s now lists %d retirements, %d at %s: the page's shape may have changed", p.Page.URL, len(want), len(before), last.SourceURL) - } - } - - read := func(b []byte) ([]retire.Retirement, error) { return retire.Parse(b, p.Page.Keep) } - snapURL, snap, got, err := kit.Cite(ctx, p.Archiver, p.Page.URL, read, want) - if err != nil { - return plugin.Result{}, err - } - - now := env.Now().UTC() - events, errs := retire.Events(p.Page, got, snapURL, now) - // The hash of the live page, so the next run compares like with like. - baseline := plugin.Baseline(p.Page.API, now.Format("2006-01-02"), snapURL, snapURL, snap, false, now) - baseline.SHA256 = hash - converted, invalid := migrate.Fresh(events) - return plugin.Result{Label: snapURL, Events: converted, Rejected: append(errs, invalid...), Baselines: []plugin.Spec{baseline}}, nil -} diff --git a/plugins/retirements/testdata/README.md b/plugins/retirements/testdata/README.md deleted file mode 100644 index 5d272e2..0000000 --- a/plugins/retirements/testdata/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# Golden events - -`golden/openai-models.json` and `golden/anthropic-models.json` are what the `openai-models` and `anthropic-models` plugins store from the saved deprecations pages. The pages themselves are shared with the `retire` package: see [`retire/testdata/README.md`](../../../retire/testdata/README.md) for their URLs, dates and licenses. - -Rewrite them after an intended change with `go test ./plugins/retirements -update`, and say in the PR why the new output is right. diff --git a/providers/README.md b/providers/README.md index 550b4fa..56d8d6d 100644 --- a/providers/README.md +++ b/providers/README.md @@ -1,6 +1,6 @@ # Providers -One page per plugin id: `providers/.md`. Start from [`_template.md`](_template.md). Each page says: +One page per provider: `providers/-.md`, or the provider's own page shared by its sources. Start from [`_template.md`](_template.md). Each page says: - **What the plugin watches.** - **Why this source:** the link the plugin reads, when it was checked, why it's the most reliable place this provider announces breaking changes, which other sources were considered and why they weren't used, and one short quote from it. diff --git a/providers/_template.md b/providers/_template.md index 533dd71..b7eab39 100644 --- a/providers/_template.md +++ b/providers/_template.md @@ -1,6 +1,6 @@ -# (``) +# (`/`) -Copy this file to `providers/.md` and fill every section. Delete these instructions. +Copy this file to `providers/-.md` and fill every section. Delete these instructions. ## What it watches diff --git a/providers/algolia.md b/providers/algolia.md index 9158969..5fbd906 100644 --- a/providers/algolia.md +++ b/providers/algolia.md @@ -1,10 +1,10 @@ -# Algolia (`algolia-search`, `algolia-ingestion`, `algolia-recommend`) +# Algolia (`algolia/search-api`, `algolia/ingestion-api`, `algolia/recommend-api`) ## What it watches Three of Algolia's REST APIs, one plugin each: the Search API (`algolia-search`), the Ingestion API (`algolia-ingestion`) and the Recommend API (`algolia-recommend`). Each reports operations Algolia marks deprecated, and removals of operations it had marked deprecated, between two releases of that API's OpenAPI spec. -Format plugin: `openapi` (`plugins/openapi`), with `adapter.Algolia`. +Kind: `openapi` (`plugins/openapi`), with `adapter.Algolia`. ## Why this source diff --git a/providers/anthropic-models.md b/providers/anthropic-models.md index 77b50db..56ee9fc 100644 --- a/providers/anthropic-models.md +++ b/providers/anthropic-models.md @@ -1,10 +1,10 @@ -# Anthropic model retirements (`anthropic-models`) +# Anthropic model retirements (`anthropic/models`) ## What it watches 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 `plugins/retirements/retire/`. +Kind: `notices` (`plugins/notices`), reading with the deprecations-page reader, `plugins/notices/retire/`. ## Why this source diff --git a/providers/anthropic.md b/providers/anthropic.md index cac9358..6b10823 100644 --- a/providers/anthropic.md +++ b/providers/anthropic.md @@ -1,10 +1,10 @@ -# Anthropic Python SDK (`anthropic`) +# Anthropic Python SDK (`anthropic/python-sdk`) ## What it watches 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 `plugins/migrationguide/sdkguide/`. +Kind: `migrationguide` (`plugins/migrationguide`), reading with `plugins/migrationguide/sdkguide/`. ## Why this source diff --git a/providers/appwrite.md b/providers/appwrite.md index 1b44940..0d5e8e2 100644 --- a/providers/appwrite.md +++ b/providers/appwrite.md @@ -1,10 +1,10 @@ -# Appwrite (`appwrite`) +# Appwrite (`appwrite/api`) ## What it watches The Appwrite REST API as a server SDK calls it (the operations an Appwrite server SDK, in a repo's backend code, can call): operations Appwrite marks deprecated between two commits of its OpenAPI spec. SDK method renames that don't deprecate the route are left out, and so are removals. -Format plugin: `openapi` (`plugins/openapi`), with `adapter.Appwrite`. +Kind: `openapi` (`plugins/openapi`), with `adapter.Appwrite`. ## Why this source @@ -38,7 +38,7 @@ Format plugin: `openapi` (`plugins/openapi`), with `adapter.Appwrite`. - **Removals, all of them,** even of deprecated operations. Read as the plugin reads it (139 commits on `main`), 78 operations left the server operations (from the spec, or from the `server` platform). Only one had been flagged first, and it was a path move: `PATCH .../attributes/{key}/relationship` became `.../attributes/relationship/{key}` on 2026-03-20. 13 are back now: on 2026-10-12, `06e6fafa` took `server` off 13 operations of 2.4.x's single document ("listed server and client methods no released SDK ships yet"), and 2.5.x had them on `server` again the next day. Nothing in the spec says when an operation stops answering. - **Request and response property changes, and new operations.** - Over the 139 commits this keeps 14 events, all on 2026-06-24 (`7d74bf9f`): the six `/v1/databases/transactions` operations and the `longtext`, `mediumtext`, `text` and `varchar` attribute operations, each replaced by a `tablesDB` method. None is a rename or has a live method, so the filter drops none of them. -- **Replays** a pair of commits (`Replay`, as the golden test does from `8c00ba35` to `7d74bf9f`). A tag can name an older minor's directory, `1.7.x@`, as the rename test does. The pinned drop test is the 2.4.x pair (13 removals, no event). A single document where no operation is on `server` (the platforms gone or renamed) fails the fetch, rather than read as nothing deprecated. +- **Reads** a pair of commits (a version pair, as the golden test does from `8c00ba35` to `7d74bf9f`). A tag can name an older minor's directory, `1.7.x@`, as the rename test does. The pinned drop test is the 2.4.x pair (13 removals, no event). A single document where no operation is on `server` (the platforms gone or renamed) fails the fetch, rather than read as nothing deprecated. ## Known gaps diff --git a/providers/cloudflare.md b/providers/cloudflare.md index e70607f..8937bd7 100644 --- a/providers/cloudflare.md +++ b/providers/cloudflare.md @@ -1,10 +1,10 @@ -# Cloudflare (`cloudflare`) +# Cloudflare (`cloudflare/api`) ## What it watches Cloudflare's REST API (`api.cloudflare.com/client/v4`): every operation Cloudflare names as deprecated on its API deprecations page. It's a `breaking` event, dated by the end of life, when the item says the endpoints stop on a full end-of-life date. Otherwise it's a `deprecation`. -Format plugin: `feed` (`plugins/feed`), with the `CloudflareAPI` reader. +Kind: `notices` (`plugins/notices`), with the feed reader (`plugins/notices/feed`) and its `CloudflareAPI` feed. ## Why this source diff --git a/providers/convex.md b/providers/convex.md index c848d5c..b8898c8 100644 --- a/providers/convex.md +++ b/providers/convex.md @@ -1,10 +1,10 @@ -# Convex (`convex`) +# Convex (`convex/deployment-api`) ## What it watches The Convex Deployment API (`{deployment-url}/api/v1`, the platform API for managing one deployment: environment variables, log streams and integrations, usage limits, data sync): operations Convex marks deprecated, and removals of operations it had marked deprecated, between two versions of the API's OpenAPI spec. -Format plugin: `openapi` (`plugins/openapi`), with `adapter.Convex`. +Kind: `openapi` (`plugins/openapi`), with `adapter.Convex`. ## Why this source @@ -38,7 +38,7 @@ Format plugin: `openapi` (`plugins/openapi`), with `adapter.Convex`. - **Request and response property changes,** and new operations. Over the history the differ finds 18 property removals, 16 type changes, 10 schema removals and 3 properties no longer required, most of them in the data sync, usage-limit and S3 export APIs. The drop test is one of them: on 2026-07-14 (`3ead9091`, "Remove name from usage limits") the optional `name` left the usage-limit request and response; the commit says it "was never editable in the UI (always `None` on create, only echoed back)", and the request type at that commit doesn't reject unknown fields, so a caller still sending it isn't refused. - **Removals of operations that were never deprecated.** None in the history: no operation has left the spec. - Over the 68 commits this keeps 6 events, all deprecations on 2026-11-05: `GET /api/v1/list_log_streams`, `GET /api/v1/get_log_stream/{id}`, `POST /api/v1/create_log_stream`, `POST /api/v1/update_log_stream/{id}`, `POST /api/v1/delete_log_stream/{id}`, `POST /api/v1/rotate_webhook_secret/{id}`. -- **Replays** a historical pair (`Replay`, from `f35879bb` to `5e5159cb`) and recreates those six; the golden test also runs them as a daily ingest. The drop test replays `3f6edf7a` to `3ead9091`. +- **Reads** a historical pair (a version pair, `f35879bb` → `5e5159cb`) and recreates those six; the golden test also runs them as a daily ingest. The drop test replays `3f6edf7a` to `3ead9091`. ## Known gaps diff --git a/providers/datadog.md b/providers/datadog.md index 9451a82..56befde 100644 --- a/providers/datadog.md +++ b/providers/datadog.md @@ -1,10 +1,10 @@ -# Datadog (`datadog`) +# Datadog (`datadog/api`) ## What it watches Datadog's API v2, release by release: endpoints, request and response properties and schemas removed or changed between two versions of the OpenAPI spec Datadog generates its official clients from. -Format plugin: `openapi` (`plugins/openapi`), with `adapter.Datadog`. +Kind: `openapi` (`plugins/openapi`), with `adapter.Datadog`. ## Why this source @@ -24,7 +24,7 @@ Format plugin: `openapi` (`plugins/openapi`), with `adapter.Datadog`. - Reads: the v2 spec at the newest tag, diffed against the last one. - Ignores: changes to OpenAPI `tags` (they only rename generated SDK methods; the REST API is unchanged). The v1 spec isn't read yet. -- Replays a historical pair (`Replay`, from `2.60.0` to `2.61.0`) and recreates the removal of two properties from `TagIndexingRuleDynamicTags` (the golden test uses trimmed excerpts of both specs). +- Reads a historical pair (a version pair, `2.60.0` → `2.61.0`) and recreates the removal of two properties from `TagIndexingRuleDynamicTags` (the golden test uses trimmed excerpts of both specs). ## Known gaps diff --git a/providers/elasticsearch.md b/providers/elasticsearch.md index c1dcdbf..72667ba 100644 --- a/providers/elasticsearch.md +++ b/providers/elasticsearch.md @@ -1,10 +1,10 @@ -# Elasticsearch (`elasticsearch`) +# Elasticsearch (`elastic/elasticsearch-api`) ## What it watches The Elasticsearch REST API, minor version by minor version: operations Elastic marks deprecated, and removals of operations it had marked deprecated, between two versions of the OpenAPI spec generated from Elastic's API specification. -Format plugin: `openapi` (`plugins/openapi`), with `adapter.Elasticsearch`. +Kind: `openapi` (`plugins/openapi`), with `adapter.Elasticsearch`. ## Why this source @@ -42,7 +42,7 @@ Format plugin: `openapi` (`plugins/openapi`), with `adapter.Elasticsearch`. - **History:** over 8.14 to 9.6, this keeps 26 events. - **23 deprecations.** For example, the rollup and legacy `_template` endpoints (8.17), `/_application/analytics` (9.0), and `POST /_ml/anomaly_detectors/{job_id}/_flush` (9.1). - **3 removals, in 9.0:** GET and POST `/{index}/_knn_search`, and POST `/{index}/_unfreeze`. -- **Replays** 8.19 → 9.0 in the golden test. The drop test replays 9.1 → 9.2. +- **Reads** 8.19 → 9.0 in the golden test. The drop test replays 9.1 → 9.2. ## Known gaps diff --git a/providers/flagsmith.md b/providers/flagsmith.md index 40ff7ae..555cd71 100644 --- a/providers/flagsmith.md +++ b/providers/flagsmith.md @@ -1,10 +1,10 @@ -# Flagsmith (`flagsmith`) +# Flagsmith (`flagsmith/api`) ## What it watches Flagsmith's REST API (the Admin/Management API and the SDK-facing endpoints together) between releases of Flagsmith's own OpenAPI 3.1 spec: whole operations removed, and request parameters callers send that are removed, renamed or newly required. -Format plugin: `openapi` (`plugins/openapi`), with `adapter.Flagsmith` and a request-side filter (`openapi.Plugin.Keep`, same `requestSide` GitLab uses). +Kind: `openapi` (`plugins/openapi`), with `adapter.Flagsmith` and a request-side filter (`openapi.Plugin.Keep`, same `requestSide` GitLab uses). ## Why this source diff --git a/providers/github-actions.md b/providers/github-actions.md index 3fa321f..25076d6 100644 --- a/providers/github-actions.md +++ b/providers/github-actions.md @@ -1,10 +1,10 @@ -# GitHub Actions runner images (`github-actions`) +# GitHub Actions runner images (`github/actions`) ## What it watches GitHub-hosted runner images that GitHub retires: one `ci_runtime` event per `runs-on` label the retirement removes (`macos-14`, `macos-14-large`, …), dated by the removal date. -Format plugin: `feed` (`plugins/feed`), with the `GitHubActions` reader. +Kind: `notices` (`plugins/notices`), with the feed reader (`plugins/notices/feed`) and its `GitHubActions` feed. ## Why this source diff --git a/providers/github.md b/providers/github.md index 3bd5c02..aad0118 100644 --- a/providers/github.md +++ b/providers/github.md @@ -1,10 +1,10 @@ -# GitHub REST API (`github`) +# GitHub REST API (`github/rest-api`) ## What it watches GitHub's REST API between dated API versions (`2022-11-28` → `2026-03-10`): properties, schemas, parameters and operations removed or changed in a new version. -Format plugin: `openapi` (`plugins/openapi`), with `adapter.GitHub`. +Kind: `openapi` (`plugins/openapi`), with `adapter.GitHub`. ## Why this source diff --git a/providers/gitlab.md b/providers/gitlab.md index c68d8d3..e068267 100644 --- a/providers/gitlab.md +++ b/providers/gitlab.md @@ -1,10 +1,10 @@ -# GitLab REST API (`gitlab`) +# GitLab REST API (`gitlab/rest-api`) ## What it watches GitLab's REST API (`/api/v4`) between releases, **request side only**: endpoints removed, and parameters callers send that are removed, renamed or newly required. -Format plugin: `openapi` (`plugins/openapi`), with `adapter.GitLab` and a request-side filter (`openapi.Plugin.Keep`). +Kind: `openapi` (`plugins/openapi`), with `adapter.GitLab` and a request-side filter (`openapi.Plugin.Keep`). ## Why this source @@ -24,7 +24,7 @@ Format plugin: `openapi` (`plugins/openapi`), with `adapter.GitLab` and a reques - **Response-side changes are dropped.** Between 18.11 and 19.0 the generator retyped hundreds of response properties (default `string` to the real type) while GitLab returned the same JSON; reporting them would be wrong pull requests. Precision over recall: only request-side changes are kept. - Request bodies are named by a hash of their content (`RequestBody_`), so adding one field renames the schema. The adapter inlines those bodies back under their operations, and each event's pointer still names the node in the published file. - Release candidates are skipped; tags are sorted numerically. -- The OpenAPI 3 file exists from `v18.10.0-ee`; 19.0 is the first major release that can be replayed (`Replay` from `v18.11.0-ee` to `v19.0.0-ee`). +- The OpenAPI 3 file exists from `v18.10.0-ee`; 19.0 is the first major release that can be replayed (the pair `v18.11.0-ee` → `v19.0.0-ee`). ## Known gaps diff --git a/providers/mongodb-atlas.md b/providers/mongodb-atlas.md index 19d14b2..d47dc78 100644 --- a/providers/mongodb-atlas.md +++ b/providers/mongodb-atlas.md @@ -1,10 +1,10 @@ -# MongoDB Atlas (`mongodb-atlas`) +# MongoDB Atlas (`mongodb/atlas-admin-api`) ## What it watches The MongoDB Atlas Administration API (`/api/atlas/v2`): an endpoint's API version deprecated (unless MongoDB reactivates it), and an endpoint's API version removed at its sunset date, as MongoDB lists them in its own machine-readable API changelog. -Format plugin: `apichangelog` (`plugins/apichangelog`), with the `MongoDBAtlas` log. +Kind: `changelog` (`plugins/changelog`), with its JSON parser (`json.go`) and the `MongoDBAtlas` log. ## Why this source diff --git a/providers/neon.md b/providers/neon.md index 15bb787..91ffd93 100644 --- a/providers/neon.md +++ b/providers/neon.md @@ -1,10 +1,10 @@ -# Neon (`neon`) +# Neon (`neon/api`) ## What it watches The Neon API (`console.neon.tech/api/v2`), the management API for Neon projects, branches, computes, databases and roles: operations Neon marks deprecated, and removals of operations it had marked deprecated, between two versions of the API's OpenAPI spec. -Format plugin: `openapi` (`plugins/openapi`), with `adapter.Neon`. +Kind: `openapi` (`plugins/openapi`), with `adapter.Neon`. ## Why this source @@ -40,7 +40,7 @@ Format plugin: `openapi` (`plugins/openapi`), with `adapter.Neon`. - **`x-sunset` dates and "Removal scheduled" words:** quoted in the deprecation's excerpt, but not events of their own, since the operations outlive them. - **Request and response property changes, and new operations.** - **History:** over the 23 commits this keeps 1 event: the deprecation of `POST /projects/{project_id}/branches/{branch_id}/auth/send_test_email` (beta) on 2026-08-23. The other 15 deprecated operations were already flagged in the first commit. -- **Replays** a historical pair (`Replay`, from `5c57d009` to `93b93dc9`) and recreates that deprecation (the golden test). The drop test replays `4c6b3be4` to `4497de89`, the `recover` removal. +- **Reads** a historical pair (a version pair, `5c57d009` → `93b93dc9`) and recreates that deprecation (the golden test). The drop test replays `4c6b3be4` to `4497de89`, the `recover` removal. - **A kept removal:** none happened in neon-pkgs's history, so a test replays the same spec from `@neondatabase/api-client` 2.7.2 to 2.7.3 (a different source, used only for this test): `GET /consumption_history/account`, deprecated and then removed, the removal Neon's changelog announced. That's one breaking event. ## Known gaps diff --git a/providers/newrelic.md b/providers/newrelic.md index 37b1a9e..9e87fc3 100644 --- a/providers/newrelic.md +++ b/providers/newrelic.md @@ -1,10 +1,10 @@ -# New Relic (`newrelic`) +# New Relic (`newrelic/python-agent`) ## What it watches Functions and classes removed from New Relic's Python agent (the `newrelic` package) in 11.0.0: `newrelic.agent.record_exception`, `newrelic.agent.add_custom_parameter`, `newrelic.api.log.NewRelicLogHandler`, and others. Code that uses one breaks on the upgrade. The plugin emits one event per member, pinned to that release. -Format plugin: `removedmembers` (`plugins/removedmembers`), reading a Markdown table. +Kind: `migrationguide` (`plugins/migrationguide`), with the removed-members reader (`plugins/migrationguide/members`), reading a Markdown table. ## Why this source diff --git a/providers/numpy.md b/providers/numpy.md index 1810d8d..32357a6 100644 --- a/providers/numpy.md +++ b/providers/numpy.md @@ -1,10 +1,10 @@ -# NumPy (`numpy`) +# NumPy (`numpy/numpy`) ## What it watches Members removed from or renamed in NumPy's main namespace in 2.0.0 (`np.float_`, `np.NaN`, `np.product` and about fifty more): code using one raises `AttributeError`. One event per member. Pinned to that release. -Format plugin: `removedmembers` (`plugins/removedmembers`). +Kind: `migrationguide` (`plugins/migrationguide`), with the removed-members reader (`plugins/migrationguide/members`). ## Why this source diff --git a/providers/openai-models.md b/providers/openai-models.md index ae73355..a021144 100644 --- a/providers/openai-models.md +++ b/providers/openai-models.md @@ -1,10 +1,10 @@ -# OpenAI model retirements (`openai-models`) +# OpenAI model retirements (`openai/models`) ## What it watches 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 `plugins/retirements/retire/`. +Kind: `notices` (`plugins/notices`), reading with the deprecations-page reader, `plugins/notices/retire/`. ## Why this source diff --git a/providers/openai-python-sdk.md b/providers/openai-python-sdk.md new file mode 100644 index 0000000..4d233f1 --- /dev/null +++ b/providers/openai-python-sdk.md @@ -0,0 +1,33 @@ +# OpenAI Python SDK (`openai/python-sdk`) + +## What it watches + +The public API of the `openai` package on PyPI, release by release: classes, functions and methods removed or renamed, parameters removed, and parameters that lost their default (callers must now pass them). One `package_release` event per change. Every final release is listed from PyPI, and each consecutive pair is compared. + +Kind: `apisurface` (`plugins/apisurface`), with the Python reader (`plugins/apisurface/pysurface`). + +## Why this source + +- **Source:** the release files on PyPI (): each release's wheel, `openai--py3-none-any.whl`, read as published. Checked on 2026-11-20. +- **Why this one:** the wheel is exactly what `pip install openai==` installs, so its public names and signatures are what a customer's code calls. A published file never changes, so its URL is its own citation, and the line quoted is in it. +- **Alternatives considered:** the repo's CHANGELOG.md (generated from commit titles; it says "chore(types): rename" without the old and new names a fix needs); GitHub release notes (the same text); the API's OpenAPI spec (the HTTP API, not the Python names and parameters code uses; the `openai/models` source covers the models). +- **Quote:** `class AsssitantDeleted(BaseModel)`, `openai/types/beta/asssitant_deleted.py` line 10 at 1.1.1, gone at 1.1.2 (renamed `AssistantDeleted`). + +## How the provider announces changes + +- The SDK is generated from OpenAI's API spec and released often (several times a week at times). Type names follow the spec, so a renamed schema renames a class without a deprecation step. +- **Forced on upgrade**, for a repo whose pin reaches the release. + +## What the plugin reads and ignores + +- Reads the `.py` and `.pyi` files under `openai/` as text, never importing or running them: module-level classes and functions, the methods of module-level classes, their parameters and defaults, `__all__`, and an `__init__`'s re-exports. +- Ignores private names (a leading underscore, a module under a private one, a name left out of `__all__`), classes nested in classes, and tests. +- Drops (and logs): an overloaded function's parameters; a removed parameter when the function now takes `**kwargs`; a new parameter without a default (the change-event contract has no subject for it yet). +- A removal is a rename only when the same scope loses one and gains one of the same kind with identical parameters, at least one of them besides `self`/`cls`; anything less sure is a removal. +- Drops (and logs) a removal that may not be one: a symbol whose file the newer release has too big to read (`MaxFileBytes`); a method whose class is still there but whose bases changed, which one of its bases (followed through the package's own classes, private ones included) now defines, or which the class now defines as an attribute (`create = _create`, a property made a plain attribute). + +## Known gaps + +- A class with no `__init__` of its own (the generated pydantic types) has no parameters to compare, so its rename reads as a removal of the old name, and its fields aren't compared. +- A method moved to a base class from outside the package (a dependency's class) is still read as removed when the bases themselves didn't change: the dependency's code isn't read. +- Type changes (an annotation narrowed) aren't events. diff --git a/providers/planetscale.md b/providers/planetscale.md index 4ff0a46..9a54a6f 100644 --- a/providers/planetscale.md +++ b/providers/planetscale.md @@ -1,10 +1,10 @@ -# PlanetScale (`planetscale`) +# PlanetScale (`planetscale/api`) ## What it watches The PlanetScale API (`api.planetscale.com/v1`): operations PlanetScale marks deprecated, and removals of operations it had marked deprecated, between two versions of the API's OpenAPI spec. PlanetScale says it in the operation's description, never with the `deprecated` flag. -Format plugin: `openapi` (`plugins/openapi`), with `adapter.PlanetScale`. +Kind: `openapi` (`plugins/openapi`), with `adapter.PlanetScale`. ## Why this source @@ -40,7 +40,7 @@ Format plugin: `openapi` (`plugins/openapi`), with `adapter.PlanetScale`. - **Removals of operations that were never deprecated.** 41 in the history: 1 on 2026-06-01, 7 on 2026-10-03, 17 on 2026-10-14, 7 on 2026-10-23, 9 on 2026-11-09. On 2026-10-03, 6 of them were the read-only replica operations, renamed to dedicated read replicas, and on 2026-11-19 planetscale-go's `main` still sends `.../read-only-replicas` ("the deprecated read-only-replicas path", in its own words). Leaving the spec isn't the same as stopping working. - **Request and response property changes, and new operations.** The history has 216 new operations, and the property side is noisy: 226 type changes on 2025-12-06 alone, when whole numbers became `integer`. - Over the 31 consecutive pairs this keeps 5 events, all deprecations on 2026-11-09 (`fc13e09d`): `GET` and `DELETE .../bouncers/{bouncer}/resizes`, `GET .../neki-changes`, `GET` and `DELETE .../neki-changes/{id}`. A pattern matching "deprecat" anywhere in the description finds the same 5. -- **Replays** a historical pair (`Replay`, from `e631095a` to `fc13e09d`) and recreates those 5. The drop test replays `b49c3540` to `f6d6ad4d` (the replica rename): no event, where the same pair unfiltered reports the 7 removals. +- **Reads** a historical pair (a version pair, `e631095a` → `fc13e09d`) and recreates those 5. The drop test replays `b49c3540` to `f6d6ad4d` (the replica rename): no event, where the same pair unfiltered reports the 7 removals. ## Known gaps diff --git a/providers/posthog.md b/providers/posthog.md index 473547b..917620c 100644 --- a/providers/posthog.md +++ b/providers/posthog.md @@ -1,10 +1,10 @@ -# PostHog (`posthog`) +# PostHog (`posthog/python-sdk`) ## What it watches Members removed from the `posthog` Python SDK in 8.0.0 (`CaptureMode`, `posthog.capture_v1`, `posthog.capture_v1.CaptureV1Error`, `posthog.request.batch_post`…): code using one breaks on the upgrade. One event per member. Pinned to that release. -Format plugin: `removedmembers` (`plugins/removedmembers`), reading a Markdown table. +Kind: `migrationguide` (`plugins/migrationguide`), with the removed-members reader (`plugins/migrationguide/members`), reading a Markdown table. ## Why this source diff --git a/providers/redis.md b/providers/redis.md index 98808be..fb28c52 100644 --- a/providers/redis.md +++ b/providers/redis.md @@ -1,10 +1,10 @@ -# Redis (`redis`) +# Redis (`redis/commands`) ## What it watches Redis's command surface: commands that disappear entirely from `redis-doc`'s own catalog of every command, between two snapshots of it. -Format plugin: `catalog` (`plugins/catalog`), new in this change — no existing format plugin reads a flat JSON catalog keyed by name; see "Alternatives considered" for the formats checked and ruled out first. +Kind: `catalog` (`plugins/catalog`), new in this change — no existing format plugin reads a flat JSON catalog keyed by name; see "Alternatives considered" for the formats checked and ruled out first. ## Why this source @@ -25,10 +25,10 @@ Format plugin: `catalog` (`plugins/catalog`), new in this change — no existing ## What the plugin reads and ignores -- Reads: `commands.json` at the newest commit, diffed against the last one stored (or two given commits, to replay). A name present before and missing after becomes a `breaking` `package_release` event (`change: removed_symbol`); the excerpt quotes the entry's own JSON from the snapshot where it still existed. +- Reads: `commands.json` at the newest commit, compared with the commit read before it. A name present before and missing after becomes a `breaking` `package_release` event (`change: removed_symbol`); the excerpt quotes the entry's own JSON from the snapshot where it still existed. - Ignores: everything else about a command (arguments, flags, complexity, ACL categories) — only presence is diffed. A name that's only *added* is not an event. A rename is read as one removal, since nothing in the catalog says a disappearance and an appearance are the same command; guessing that would trade precision for recall. - The live `deprecated_since` / `replaced_by` fields on still-present commands aren't read yet (see "Known gaps"): they're deprecations, not removals, and every one of them already works forever regardless. -- Replays a historical pair (`Replay`, from commit `cc0427b` to `06f3598`) and recreates the real removal of `FUNCTION CREATE` and `FUNCTION INFO` (the golden test uses trimmed excerpts of both commits' `commands.json`, alongside `GET`, unchanged, as the drop-test fixture). +- Reads a historical pair (a version pair, commit `cc0427b` → `06f3598`) and recreates the real removal of `FUNCTION CREATE` and `FUNCTION INFO` (the golden test uses trimmed excerpts of both commits' `commands.json`, alongside `GET`, unchanged, as the drop-test fixture). ## Known gaps diff --git a/providers/salesforce.md b/providers/salesforce.md index 1396a1b..ddb6c19 100644 --- a/providers/salesforce.md +++ b/providers/salesforce.md @@ -1,10 +1,10 @@ -# Salesforce (`salesforce`) +# Salesforce (`salesforce/rest-api`) ## What it watches Salesforce's REST API version policy: whole numbered API version ranges (`/services/data/vNN.N/`) that Salesforce's own end-of-life page says are already retired (every resource under that version returns `410:GONE`) or scheduled to be. -Format plugin: `eol` (`plugins/eol`), with the `Salesforce` page. +Kind: `notices` (`plugins/notices`), with the end-of-life reader (`plugins/notices/eol`) and its `Salesforce` page. ## Why this source diff --git a/providers/sentry.md b/providers/sentry.md index c851d03..06914d5 100644 --- a/providers/sentry.md +++ b/providers/sentry.md @@ -1,10 +1,10 @@ -# Sentry (`sentry`) +# Sentry (`sentry/api`) ## What it watches Sentry's public REST API (`https://{region}.sentry.io/api/0/...`): operations Sentry deprecates, between releases of its OpenAPI spec. Most of them it deprecates in the operation's description, not with the `deprecated` flag. -Format plugin: `openapi` (`plugins/openapi`), with `adapter.Sentry`. +Kind: `openapi` (`plugins/openapi`), with `adapter.Sentry`. ## Why this source @@ -47,7 +47,7 @@ Format plugin: `openapi` (`plugins/openapi`), with `adapter.Sentry`. - Compared as published, 446 operations left the spec: the 289 more are the 2026-11-13 move of `/api/0`, `GET .../issues/` and `POST .../user-feedback/` among them, both flagged deprecated. A rule keeping removals of deprecated operations would report those two shut down. - **Property changes, and new operations.** - **History:** 13 events over the whole history, all deprecations: the 13 above, none withdrawn. By the flag alone it would be 3, two of them dated 2026-06-16 instead of 2024 and 2025. -- **Replays** the three description deprecations in the golden test (sentry-api-schema commits `ead7f0cf` → `4650a66a`, `d64149d6` → `c2f638f6`, `47231e61` → `1da1f31f`). The drop test replays `2.0.1` → `2.1.0`, the `/api/0` move. Other tests replay `0.223.0` → `0.224.0` (the flag after the words) and the two commits that added the "deprecation" wording that isn't a deprecation. +- **Reads** the three description deprecations in the golden test (sentry-api-schema commits `ead7f0cf` → `4650a66a`, `d64149d6` → `c2f638f6`, `47231e61` → `1da1f31f`). The drop test replays `2.0.1` → `2.1.0`, the `/api/0` move. Other tests replay `0.223.0` → `0.224.0` (the flag after the words) and the two commits that added the "deprecation" wording that isn't a deprecation. ## Known gaps diff --git a/providers/stripe.md b/providers/stripe.md index 6c94bd1..2f385a7 100644 --- a/providers/stripe.md +++ b/providers/stripe.md @@ -1,10 +1,10 @@ -# Stripe (`stripe`) +# Stripe (`stripe/api`) ## What it watches Stripe's REST API, release by release: endpoints, parameters, fields, schemas and enum values that are removed, renamed, retyped or added between two versions of Stripe's own OpenAPI spec. Breaking events carry Stripe's own explanation from its API changelog as the migration hint when the changelog has one. -Format plugin: `openapi` (`plugins/openapi`), with `adapter.Stripe` and the changelog hint source in `hint/`. +Kind: `openapi` (`plugins/openapi`), with `adapter.Stripe` and the changelog hint source in `hint/`. ## Why this source @@ -24,7 +24,7 @@ Format plugin: `openapi` (`plugins/openapi`), with `adapter.Stripe` and the chan - 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). +- Reads a historical pair (a version pair, `v207` → `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. ## Known gaps diff --git a/providers/supabase.md b/providers/supabase.md index 87ec785..8d096bd 100644 --- a/providers/supabase.md +++ b/providers/supabase.md @@ -1,10 +1,10 @@ -# Supabase (`supabase`) +# Supabase (`supabase/management-api`) ## What it watches The Supabase Management API (`api.supabase.com/v1`): operations Supabase marks deprecated, and removals of operations it had marked deprecated, between two versions of the API's OpenAPI spec. -Format plugin: `openapi` (`plugins/openapi`), with `adapter.Supabase`. +Kind: `openapi` (`plugins/openapi`), with `adapter.Supabase`. ## Why this source @@ -35,7 +35,7 @@ Format plugin: `openapi` (`plugins/openapi`), with `adapter.Supabase`. - **Removals of operations that were never deprecated.** 22 operations left the spec in its history, none deprecated first: 14 analytics warehouse operations on 2024-07-15, 7 path-parameter renames, and one that came back 12 days later. Without credentials every route answers `401`, made-up ones included, so whether a removed one still works can't be checked from outside. - **Request and response property changes, and new operations.** - Over the 90 commits this keeps 2 events, both deprecations: `POST /v1/projects/{ref}/functions` (2025-02-19) and `GET /v1/projects/{ref}/analytics/endpoints/logs.all` (2026-06-29). -- **Replays** a historical pair (`Replay`, from `693bdc38` to `eb21ae25`) and recreates the `logs.all` deprecation. The golden test also runs the `functions` deprecation as a daily ingest. The drop tests replay the warehouse removal and the branch path-parameter rename. +- **Reads** a historical pair (a version pair, `693bdc38` → `eb21ae25`) and recreates the `logs.all` deprecation. The golden test also runs the `functions` deprecation as a daily ingest. The drop tests replay the warehouse removal and the branch path-parameter rename. ## Known gaps diff --git a/providers/textual.md b/providers/textual.md index 4b13089..602855e 100644 --- a/providers/textual.md +++ b/providers/textual.md @@ -1,10 +1,10 @@ -# Textual (`textual`) +# Textual (`textual/textual`) ## What it watches Removals and breaking changes in each Textual release, read from that release's section of its changelog: symbols removed (`App.dark`, …) or renamed. One `package_release` event per changelog bullet the plugin can read with certainty. The releases are listed from PyPI (final releases only) and each is read at its tag (`v`); 0.86.0 is the release the golden test pins. -Format plugin: `changelog` (`plugins/changelog`). +Kind: `changelog` (`plugins/changelog`). ## Why this source diff --git a/providers/urllib3.md b/providers/urllib3.md index df1088c..7ba3bcc 100644 --- a/providers/urllib3.md +++ b/providers/urllib3.md @@ -1,10 +1,10 @@ -# urllib3 (`urllib3`) +# urllib3 (`urllib3/urllib3`) ## What it watches Removals and deprecations in each urllib3 release, read from that release's section of its changelog: classes, methods and modules removed or renamed. One `package_release` event per bullet the plugin can read with certainty. The releases are listed from PyPI (final releases only) and each is read at its git tag (``); 2.0.0 is the release the golden test pins. -Format plugin: `changelog` (`plugins/changelog`). +Kind: `changelog` (`plugins/changelog`). ## Why this source diff --git a/providers/vercel.md b/providers/vercel.md index fb6e034..1b01fc9 100644 --- a/providers/vercel.md +++ b/providers/vercel.md @@ -1,10 +1,10 @@ -# Vercel (`vercel`) +# Vercel (`vercel/api`) ## What it watches Vercel's REST API, release by release: operations Vercel marks deprecated, and deprecated operations it then removes, between two versions of the OpenAPI spec Vercel generates its official SDK (`@vercel/sdk`) from. -Format plugin: `openapi` (`plugins/openapi`), with `adapter.Vercel`. +Kind: `openapi` (`plugins/openapi`), with `adapter.Vercel`. ## Why this source @@ -36,7 +36,7 @@ Format plugin: `openapi` (`plugins/openapi`), with `adapter.Vercel`. - **Request properties.** 478 breaking request-property changes, most of them union members compared by position as their order moved. Outside unions there were 142, and 27 of those reverted later. - **New operations.** Nobody has to fix code for a new endpoint. - Over the 207 releases, this keeps 26 events: 22 deprecations, and the removal of the four Legacy Domains operations, all four of which Vercel shut down. -- **Replays** a historical pair (`Replay`, from `v1.18.6` to `v1.18.7`) and recreates the removal of `GET /v4/domains/price` and `GET /v4/domains/status`. The golden test also runs the deprecation of all four operations (`v1.13.4` to `v1.13.5`). The drop tests replay an unmarked removal (`v1.6.2` to `v1.6.3`) and the path-parameter rename (`v1.28.64` to `v1.28.65`). +- **Reads** a historical pair (a version pair, `v1.18.6` → `v1.18.7`) and recreates the removal of `GET /v4/domains/price` and `GET /v4/domains/status`. The golden test also runs the deprecation of all four operations (`v1.13.4` to `v1.13.5`). The drop tests replay an unmarked removal (`v1.6.2` to `v1.6.3`) and the path-parameter rename (`v1.28.64` to `v1.28.65`). ## Known gaps diff --git a/providers/vertex-ai-models.md b/providers/vertex-ai-models.md index d167ad0..b34e22c 100644 --- a/providers/vertex-ai-models.md +++ b/providers/vertex-ai-models.md @@ -1,10 +1,10 @@ -# Vertex AI generative models (`vertex-ai-models`) +# Vertex AI generative models (`google/vertex-ai-models`) ## What it watches Generative AI model endpoints on Google Cloud's Vertex AI that Google deprecates: one `model` event per model id in a "Discontinued endpoints" table, with the replacement when the row names exactly one. -Format plugin: `feed` (`plugins/feed`), with the `VertexAIModels` reader. +Kind: `notices` (`plugins/notices`), with the feed reader (`plugins/notices/feed`) and its `VertexAIModels` feed. ## Why this source diff --git a/retire/retire.go b/retire/retire.go deleted file mode 100644 index e519a3e..0000000 --- a/retire/retire.go +++ /dev/null @@ -1,23 +0,0 @@ -// Package retire is the old import path of github.com/patch-it-dev/patch-it-plugins/plugins/retirements/retire. -// -// 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 moved "github.com/patch-it-dev/patch-it-plugins/plugins/retirements/retire" - -// Deprecated: the types live in github.com/patch-it-dev/patch-it-plugins/plugins/retirements/retire. -type ( - Page = moved.Page - Retirement = moved.Retirement -) - -// Deprecated: the functions and values live in github.com/patch-it-dev/patch-it-plugins/plugins/retirements/retire. -var ( - Events = moved.Events - First = moved.First - Parse = moved.Parse - Anthropic = moved.Anthropic - OpenAI = moved.OpenAI -) diff --git a/scripts/check_contract.py b/scripts/check_contract.py index 5bbc0fd..5477c14 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 core/event/ and -core/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/ +tests 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 deleted file mode 100644 index 7b1a75f..0000000 --- a/sdkguide/sdkguide.go +++ /dev/null @@ -1,21 +0,0 @@ -// Package sdkguide is the old import path of github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/sdkguide. -// -// 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 moved "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/sdkguide" - -// Deprecated: the types live in github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/sdkguide. -type ( - Guide = moved.Guide - Removal = moved.Removal -) - -// 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 -)