From dde9f098ef1305b56f3eff7a8f4c66d2693032d3 Mon Sep 17 00:00:00 2001 From: adssib <75389300+adssib@users.noreply.github.com> Date: Fri, 20 Nov 2026 17:48:12 -0500 Subject: [PATCH 01/16] merge removedmembers into the migrationguide kind One kind for a guide that lists what a release removed: the SDK guide and the removed-members readers implement migrationguide.Guide, and one Plugin lists, reads and extracts for both. plugins/removedmembers only forwards now; old kind names resolve through plugin.CanonicalKind. Co-Authored-By: Claude Opus 5.5 Signed-off-by: adssib <75389300+adssib@users.noreply.github.com> --- AGENTS.md | 5 +- cmd/new-plugin/formats.go | 27 +- cmd/new-plugin/main.go | 20 +- core/plugin/provider.go | 18 +- core/plugin/provider_test.go | 13 + docs/how-it-works.md | 4 +- docs/plugins.schema.json | 2 +- docs/writing-a-plugin.md | 5 +- internal/pluginlist/schema_test.go | 3 +- plugins/all/all.go | 1 - plugins/migrationguide/members/export_test.go | 11 + plugins/migrationguide/members/golden_test.go | 18 + .../members}/markdown.go | 2 +- plugins/migrationguide/members/members.go | 327 ++++++++++++++ .../migrationguide/members/members_test.go | 91 ++++ .../members}/newrelic.go | 2 +- .../members}/newrelic_test.go | 21 +- .../members}/posthog.go | 2 +- .../members}/posthog_test.go | 15 +- .../migrationguide/members/registered_test.go | 14 + .../members}/testdata/README.md | 2 +- .../migration-7.x-to-8.0-posthog-v8.0.0.md | 0 .../numpy_2_0_migration_guide-v2.0.0.rst | 0 .../members}/testdata/pypi-numpy-excerpt.json | 0 .../testdata/python-agent-110000-f0b4f817.mdx | 0 .../members}/versions_test.go | 9 +- plugins/migrationguide/migrationguide.go | 151 ++++--- plugins/migrationguide/sdkguide/versions.go | 86 ++++ plugins/migrationguide/testdata/README.md | 4 +- .../testdata/golden/newrelic-11.0.0.json | 0 .../testdata/golden/numpy-2.0.0.json | 0 .../testdata/golden/posthog-8.0.0.json | 0 plugins/removedmembers/golden_test.go | 15 - plugins/removedmembers/registered_test.go | 11 - plugins/removedmembers/removedmembers.go | 399 ++---------------- plugins/removedmembers/removedmembers_test.go | 84 +--- providers/newrelic.md | 2 +- providers/numpy.md | 2 +- providers/posthog.md | 2 +- 39 files changed, 767 insertions(+), 601 deletions(-) create mode 100644 plugins/migrationguide/members/export_test.go create mode 100644 plugins/migrationguide/members/golden_test.go rename plugins/{removedmembers => migrationguide/members}/markdown.go (99%) create mode 100644 plugins/migrationguide/members/members.go create mode 100644 plugins/migrationguide/members/members_test.go rename plugins/{removedmembers => migrationguide/members}/newrelic.go (99%) rename plugins/{removedmembers => migrationguide/members}/newrelic_test.go (91%) rename plugins/{removedmembers => migrationguide/members}/posthog.go (99%) rename plugins/{removedmembers => migrationguide/members}/posthog_test.go (93%) create mode 100644 plugins/migrationguide/members/registered_test.go rename plugins/{removedmembers => migrationguide/members}/testdata/README.md (91%) rename plugins/{removedmembers => migrationguide/members}/testdata/migration-7.x-to-8.0-posthog-v8.0.0.md (100%) rename plugins/{removedmembers => migrationguide/members}/testdata/numpy_2_0_migration_guide-v2.0.0.rst (100%) rename plugins/{removedmembers => migrationguide/members}/testdata/pypi-numpy-excerpt.json (100%) rename plugins/{removedmembers => migrationguide/members}/testdata/python-agent-110000-f0b4f817.mdx (100%) rename plugins/{removedmembers => migrationguide/members}/versions_test.go (88%) create mode 100644 plugins/migrationguide/sdkguide/versions.go rename plugins/{removedmembers => migrationguide}/testdata/golden/newrelic-11.0.0.json (100%) rename plugins/{removedmembers => migrationguide}/testdata/golden/numpy-2.0.0.json (100%) rename plugins/{removedmembers => migrationguide}/testdata/golden/posthog-8.0.0.json (100%) delete mode 100644 plugins/removedmembers/golden_test.go delete mode 100644 plugins/removedmembers/registered_test.go diff --git a/AGENTS.md b/AGENTS.md index 24b5996..8e27cd2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -57,9 +57,10 @@ core/kit/ core/kit/kittest/ Unchanged, Cite, Wayback; the test kit (Mem, Page core/event/ core/migrate/ the change-event types from patch-it's contract (v1 + v2), v1 -> v2 core/diff/ core/normalize/ core/hint/ the OpenAPI diff engine and its helpers plugins// one package per kind, with its providers: openapi (+ adapter/, one spec adapter - per provider), retirements (+ retire/), migrationguide (+ sdkguide/), - removedmembers, changelog, feed, apichangelog, catalog, eol; + per provider), retirements (+ retire/), migrationguide (+ sdkguide/, + members/), changelog, feed, apichangelog, catalog, eol; plugins/all imports every one +plugins/removedmembers/ deprecated: merged into migrationguide, only forwards there 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 diff --git a/cmd/new-plugin/formats.go b/cmd/new-plugin/formats.go index 7c88291..2887c0d 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) @@ -30,6 +31,7 @@ const todo = "TODO(new-plugin)" var formats = map[string]formatSpec{ "feed": { + kind: "feed", layer: "api", defDir: "plugins/feed", def: `package feed @@ -80,6 +82,7 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { }, "retirements": { + kind: "retirements", layer: "ai-models", defDir: "plugins/retirements/retire", def: `package retire @@ -153,6 +156,7 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { }, "migrationguide": { + kind: "migrationguide", layer: "sdk", defDir: "plugins/migrationguide/sdkguide", def: `package sdkguide @@ -219,9 +223,10 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { }, "removedmembers": { + 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. @@ -238,8 +243,8 @@ var {{.Ident}} = Guide{ 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 @@ -278,7 +283,7 @@ 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) } } } @@ -287,13 +292,14 @@ func Test{{.Ident}}DropsANonChange(t *testing.T) { ingest: `// {{.Lower}}Ingest runs the plugin over a saved copy of the guide. func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { 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": { + kind: "changelog", layer: "package", defDir: "plugins/changelog", def: `package changelog @@ -335,6 +341,7 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { }, "apichangelog": { + kind: "apichangelog", layer: "api", defDir: "plugins/apichangelog", def: `package apichangelog @@ -372,6 +379,7 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { }, "catalog": { + kind: "catalog", layer: "runtime", defDir: "plugins/catalog", def: `package catalog @@ -421,6 +429,7 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { }, "openapi": { + kind: "openapi", layer: "api", defDir: "plugins/openapi/adapter", def: `package adapter @@ -497,7 +506,7 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { } // testFile is the generated test, the same for every format. -const testFile = `package {{.Format}} +const testFile = `package {{.Kind}} import ( {{range .Imports}} "{{.}}" @@ -518,7 +527,7 @@ 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 // pull request someone may get. diff --git a/cmd/new-plugin/main.go b/cmd/new-plugin/main.go index 12e21bc..7fc2db6 100644 --- a/cmd/new-plugin/main.go +++ b/cmd/new-plugin/main.go @@ -94,10 +94,10 @@ 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, Ident, Lower, Provider, Source, File, Format, Kind 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. @@ -143,7 +143,7 @@ func Run(o Options, out io.Writer) error { return fmt.Errorf("a plugin named %q is already registered: pick another --api", o.API) } - d := data{ID: o.API, Provider: o.Provider, Source: o.Source, Format: o.Format} + d := data{ID: o.API, Provider: o.Provider, Source: o.Source, Format: o.Format, Kind: f.kind} d.Ident = ident(o.API) d.Lower = string(unicode.ToLower(rune(d.Ident[0]))) + d.Ident[1:] d.File = fileBase(o.API) @@ -156,7 +156,7 @@ 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 } @@ -267,13 +267,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. diff --git a/core/plugin/provider.go b/core/plugin/provider.go index 4546d40..88e75e9 100644 --- a/core/plugin/provider.go +++ b/core/plugin/provider.go @@ -204,7 +204,7 @@ func (p Provider) check() error { return fmt.Errorf("source %q has no URLs", id) case !strings.HasPrefix(s.Page, "providers/") || !strings.HasSuffix(s.Page, ".md"): return fmt.Errorf("source %q: Page %q isn't providers/.md", id, s.Page) - case s.Kind != "" && s.Kind != KindOf(s.Plugin): + case s.Kind != "" && CanonicalKind(s.Kind) != KindOf(s.Plugin): return fmt.Errorf("source %q: Kind %q, but its plugin is in plugins/%s", id, s.Kind, KindOf(s.Plugin)) } for _, u := range s.URLs { @@ -232,6 +232,22 @@ func KindOf(p Plugin) string { return path.Base(t.PkgPath()) } +// mergedKinds are the kinds merged into another, by their old name: what +// they read is read by the new kind, with the same events. +var mergedKinds = map[string]string{ + "removedmembers": "migrationguide", +} + +// CanonicalKind is the kind name means now: name itself, or, for a kind +// merged into another ("removedmembers"), the kind that reads its sources +// now ("migrationguide"). Code that still says an old kind keeps working. +func CanonicalKind(name string) string { + if k, ok := mergedKinds[name]; ok { + return k + } + return name +} + // Providers are the registered providers with their sources, sorted by id // (sources by id within each). func Providers() []Provider { diff --git a/core/plugin/provider_test.go b/core/plugin/provider_test.go index e890f1d..cc2bdf6 100644 --- a/core/plugin/provider_test.go +++ b/core/plugin/provider_test.go @@ -82,3 +82,16 @@ func TestRegisterProviderRefusesConflictingProvider(t *testing.T) { p.Name = "Acme Corp" RegisterProvider(p) } + +// A kind merged into another still names it: a source registered with the +// old name passes the check, and the old name reads as the new one. +func TestMergedKindsKeepWorking(t *testing.T) { + for old, now := range mergedKinds { + if got := CanonicalKind(old); got != now { + t.Errorf("CanonicalKind(%q) = %q, want %q", old, got, now) + } + } + if got := CanonicalKind("openapi"); got != "openapi" { + t.Errorf("CanonicalKind(openapi) = %q", got) + } +} diff --git a/docs/how-it-works.md b/docs/how-it-works.md index 9a30707..2ffe84c 100644 --- a/docs/how-it-works.md +++ b/docs/how-it-works.md @@ -26,9 +26,9 @@ There's no list in this repo: `make plugins` prints every provider and source fr | [`core/kit/`](../core/kit/), [`core/kit/kittest/`](../core/kit/kittest/), [`core/github/`](../core/github/) | What plugins share (the unchanged-page check, Wayback citing, the newest release or commit on GitHub) and the test kit (in-memory store, saved pages, golden files) | | [`core/event/`](../core/event/), [`core/migrate/`](../core/migrate/) | The change-event types of [patch-it's contract](https://github.com/patch-it-dev/patch-it/tree/main/docs/contract), and the v1 → v2 conversion | | [`core/diff/`](../core/diff/), [`core/normalize/`](../core/normalize/), [`core/hint/`](../core/hint/), [`plugins/openapi/adapter/`](../plugins/openapi/adapter/) | The OpenAPI diff engine: compare two specs, turn the changes into events, attach changelog hints; one adapter per spec provider | -| [`plugins/retirements/retire/`](../plugins/retirements/retire/), [`plugins/migrationguide/sdkguide/`](../plugins/migrationguide/sdkguide/), [`core/fetch/`](../core/fetch/) | The deprecations-page and migration-guide readers; the HTTP fetch and cache | +| [`plugins/retirements/retire/`](../plugins/retirements/retire/), [`plugins/migrationguide/sdkguide/`](../plugins/migrationguide/sdkguide/), [`plugins/migrationguide/members/`](../plugins/migrationguide/members/), [`core/fetch/`](../core/fetch/) | The deprecations-page and 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 | +| `plugin/`, `event/`, `fetch/`, `migrate/`, `kit/`, `kit/kittest/`, `retire/`, `sdkguide/`, `plugins/removedmembers/` | 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..79db6ab 100644 --- a/docs/plugins.schema.json +++ b/docs/plugins.schema.json @@ -37,7 +37,7 @@ "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"] }, + "kind": { "type": "string", "enum": ["openapi", "retirements", "migrationguide", "changelog", "feed", "apichangelog", "catalog", "eol"] }, "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/writing-a-plugin.md b/docs/writing-a-plugin.md index 58aab2b..1b6fb89 100644 --- a/docs/writing-a-plugin.md +++ b/docs/writing-a-plugin.md @@ -10,7 +10,7 @@ Pick the source and the kind that reads it (steps 2 and 3), then let the starter ```sh go run ./cmd/new-plugin --api acme --provider Acme --format openapi -# --format: openapi, retirements, migrationguide, removedmembers, changelog, feed, apichangelog, catalog +# --format: openapi, retirements, migrationguide, removedmembers (a migrationguide source), 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/) ``` @@ -76,8 +76,7 @@ Write the numbers on the provider page, as `providers/vercel.md` does for its sp |---|---|---| | `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/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.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/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 | diff --git a/internal/pluginlist/schema_test.go b/internal/pluginlist/schema_test.go index 4b7df50..65cb7ea 100644 --- a/internal/pluginlist/schema_test.go +++ b/internal/pluginlist/schema_test.go @@ -95,7 +95,8 @@ func TestSchemaEnumsMatchTheRegistry(t *testing.T) { t.Fatal(err) } for _, k := range kinds { - if name := filepath.Base(k); name != "all" && !slices.Contains(src["kind"].Enum, name) { + // A merged kind's old package only forwards: no source has its name. + if name := filepath.Base(k); name != "all" && plugin.CanonicalKind(name) == name && !slices.Contains(src["kind"].Enum, name) { t.Errorf("kind %s is missing from the schema's kind enum", name) } } diff --git a/plugins/all/all.go b/plugins/all/all.go index 7ca6527..d93ee4d 100644 --- a/plugins/all/all.go +++ b/plugins/all/all.go @@ -11,6 +11,5 @@ import ( _ "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/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/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/migrationguide/members/members.go b/plugins/migrationguide/members/members.go new file mode 100644 index 0000000..ddd25f3 --- /dev/null +++ b/plugins/migrationguide/members/members.go @@ -0,0 +1,327 @@ +// 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). +// +// A row whose guideline is exactly one replacement in the module ("Use +// “np.float64“ instead.") becomes a `renamed_symbol` with that replacement: +// the rename works on NumPy 1.x too, so a fix holds before and after the +// upgrade. Every other row (no replacement, a builtin, an expression, a +// sentence of advice) becomes a `removed_symbol`, which the patch-it client +// opens as an issue: precision over recall. +// +// A guide's table is an RST simple table (NumPy) or a Markdown pipe table +// (PostHog, New Relic, markdown.go). A Markdown row may list several members in one cell; +// 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 members + +import ( + "context" + "fmt" + "log" + "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" +) + +// Guide is one package's guide to one release. +type Guide struct { + Package string // the PyPI name and the events' api: "numpy" + Module string // how the guide writes the module in a replacement: "np" + Release string // "2.0.0" + Repo string // owner/name on GitHub + Path string // the guide's path in the repo at the release tag + Section string // the heading the table is under + + // TagPrefix makes a release's git tag: TagPrefix + version ("" is "v": + // v2.0.0; PostHog's is "posthog-v"). The guide is read at Release's tag. + TagPrefix string + // DocsRef, when the guide isn't in the package's own repo but in a docs + // repo with no release tags (New Relic's release notes), is the commit + // of Repo the guide is read at. + DocsRef string + // Format is how the table is written: FormatRST (the default) or + // FormatMarkdown. + Format Format + // Header is the table's first column heading, matched case-insensitively + // (as a prefix in an RST table); "" is "removed member". + Header string + // Effect is what code using any removed member gets, said in every + // event's description after ". was removed": only for a + // guide whose members are all attributes of Module and all fail the same + // way. "" says only that it was removed. + Effect string + // EnvVars are names in the table that are environment variables, not + // members of the package: no code imports one, so they're dropped. Listed + // by hand from the code, not guessed from a prefix (a package can have + // constants named like its environment variables). + EnvVars []string + // NewReplacements says the release's replacements are new in it: a + // rename fix wouldn't run on the release before, and may need a different + // import. A row with one replacement is then a removed_symbol, with the + // replacement in the migration hint (the guide's own cell), not a + // renamed_symbol the client would apply as a rename. NumPy 2.0's + // replacements already worked on 1.x, so it doesn't set this. + NewReplacements bool + // Paths gives a name the table writes in shorthand the path code imports + // it by, after Module ("EVENTS_ENDPOINT" -> "request.EVENTS_ENDPOINT"), + // checked by hand against the package at the release before. A guide's + // cell can list names that share a prefix only the first one spells out. + // It applies to a removed name and to a replacement alike. + Paths map[string]string + // DropIns, when set, are the only removed members (as the events name + // them, after Paths) whose one replacement is a drop-in: it existed in the + // release before, at the same path, with the same call signature and + // behavior, checked by hand against the code. Only they become a + // renamed_symbol, which the client applies as a rename; every other row + // with one replacement is a removed_symbol, the replacement in the + // migration hint (the guide's own cell). nil leaves it to the table: every + // row with one replacement is a rename (NumPy's guide says each works on + // 1.x), unless NewReplacements. + DropIns []string + // Doc is what the hint calls the source: "'s for + // ". "" is "migration guide". + Doc string + // LinkBase makes the guide's site-relative links absolute in the hint + // ("](/docs/…)" -> "](/docs/…)"): the hint is shown outside the + // vendor's site, in a pull request or an issue, where a relative link + // breaks. "" leaves links as written. + LinkBase string + // StillWork are names the table lists as removed but the same guide says + // still work or have no effect: no event, with the guide's reason. + StillWork map[string]string +} + +// Format is how a guide writes its table. +type Format string + +const ( + FormatRST Format = "" + FormatMarkdown Format = "markdown" +) + +func (g Guide) tag() string { return g.tagOf(g.Release) } + +// tagOf is the git ref a release of the package is read at. +func (g Guide) tagOf(release string) string { + if g.DocsRef != "" { + return g.DocsRef + } + if g.TagPrefix != "" { + return g.TagPrefix + release + } + return "v" + release +} + +func (g Guide) doc() string { + if g.Doc != "" { + return g.Doc + } + return "migration guide" +} + +func (g Guide) header() string { + if g.Header != "" { + return g.Header + } + return "removed member" +} + +// NumPy2 is NumPy's 2.0 migration guide, "Main namespace" table. +var NumPy2 = Guide{ + Package: "numpy", + Module: "np", + Release: "2.0.0", + Repo: "numpy/numpy", + Path: "doc/source/numpy_2_0_migration_guide.rst", + Section: "Main namespace", + Effect: "code using it raises AttributeError", +} + +// URL is the guide as it was at the release tag: its own provenance. +func (g Guide) URL() string { + return fmt.Sprintf("https://raw.githubusercontent.com/%s/%s/%s", g.Repo, g.tag(), g.Path) +} + +// Removal is one removed member and the guide's guideline for it. +type Removal struct { + Member string + Guideline string + Replacement string // the one member to use instead, or "" + Excerpt string // the table's header and the row + Dropped string // why it isn't an event; "" when it is +} + +// Parse reads the section's table: one Removal per member, and one per row or +// name it drops, with the reason in Dropped. +func Parse(page []byte, g Guide) ([]Removal, error) { + if g.Format == FormatMarkdown { + return parseMarkdown(page, g) + } + return parseRST(page, g) +} + +// parseRST reads an RST simple table, the member in the first column, the +// guideline in the second, a guideline continued on the next lines indented to +// the second column. +func parseRST(page []byte, g Guide) ([]Removal, error) { + lines := strings.Split(strings.ReplaceAll(string(page), "\r\n", "\n"), "\n") + start := -1 + for i, l := range lines { + if strings.TrimSpace(l) == g.Section && i+1 < len(lines) && strings.HasPrefix(lines[i+1], "---") { + start = i + break + } + } + if start < 0 { + return nil, fmt.Errorf("no %q section: the guide's shape may have changed", g.Section) + } + border := -1 + for i := start; i < len(lines); i++ { + if strings.HasPrefix(lines[i], "====") && strings.Contains(lines[i], " ") { + border = i + break + } + } + if border < 0 || border+2 >= len(lines) { + return nil, fmt.Errorf("no table under %q", g.Section) + } + col := strings.Index(lines[border], " ") + 1 + for col < len(lines[border]) && lines[border][col] == ' ' { + col++ + } + header := lines[border+1] + if !strings.HasPrefix(strings.ToLower(header), strings.ToLower(g.header())) { + return nil, fmt.Errorf("the table under %q isn't the removed members: %q", g.Section, header) + } + head := strings.Join([]string{lines[border], header, lines[border+2]}, "\n") + var out []Removal + var raw []string + for i := border + 3; i < len(lines) && !strings.HasPrefix(lines[i], "===="); i++ { + l := lines[i] + if len(l) > col && strings.TrimSpace(l[:col]) == "" && len(out) > 0 { + out[len(out)-1].Guideline += " " + strings.TrimSpace(l) + raw[len(raw)-1] += "\n" + l + continue + } + if strings.TrimSpace(l) == "" { + continue + } + member, guide := l, "" + if len(l) > col { + member, guide = l[:col], l[col:] + } + out = append(out, Removal{ + Member: strings.ReplaceAll(strings.TrimSpace(member), `\_`, "_"), + Guideline: strings.TrimSpace(guide), + }) + raw = append(raw, l) + } + if len(out) == 0 { + return nil, fmt.Errorf("the removed members table under %q is empty", g.Section) + } + plain := regexp.MustCompile("^Use ``" + regexp.QuoteMeta(g.Module) + `\.([A-Za-z_][A-Za-z0-9_]*)` + "`` instead\\.$") + for i := range out { + if m := plain.FindStringSubmatch(out[i].Guideline); m != nil { + out[i].Replacement = m[1] + } + out[i].Excerpt = g.Section + "\n" + head + "\n" + raw[i] + } + return out, nil +} + +// Slug is the events' api and the source's old slug: the PyPI name. +func (g Guide) Slug() string { return g.Package } + +// 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 +} + +// Releases is every final release of the package on PyPI, oldest first, +// each with the ref its guide would be read at. +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 = g.tagOf(vs[i].ID) + } + return vs, nil +} + +// 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 "" + } + return g.URL() +} + +// 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) (_ []event.ChangeEvent, events []event.EventV2, rejected []error, err error) { + removals, err := Parse(page, g) + if err != nil { + return nil, nil, nil, err + } + for _, r := range removals { + if r.Dropped != "" { + log.Printf("%s %s: dropped %q: %s", g.Package, g.Release, r.Member, r.Dropped) + continue + } + subject := event.Subject{ + Type: event.SubjectPackageRelease, Ecosystem: "pypi", Package: g.Package, + Change: event.PackageRemovedSymbol, Symbols: []string{r.Member}, + } + desc := fmt.Sprintf("`%s` was removed in %s %s.", r.Member, g.Package, g.Release) + if g.Effect != "" { + desc = fmt.Sprintf("%s.%s was removed in %s %s: %s.", g.Module, r.Member, g.Package, g.Release, g.Effect) + } + 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.ID, + Version: g.Release, + ChangeType: event.ChangeTypeBreaking, + Breaking: true, + Subject: subject, + Description: desc, + MigrationHint: fmt.Sprintf("%s (%s's %s for %s)", g.absoluteLinks(r.Guideline), g.Package, g.doc(), g.Release), + SourceURL: g.URL(), + SourceExcerpt: r.Excerpt, + Confidence: 1.0, + DetectedAt: now, + } + e.Fingerprint = event.FingerprintV2(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 nil, events, rejected, nil +} + +// absoluteLinks prefixes LinkBase to every Markdown link target in s that +// starts with "/". +func (g Guide) absoluteLinks(s string) string { + if g.LinkBase == "" { + return s + } + return strings.ReplaceAll(s, "](/", "]("+strings.TrimSuffix(g.LinkBase, "/")+"/") +} diff --git a/plugins/migrationguide/members/members_test.go b/plugins/migrationguide/members/members_test.go new file mode 100644 index 0000000..2cd1247 --- /dev/null +++ b/plugins/migrationguide/members/members_test.go @@ -0,0 +1,91 @@ +package members_test + +import ( + "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/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). +func guide(t *testing.T) []byte { + t.Helper() + return kittest.Read(t, "testdata/numpy_2_0_migration_guide-v2.0.0.rst") +} + +func byMember(t *testing.T) map[string]Removal { + t.Helper() + rs, err := Parse(guide(t), NumPy2) + if err != nil { + t.Fatal(err) + } + out := map[string]Removal{} + for _, r := range rs { + out[r.Member] = r + } + return out +} + +func TestEveryRemovedMemberOfTheMainNamespaceIsRead(t *testing.T) { + got := byMember(t) + if len(got) != 56 { + t.Errorf("%d removed members, want the table's 56", len(got)) + } + // A guideline continued over several lines is read whole. + if r := got["find_common_type"]; !strings.Contains(r.Guideline, "``0.0``, or ``0j``") { + t.Errorf("find_common_type: %q", r.Guideline) + } + // The table's escaped underscore is the member's own. + if _, ok := got["float_"]; !ok { + t.Error(`no "float_": the \_ escape wasn't undone`) + } +} + +// Only a guideline naming exactly one member of np is a rename; anything else +// (a builtin, an expression, advice) is a removal the patch-it client +// opens as an issue. +func TestOnlyOnePlainReplacementInNpIsARename(t *testing.T) { + got := byMember(t) + for member, want := range map[string]string{ + "float_": "float64", + "NaN": "nan", + "product": "prod", + "cumproduct": "cumprod", + "string_": "bytes_", + "Inf": "inf", + "alltrue": "", // "Use ``all`` instead.": the builtin, or np.all? Not said + "NINF": "", // "Use ``-np.inf`` instead.": an expression + "asfarray": "", // "Use ``np.asarray`` with a float dtype instead." + "compat": "", // no replacement + "who": "", + } { + if r, ok := got[member]; !ok || r.Replacement != want { + t.Errorf("%s: replacement %q, want %q", member, r.Replacement, want) + } + } +} + +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, 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 + 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\\_") { + 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..7a3baf0 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 diff --git a/plugins/removedmembers/newrelic_test.go b/plugins/migrationguide/members/newrelic_test.go similarity index 91% rename from plugins/removedmembers/newrelic_test.go rename to plugins/migrationguide/members/newrelic_test.go index 220052b..9115acb 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 @@ -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) } } } @@ -192,7 +195,7 @@ func TestDropInsLimitsRenames(t *testing.T) { 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 @@ -233,7 +236,7 @@ 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 { 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 99% rename from plugins/removedmembers/posthog.go rename to plugins/migrationguide/members/posthog.go index 9250e5c..d35b74e 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 diff --git a/plugins/removedmembers/posthog_test.go b/plugins/migrationguide/members/posthog_test.go similarity index 93% rename from plugins/removedmembers/posthog_test.go rename to plugins/migrationguide/members/posthog_test.go index 8b7d70a..44b8dee 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 @@ -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) } } } @@ -233,5 +236,5 @@ func TestMarkdownTable(t *testing.T) { // posthogIngest runs the plugin over the saved guide. func posthogIngest(t *testing.T) []event.EventV2 { 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..d0ba2fd 100644 --- a/plugins/migrationguide/migrationguide.go +++ b/plugins/migrationguide/migrationguide.go @@ -1,16 +1,25 @@ -// 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/event" "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/core/versions" + "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/members" "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/sdkguide" ) @@ -24,34 +33,67 @@ func init() { 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"}, + 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"}, + 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"}, + 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 events' api and the source's old slug: "anthropic". + 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: v1 events (converted here) or v2 ones, 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) (v1 []event.ChangeEvent, v2 []event.EventV2, 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 +103,41 @@ 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, false, 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) + v1, v2, 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) + converted, invalid := migrate.Fresh(v1) + return plugin.Result{Label: to.SourceURL, Events: append(converted, v2...), Rejected: append(rejected, invalid...)}, nil } var _ plugin.Versioned = Plugin{} diff --git a/plugins/migrationguide/sdkguide/versions.go b/plugins/migrationguide/sdkguide/versions.go new file mode 100644 index 0000000..592daab --- /dev/null +++ b/plugins/migrationguide/sdkguide/versions.go @@ -0,0 +1,86 @@ +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 events' api and the source's old slug: the SDK's PyPI name. +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.API) + 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 request parameter the to major removed, read from +// its guide, with previous_version from's release. They're v1 events +// (the kind converts them to v2: core/migrate reads this package, so it +// can't be called from here). +func (g Guide) Read(page []byte, from, to plugin.Version, now time.Time) (v1 []event.ChangeEvent, _ []event.EventV2, rejected []error, err error) { + g = g.At(versions.Major(to.ID)) + removals, err := Parse(page, g) + if err != nil { + return nil, nil, nil, err + } + events, errs := Events(g, removals, now) + for i := range events { + events[i].PreviousVersion = from.ID + } + return events, nil, 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/removedmembers/testdata/golden/newrelic-11.0.0.json b/plugins/migrationguide/testdata/golden/newrelic-11.0.0.json similarity index 100% rename from plugins/removedmembers/testdata/golden/newrelic-11.0.0.json rename to plugins/migrationguide/testdata/golden/newrelic-11.0.0.json diff --git a/plugins/removedmembers/testdata/golden/numpy-2.0.0.json b/plugins/migrationguide/testdata/golden/numpy-2.0.0.json similarity index 100% rename from plugins/removedmembers/testdata/golden/numpy-2.0.0.json rename to plugins/migrationguide/testdata/golden/numpy-2.0.0.json diff --git a/plugins/removedmembers/testdata/golden/posthog-8.0.0.json b/plugins/migrationguide/testdata/golden/posthog-8.0.0.json similarity index 100% rename from plugins/removedmembers/testdata/golden/posthog-8.0.0.json rename to plugins/migrationguide/testdata/golden/posthog-8.0.0.json 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/removedmembers/removedmembers.go b/plugins/removedmembers/removedmembers.go index ec78e71..d012195 100644 --- a/plugins/removedmembers/removedmembers.go +++ b/plugins/removedmembers/removedmembers.go @@ -1,385 +1,36 @@ -// 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` -// 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). +// Package removedmembers is the old import path of the migration-guide +// kind's removed-members reader, kept so code that imports it still builds. // -// A row whose guideline is exactly one replacement in the module ("Use -// “np.float64“ instead.") becomes a `renamed_symbol` with that replacement: -// the rename works on NumPy 1.x too, so a fix holds before and after the -// upgrade. Every other row (no replacement, a builtin, an expression, a -// sentence of advice) becomes a `removed_symbol`, which the patch-it client -// opens as an issue: precision over recall. -// -// A guide's table is an RST simple table (NumPy) or a Markdown pipe table -// (PostHog, New Relic, markdown.go). A Markdown row may list several members in one cell; -// 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. +// Deprecated: use plugins/migrationguide (the kind: Plugin) and +// plugins/migrationguide/members (the reader: Guide, NumPy2, Parse). This +// package only forwards to them and registers nothing; it goes once nothing +// imports it. package removedmembers import ( - "context" - "fmt" - "log" - "regexp" - "slices" - "strings" - - "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" + "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/members" ) -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" - Module string // how the guide writes the module in a replacement: "np" - Release string // "2.0.0" - Repo string // owner/name on GitHub - Path string // the guide's path in the repo at the release tag - Section string // the heading the table is under - - // TagPrefix makes a release's git tag: TagPrefix + version ("" is "v": - // v2.0.0; PostHog's is "posthog-v"). The guide is read at Release's tag. - TagPrefix string - // DocsRef, when the guide isn't in the package's own repo but in a docs - // repo with no release tags (New Relic's release notes), is the commit - // of Repo the guide is read at. - DocsRef string - // Format is how the table is written: FormatRST (the default) or - // FormatMarkdown. - Format Format - // Header is the table's first column heading, matched case-insensitively - // (as a prefix in an RST table); "" is "removed member". - Header string - // Effect is what code using any removed member gets, said in every - // event's description after ". was removed": only for a - // guide whose members are all attributes of Module and all fail the same - // way. "" says only that it was removed. - Effect string - // EnvVars are names in the table that are environment variables, not - // members of the package: no code imports one, so they're dropped. Listed - // by hand from the code, not guessed from a prefix (a package can have - // constants named like its environment variables). - EnvVars []string - // NewReplacements says the release's replacements are new in it: a - // rename fix wouldn't run on the release before, and may need a different - // import. A row with one replacement is then a removed_symbol, with the - // replacement in the migration hint (the guide's own cell), not a - // renamed_symbol the client would apply as a rename. NumPy 2.0's - // replacements already worked on 1.x, so it doesn't set this. - NewReplacements bool - // Paths gives a name the table writes in shorthand the path code imports - // it by, after Module ("EVENTS_ENDPOINT" -> "request.EVENTS_ENDPOINT"), - // checked by hand against the package at the release before. A guide's - // cell can list names that share a prefix only the first one spells out. - // It applies to a removed name and to a replacement alike. - Paths map[string]string - // DropIns, when set, are the only removed members (as the events name - // them, after Paths) whose one replacement is a drop-in: it existed in the - // release before, at the same path, with the same call signature and - // behavior, checked by hand against the code. Only they become a - // renamed_symbol, which the client applies as a rename; every other row - // with one replacement is a removed_symbol, the replacement in the - // migration hint (the guide's own cell). nil leaves it to the table: every - // row with one replacement is a rename (NumPy's guide says each works on - // 1.x), unless NewReplacements. - DropIns []string - // Doc is what the hint calls the source: "'s for - // ". "" is "migration guide". - Doc string - // LinkBase makes the guide's site-relative links absolute in the hint - // ("](/docs/…)" -> "](/docs/…)"): the hint is shown outside the - // vendor's site, in a pull request or an issue, where a relative link - // breaks. "" leaves links as written. - LinkBase string - // StillWork are names the table lists as removed but the same guide says - // still work or have no effect: no event, with the guide's reason. - StillWork map[string]string -} - -// Format is how a guide writes its table. -type Format string +type ( + // Plugin is migrationguide.Plugin: its Guide is now any reader, a + // members.Guide among them. + Plugin = migrationguide.Plugin + Guide = members.Guide + Format = members.Format + Removal = members.Removal +) const ( - FormatRST Format = "" - FormatMarkdown Format = "markdown" + FormatRST = members.FormatRST + FormatMarkdown = members.FormatMarkdown ) -func (g Guide) tag() string { return g.tagOf(g.Release) } - -// tagOf is the git ref a release of the package is read at. -func (g Guide) tagOf(release string) string { - if g.DocsRef != "" { - return g.DocsRef - } - if g.TagPrefix != "" { - return g.TagPrefix + release - } - return "v" + release -} - -func (g Guide) doc() string { - if g.Doc != "" { - return g.Doc - } - return "migration guide" -} - -func (g Guide) header() string { - if g.Header != "" { - return g.Header - } - return "removed member" -} - -// NumPy2 is NumPy's 2.0 migration guide, "Main namespace" table. -var NumPy2 = Guide{ - Package: "numpy", - Module: "np", - Release: "2.0.0", - Repo: "numpy/numpy", - Path: "doc/source/numpy_2_0_migration_guide.rst", - Section: "Main namespace", - Effect: "code using it raises AttributeError", -} - -// URL is the guide as it was at the release tag: its own provenance. -func (g Guide) URL() string { - return fmt.Sprintf("https://raw.githubusercontent.com/%s/%s/%s", g.Repo, g.tag(), g.Path) -} - -// Removal is one removed member and the guide's guideline for it. -type Removal struct { - Member string - Guideline string - Replacement string // the one member to use instead, or "" - Excerpt string // the table's header and the row - Dropped string // why it isn't an event; "" when it is -} - -// Parse reads the section's table: one Removal per member, and one per row or -// name it drops, with the reason in Dropped. -func Parse(page []byte, g Guide) ([]Removal, error) { - if g.Format == FormatMarkdown { - return parseMarkdown(page, g) - } - return parseRST(page, g) -} - -// parseRST reads an RST simple table, the member in the first column, the -// guideline in the second, a guideline continued on the next lines indented to -// the second column. -func parseRST(page []byte, g Guide) ([]Removal, error) { - lines := strings.Split(strings.ReplaceAll(string(page), "\r\n", "\n"), "\n") - start := -1 - for i, l := range lines { - if strings.TrimSpace(l) == g.Section && i+1 < len(lines) && strings.HasPrefix(lines[i+1], "---") { - start = i - break - } - } - if start < 0 { - return nil, fmt.Errorf("no %q section: the guide's shape may have changed", g.Section) - } - border := -1 - for i := start; i < len(lines); i++ { - if strings.HasPrefix(lines[i], "====") && strings.Contains(lines[i], " ") { - border = i - break - } - } - if border < 0 || border+2 >= len(lines) { - return nil, fmt.Errorf("no table under %q", g.Section) - } - col := strings.Index(lines[border], " ") + 1 - for col < len(lines[border]) && lines[border][col] == ' ' { - col++ - } - header := lines[border+1] - if !strings.HasPrefix(strings.ToLower(header), strings.ToLower(g.header())) { - return nil, fmt.Errorf("the table under %q isn't the removed members: %q", g.Section, header) - } - head := strings.Join([]string{lines[border], header, lines[border+2]}, "\n") - var out []Removal - var raw []string - for i := border + 3; i < len(lines) && !strings.HasPrefix(lines[i], "===="); i++ { - l := lines[i] - if len(l) > col && strings.TrimSpace(l[:col]) == "" && len(out) > 0 { - out[len(out)-1].Guideline += " " + strings.TrimSpace(l) - raw[len(raw)-1] += "\n" + l - continue - } - if strings.TrimSpace(l) == "" { - continue - } - member, guide := l, "" - if len(l) > col { - member, guide = l[:col], l[col:] - } - out = append(out, Removal{ - Member: strings.ReplaceAll(strings.TrimSpace(member), `\_`, "_"), - Guideline: strings.TrimSpace(guide), - }) - raw = append(raw, l) - } - if len(out) == 0 { - return nil, fmt.Errorf("the removed members table under %q is empty", g.Section) - } - plain := regexp.MustCompile("^Use ``" + regexp.QuoteMeta(g.Module) + `\.([A-Za-z_][A-Za-z0-9_]*)` + "`` instead\\.$") - for i := range out { - if m := plain.FindStringSubmatch(out[i].Guideline); m != nil { - out[i].Replacement = m[1] - } - out[i].Excerpt = g.Section + "\n" + head + "\n" + raw[i] - } - return out, nil -} - -// Plugin reads one guide. -type Plugin struct { - Guide Guide -} - -func (p Plugin) Name() string { return p.Guide.Package } - -// 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 -} - -// ListVersions 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) - if err != nil { - return nil, err - } - for i := range vs { - vs[i].Ref = p.Guide.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 - 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 plugin.Snapshot{Version: v, Content: page, SourceURL: g.URL()}, nil -} - -// 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) - if err != nil { - return plugin.Result{}, fmt.Errorf("reading %s: %w", g.URL(), 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) - continue - } - subject := event.Subject{ - Type: event.SubjectPackageRelease, Ecosystem: "pypi", Package: g.Package, - Change: event.PackageRemovedSymbol, Symbols: []string{r.Member}, - } - desc := fmt.Sprintf("`%s` was removed in %s %s.", r.Member, g.Package, g.Release) - if g.Effect != "" { - desc = fmt.Sprintf("%s.%s was removed in %s %s: %s.", g.Module, r.Member, g.Package, g.Release, g.Effect) - } - 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, - Version: g.Release, - ChangeType: event.ChangeTypeBreaking, - Breaking: true, - Subject: subject, - Description: desc, - MigrationHint: fmt.Sprintf("%s (%s's %s for %s)", g.absoluteLinks(r.Guideline), g.Package, g.doc(), g.Release), - SourceURL: g.URL(), - SourceExcerpt: r.Excerpt, - Confidence: 1.0, - DetectedAt: now, - } - e.Fingerprint = event.FingerprintV2(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 -} - -var _ plugin.Versioned = Plugin{} +var ( + NumPy2 = members.NumPy2 + PostHog8 = members.PostHog8 + NewRelic11 = members.NewRelic11 +) -// absoluteLinks prefixes LinkBase to every Markdown link target in s that -// starts with "/". -func (g Guide) absoluteLinks(s string) string { - if g.LinkBase == "" { - return s - } - return strings.ReplaceAll(s, "](/", "]("+strings.TrimSuffix(g.LinkBase, "/")+"/") -} +// Parse is members.Parse. +func Parse(page []byte, g Guide) ([]Removal, error) { return members.Parse(page, g) } diff --git a/plugins/removedmembers/removedmembers_test.go b/plugins/removedmembers/removedmembers_test.go index afab21b..480bbdb 100644 --- a/plugins/removedmembers/removedmembers_test.go +++ b/plugins/removedmembers/removedmembers_test.go @@ -1,88 +1,16 @@ package removedmembers import ( - "strings" "testing" - "github.com/patch-it-dev/patch-it-plugins/core/event" "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" ) -// The guide as published at tag v2.0.0 (fetched 2026-11-04). -func guide(t *testing.T) []byte { - t.Helper() - return kittest.Read(t, "testdata/numpy_2_0_migration_guide-v2.0.0.rst") -} - -func byMember(t *testing.T) map[string]Removal { - t.Helper() - rs, err := Parse(guide(t), NumPy2) - if err != nil { - t.Fatal(err) - } - out := map[string]Removal{} - for _, r := range rs { - out[r.Member] = r - } - return out -} - -func TestEveryRemovedMemberOfTheMainNamespaceIsRead(t *testing.T) { - got := byMember(t) - if len(got) != 56 { - t.Errorf("%d removed members, want the table's 56", len(got)) - } - // A guideline continued over several lines is read whole. - if r := got["find_common_type"]; !strings.Contains(r.Guideline, "``0.0``, or ``0j``") { - t.Errorf("find_common_type: %q", r.Guideline) - } - // The table's escaped underscore is the member's own. - if _, ok := got["float_"]; !ok { - t.Error(`no "float_": the \_ escape wasn't undone`) - } -} - -// Only a guideline naming exactly one member of np is a rename; anything else -// (a builtin, an expression, advice) is a removal the patch-it client -// opens as an issue. -func TestOnlyOnePlainReplacementInNpIsARename(t *testing.T) { - got := byMember(t) - for member, want := range map[string]string{ - "float_": "float64", - "NaN": "nan", - "product": "prod", - "cumproduct": "cumprod", - "string_": "bytes_", - "Inf": "inf", - "alltrue": "", // "Use ``all`` instead.": the builtin, or np.all? Not said - "NINF": "", // "Use ``-np.inf`` instead.": an expression - "asfarray": "", // "Use ``np.asarray`` with a float dtype instead." - "compat": "", // no replacement - "who": "", - } { - if r, ok := got[member]; !ok || r.Replacement != want { - t.Errorf("%s: replacement %q, want %q", member, r.Replacement, want) - } - } -} - -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{ - "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 - 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\\_") { - t.Errorf("float_: %+v", float) +// Code written against the old path still builds and runs the same source. +func TestTheOldPathStillWorks(t *testing.T) { + p := Plugin{Guide: NumPy2} + kittest.Registered(t, p) + if p.Name() != "numpy" || NumPy2.URL() == "" { + t.Errorf("Plugin{Guide: NumPy2} is %q at %q", p.Name(), NumPy2.URL()) } } diff --git a/providers/newrelic.md b/providers/newrelic.md index 37b1a9e..dcfdb82 100644 --- a/providers/newrelic.md +++ b/providers/newrelic.md @@ -4,7 +4,7 @@ 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..2a0058b 100644 --- a/providers/numpy.md +++ b/providers/numpy.md @@ -4,7 +4,7 @@ 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/posthog.md b/providers/posthog.md index 473547b..c822b09 100644 --- a/providers/posthog.md +++ b/providers/posthog.md @@ -4,7 +4,7 @@ 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 From 3dd09e7b34e0ac2284ec2cf519a4e250b8af167e Mon Sep 17 00:00:00 2001 From: adssib <75389300+adssib@users.noreply.github.com> Date: Fri, 20 Nov 2026 17:50:07 -0500 Subject: [PATCH 02/16] merge apichangelog into the changelog kind as its json parser changelog.Plugin reads a Markdown/RST changelog (File) or a JSON one (Log). The JSON one now lists its versions (the commits that changed the file), reads each, and extracts what a commit added. plugins/apichangelog only forwards. Co-Authored-By: Claude Opus 5.5 Signed-off-by: adssib <75389300+adssib@users.noreply.github.com> --- AGENTS.md | 5 +- cmd/new-plugin/formats.go | 8 +- core/plugin/provider.go | 1 + docs/how-it-works.md | 2 +- docs/plugins.schema.json | 2 +- docs/writing-a-plugin.md | 5 +- plugins/all/all.go | 1 - plugins/apichangelog/apichangelog.go | 288 +--------------- plugins/apichangelog/apichangelog_test.go | 275 +-------------- plugins/apichangelog/testdata/README.md | 9 - plugins/changelog/changelog.go | 46 ++- plugins/changelog/json.go | 310 +++++++++++++++++ plugins/changelog/json_test.go | 324 ++++++++++++++++++ plugins/changelog/registered_test.go | 1 + plugins/changelog/testdata/README.md | 16 + .../testdata/commits-c0f99ca9.json | 0 .../testdata/commits-day.json | 0 .../testdata/golden/mongodb-atlas.json | 0 .../testdata/log-history/changelog-1.json | 1 + .../testdata/log-history/changelog-2.json | 1 + .../testdata/log-history/changelog-3.json | 1 + .../testdata/log-history/commits.json | 5 + ...ongodb-atlas-changelog-2026-11-18-day.json | 0 .../mongodb-atlas-changelog-c0f99ca9.json | 0 providers/mongodb-atlas.md | 2 +- 25 files changed, 731 insertions(+), 572 deletions(-) delete mode 100644 plugins/apichangelog/testdata/README.md create mode 100644 plugins/changelog/json.go create mode 100644 plugins/changelog/json_test.go rename plugins/{apichangelog => changelog}/testdata/commits-c0f99ca9.json (100%) rename plugins/{apichangelog => changelog}/testdata/commits-day.json (100%) rename plugins/{apichangelog => changelog}/testdata/golden/mongodb-atlas.json (100%) create mode 100644 plugins/changelog/testdata/log-history/changelog-1.json create mode 100644 plugins/changelog/testdata/log-history/changelog-2.json create mode 100644 plugins/changelog/testdata/log-history/changelog-3.json create mode 100644 plugins/changelog/testdata/log-history/commits.json rename plugins/{apichangelog => changelog}/testdata/mongodb-atlas-changelog-2026-11-18-day.json (100%) rename plugins/{apichangelog => changelog}/testdata/mongodb-atlas-changelog-c0f99ca9.json (100%) diff --git a/AGENTS.md b/AGENTS.md index 8e27cd2..efbd38b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -58,9 +58,10 @@ core/event/ core/migrate/ the change-event types from patch-it's contract ( 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/, - members/), changelog, feed, apichangelog, catalog, eol; + members/), changelog (Markdown, RST or JSON), feed, catalog, eol; plugins/all imports every one -plugins/removedmembers/ deprecated: merged into migrationguide, only forwards there +plugins/removedmembers/ plugins/apichangelog/ deprecated: merged into migrationguide and + changelog, they only forward there 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 diff --git a/cmd/new-plugin/formats.go b/cmd/new-plugin/formats.go index 2887c0d..b610c6d 100644 --- a/cmd/new-plugin/formats.go +++ b/cmd/new-plugin/formats.go @@ -341,15 +341,15 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { }, "apichangelog": { - kind: "apichangelog", + 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", diff --git a/core/plugin/provider.go b/core/plugin/provider.go index 88e75e9..86f4d83 100644 --- a/core/plugin/provider.go +++ b/core/plugin/provider.go @@ -236,6 +236,7 @@ func KindOf(p Plugin) string { // they read is read by the new kind, with the same events. var mergedKinds = map[string]string{ "removedmembers": "migrationguide", + "apichangelog": "changelog", } // CanonicalKind is the kind name means now: name itself, or, for a kind diff --git a/docs/how-it-works.md b/docs/how-it-works.md index 2ffe84c..551dcfb 100644 --- a/docs/how-it-works.md +++ b/docs/how-it-works.md @@ -28,7 +28,7 @@ There's no list in this repo: `make plugins` prints every provider and source fr | [`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/), [`plugins/migrationguide/members/`](../plugins/migrationguide/members/), [`core/fetch/`](../core/fetch/) | The deprecations-page and 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/`, `plugins/removedmembers/` | Deprecated: the old import paths, forwarding to the packages above until code that imports them moves | +| `plugin/`, `event/`, `fetch/`, `migrate/`, `kit/`, `kit/kittest/`, `retire/`, `sdkguide/`, `plugins/removedmembers/`, `plugins/apichangelog/` | 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 79db6ab..8615cac 100644 --- a/docs/plugins.schema.json +++ b/docs/plugins.schema.json @@ -37,7 +37,7 @@ "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", "changelog", "feed", "apichangelog", "catalog", "eol"] }, + "kind": { "type": "string", "enum": ["openapi", "retirements", "migrationguide", "changelog", "feed", "catalog", "eol"] }, "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/writing-a-plugin.md b/docs/writing-a-plugin.md index 1b6fb89..3fa7024 100644 --- a/docs/writing-a-plugin.md +++ b/docs/writing-a-plugin.md @@ -10,7 +10,7 @@ Pick the source and the kind that reads it (steps 2 and 3), then let the starter ```sh go run ./cmd/new-plugin --api acme --provider Acme --format openapi -# --format: openapi, retirements, migrationguide, removedmembers (a migrationguide source), changelog, feed, apichangelog, catalog +# --format: openapi, retirements, migrationguide, removedmembers (a migrationguide source), changelog, feed, apichangelog (a JSON changelog source), 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/) ``` @@ -77,10 +77,9 @@ Write the numbers on the provider page, as `providers/vercel.md` does for its sp | `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` | 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.md` / `CHANGES.rst` / `HISTORY.rst`, each release's section at its tag (releases from PyPI or npm) | A `changelog.File` with its `TagPrefix` | +| `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/feed` | An RSS or Atom feed | A `feed.Feed` with a reader for that vendor's entries | | `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 | ## 4. The interface diff --git a/plugins/all/all.go b/plugins/all/all.go index d93ee4d..74a0d2c 100644 --- a/plugins/all/all.go +++ b/plugins/all/all.go @@ -4,7 +4,6 @@ package all import ( - _ "github.com/patch-it-dev/patch-it-plugins/plugins/apichangelog" _ "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" diff --git a/plugins/apichangelog/apichangelog.go b/plugins/apichangelog/apichangelog.go index 271129f..1013b47 100644 --- a/plugins/apichangelog/apichangelog.go +++ b/plugins/apichangelog/apichangelog.go @@ -1,282 +1,18 @@ -// 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. +// Package apichangelog is the old import path of the changelog kind's JSON +// parser, kept so code that imports it still builds. // -// 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. -// -// 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. +// Deprecated: use plugins/changelog: Plugin{Log: changelog.MongoDBAtlas}. +// This package only forwards there and registers nothing; it goes once +// nothing imports it. package apichangelog -import ( - "bytes" - "context" - "encoding/json" - "fmt" - "log" - "sort" +import "github.com/patch-it-dev/patch-it-plugins/plugins/changelog" - "github.com/patch-it-dev/patch-it-plugins/core/event" - "github.com/patch-it-dev/patch-it-plugins/core/github" - "github.com/patch-it-dev/patch-it-plugins/core/kit" - "github.com/patch-it-dev/patch-it-plugins/core/plugin" +type ( + // Plugin is changelog.Plugin: set Log, as before. + Plugin = changelog.Plugin + Log = changelog.Log + Finding = changelog.LogFinding ) -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" - Vendor string // for sentences: "MongoDB" - Name string // the API, for sentences: "Atlas Administration API" - Repo string // owner/name on GitHub - Path string // the file's path in the repo -} - -// MongoDBAtlas is the Atlas Administration API's changelog, -// changelog/changelog.json in mongodb/openapi (checked 2026-11-19: 188 days -// from 2023-02-01 to 2026-11-18, released by MongoDB's CI, "Release API -// Changelog", a few times a month; the docs page -// https://www.mongodb.com/docs/atlas/reference/api-resources-spec/changelog/ -// 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", - Repo: "mongodb/openapi", Path: "changelog/changelog.json", -} - -// CommitsURL lists the newest commit that changed the file. -func (l Log) CommitsURL() string { - return fmt.Sprintf("https://api.github.com/repos/%s/commits?path=%s&per_page=1", l.Repo, l.Path) -} - -// URL is the file at one commit: its own provenance. -func (l Log) URL(sha string) string { - return fmt.Sprintf("https://raw.githubusercontent.com/%s/%s/%s", l.Repo, sha, l.Path) -} - -// The file's shape: newest day first. -type day struct { - Date string `json:"date"` - Paths []struct { - Path string `json:"path"` - Method string `json:"httpMethod"` - Versions []struct { - Version string `json:"version"` - Changes []json.RawMessage `json:"changes"` - } `json:"versions"` - } `json:"paths"` -} - -type change struct { - Change string `json:"change"` - ChangeCode string `json:"changeCode"` - BackwardCompatible bool `json:"backwardCompatible"` -} - -// lifecycle is what each change code this plugin reads means, each about a -// whole endpoint at one API version: "endpoint deprecated"; "new resource -// added 2023-02-01. Resource version 2023-01-01 deprecated and marked for -// removal on 2025-06-01"; "endpoint with API Version '2023-01-01' was removed -// as it has reached its sunset date '2026-01-22'". -// -// Not read: "api path removed without deprecation". Its one entry -// (streams/activeVpcPeeringConnections, 2025-01-10) comes with -// `endpoint-added` the same day, and the endpoint changes again later: it -// wasn't removed. -var lifecycle = map[string]event.ChangeType{ - "endpoint-deprecated": event.ChangeTypeDeprecation, - "resource-version-deprecated": event.ChangeTypeDeprecation, - "endpoint-removed": event.ChangeTypeBreaking, -} - -// reactivated withdraws a deprecation: "endpoint reactivated". MongoDB does -// it (13 times by 2026-11-18): GET /api/atlas/v2/groups/{groupId}/clusters -// 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 { - ChangeType event.ChangeType - Date string // the changelog's day - Operation string // "GET /api/atlas/v2/groups/{groupId}/clusters" - Version string // the API version it's about: "2023-01-01" - Code string - Pointer string // RFC 6901, into the file - Excerpt string // the change, as JSON -} - -// Read finds every life-cycle change in the file that still stands, by -// replaying the days oldest first: a reactivation of an endpoint's version -// withdraws its deprecation, and a deprecation after that is a new one. A -// deprecation counts from the first time it's announced since the last -// reactivation; the changelog repeats some. A removal counts from its first -// announcement too, and is withdrawn, with any deprecation before it, if the -// 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) { - var days []day - if err := json.Unmarshal(b, &days); err != nil { - return nil, fmt.Errorf("not a changelog: %w", err) - } - if len(days) == 0 { - return nil, fmt.Errorf("the changelog has no days: it may have moved or changed shape") - } - type item struct { - seq int - f Finding - } - deprecated := map[string]item{} // by operation and version, until reactivated - removed := map[string]item{} - seq := 0 - for di := len(days) - 1; di >= 0; di-- { - d := days[di] - for pi, p := range d.Paths { - for vi, v := range p.Versions { - for ci, raw := range v.Changes { - var c change - if err := json.Unmarshal(raw, &c); err != nil { - return nil, fmt.Errorf("day %s, %s %s: %w", d.Date, p.Method, p.Path, err) - } - op := p.Method + " " + p.Path - key := op + " " + v.Version - if r, ok := removed[key]; ok && r.f.Date < d.Date && lifecycle[c.ChangeCode] != event.ChangeTypeBreaking { - // It came back. Whether its old deprecation still - // applies is unclear, so that goes too. - delete(removed, key) - delete(deprecated, key) - } - if c.ChangeCode == reactivated { - delete(deprecated, key) - continue - } - ct, ok := lifecycle[c.ChangeCode] - if !ok { - continue - } - var ex bytes.Buffer - if err := json.Compact(&ex, raw); err != nil { - return nil, err - } - f := Finding{ - 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(), - } - seq++ - target := deprecated - if ct == event.ChangeTypeBreaking { - target = removed - } - if _, dup := target[key]; !dup { - target[key] = item{seq, f} - } - } - } - } - } - all := make([]item, 0, len(deprecated)+len(removed)) - for _, it := range deprecated { - all = append(all, it) - } - for _, it := range removed { - all = append(all, it) - } - sort.Slice(all, func(i, j int) bool { return all[i].seq < all[j].seq }) - out := make([]Finding, 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) { - 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) - if err != nil { - return plugin.Result{}, fmt.Errorf("fetching %s: %w", url, err) - } - last, same, err := kit.Unchanged(env, l.API, page) - if err != nil { - return plugin.Result{}, err - } - if same { - log.Printf("%s: no change since %s", l.API, last.SourceURL) - return plugin.Result{}, nil - } - findings, err := l.Read(page) - if err != nil { - return plugin.Result{}, fmt.Errorf("reading %s: %w", url, err) - } - - now := env.Now().UTC() - var events []event.EventV2 - var rejected []error - for _, f := range findings { - e := event.EventV2{ - 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, - SourcePointer: f.Pointer, - SourceExcerpt: f.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 %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 -} - -func describe(l Log, f Finding) 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) - default: - return fmt.Sprintf("%s %s, API version %s, deprecated on %s (%s's changelog, %s).", l.Name, f.Operation, f.Version, f.Date, l.Vendor, f.Code) - } -} +var MongoDBAtlas = changelog.MongoDBAtlas diff --git a/plugins/apichangelog/apichangelog_test.go b/plugins/apichangelog/apichangelog_test.go index 21a0eea..ed0bdad 100644 --- a/plugins/apichangelog/apichangelog_test.go +++ b/plugins/apichangelog/apichangelog_test.go @@ -1,279 +1,16 @@ package apichangelog import ( - "encoding/json" - "reflect" - "strconv" - "strings" "testing" - "github.com/patch-it-dev/patch-it-plugins/core/event" "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" ) -const ( - latestSHA = "c0f99ca9145e5aa74d08ae4451020857e93b5f28" // 2026-11-18 20:15 UTC, "Release API Changelog" - fixture = "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 { - 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) - 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) { - t.Errorf("%s: source_url %s", e.Subject.Operation, e.SourceURL) - } - if node := nodeAt(t, fixture, e.SourcePointer); !sameJSON(node, e.SourceExcerpt) { - t.Errorf("%s: excerpt %s, but %s holds %s", e.Subject.Operation, e.SourceExcerpt, e.SourcePointer, node) - } - } -} - -// The historical breaking change: on 2026-01-22 Atlas removed API version -// 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)) - if err != nil { - t.Fatal(err) - } - var n int - for _, f := range fs { - if !strings.Contains(f.Operation, "/backup/tenant/") || f.Version != "2023-01-01" { - continue - } - n++ - if f.ChangeType != event.ChangeTypeBreaking || f.Date != "2026-01-22" || f.Code != "endpoint-removed" { - t.Errorf("%s: %s %s %s", f.Operation, f.ChangeType, f.Date, f.Code) - } - if !strings.Contains(f.Excerpt, "has reached its sunset date '2026-01-22'") { - t.Errorf("%s: excerpt %s", f.Operation, f.Excerpt) - } - } - if n == 0 { - t.Error("no tenant backup removal read") - } -} - -// The pinned drop test: the changelog's newest day (2026-11-18), whole and -// unchanged: 104 changes, 23 of them marked not backward compatible -// (`request-property-one-of-removed`, …), none an endpoint's life cycle. -// No event. -func TestPropertyChangesMakeNoEvent(t *testing.T) { - const sha = "0000000000000000000000000000000000000001" - file := "testdata/mongodb-atlas-changelog-2026-11-18-day.json" - var days []day - if err := json.Unmarshal(kittest.Read(t, file), &days); err != nil { - t.Fatal(err) - } - var notBC int - for _, p := range days[0].Paths { - for _, v := range p.Versions { - for _, raw := range v.Changes { - var c change - if err := json.Unmarshal(raw, &c); err != nil { - t.Fatal(err) - } - if !c.BackwardCompatible { - notBC++ - } - } - } - } - if notBC != 23 { - t.Fatalf("the fixture 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 { - for _, e := range got { - t.Logf("got: %s", e.Description) - } - t.Fatalf("%d events, want none", len(got)) - } -} - -// MongoDB deprecated GET and POST /api/atlas/v2/groups/{groupId}/clusters at -// API version 2024-05-30 on 2024-06-25 and reactivated them on 2024-06-26 (and -// 2023-11-15 on 2024-05-09, reactivated 2024-05-16): versions still in use. -// No deprecation of either stands. -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 { - t.Fatal(err) - } - codes := map[string]int{} - for _, d := range days { - for _, p := range d.Paths { - for _, v := range p.Versions { - for _, raw := range v.Changes { - var c change - if err := json.Unmarshal(raw, &c); err != nil { - t.Fatal(err) - } - if p.Path == "/api/atlas/v2/groups/{groupId}/clusters" && v.Version == "2024-05-30" { - codes[c.ChangeCode]++ - } - } - } - } - } - 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) - } - fs, err := MongoDBAtlas.Read(kittest.Read(t, fixture)) - if err != nil { - t.Fatal(err) - } - for _, f := range fs { - if strings.HasSuffix(f.Operation, " /api/atlas/v2/groups/{groupId}/clusters") && (f.Version == "2024-05-30" || f.Version == "2023-11-15") { - t.Errorf("%s %s: %s on %s, but MongoDB reactivated it", f.Operation, f.Version, f.ChangeType, f.Date) - } - } -} - -// 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) { - ch := func(code string) string { - return `{"change":"x","changeCode":"` + code + `","backwardCompatible":true}` - } - day := func(date, path, code string) string { - return `{"date":"` + date + `","paths":[{"path":"` + path + `","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[` + ch(code) + `]}]}]}` - } - b := []byte("[" + strings.Join([]string{ // newest day first, as the file is - day("2026-05-01", "/b", "endpoint-removed"), - day("2026-04-01", "/c", "api-path-removed-without-deprecation"), - day("2026-03-01", "/a", "endpoint-deprecated"), - day("2026-02-01", "/a", "endpoint-reactivated"), - day("2026-01-15", "/b", "resource-version-deprecated"), - day("2026-01-01", "/a", "endpoint-deprecated"), - }, ",") + "]") - fs, err := MongoDBAtlas.Read(b) - if err != nil { - t.Fatal(err) - } - var got []string - for _, f := range fs { - got = append(got, f.Date+" "+f.Operation+" "+string(f.ChangeType)) - } - want := []string{"2026-01-15 GET /b deprecation", "2026-03-01 GET /a deprecation", "2026-05-01 GET /b breaking"} - if strings.Join(got, "; ") != strings.Join(want, "; ") { - t.Errorf("got %q, want %q", got, want) - } -} - -// A removal followed by the same endpoint and version on a later day (an -// `endpoint-added`, any change) didn't happen: no event. And the excerpt -// keeps every field the vendor wrote, in its order. -func TestRemovalUndoneAndRawExcerpt(t *testing.T) { - b := []byte(`[ - {"date":"2026-03-01","paths":[{"path":"/a","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"endpoint added","changeCode":"endpoint-added","backwardCompatible":true}]}]}]}, - {"date":"2026-02-01","paths":[{"path":"/a","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"removed","changeCode":"endpoint-removed","backwardCompatible":false}]}]}, - {"path":"/b","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"removed","changeCode":"endpoint-removed","backwardCompatible":false,"sunset":"2026-02-01"}]}]}]} - ]`) - fs, err := MongoDBAtlas.Read(b) - if err != nil { - t.Fatal(err) - } - if len(fs) != 1 || fs[0].Operation != "GET /b" { - t.Fatalf("got %+v, want only GET /b's removal", fs) - } - if want := `{"change":"removed","changeCode":"endpoint-removed","backwardCompatible":false,"sunset":"2026-02-01"}`; fs[0].Excerpt != want { - t.Errorf("excerpt %s, want %s", fs[0].Excerpt, want) - } -} - -// A removal announced twice keeps its first announcement. A version that's -// deprecated, removed and then back has neither event. -func TestRepeatedRemovalAndReturn(t *testing.T) { - day := func(date, path, code string) string { - return `{"date":"` + date + `","paths":[{"path":"` + path + `","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"x","changeCode":"` + code + `","backwardCompatible":true}]}]}]}` - } - b := []byte("[" + strings.Join([]string{ - day("2026-04-01", "/a", "endpoint-added"), - day("2026-03-01", "/b", "endpoint-removed"), - day("2026-02-01", "/b", "endpoint-removed"), - day("2026-02-01", "/a", "endpoint-removed"), - day("2026-01-01", "/a", "endpoint-deprecated"), - }, ",") + "]") - fs, err := MongoDBAtlas.Read(b) - if err != nil { - t.Fatal(err) - } - if len(fs) != 1 || fs[0].Operation != "GET /b" || fs[0].Date != "2026-02-01" || fs[0].Pointer != "/2/paths/0/versions/0/changes/0" { - t.Errorf("got %+v, want GET /b's removal once, as announced on 2026-02-01", fs) - } -} - -// A change announced again on a later day is one event, as first announced. -func TestRepeatsAreReadOnce(t *testing.T) { - b := []byte(`[ - {"date":"2026-02-01","paths":[{"path":"/a","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"endpoint deprecated","changeCode":"endpoint-deprecated","backwardCompatible":true}]}]}]}, - {"date":"2026-01-01","paths":[{"path":"/a","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"endpoint deprecated","changeCode":"endpoint-deprecated","backwardCompatible":true},{"change":"added the new optional request property","changeCode":"new-optional-request-property","backwardCompatible":true}]}]}]} - ]`) - fs, err := MongoDBAtlas.Read(b) - if err != nil { - t.Fatal(err) - } - if len(fs) != 1 || fs[0].Date != "2026-01-01" || fs[0].Pointer != "/1/paths/0/versions/0/changes/0" { - t.Errorf("got %+v, want the 2026-01-01 announcement once", fs) - } -} - -func TestReadRefusesWhatIsntAChangelog(t *testing.T) { - for name, b := range map[string]string{"html": "moved", "empty": "[]", "object": `{"date":"x"}`} { - if _, err := MongoDBAtlas.Read([]byte(b)); err == nil { - t.Errorf("%s: want an error, never zero events read as a quiet week", name) - } - } -} - -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 { - return false - } - return reflect.DeepEqual(x, y) -} - -// nodeAt resolves an RFC 6901 pointer in a JSON file and serializes the node. -func nodeAt(t *testing.T, file, pointer string) string { - t.Helper() - var node any - if err := json.Unmarshal(kittest.Read(t, file), &node); err != nil { - t.Fatal(err) - } - for _, tok := range strings.Split(strings.TrimPrefix(pointer, "/"), "/") { - switch n := node.(type) { - case map[string]any: - node = n[tok] - case []any: - i, err := strconv.Atoi(tok) - if err != nil || i >= len(n) { - return "" - } - node = n[i] - default: - return "" - } +// Code written against the old path still builds and runs the same source. +func TestTheOldPathStillWorks(t *testing.T) { + p := Plugin{Log: MongoDBAtlas} + kittest.Registered(t, p) + if p.Name() != "mongodb-atlas" { + t.Errorf("Plugin{Log: MongoDBAtlas} is %q", p.Name()) } - b, _ := json.Marshal(node) - return string(b) } 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/changelog/changelog.go b/plugins/changelog/changelog.go index 25bea03..ff3f790 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. @@ -44,6 +48,15 @@ func init() { 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}, + }}, + }) } // File is one package's changelog. Unpinned (Tag and Release empty), it is @@ -147,18 +160,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.Package +} // 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) @@ -185,6 +212,9 @@ func (p Plugin) Run(ctx context.Context, env plugin.Env) (plugin.Result, error) // 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 +240,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 +257,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) diff --git a/plugins/changelog/json.go b/plugins/changelog/json.go new file mode 100644 index 0000000..421bfff --- /dev/null +++ b/plugins/changelog/json.go @@ -0,0 +1,310 @@ +// 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. +// +// 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" + "context" + "encoding/json" + "fmt" + "log" + "sort" + + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/github" + "github.com/patch-it-dev/patch-it-plugins/core/kit" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" + "github.com/patch-it-dev/patch-it-plugins/core/versions" +) + +// Log is one vendor's changelog file. +type Log struct { + API string // the events' api: "mongodb-atlas" + Vendor string // for sentences: "MongoDB" + Name string // the API, for sentences: "Atlas Administration API" + Repo string // owner/name on GitHub + Path string // the file's path in the repo +} + +// MongoDBAtlas is the Atlas Administration API's changelog, +// changelog/changelog.json in mongodb/openapi (checked 2026-11-19: 188 days +// from 2023-02-01 to 2026-11-18, released by MongoDB's CI, "Release API +// Changelog", a few times a month; the docs page +// https://www.mongodb.com/docs/atlas/reference/api-resources-spec/changelog/ +// 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", + Repo: "mongodb/openapi", Path: "changelog/changelog.json", +} + +// CommitsURL lists the newest commit that changed the file. +func (l Log) CommitsURL() string { + return fmt.Sprintf("https://api.github.com/repos/%s/commits?path=%s&per_page=1", l.Repo, l.Path) +} + +// URL is the file at one commit: its own provenance. +func (l Log) URL(sha string) string { + return fmt.Sprintf("https://raw.githubusercontent.com/%s/%s/%s", l.Repo, sha, l.Path) +} + +// The file's shape: newest day first. +type day struct { + Date string `json:"date"` + Paths []struct { + Path string `json:"path"` + Method string `json:"httpMethod"` + Versions []struct { + Version string `json:"version"` + Changes []json.RawMessage `json:"changes"` + } `json:"versions"` + } `json:"paths"` +} + +type change struct { + Change string `json:"change"` + ChangeCode string `json:"changeCode"` + BackwardCompatible bool `json:"backwardCompatible"` +} + +// lifecycle is what each change code this plugin reads means, each about a +// whole endpoint at one API version: "endpoint deprecated"; "new resource +// added 2023-02-01. Resource version 2023-01-01 deprecated and marked for +// removal on 2025-06-01"; "endpoint with API Version '2023-01-01' was removed +// as it has reached its sunset date '2026-01-22'". +// +// Not read: "api path removed without deprecation". Its one entry +// (streams/activeVpcPeeringConnections, 2025-01-10) comes with +// `endpoint-added` the same day, and the endpoint changes again later: it +// wasn't removed. +var lifecycle = map[string]event.ChangeType{ + "endpoint-deprecated": event.ChangeTypeDeprecation, + "resource-version-deprecated": event.ChangeTypeDeprecation, + "endpoint-removed": event.ChangeTypeBreaking, +} + +// reactivated withdraws a deprecation: "endpoint reactivated". MongoDB does +// it (13 times by 2026-11-18): GET /api/atlas/v2/groups/{groupId}/clusters +// at 2024-05-30 was deprecated on 2024-06-25 and reactivated the next day. +const reactivated = "endpoint-reactivated" + +// 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" + Version string // the API version it's about: "2023-01-01" + Code string + Pointer string // RFC 6901, into the file + Excerpt string // the change, as JSON +} + +// Read finds every life-cycle change in the file that still stands, by +// replaying the days oldest first: a reactivation of an endpoint's version +// withdraws its deprecation, and a deprecation after that is a new one. A +// deprecation counts from the first time it's announced since the last +// reactivation; the changelog repeats some. A removal counts from its first +// announcement too, and is withdrawn, with any deprecation before it, if the +// 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) ([]LogFinding, error) { + var days []day + if err := json.Unmarshal(b, &days); err != nil { + return nil, fmt.Errorf("not a changelog: %w", err) + } + if len(days) == 0 { + return nil, fmt.Errorf("the changelog has no days: it may have moved or changed shape") + } + type item struct { + seq int + f LogFinding + } + deprecated := map[string]item{} // by operation and version, until reactivated + removed := map[string]item{} + seq := 0 + for di := len(days) - 1; di >= 0; di-- { + d := days[di] + for pi, p := range d.Paths { + for vi, v := range p.Versions { + for ci, raw := range v.Changes { + var c change + if err := json.Unmarshal(raw, &c); err != nil { + return nil, fmt.Errorf("day %s, %s %s: %w", d.Date, p.Method, p.Path, err) + } + op := p.Method + " " + p.Path + key := op + " " + v.Version + if r, ok := removed[key]; ok && r.f.Date < d.Date && lifecycle[c.ChangeCode] != event.ChangeTypeBreaking { + // It came back. Whether its old deprecation still + // applies is unclear, so that goes too. + delete(removed, key) + delete(deprecated, key) + } + if c.ChangeCode == reactivated { + delete(deprecated, key) + continue + } + ct, ok := lifecycle[c.ChangeCode] + if !ok { + continue + } + var ex bytes.Buffer + if err := json.Compact(&ex, raw); err != nil { + return nil, err + } + 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(), + } + seq++ + target := deprecated + if ct == event.ChangeTypeBreaking { + target = removed + } + if _, dup := target[key]; !dup { + target[key] = item{seq, f} + } + } + } + } + } + all := make([]item, 0, len(deprecated)+len(removed)) + for _, it := range deprecated { + all = append(all, it) + } + for _, it := range removed { + all = append(all, it) + } + sort.Slice(all, func(i, j int) bool { return all[i].seq < all[j].seq }) + out := make([]LogFinding, len(all)) + for i, it := range all { + out[i] = it.f + } + return out, nil +} + +// 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) + } + to, err := p.readLog(ctx, env, plugin.Version{ID: sha, Ref: sha}) + if err != nil { + return plugin.Result{}, err + } + last, same, err := kit.Unchanged(env, l.API, to.Content) + if err != nil { + return plugin.Result{}, err + } + if same { + log.Printf("%s: no change since %s", l.API, last.SourceURL) + return plugin.Result{}, nil + } + 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, false, 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.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 rejected []error + for _, f := range findings { + e := event.EventV2{ + 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: 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, "") + 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: to.SourceURL, Events: events, Rejected: rejected}, nil +} + +// 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) + default: + return fmt.Sprintf("%s %s, API version %s, deprecated on %s (%s's changelog, %s).", l.Name, f.Operation, f.Version, f.Date, l.Vendor, f.Code) + } +} diff --git a/plugins/changelog/json_test.go b/plugins/changelog/json_test.go new file mode 100644 index 0000000..e065056 --- /dev/null +++ b/plugins/changelog/json_test.go @@ -0,0 +1,324 @@ +package changelog + +import ( + "context" + "encoding/json" + "fmt" + "reflect" + "strconv" + "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" +) + +const ( + 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 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 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(atlasSHA) { + t.Errorf("%s: source_url %s", e.Subject.Operation, e.SourceURL) + } + 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) + } + } +} + +// The historical breaking change: on 2026-01-22 Atlas removed API version +// 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, atlasFixture)) + if err != nil { + t.Fatal(err) + } + var n int + for _, f := range fs { + if !strings.Contains(f.Operation, "/backup/tenant/") || f.Version != "2023-01-01" { + continue + } + n++ + if f.ChangeType != event.ChangeTypeBreaking || f.Date != "2026-01-22" || f.Code != "endpoint-removed" { + t.Errorf("%s: %s %s %s", f.Operation, f.ChangeType, f.Date, f.Code) + } + if !strings.Contains(f.Excerpt, "has reached its sunset date '2026-01-22'") { + t.Errorf("%s: excerpt %s", f.Operation, f.Excerpt) + } + } + if n == 0 { + t.Error("no tenant backup removal read") + } +} + +// The pinned drop test: the changelog's newest day (2026-11-18), whole and +// unchanged: 104 changes, 23 of them marked not backward compatible +// (`request-property-one-of-removed`, …), none an endpoint's life cycle. +// No event. +func TestPropertyChangesMakeNoEvent(t *testing.T) { + const sha = "0000000000000000000000000000000000000001" + file := "testdata/mongodb-atlas-changelog-2026-11-18-day.json" + var days []day + if err := json.Unmarshal(kittest.Read(t, file), &days); err != nil { + t.Fatal(err) + } + var notBC int + for _, p := range days[0].Paths { + for _, v := range p.Versions { + for _, raw := range v.Changes { + var c change + if err := json.Unmarshal(raw, &c); err != nil { + t.Fatal(err) + } + if !c.BackwardCompatible { + notBC++ + } + } + } + } + if notBC != 23 { + t.Fatalf("the atlasFixture has %d changes not backward compatible, want 23", notBC) + } + 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) + } + t.Fatalf("%d events, want none", len(got)) + } +} + +// MongoDB deprecated GET and POST /api/atlas/v2/groups/{groupId}/clusters at +// API version 2024-05-30 on 2024-06-25 and reactivated them on 2024-06-26 (and +// 2023-11-15 on 2024-05-09, reactivated 2024-05-16): versions still in use. +// No deprecation of either stands. +func TestReactivationWithdrawsTheDeprecation(t *testing.T) { + // The saved file does hold those deprecations and reactivations. + var days []day + if err := json.Unmarshal(kittest.Read(t, atlasFixture), &days); err != nil { + t.Fatal(err) + } + codes := map[string]int{} + for _, d := range days { + for _, p := range d.Paths { + for _, v := range p.Versions { + for _, raw := range v.Changes { + var c change + if err := json.Unmarshal(raw, &c); err != nil { + t.Fatal(err) + } + if p.Path == "/api/atlas/v2/groups/{groupId}/clusters" && v.Version == "2024-05-30" { + codes[c.ChangeCode]++ + } + } + } + } + } + if codes["endpoint-deprecated"] == 0 || codes["endpoint-reactivated"] == 0 { + 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, atlasFixture)) + if err != nil { + t.Fatal(err) + } + for _, f := range fs { + if strings.HasSuffix(f.Operation, " /api/atlas/v2/groups/{groupId}/clusters") && (f.Version == "2024-05-30" || f.Version == "2023-11-15") { + t.Errorf("%s %s: %s on %s, but MongoDB reactivated it", f.Operation, f.Version, f.ChangeType, f.Date) + } + } +} + +// 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) { + ch := func(code string) string { + return `{"change":"x","changeCode":"` + code + `","backwardCompatible":true}` + } + day := func(date, path, code string) string { + return `{"date":"` + date + `","paths":[{"path":"` + path + `","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[` + ch(code) + `]}]}]}` + } + b := []byte("[" + strings.Join([]string{ // newest day first, as the file is + day("2026-05-01", "/b", "endpoint-removed"), + day("2026-04-01", "/c", "api-path-removed-without-deprecation"), + day("2026-03-01", "/a", "endpoint-deprecated"), + day("2026-02-01", "/a", "endpoint-reactivated"), + day("2026-01-15", "/b", "resource-version-deprecated"), + day("2026-01-01", "/a", "endpoint-deprecated"), + }, ",") + "]") + fs, err := MongoDBAtlas.Read(b) + if err != nil { + t.Fatal(err) + } + var got []string + for _, f := range fs { + got = append(got, f.Date+" "+f.Operation+" "+string(f.ChangeType)) + } + want := []string{"2026-01-15 GET /b deprecation", "2026-03-01 GET /a deprecation", "2026-05-01 GET /b breaking"} + if strings.Join(got, "; ") != strings.Join(want, "; ") { + t.Errorf("got %q, want %q", got, want) + } +} + +// A removal followed by the same endpoint and version on a later day (an +// `endpoint-added`, any change) didn't happen: no event. And the excerpt +// keeps every field the vendor wrote, in its order. +func TestRemovalUndoneAndRawExcerpt(t *testing.T) { + b := []byte(`[ + {"date":"2026-03-01","paths":[{"path":"/a","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"endpoint added","changeCode":"endpoint-added","backwardCompatible":true}]}]}]}, + {"date":"2026-02-01","paths":[{"path":"/a","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"removed","changeCode":"endpoint-removed","backwardCompatible":false}]}]}, + {"path":"/b","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"removed","changeCode":"endpoint-removed","backwardCompatible":false,"sunset":"2026-02-01"}]}]}]} + ]`) + fs, err := MongoDBAtlas.Read(b) + if err != nil { + t.Fatal(err) + } + if len(fs) != 1 || fs[0].Operation != "GET /b" { + t.Fatalf("got %+v, want only GET /b's removal", fs) + } + if want := `{"change":"removed","changeCode":"endpoint-removed","backwardCompatible":false,"sunset":"2026-02-01"}`; fs[0].Excerpt != want { + t.Errorf("excerpt %s, want %s", fs[0].Excerpt, want) + } +} + +// A removal announced twice keeps its first announcement. A version that's +// deprecated, removed and then back has neither event. +func TestRepeatedRemovalAndReturn(t *testing.T) { + day := func(date, path, code string) string { + return `{"date":"` + date + `","paths":[{"path":"` + path + `","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"x","changeCode":"` + code + `","backwardCompatible":true}]}]}]}` + } + b := []byte("[" + strings.Join([]string{ + day("2026-04-01", "/a", "endpoint-added"), + day("2026-03-01", "/b", "endpoint-removed"), + day("2026-02-01", "/b", "endpoint-removed"), + day("2026-02-01", "/a", "endpoint-removed"), + day("2026-01-01", "/a", "endpoint-deprecated"), + }, ",") + "]") + fs, err := MongoDBAtlas.Read(b) + if err != nil { + t.Fatal(err) + } + if len(fs) != 1 || fs[0].Operation != "GET /b" || fs[0].Date != "2026-02-01" || fs[0].Pointer != "/2/paths/0/versions/0/changes/0" { + t.Errorf("got %+v, want GET /b's removal once, as announced on 2026-02-01", fs) + } +} + +// A change announced again on a later day is one event, as first announced. +func TestRepeatsAreReadOnce(t *testing.T) { + b := []byte(`[ + {"date":"2026-02-01","paths":[{"path":"/a","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"endpoint deprecated","changeCode":"endpoint-deprecated","backwardCompatible":true}]}]}]}, + {"date":"2026-01-01","paths":[{"path":"/a","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"endpoint deprecated","changeCode":"endpoint-deprecated","backwardCompatible":true},{"change":"added the new optional request property","changeCode":"new-optional-request-property","backwardCompatible":true}]}]}]} + ]`) + fs, err := MongoDBAtlas.Read(b) + if err != nil { + t.Fatal(err) + } + if len(fs) != 1 || fs[0].Date != "2026-01-01" || fs[0].Pointer != "/1/paths/0/versions/0/changes/0" { + t.Errorf("got %+v, want the 2026-01-01 announcement once", fs) + } +} + +func TestReadRefusesWhatIsntAChangelog(t *testing.T) { + for name, b := range map[string]string{"html": "moved", "empty": "[]", "object": `{"date":"x"}`} { + if _, err := MongoDBAtlas.Read([]byte(b)); err == nil { + t.Errorf("%s: want an error, never zero events read as a quiet week", name) + } + } +} + +func sameJSON(a, b string) bool { + var x, y any + if json.Unmarshal([]byte(a), &x) != nil || json.Unmarshal([]byte(b), &y) != nil { + return false + } + return reflect.DeepEqual(x, y) +} + +// nodeAt resolves an RFC 6901 pointer in a JSON file and serializes the node. +func nodeAt(t *testing.T, file, pointer string) string { + t.Helper() + var node any + if err := json.Unmarshal(kittest.Read(t, file), &node); err != nil { + t.Fatal(err) + } + for _, tok := range strings.Split(strings.TrimPrefix(pointer, "/"), "/") { + switch n := node.(type) { + case map[string]any: + node = n[tok] + case []any: + i, err := strconv.Atoi(tok) + if err != nil || i >= len(n) { + return "" + } + node = n[i] + default: + return "" + } + } + 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 100% rename from plugins/apichangelog/testdata/golden/mongodb-atlas.json rename to plugins/changelog/testdata/golden/mongodb-atlas.json 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/providers/mongodb-atlas.md b/providers/mongodb-atlas.md index 19d14b2..c0a5143 100644 --- a/providers/mongodb-atlas.md +++ b/providers/mongodb-atlas.md @@ -4,7 +4,7 @@ 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 From 7ff927bf7f187d8cbaee803bff6f7c68a29d016c Mon Sep 17 00:00:00 2001 From: adssib <75389300+adssib@users.noreply.github.com> Date: Fri, 20 Nov 2026 17:54:06 -0500 Subject: [PATCH 03/16] merge retirements, feed and eol into one notices kind One Plugin reads every live page of dated notices: fetch, unchanged check, shape guard and blocked-page fallback as reader options, Wayback cite, events, baseline. The deprecations-page, feed and end-of-life readers live under plugins/notices; the RSS/Atom and HTML helpers move to core/extract. The old packages only forward. Co-Authored-By: Claude Opus 5.5 Signed-off-by: adssib <75389300+adssib@users.noreply.github.com> --- AGENTS.md | 11 +- README.md | 2 +- cmd/new-plugin/formats.go | 20 +- plugins/feed/parse.go => core/extract/feed.go | 10 +- core/kit/notices.go | 11 + core/migrate/migrate.go | 2 +- core/plugin/provider.go | 3 + docs/how-it-works.md | 6 +- docs/plugins.schema.json | 2 +- docs/writing-a-plugin.md | 11 +- plugins/all/all.go | 4 +- plugins/eol/eol.go | 306 +----------------- plugins/eol/eol_test.go | 116 +------ plugins/feed/feed.go | 176 ++-------- plugins/feed/feed_test.go | 130 +------- plugins/feed/registered_test.go | 13 - plugins/notices/eol/eol.go | 241 ++++++++++++++ plugins/{ => notices}/eol/testdata/README.md | 0 .../salesforce-api-rest-eol-2026-10-31.html | 0 plugins/notices/eol_test.go | 121 +++++++ plugins/{ => notices}/feed/cloudflare_test.go | 0 plugins/notices/feed/extract.go | 19 ++ plugins/notices/feed/feed.go | 121 +++++++ plugins/notices/feed/feed_test.go | 107 ++++++ plugins/{ => notices}/feed/readers.go | 0 plugins/{ => notices}/feed/testdata/README.md | 4 +- .../cloudflare-api-deprecations.rss.xml | 0 .../testdata/github-changelog-actions.rss.xml | 0 .../testdata/vertex-ai-generative-ai.atom.xml | 0 plugins/notices/feed_golden_test.go | 33 ++ plugins/notices/feed_registered_test.go | 14 + plugins/notices/notices.go | 201 ++++++++++++ plugins/notices/retire/notices.go | 41 +++ .../retire/providers.go | 0 plugins/notices/retire/retire.go | 245 ++++++++++++++ .../retire/retire_test.go | 0 .../retire/testdata/README.md | 2 +- .../retire/testdata/anthropic-deprecations.md | 0 .../retire/testdata/openai-deprecations.md | 0 .../retirements_golden_test.go} | 6 +- .../retirements_registered_test.go} | 6 +- .../notices/retirements_retirements_test.go | 133 ++++++++ plugins/notices/testdata/README.md | 7 + .../testdata/golden/anthropic-models.json | 0 .../testdata/golden/cloudflare.json | 0 .../testdata/golden/github-actions.json | 0 .../testdata/golden/openai-models.json | 0 .../testdata/golden/salesforce.json | 0 .../testdata/golden/vertex-ai-models.json | 0 plugins/retirements/retire/retire.go | 253 +-------------- plugins/retirements/retirements.go | 99 +----- plugins/retirements/retirements_test.go | 128 +------- plugins/retirements/testdata/README.md | 5 - providers/anthropic-models.md | 2 +- providers/cloudflare.md | 2 +- providers/github-actions.md | 2 +- providers/openai-models.md | 2 +- providers/salesforce.md | 2 +- providers/vertex-ai-models.md | 2 +- retire/retire.go | 10 +- 60 files changed, 1445 insertions(+), 1186 deletions(-) rename plugins/feed/parse.go => core/extract/feed.go (93%) create mode 100644 core/kit/notices.go delete mode 100644 plugins/feed/registered_test.go create mode 100644 plugins/notices/eol/eol.go rename plugins/{ => notices}/eol/testdata/README.md (100%) rename plugins/{ => notices}/eol/testdata/salesforce-api-rest-eol-2026-10-31.html (100%) create mode 100644 plugins/notices/eol_test.go rename plugins/{ => notices}/feed/cloudflare_test.go (100%) create mode 100644 plugins/notices/feed/extract.go create mode 100644 plugins/notices/feed/feed.go create mode 100644 plugins/notices/feed/feed_test.go rename plugins/{ => notices}/feed/readers.go (100%) rename plugins/{ => notices}/feed/testdata/README.md (89%) rename plugins/{ => notices}/feed/testdata/cloudflare-api-deprecations.rss.xml (100%) rename plugins/{ => notices}/feed/testdata/github-changelog-actions.rss.xml (100%) rename plugins/{ => notices}/feed/testdata/vertex-ai-generative-ai.atom.xml (100%) create mode 100644 plugins/notices/feed_golden_test.go create mode 100644 plugins/notices/feed_registered_test.go create mode 100644 plugins/notices/notices.go create mode 100644 plugins/notices/retire/notices.go rename plugins/{retirements => notices}/retire/providers.go (100%) create mode 100644 plugins/notices/retire/retire.go rename plugins/{retirements => notices}/retire/retire_test.go (100%) rename plugins/{retirements => notices}/retire/testdata/README.md (94%) rename plugins/{retirements => notices}/retire/testdata/anthropic-deprecations.md (100%) rename plugins/{retirements => notices}/retire/testdata/openai-deprecations.md (100%) rename plugins/{retirements/golden_test.go => notices/retirements_golden_test.go} (87%) rename plugins/{retirements/registered_test.go => notices/retirements_registered_test.go} (59%) create mode 100644 plugins/notices/retirements_retirements_test.go create mode 100644 plugins/notices/testdata/README.md rename plugins/{retirements => notices}/testdata/golden/anthropic-models.json (100%) rename plugins/{feed => notices}/testdata/golden/cloudflare.json (100%) rename plugins/{feed => notices}/testdata/golden/github-actions.json (100%) rename plugins/{retirements => notices}/testdata/golden/openai-models.json (100%) rename plugins/{eol => notices}/testdata/golden/salesforce.json (100%) rename plugins/{feed => notices}/testdata/golden/vertex-ai-models.json (100%) delete mode 100644 plugins/retirements/testdata/README.md diff --git a/AGENTS.md b/AGENTS.md index efbd38b..2292472 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -53,15 +53,16 @@ core/plugin/ the Plugin interface (Run; ListVersions, ReadAt, Extract) 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/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/ core/migrate/ the change-event types from patch-it's contract (v1 + v2), v1 -> v2 core/diff/ core/normalize/ core/hint/ the OpenAPI diff engine and its helpers plugins// one package per kind, with its providers: openapi (+ adapter/, one spec adapter - per provider), retirements (+ retire/), migrationguide (+ sdkguide/, - members/), changelog (Markdown, RST or JSON), feed, catalog, eol; + per provider), notices (+ retire/, feed/, eol/), migrationguide (+ sdkguide/, + members/), changelog (Markdown, RST or JSON), catalog; plugins/all imports every one -plugins/removedmembers/ plugins/apichangelog/ deprecated: merged into migrationguide and - changelog, they only forward there +plugins/removedmembers/ apichangelog/ retirements/ feed/ eol/ deprecated: merged into + migrationguide, changelog and notices, they only forward there 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 diff --git a/README.md b/README.md index ab32e15..9b8da30 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ You need Go (the version in `go.mod`), `make` and Python 3. ``` 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: ```sh - go test ./plugins/feed -run TestAcme -update + go test ./plugins/notices -run TestAcme -update ``` 3. **Check it the way CI will, and open the PR** (`git commit -s`, one provider per PR): ```sh diff --git a/cmd/new-plugin/formats.go b/cmd/new-plugin/formats.go index b610c6d..a14761b 100644 --- a/cmd/new-plugin/formats.go +++ b/cmd/new-plugin/formats.go @@ -31,9 +31,9 @@ const todo = "TODO(new-plugin)" var formats = map[string]formatSpec{ "feed": { - kind: "feed", + kind: "notices", layer: "api", - defDir: "plugins/feed", + defDir: "plugins/notices/feed", def: `package feed // {{.Ident}} is {{.Provider}}'s feed of changes. @@ -60,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 @@ -73,18 +73,18 @@ func read{{.Ident}}(e Entry) []Finding { // through a test archive that serves the same copy. func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { 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": { - kind: "retirements", + kind: "notices", layer: "ai-models", - defDir: "plugins/retirements/retire", + defDir: "plugins/notices/retire", def: `package retire import "strings" @@ -152,7 +152,7 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { return kittest.IngestWith(t, kittest.Env(t, saved), Plugin{Page: retire.{{.Ident}}, Archiver: archive}) } `, - imports: []string{"encoding/json", "strings", "github.com/patch-it-dev/patch-it-plugins/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": { 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/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 index 3ffa523..4cc5b0f 100644 --- a/core/migrate/migrate.go +++ b/core/migrate/migrate.go @@ -16,7 +16,7 @@ import ( "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" + "github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire" ) // providers are the model retirement slugs and who retires the models. diff --git a/core/plugin/provider.go b/core/plugin/provider.go index 86f4d83..4a02323 100644 --- a/core/plugin/provider.go +++ b/core/plugin/provider.go @@ -237,6 +237,9 @@ func KindOf(p Plugin) string { var mergedKinds = map[string]string{ "removedmembers": "migrationguide", "apichangelog": "changelog", + "retirements": "notices", + "feed": "notices", + "eol": "notices", } // CanonicalKind is the kind name means now: name itself, or, for a kind diff --git a/docs/how-it-works.md b/docs/how-it-works.md index 551dcfb..9bacfff 100644 --- a/docs/how-it-works.md +++ b/docs/how-it-works.md @@ -23,12 +23,12 @@ There's no list in this repo: `make plugins` prints every provider and source fr | [`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 | | [`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/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/), [`core/migrate/`](../core/migrate/) | The change-event types of [patch-it's contract](https://github.com/patch-it-dev/patch-it/tree/main/docs/contract), and the v1 → v2 conversion | | [`core/diff/`](../core/diff/), [`core/normalize/`](../core/normalize/), [`core/hint/`](../core/hint/), [`plugins/openapi/adapter/`](../plugins/openapi/adapter/) | The OpenAPI diff engine: compare two specs, turn the changes into events, attach changelog hints; one adapter per spec provider | -| [`plugins/retirements/retire/`](../plugins/retirements/retire/), [`plugins/migrationguide/sdkguide/`](../plugins/migrationguide/sdkguide/), [`plugins/migrationguide/members/`](../plugins/migrationguide/members/), [`core/fetch/`](../core/fetch/) | The deprecations-page and migration-guide readers (removed parameters, removed members); 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/`, `plugins/removedmembers/`, `plugins/apichangelog/` | Deprecated: the old import paths, forwarding to the packages above until code that imports them moves | +| `plugin/`, `event/`, `fetch/`, `migrate/`, `kit/`, `kit/kittest/`, `retire/`, `sdkguide/`, `plugins/removedmembers/`, `plugins/apichangelog/`, `plugins/retirements/`, `plugins/feed/`, `plugins/eol/` | 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 8615cac..d59ddc8 100644 --- a/docs/plugins.schema.json +++ b/docs/plugins.schema.json @@ -37,7 +37,7 @@ "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", "changelog", "feed", "catalog", "eol"] }, + "kind": { "type": "string", "enum": ["openapi", "changelog", "notices", "migrationguide", "catalog"] }, "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/writing-a-plugin.md b/docs/writing-a-plugin.md index 3fa7024..b27dd55 100644 --- a/docs/writing-a-plugin.md +++ b/docs/writing-a-plugin.md @@ -10,14 +10,15 @@ Pick the source and the kind that reads it (steps 2 and 3), then let the starter ```sh go run ./cmd/new-plugin --api acme --provider Acme --format openapi -# --format: openapi, retirements, migrationguide, removedmembers (a migrationguide source), changelog, feed, apichangelog (a JSON changelog source), catalog +# --format: openapi, retirements and feed (notices sources), migrationguide, removedmembers (a migrationguide source), +# changelog, apichangelog (a JSON changelog source), 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/) ``` 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); +- the provider's definition, in the package the format reads it from (`plugins/openapi/adapter/`, `plugins/notices/retire/`, `plugins/notices/feed/`, `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 the deprecations-page and SDK-guide readers need); - `plugins//_test.go`: the registration test, a golden test and a pinned drop test, over placeholder sources in `testdata/`, with the golden file written from them; - a row per saved file in that `testdata/README.md` (URL, date, license, quote to fill in); - `providers/.md` from the template (or nothing, with `--page`, when the provider already has one); @@ -75,12 +76,10 @@ Write the numbers on the provider page, as `providers/vercel.md` does for its sp | 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/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/` (`--format` doesn't scaffold this one 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/feed` | An RSS or Atom feed | A `feed.Feed` with a reader for that vendor's entries | | `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/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 | ## 4. The interface @@ -160,7 +159,7 @@ The event format is [patch-it's change-event contract](https://github.com/patch- ## 5. Save the source -Save a real copy of what the plugin reads under your package's `testdata/` (or the reader package's, like `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/plugins/all/all.go b/plugins/all/all.go index 74a0d2c..834349d 100644 --- a/plugins/all/all.go +++ b/plugins/all/all.go @@ -6,9 +6,7 @@ package all import ( _ "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/retirements" ) diff --git a/plugins/eol/eol.go b/plugins/eol/eol.go index 4bd1e31..906b2ab 100644 --- a/plugins/eol/eol.go +++ b/plugins/eol/eol.go @@ -1,298 +1,26 @@ -// Package eol is the source plugin for a vendor's own API end-of-life page: 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. +// Package eol is the old import path of the notices kind's end-of-life +// page reader, kept so code that imports it still builds. // -// There is no spec to diff, like retirements and feed: the page is read as it -// is now, and (as with them) the events cite a Wayback Machine snapshot of -// 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 -// 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, -// 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. -// -// Unlike retirements (one named model per row) and feed (an RSS or Atom -// entry), a row here names a whole range of version numbers and no -// replacement: moving up to any newer version clears it. +// Deprecated: use plugins/notices (Plugin) and plugins/notices/eol (the +// reader: Page, Salesforce, Findings). This package only forwards to them +// and registers nothing; it goes once nothing imports it. package eol import ( - "context" - "errors" - "fmt" - "log" - "regexp" - "strconv" - "strings" - - "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/plugins/notices" + moved "github.com/patch-it-dev/patch-it-plugins/plugins/notices/eol" ) -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" - Vendor string // for sentences: "Salesforce" - URL string // the page, as HTML - // Operation names the one real, documented, version-rooted resource a - // retired version takes down: Salesforce's "List Available REST - // Resources" call, GET /services/data/vXX.X/. Every other resource under - // that version is gone too (the page says so), but this is the one this - // plugin can point at honestly, without inventing a wildcard operation - // nothing calls. - Operation func(version string) string -} - -// Salesforce is the REST API's end-of-life policy page (checked 2026-11-20): -// a table of version ranges, each "Supported.", already retired ("As of -// Summer '25, these versions are retired and unavailable."), or scheduled -// ("Deprecated and unsupported from Summer '27. Retired from Summer '28."). -// Salesforce gives no exact date, only the named release ("Summer '27"); the -// policy text above the table says the notice is at least a year ahead of -// retirement. -var Salesforce = Page{ - API: "salesforce", 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 + "/" }, -} - -// Row is one version range and what its status cell says, cleaned of HTML. -type Row struct { - From, To int // inclusive, both ends; From == To for a single version - Label string // the first cell's own text, word for word ("Versions 31.0 through 40.0") - Status string // every

in the status cell, joined with a space -} - -// Finding is one version number a row's status names, or a row that names -// none (Dropped set). -type Finding struct { - ChangeType event.ChangeType - Version string // "21.0" - Season string // "Summer ’25", or "Summer ’27, retired from Summer ’28" - Excerpt string - Row string // the row's version-range text, for Dropped's log line - Dropped string -} +type ( + // Plugin is notices.Plugin: set Page and Archiver, as before. + Plugin = notices.Plugin + Page = moved.Page + Row = moved.Row + Finding = moved.Finding +) var ( - table = regexp.MustCompile(`(?is)(.*?)`) - row = regexp.MustCompile(`(?is)(.*?)`) - // cell tolerates an attribute (): a future style change - // shouldn't make every row unreadable. - cell = regexp.MustCompile(`(?is)]*>(.*?)`) - tag = regexp.MustCompile(`<[^>]+>`) - // versions reads only the whole-number part of a version ("31.0 through - // 40.0" -> 31, 40): every version on the page today is a whole number. - // Salesforce has never shipped a minor REST API version, but this would - // silently drop one ("31.5") rather than fail loudly if that changed. - versions = regexp.MustCompile(`(?i)Versions?\s+(\d+)(?:\.\d+)?(?:\s+through\s+(\d+)(?:\.\d+)?)?`) - retired = regexp.MustCompile(`(?i)As of ([^,]+), these versions are retired and unavailable\.`) - deprecd = regexp.MustCompile(`(?i)Deprecated and unsupported from ([^.]+)\.\s*Retired from ([^.]+)\.`) + Salesforce = moved.Salesforce + Parse = moved.Parse + Findings = moved.Findings ) - -// text strips tags and normalizes whitespace, the way a 's content (bare -// text, or several

s) reads as one sentence. -func text(fragment string) string { - return strings.Join(strings.Fields(tag.ReplaceAllString(fragment, " ")), " ") -} - -// Parse reads every row of the page's first table. -func Parse(page []byte) ([]Row, error) { - m := table.FindStringSubmatch(string(page)) - if m == nil { - return nil, fmt.Errorf("no table found: the page's shape may have changed") - } - var out []Row - for _, r := range row.FindAllStringSubmatch(m[1], -1) { - cells := cell.FindAllStringSubmatch(r[1], -1) - if len(cells) < 2 { - continue - } - label := text(cells[0][1]) - vm := versions.FindStringSubmatch(label) - if vm == nil { - continue - } - from, _ := strconv.Atoi(vm[1]) - to := from - if vm[2] != "" { - to, _ = strconv.Atoi(vm[2]) - } - out = append(out, Row{From: from, To: to, Label: label, Status: text(cells[1][1])}) - } - if len(out) == 0 { - return nil, fmt.Errorf("no version rows found: the page's shape may have changed") - } - return out, nil -} - -// Findings classifies every row and names every version number a breaking or -// deprecated row covers. A row that's merely "Supported." names none. -func Findings(page []byte) ([]Finding, error) { - rows, err := Parse(page) - if err != nil { - return nil, err - } - var out []Finding - for _, r := range rows { - label := r.Label - excerpt := label + " | " + r.Status - - var ct event.ChangeType - var season string - switch { - case retired.MatchString(r.Status): - ct, season = event.ChangeTypeBreaking, retired.FindStringSubmatch(r.Status)[1] - case deprecd.MatchString(r.Status): - m := deprecd.FindStringSubmatch(r.Status) - ct, season = event.ChangeTypeDeprecation, m[1]+", retired from "+m[2] - default: - out = append(out, Finding{Row: label, Dropped: fmt.Sprintf("status %q names neither a retirement nor a deprecation", r.Status)}) - continue - } - for v := r.From; v <= r.To; v++ { - out = append(out, Finding{ - ChangeType: ct, - Version: fmt.Sprintf("%d.0", v), - Season: season, - Excerpt: excerpt, - Row: label, - }) - } - } - return out, nil -} - -// Plugin reads one vendor's end-of-life page. -type Plugin struct { - Page Page - Archiver kit.Archiver -} - -func (p Plugin) Name() string { return p.Page.API } - -// 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 - } - - want, err := Findings(live) - if err != nil { - return plugin.Result{}, fmt.Errorf("reading %s: %w", pg.URL, err) - } - - 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 - } - } - - now := env.Now().UTC() - var events []event.EventV2 - var rejected []error - for _, f := range got { - if f.Dropped != "" { - log.Printf("%s: dropped %s: %s", pg.API, f.Row, f.Dropped) - continue - } - e := event.EventV2{ - API: pg.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: 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, - SourceExcerpt: f.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", 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 -} - -func describe(pg Page, f Finding) string { - if f.ChangeType == event.ChangeTypeBreaking { - return fmt.Sprintf("%s REST API version %s is retired, as of %s: it returns 410:GONE for every resource.", pg.Vendor, f.Version, f.Season) - } - return fmt.Sprintf("%s REST API version %s is deprecated and scheduled for retirement: unsupported from %s.", pg.Vendor, f.Version, f.Season) -} diff --git a/plugins/eol/eol_test.go b/plugins/eol/eol_test.go index 6ceac40..27019ea 100644 --- a/plugins/eol/eol_test.go +++ b/plugins/eol/eol_test.go @@ -1,120 +1,16 @@ package eol import ( - "context" - "fmt" "testing" - "time" - "github.com/patch-it-dev/patch-it-plugins/core/fetch" "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" - "github.com/patch-it-dev/patch-it-plugins/core/plugin" ) -func TestRegistersItself(t *testing.T) { - kittest.Registered(t, Plugin{Page: Salesforce}) -} - -// The golden test: 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 -// through 30.0, retired as of Summer '25) and one real, scheduled one -// (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"} - archive := &kittest.Archive{T: t, Pages: saved} - got := kittest.IngestWith(t, kittest.Env(t, saved), Plugin{Page: Salesforce, Archiver: archive}) - if archive.Calls != 1 { - t.Errorf("%d snapshots, want 1: the second run's page is unchanged", archive.Calls) - } - kittest.Golden(t, "testdata/golden/salesforce.json", got) -} - -// 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) - if err != nil { - t.Fatal(err) - } - supported := map[string]bool{} - for v := 41; v <= 67; v++ { - supported[fmt.Sprintf("%d.0", v)] = true - } - var dropped bool - for _, f := range found { - if f.Dropped == "" && supported[f.Version] { - t.Errorf("version %s got an event, want none: it's still Supported", f.Version) - } - if f.Dropped != "" && f.Row == "Versions 41.0 through 67.0" { - dropped = true - } - } - if !dropped { - t.Error("the still-supported band wasn't found and dropped") - } -} - -// 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"} - 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} - }, - Now: func() time.Time { return kittest.Clock }, - } - got := kittest.IngestWith(t, env, Plugin{Page: Salesforce, Archiver: archive}) - if len(got) == 0 { - t.Fatal("no events: the archive fallback didn't run") - } - // Unlike the normal path, a permanently blocked live page has no - // cheap way to check "did it change": liveOrArchived needs the - // archive's own fetch just to get bytes to hash, on every run, - // not only a changed one. The second run still stores nothing - // new: the hash matches. - if archive.Calls != 2 { - t.Errorf("%d snapshots, want 2: the live page is blocked every run", archive.Calls) - } - for _, e := range got { - if e.SourceURL == Salesforce.URL { - t.Errorf("%s: source_url is the blocked live page, want the archive's snapshot", e.Fingerprint) - } - } - }) - } -} - -// A real failure (not the provider blocking a plain fetch) must stay a -// failure: falling back to the archive for a timeout or a 5xx would hide it -// as a real page. -func TestDoesNotFallBackOnATransientError(t *testing.T) { - for _, code := range []int{404, 429, 503} { - t.Run(fmt.Sprint(code), func(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} - }, - 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) - if err == nil { - t.Fatalf("want an error for a %d, got none", code) - } - }) +// Code written against the old path still builds and runs the same source. +func TestTheOldPathStillWorks(t *testing.T) { + p := Plugin{Page: Salesforce} + kittest.Registered(t, p) + if p.Name() != "salesforce" { + t.Errorf("Plugin{Page: Salesforce} is %q", p.Name()) } } diff --git a/plugins/feed/feed.go b/plugins/feed/feed.go index dba0f77..7690531 100644 --- a/plugins/feed/feed.go +++ b/plugins/feed/feed.go @@ -1,165 +1,51 @@ -// 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. +// Package feed is the old import path of the notices kind's RSS and Atom +// feed reader, kept so code that imports it still builds. // -// 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. +// Deprecated: use plugins/notices (notices.Plugin{Page: feed.GitHubActions}) +// and plugins/notices/feed (the reader). This package only forwards to them +// and registers nothing; it goes once nothing imports it. 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" + "github.com/patch-it-dev/patch-it-plugins/plugins/notices" + moved "github.com/patch-it-dev/patch-it-plugins/plugins/notices/feed" ) -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 -} +type ( + Feed = moved.Feed + Reader = moved.Reader + Finding = moved.Finding + Entry = moved.Entry + Section = moved.Section +) -// 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 -} +var ( + GitHubActions = moved.GitHubActions + VertexAIModels = moved.VertexAIModels + CloudflareAPI = moved.CloudflareAPI + Parse = moved.Parse + Text = moved.Text + Lines = moved.Lines + SplitBy = moved.SplitBy + Date = moved.Date + Codes = moved.Codes +) -// Plugin reads one feed. +// Plugin reads one feed: notices.Plugin{Page: Feed, Archiver: Archiver}. type Plugin struct { Feed Feed Archiver kit.Archiver } -func (p Plugin) Name() string { return p.Feed.API } +func (p Plugin) notices() notices.Plugin { return notices.Plugin{Page: p.Feed, Archiver: p.Archiver} } -// 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 - } +func (p Plugin) Name() string { return p.notices().Name() } - 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 +// Run is notices.Plugin's Run. +func (p Plugin) Run(ctx context.Context, env plugin.Env) (plugin.Result, error) { + return p.notices().Run(ctx, env) } diff --git a/plugins/feed/feed_test.go b/plugins/feed/feed_test.go index fe58a89..610dd33 100644 --- a/plugins/feed/feed_test.go +++ b/plugins/feed/feed_test.go @@ -1,132 +1,16 @@ package feed import ( - "strings" "testing" "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) { - for _, c := range []struct { - feed Feed - file string - dropped []string // a substring of each drop reason, in order - }{ - {GitHubActions, "testdata/github-changelog-actions.rss.xml", []string{ - "arm32-linux-windows-retirement", // no runner label: no ci_runtime to name - "pull_request_target-blocked-by-default-december-2", // a behavior change, no subject type fits - }}, - {VertexAIModels, "testdata/vertex-ai-generative-ai.atom.xml", []string{ - "Vertex AI Extensions deprecation", - "Anthropic's Claude 3 Haiku", // a product name in prose, not a model id - "Anthropic's Claude 3.5 Haiku", - }}, - } { - fs, err := c.feed.Findings(kittest.Read(t, c.file)) - if err != nil { - t.Fatal(err) - } - var drops []string - for _, f := range fs { - if f.Dropped != "" { - drops = append(drops, f.Entry+" "+f.Dropped) - } - } - if len(drops) != len(c.dropped) { - t.Errorf("%s: dropped %d, want %d:\n%s", c.feed.API, len(drops), len(c.dropped), strings.Join(drops, "\n")) - continue - } - for i, want := range c.dropped { - if !strings.Contains(drops[i], want) { - t.Errorf("%s: drop %d is %q, want %q", c.feed.API, i, drops[i], want) - } - } - } -} - -func TestParseRefusesWhatIsntAFeed(t *testing.T) { - for name, b := range map[string]string{ - "html": "moved", - "no items": `x`, - "no entry": `x`, - } { - if _, err := Parse([]byte(b)); err == nil { - t.Errorf("%s: want an error, never zero events read as a quiet week", name) - } - } -} - -// RSS without content:encoded falls back to description; Atom takes the -// alternate link and the category terms. -func TestParseReadsBothFormats(t *testing.T) { - r, err := Parse([]byte(`A & Bhttps://x.test/a - Retired<p>text</p>`)) - if err != nil || r[0].Title != "A & B" || r[0].HTML != "

text

" || r[0].Categories[0] != "Retired" || r[0].ID != "https://x.test/a" { - t.Errorf("rss: %+v %v", r, err) - } - a, err := Parse([]byte(`iT - - <b>s</b>`)) - if err != nil || a[0].Link != "https://x.test/e" || a[0].HTML != "s" || a[0].Categories[0] != "Deprecated" { - t.Errorf("atom: %+v %v", a, err) - } -} - -// Breaking only when the vendor says the thing stops on the date; softer -// words downgrade to a deprecation, and no date drops the entry. -func TestBreakingNeedsTheVendorToSayItStops(t *testing.T) { - entry := func(sentence string) Entry { - return Entry{Title: "Ubuntu 22.04 runner image retirement", Link: "https://x.test/e", Categories: []string{"Retired"}, - HTML: "

" + sentence + "

This deprecation includes the following labels:

  • ubuntu-22.04
"} - } - for sentence, want := range map[string]string{ - "The Ubuntu 22.04 runner image will be retired on March 1, 2027.": "breaking 2027-03-01", - "The Ubuntu 22.04 runner image will be removed on March 1, 2027.": "breaking 2027-03-01", - "The Ubuntu 22.04 runner image will be deprecated on March 1, 2027.": "deprecation 2027-03-01", - "Please move off the Ubuntu 22.04 runner image before March 1, 2027.": "deprecation 2027-03-01", - "The Ubuntu 22.04 runner image will be retired in the coming months.": "dropped", - "Announced March 1, 2027: the Ubuntu 22.04 image is being looked at.": "dropped", - } { - fs := readGitHubActions(entry(sentence)) - got := "dropped" - if len(fs) == 1 && fs[0].Dropped == "" { - got = string(fs[0].ChangeType) + " " + fs[0].Version - } - if got != want { - t.Errorf("%q: %s, want %s", sentence, got, want) - } - } - unmarked := entry("The Ubuntu 22.04 runner image will be retired on March 1, 2027.") - unmarked.Categories = []string{"Improvement"} - if fs := readGitHubActions(unmarked); len(fs) != 0 { - t.Errorf("an entry the vendor didn't mark: %+v", fs) - } +// Code written against the old path still builds and runs the same feed +// with the same events. +func TestTheOldPathStillWorks(t *testing.T) { + saved := kittest.Pages{GitHubActions.URL: "../notices/feed/testdata/github-changelog-actions.rss.xml"} + archive := &kittest.Archive{T: t, Pages: saved} + got := kittest.IngestWith(t, kittest.Env(t, saved), Plugin{Feed: GitHubActions, Archiver: archive}) + kittest.CompareGolden(t, "../notices/testdata/golden/github-actions.json", got) } 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/notices/eol/eol.go b/plugins/notices/eol/eol.go new file mode 100644 index 0000000..823b707 --- /dev/null +++ b/plugins/notices/eol/eol.go @@ -0,0 +1,241 @@ +// 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. +// +// There is no spec to diff, like retirements and feed: the page is read as it +// is now, and (as with them) the events cite a Wayback Machine snapshot of +// 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 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 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. +// +// Unlike retirements (one named model per row) and feed (an RSS or Atom +// entry), a row here names a whole range of version numbers and no +// replacement: moving up to any newer version clears it. +package eol + +import ( + "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/kit" +) + +// Page is one vendor's end-of-life table. +type Page struct { + API string // the events' api: "salesforce" + Vendor string // for sentences: "Salesforce" + URL string // the page, as HTML + // Operation names the one real, documented, version-rooted resource a + // retired version takes down: Salesforce's "List Available REST + // Resources" call, GET /services/data/vXX.X/. Every other resource under + // that version is gone too (the page says so), but this is the one this + // plugin can point at honestly, without inventing a wildcard operation + // nothing calls. + Operation func(version string) string +} + +// Salesforce is the REST API's end-of-life policy page (checked 2026-11-20): +// a table of version ranges, each "Supported.", already retired ("As of +// Summer '25, these versions are retired and unavailable."), or scheduled +// ("Deprecated and unsupported from Summer '27. Retired from Summer '28."). +// Salesforce gives no exact date, only the named release ("Summer '27"); the +// policy text above the table says the notice is at least a year ahead of +// retirement. +var Salesforce = Page{ + API: "salesforce", 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 + "/" }, +} + +// Row is one version range and what its status cell says, cleaned of HTML. +type Row struct { + From, To int // inclusive, both ends; From == To for a single version + Label string // the first cell's own text, word for word ("Versions 31.0 through 40.0") + Status string // every

in the status cell, joined with a space +} + +// Finding is one version number a row's status names, or a row that names +// none (Dropped set). +type Finding struct { + ChangeType event.ChangeType + Version string // "21.0" + Season string // "Summer ’25", or "Summer ’27, retired from Summer ’28" + Excerpt string + Row string // the row's version-range text, for Dropped's log line + Dropped string +} + +var ( + table = regexp.MustCompile(`(?is)(.*?)`) + row = regexp.MustCompile(`(?is)(.*?)`) + // cell tolerates an attribute (): a future style change + // shouldn't make every row unreadable. + cell = regexp.MustCompile(`(?is)]*>(.*?)`) + tag = regexp.MustCompile(`<[^>]+>`) + // versions reads only the whole-number part of a version ("31.0 through + // 40.0" -> 31, 40): every version on the page today is a whole number. + // Salesforce has never shipped a minor REST API version, but this would + // silently drop one ("31.5") rather than fail loudly if that changed. + versions = regexp.MustCompile(`(?i)Versions?\s+(\d+)(?:\.\d+)?(?:\s+through\s+(\d+)(?:\.\d+)?)?`) + retired = regexp.MustCompile(`(?i)As of ([^,]+), these versions are retired and unavailable\.`) + deprecd = regexp.MustCompile(`(?i)Deprecated and unsupported from ([^.]+)\.\s*Retired from ([^.]+)\.`) +) + +// text strips tags and normalizes whitespace, the way a 's content (bare +// text, or several

s) reads as one sentence. +func text(fragment string) string { + return strings.Join(strings.Fields(tag.ReplaceAllString(fragment, " ")), " ") +} + +// Parse reads every row of the page's first table. +func Parse(page []byte) ([]Row, error) { + m := table.FindStringSubmatch(string(page)) + if m == nil { + return nil, fmt.Errorf("no table found: the page's shape may have changed") + } + var out []Row + for _, r := range row.FindAllStringSubmatch(m[1], -1) { + cells := cell.FindAllStringSubmatch(r[1], -1) + if len(cells) < 2 { + continue + } + label := text(cells[0][1]) + vm := versions.FindStringSubmatch(label) + if vm == nil { + continue + } + from, _ := strconv.Atoi(vm[1]) + to := from + if vm[2] != "" { + to, _ = strconv.Atoi(vm[2]) + } + out = append(out, Row{From: from, To: to, Label: label, Status: text(cells[1][1])}) + } + if len(out) == 0 { + return nil, fmt.Errorf("no version rows found: the page's shape may have changed") + } + return out, nil +} + +// Findings classifies every row and names every version number a breaking or +// deprecated row covers. A row that's merely "Supported." names none. +func Findings(page []byte) ([]Finding, error) { + rows, err := Parse(page) + if err != nil { + return nil, err + } + var out []Finding + for _, r := range rows { + label := r.Label + excerpt := label + " | " + r.Status + + var ct event.ChangeType + var season string + switch { + case retired.MatchString(r.Status): + ct, season = event.ChangeTypeBreaking, retired.FindStringSubmatch(r.Status)[1] + case deprecd.MatchString(r.Status): + m := deprecd.FindStringSubmatch(r.Status) + ct, season = event.ChangeTypeDeprecation, m[1]+", retired from "+m[2] + default: + out = append(out, Finding{Row: label, Dropped: fmt.Sprintf("status %q names neither a retirement nor a deprecation", r.Status)}) + continue + } + for v := r.From; v <= r.To; v++ { + out = append(out, Finding{ + ChangeType: ct, + Version: fmt.Sprintf("%d.0", v), + Season: season, + Excerpt: excerpt, + Row: label, + }) + } + } + return out, nil +} + +// What the notices kind (plugins/notices) asks of an end-of-life page. + +// Read is what one read of a page found, dropped rows included. +type Read []Finding + +// Count is how many findings the page gave. +func (r Read) Count() int { return len(r) } + +// Slug is the events' api: "salesforce". +func (pg Page) Slug() string { return pg.API } + +// 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 +} + +// 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.ChangeEvent, []event.EventV2, []error) { + var events []event.EventV2 + var rejected []error + for _, f := range found.(Read) { + if f.Dropped != "" { + log.Printf("%s: dropped %s: %s", pg.API, f.Row, f.Dropped) + continue + } + e := event.EventV2{ + API: pg.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: 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, citeURL), + SourceURL: citeURL, + SourceExcerpt: f.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", pg.API, f.Version, err)) + continue + } + events = append(events, e) + } + return nil, events, rejected +} + +func describe(pg Page, f Finding) string { + if f.ChangeType == event.ChangeTypeBreaking { + return fmt.Sprintf("%s REST API version %s is retired, as of %s: it returns 410:GONE for every resource.", pg.Vendor, f.Version, f.Season) + } + return fmt.Sprintf("%s REST API version %s is deprecated and scheduled for retirement: unsupported from %s.", pg.Vendor, f.Version, f.Season) +} 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/notices/eol_test.go b/plugins/notices/eol_test.go new file mode 100644 index 0000000..eea4725 --- /dev/null +++ b/plugins/notices/eol_test.go @@ -0,0 +1,121 @@ +package notices + +import ( + "context" + "fmt" + "testing" + "time" + + "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 TestEOLRegistersItself(t *testing.T) { + kittest.Registered(t, Plugin{Page: eol.Salesforce}) +} + +// 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 +// through 30.0, retired as of Summer '25) and one real, scheduled one +// (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 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: eol.Salesforce, Archiver: archive}) + if archive.Calls != 1 { + t.Errorf("%d snapshots, want 1: the second run's page is unchanged", archive.Calls) + } + kittest.Golden(t, "testdata/golden/salesforce.json", got) +} + +// 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, "eol/testdata/salesforce-api-rest-eol-2026-10-31.html") + found, err := eol.Findings(page) + if err != nil { + t.Fatal(err) + } + supported := map[string]bool{} + for v := 41; v <= 67; v++ { + supported[fmt.Sprintf("%d.0", v)] = true + } + var dropped bool + for _, f := range found { + if f.Dropped == "" && supported[f.Version] { + t.Errorf("version %s got an event, want none: it's still Supported", f.Version) + } + if f.Dropped != "" && f.Row == "Versions 41.0 through 67.0" { + dropped = true + } + } + if !dropped { + t.Error("the still-supported band wasn't found and dropped") + } +} + +// 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{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: eol.Salesforce.URL, StatusCode: code} + }, + Now: func() time.Time { return kittest.Clock }, + } + 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") + } + // Unlike the normal path, a permanently blocked live page has no + // cheap way to check "did it change": liveOrArchived needs the + // archive's own fetch just to get bytes to hash, on every run, + // not only a changed one. The second run still stores nothing + // new: the hash matches. + if archive.Calls != 2 { + t.Errorf("%d snapshots, want 2: the live page is blocked every run", archive.Calls) + } + for _, e := range got { + if e.SourceURL == eol.Salesforce.URL { + t.Errorf("%s: source_url is the blocked live page, want the archive's snapshot", e.Fingerprint) + } + } + }) + } +} + +// A real failure (not the provider blocking a plain fetch) must stay a +// failure: falling back to the archive for a timeout or a 5xx would hide it +// as a real page. +func TestDoesNotFallBackOnATransientError(t *testing.T) { + for _, code := range []int{404, 429, 503} { + t.Run(fmt.Sprint(code), func(t *testing.T) { + env := plugin.Env{ + Baselines: kittest.NewMem(), + Get: func(context.Context, string) ([]byte, error) { + 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: 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 100% rename from plugins/feed/cloudflare_test.go rename to plugins/notices/feed/cloudflare_test.go 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..a4a40d7 --- /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 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 +} + +// 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 events' api: "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.ChangeEvent, []event.EventV2, []error) { + var events []event.EventV2 + 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.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: citeURL, + 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) + } + return nil, events, rejected +} diff --git a/plugins/notices/feed/feed_test.go b/plugins/notices/feed/feed_test.go new file mode 100644 index 0000000..01158cd --- /dev/null +++ b/plugins/notices/feed/feed_test.go @@ -0,0 +1,107 @@ +package feed + +import ( + "strings" + "testing" + + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" +) + +// 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) { + for _, c := range []struct { + feed Feed + file string + dropped []string // a substring of each drop reason, in order + }{ + {GitHubActions, "testdata/github-changelog-actions.rss.xml", []string{ + "arm32-linux-windows-retirement", // no runner label: no ci_runtime to name + "pull_request_target-blocked-by-default-december-2", // a behavior change, no subject type fits + }}, + {VertexAIModels, "testdata/vertex-ai-generative-ai.atom.xml", []string{ + "Vertex AI Extensions deprecation", + "Anthropic's Claude 3 Haiku", // a product name in prose, not a model id + "Anthropic's Claude 3.5 Haiku", + }}, + } { + fs, err := c.feed.Findings(kittest.Read(t, c.file)) + if err != nil { + t.Fatal(err) + } + var drops []string + for _, f := range fs { + if f.Dropped != "" { + drops = append(drops, f.Entry+" "+f.Dropped) + } + } + if len(drops) != len(c.dropped) { + t.Errorf("%s: dropped %d, want %d:\n%s", c.feed.API, len(drops), len(c.dropped), strings.Join(drops, "\n")) + continue + } + for i, want := range c.dropped { + if !strings.Contains(drops[i], want) { + t.Errorf("%s: drop %d is %q, want %q", c.feed.API, i, drops[i], want) + } + } + } +} + +func TestParseRefusesWhatIsntAFeed(t *testing.T) { + for name, b := range map[string]string{ + "html": "moved", + "no items": `x`, + "no entry": `x`, + } { + if _, err := Parse([]byte(b)); err == nil { + t.Errorf("%s: want an error, never zero events read as a quiet week", name) + } + } +} + +// RSS without content:encoded falls back to description; Atom takes the +// alternate link and the category terms. +func TestParseReadsBothFormats(t *testing.T) { + r, err := Parse([]byte(`A & Bhttps://x.test/a + Retired<p>text</p>`)) + if err != nil || r[0].Title != "A & B" || r[0].HTML != "

text

" || r[0].Categories[0] != "Retired" || r[0].ID != "https://x.test/a" { + t.Errorf("rss: %+v %v", r, err) + } + a, err := Parse([]byte(`iT + + <b>s</b>`)) + if err != nil || a[0].Link != "https://x.test/e" || a[0].HTML != "s" || a[0].Categories[0] != "Deprecated" { + t.Errorf("atom: %+v %v", a, err) + } +} + +// Breaking only when the vendor says the thing stops on the date; softer +// words downgrade to a deprecation, and no date drops the entry. +func TestBreakingNeedsTheVendorToSayItStops(t *testing.T) { + entry := func(sentence string) Entry { + return Entry{Title: "Ubuntu 22.04 runner image retirement", Link: "https://x.test/e", Categories: []string{"Retired"}, + HTML: "

" + sentence + "

This deprecation includes the following labels:

  • ubuntu-22.04
"} + } + for sentence, want := range map[string]string{ + "The Ubuntu 22.04 runner image will be retired on March 1, 2027.": "breaking 2027-03-01", + "The Ubuntu 22.04 runner image will be removed on March 1, 2027.": "breaking 2027-03-01", + "The Ubuntu 22.04 runner image will be deprecated on March 1, 2027.": "deprecation 2027-03-01", + "Please move off the Ubuntu 22.04 runner image before March 1, 2027.": "deprecation 2027-03-01", + "The Ubuntu 22.04 runner image will be retired in the coming months.": "dropped", + "Announced March 1, 2027: the Ubuntu 22.04 image is being looked at.": "dropped", + } { + fs := readGitHubActions(entry(sentence)) + got := "dropped" + if len(fs) == 1 && fs[0].Dropped == "" { + got = string(fs[0].ChangeType) + " " + fs[0].Version + } + if got != want { + t.Errorf("%q: %s, want %s", sentence, got, want) + } + } + unmarked := entry("The Ubuntu 22.04 runner image will be retired on March 1, 2027.") + unmarked.Categories = []string{"Improvement"} + if fs := readGitHubActions(unmarked); len(fs) != 0 { + t.Errorf("an entry the vendor didn't mark: %+v", fs) + } +} diff --git a/plugins/feed/readers.go b/plugins/notices/feed/readers.go similarity index 100% rename from plugins/feed/readers.go rename to plugins/notices/feed/readers.go diff --git a/plugins/feed/testdata/README.md b/plugins/notices/feed/testdata/README.md similarity index 89% rename from plugins/feed/testdata/README.md rename to plugins/notices/feed/testdata/README.md index eff3f6f..d6115b7 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..05a986e --- /dev/null +++ b/plugins/notices/feed_golden_test.go @@ -0,0 +1,33 @@ +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" +) + +// 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/"+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..cfdea5f --- /dev/null +++ b/plugins/notices/notices.go @@ -0,0 +1,201 @@ +// 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 ( + "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/migrate" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" + "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"}, + 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.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"}, + 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 events' api and the source's old slug: "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: v1 events + // (converted here) or v2 ones, and the notices that failed to become + // events. + Events(found kit.Notices, citeURL string, now time.Time) (v1 []event.ChangeEvent, v2 []event.EventV2, rejected []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() + v1, v2, rejected := pg.Events(got, snapURL, now) + converted, invalid := migrate.Fresh(v1) + // 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, false, now) + baseline.SHA256 = hash + return plugin.Result{Label: snapURL, Events: append(converted, v2...), Rejected: append(rejected, invalid...), 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 +} diff --git a/plugins/notices/retire/notices.go b/plugins/notices/retire/notices.go new file mode 100644 index 0000000..3fb2ced --- /dev/null +++ b/plugins/notices/retire/notices.go @@ -0,0 +1,41 @@ +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 events' api: "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 a v1 event per retired model, citing citeURL (the kind +// converts them to v2: core/migrate reads this package, so it can't be +// called from here). +func (p Page) Events(found kit.Notices, citeURL string, now time.Time) ([]event.ChangeEvent, []event.EventV2, []error) { + v1, errs := Events(p, found.(Retirements), citeURL, now) + return v1, nil, errs +} + +// 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 100% rename from plugins/retirements/retire/providers.go rename to plugins/notices/retire/providers.go diff --git a/plugins/notices/retire/retire.go b/plugins/notices/retire/retire.go new file mode 100644 index 0000000..1c3d673 --- /dev/null +++ b/plugins/notices/retire/retire.go @@ -0,0 +1,245 @@ +// Package retire reads a model provider's deprecations page and turns every +// retired model into change events: a second kind of source next to the +// OpenAPI differ. There is no spec to diff, only the provider's own table of +// shutdown date, model and named replacement, so this reads the table. +// +// Both providers serve the page as markdown at its URL plus ".md" (checked +// 2026-10-13), and both write each announcement as a table whose first column +// is the date the model stops working. The event cites a Wayback Machine +// snapshot of that markdown (kit/), never the live page: the contract +// requires a source that can't change under the event. +package retire + +import ( + "fmt" + "regexp" + "strings" + "time" + + "github.com/patch-it-dev/patch-it-plugins/core/event" +) + +// Page is one provider's deprecations page and what its models are sent to. +type Page struct { + API string // the api slug the events carry, e.g. "openai-models" + Vendor string // for sentences: "OpenAI" + URL string // the page as markdown + Operation string // the provider's main call that takes a model name + // Keep says whether a model name belongs to this source: the operations + // above take text models, not image, audio or embedding ones. + Keep func(name string) bool +} + +// Retirement is one model name the provider stops serving on Date, with the +// replacement it names. An alias gets its own Retirement, with the row it +// came from. +type Retirement struct { + Model string + Date string // YYYY-MM-DD + Replacement string // the replacement cell, as written ("`gpt-5.6-sol` (`reasoning.mode: pro`)") + Via []string + Excerpt string // the section heading, the table header and the row +} + +var ( + dateHeader = regexp.MustCompile(`(?i)^(shutdown|retirement) date$`) + ticked = regexp.MustCompile("`([^`]+)`") +) + +var dateLayouts = []string{"January 2, 2006", "Jan 2, 2006", "2006-01-02"} + +// Parse reads every retirement table on the page. A model listed more than +// once keeps its first row: both pages list the most recent announcement +// first, and a later one supersedes an earlier date, including a later row +// that withdraws the date ("To be announced"). A replacement that is +// itself retired is followed to the model that replaces it, so a hint never +// points at a model that no longer works. +func Parse(page []byte, keep func(string) bool) ([]Retirement, error) { + lines := strings.Split(strings.ReplaceAll(string(page), "\r\n", "\n"), "\n") + var out []Retirement + seen := map[string]bool{} + heading := "" + for i := 0; i < len(lines); i++ { + line := strings.TrimSpace(lines[i]) + if strings.HasPrefix(line, "#") { + heading = line + continue + } + header := cells(line) + if len(header) < 3 || !dateHeader.MatchString(header[0]) { + continue + } + model, repl := column(header, "model"), column(header, "replacement", "substitute") + if model < 0 || repl < 0 { + continue // an endpoint ("System") or a training-price table: no model to replace + } + i++ // the |---| row + for i+1 < len(lines) && strings.HasPrefix(strings.TrimSpace(lines[i+1]), "|") { + i++ + row := strings.TrimSpace(lines[i]) + c := cells(row) + if len(c) <= model || len(c) <= repl { + return nil, fmt.Errorf("a short row under %q: %s", heading, row) + } + names := ticked.FindAllStringSubmatch(c[model], -1) + date, err := parseDate(c[0]) + if err != nil { + // "To be announced": not a retirement yet, and the newer word on + // these names, so an older row's date for them doesn't count. + for _, m := range names { + seen[m[1]] = true + } + continue + } + excerpt := strings.Join([]string{heading, strings.TrimSpace(lines[headerLine(lines, i)]), row}, "\n") + for _, m := range names { + name := m[1] + if seen[name] || !keep(name) { + continue + } + seen[name] = true + out = append(out, Retirement{Model: name, Date: date, Replacement: c[repl], Excerpt: excerpt}) + } + } + } + if len(out) == 0 { + return nil, fmt.Errorf("no retirement tables found: the page's shape may have changed") + } + follow(out) + return out, nil +} + +// headerLine walks back from a row to its table's header. +func headerLine(lines []string, i int) int { + for i > 0 && strings.HasPrefix(strings.TrimSpace(lines[i-1]), "|") { + i-- + } + return i +} + +// follow replaces a replacement that is itself retired with its own +// replacement, recording the hops: gpt-3.5-turbo-0613's named replacement is +// gpt-3.5-turbo, which shuts down on 2026-10-23 for gpt-5.6-terra. +func follow(rs []Retirement) { + by := map[string]Retirement{} + for _, r := range rs { + by[r.Model] = r + } + for i := range rs { + for hops := 0; hops < 10; hops++ { + next, ok := by[First(rs[i].Replacement)] + if !ok || next.Model == rs[i].Model { + break + } + rs[i].Via = append(rs[i].Via, next.Model) + rs[i].Replacement = next.Replacement + } + } +} + +// First is the first model name a replacement cell gives, "" when it names +// none ("The most capable cyber model available to you."). +func First(replacement string) string { + if m := ticked.FindStringSubmatch(replacement); m != nil { + return m[1] + } + return "" +} + +// cells splits a markdown table row on its unescaped pipes. A cell can hold +// an escaped one: "`gpt-4-0613` \| `gpt-4`". +func cells(row string) []string { + if !strings.HasPrefix(row, "|") { + return nil + } + row = strings.Trim(row, "|") + var out []string + var cur strings.Builder + for i := 0; i < len(row); i++ { + if row[i] == '\\' && i+1 < len(row) && row[i+1] == '|' { + cur.WriteString(`\|`) + i++ + continue + } + if row[i] == '|' { + out = append(out, strings.TrimSpace(cur.String())) + cur.Reset() + continue + } + cur.WriteByte(row[i]) + } + return append(out, strings.TrimSpace(cur.String())) +} + +func column(header []string, words ...string) int { + for i, h := range header { + for _, w := range words { + if strings.Contains(strings.ToLower(h), w) { + return i + } + } + } + return -1 +} + +func parseDate(s string) (string, error) { + for _, layout := range dateLayouts { + if t, err := time.Parse(layout, strings.TrimSpace(s)); err == nil { + return t.Format("2006-01-02"), nil + } + } + return "", fmt.Errorf("not a date: %q", s) +} + +// Events turns retirements into change events, one per model name: the +// `model` parameter can no longer take that name, in any of the provider's +// calls. affected.operation is the provider's main one; the patch-it client +// looks for the name wherever it reaches the provider's SDK, so one event per +// name gives one fix per repo, not one per operation for the same line. +// version is the shutdown date, so a provider moving the date is a new event. +// sourceURL is the snapshot the retirements were read from. +func Events(p Page, rs []Retirement, sourceURL string, now time.Time) ([]event.ChangeEvent, []error) { + var events []event.ChangeEvent + var errs []error + for _, r := range rs { + affected := event.Affected{ + Kind: event.AffectedKindRequestParameter, + Side: event.SideRequest, + Operation: p.Operation, + Property: "model", + Value: r.Model, + } + e := event.ChangeEvent{ + Fingerprint: event.Fingerprint(p.API, r.Date, event.ChangeTypeBreaking, affected, r.Model), + API: p.API, + Version: r.Date, + ChangeType: event.ChangeTypeBreaking, + Breaking: true, + Affected: affected, + Description: fmt.Sprintf("Model %q is shut down on %s: %s requests naming it fail from that date.", r.Model, r.Date, p.Vendor), + MigrationHint: hint(p.Vendor, r), + SourceURL: sourceURL, + SourceExcerpt: r.Excerpt, + Confidence: 1.0, + DetectedAt: now, + } + if err := e.Validate(); err != nil { + errs = append(errs, fmt.Errorf("%s %s: %w", p.API, r.Model, err)) + continue + } + events = append(events, e) + } + return events, errs +} + +func hint(vendor string, r Retirement) string { + repl := strings.TrimSpace(r.Replacement) + if First(repl) == "" { + return fmt.Sprintf("%s names no replacement model: %s", vendor, repl) + } + h := fmt.Sprintf("Use %s instead: %s's recommended replacement.", repl, vendor) + if len(r.Via) > 0 { + h += fmt.Sprintf(" (%s first named %s, which is itself retired.)", vendor, strings.Join(r.Via, ", then ")) + } + return h +} diff --git a/plugins/retirements/retire/retire_test.go b/plugins/notices/retire/retire_test.go similarity index 100% rename from plugins/retirements/retire/retire_test.go rename to plugins/notices/retire/retire_test.go 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 87% rename from plugins/retirements/golden_test.go rename to plugins/notices/retirements_golden_test.go index b4095c9..e3b356d 100644 --- a/plugins/retirements/golden_test.go +++ b/plugins/notices/retirements_golden_test.go @@ -1,16 +1,16 @@ -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" ) // 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, 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/notices/retirements_retirements_test.go b/plugins/notices/retirements_retirements_test.go new file mode 100644 index 0000000..5af6e91 --- /dev/null +++ b/plugins/notices/retirements_retirements_test.go @@ -0,0 +1,133 @@ +package notices + +import ( + "context" + "fmt" + "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/plugins/notices/retire" +) + +const deprecations = `### 2026-04-22: Legacy GPT model snapshots + +| Shutdown date | Model snapshot | Substitute model | +| ---------------- | -------------------------- | ---------------- | +| October 23, 2026 | ` + "`gpt-4-0613` \\| `gpt-4`" + ` | ` + "`gpt-5.6-sol`" + ` | +` + +// fakeArchive is the Wayback Machine without the network: it serves what it +// was given and counts the snapshots it was asked for. +type fakeArchive struct { + content string + err error + calls *int +} + +func (f fakeArchive) Snapshot(_ context.Context, page string) (string, []byte, error) { + *f.calls++ + if f.err != nil { + return "", nil, f.err + } + return "https://web.archive.org/web/20261013115538/" + page, []byte(f.content), nil +} + +// page is what the provider's page says now, and what the archive holds. +type page struct { + live string + archive fakeArchive +} + +var current page + +func withPage(t *testing.T, live string, archive fakeArchive) { + t.Helper() + current = page{live, archive} +} + +func openStore(*testing.T) *kittest.Mem { return kittest.NewMem() } + +// retirements runs OpenAI's plugin over the current page through the same core +// the command uses. +func retirements(ctx context.Context, s *kittest.Mem, p retire.Page) (bool, error) { + env := plugin.Env{ + Baselines: s, + Get: func(context.Context, string) ([]byte, error) { return []byte(current.live), nil }, + Now: time.Now, + } + return kittest.Run(ctx, env, s, Plugin{Page: p, Archiver: current.archive}) +} + +func TestRetirementsStoreOneEventPerModel(t *testing.T) { + ctx, s, calls := context.Background(), openStore(t), 0 + withPage(t, deprecations, fakeArchive{content: deprecations, calls: &calls}) + + if rejected, err := retirements(ctx, s, retire.OpenAI); err != nil || rejected { + t.Fatalf("rejected=%v err=%v", rejected, err) + } + events, err := s.All() + if err != nil { + t.Fatal(err) + } + got := map[string]bool{} + for _, e := range events { + got[e.Subject.Provider+" "+e.Version+" "+e.Subject.Name] = true + if !strings.HasPrefix(e.SourceURL, "https://web.archive.org/web/20261013115538/") { + t.Errorf("cites %s, want the snapshot", e.SourceURL) + } + } + if len(events) != 2 || !got["openai 2026-10-23 gpt-4-0613"] || !got["openai 2026-10-23 gpt-4"] { + t.Errorf("want one event per model name, got %v", got) + } + + // Same page again: no snapshot, nothing new. + if _, err := retirements(ctx, s, retire.OpenAI); err != nil { + t.Fatal(err) + } + if calls != 1 { + t.Errorf("%d snapshots for an unchanged page, want 1", calls) + } + if again, _ := s.All(); len(again) != 2 { + t.Errorf("%d events after a rerun, want 2", len(again)) + } +} + +func TestRetirementsStoreNothingWithoutASnapshotThatHoldsThem(t *testing.T) { + for name, archive := range map[string]fakeArchive{ + "the archive refused": {err: fmt.Errorf("429 too many requests")}, + "the page moved since": {content: strings.Replace(deprecations, "October 23", "November 23", 1)}, + } { + ctx, s, calls := context.Background(), openStore(t), 0 + archive.calls = &calls + withPage(t, deprecations, archive) + if _, err := retirements(ctx, s, retire.OpenAI); err == nil { + t.Errorf("%s: want an error", name) + } + if events, _ := s.All(); len(events) != 0 { + t.Errorf("%s: stored %d events with nothing to cite", name, len(events)) + } + if last, _ := s.LastSpec(retire.OpenAI.API); last != nil { + t.Errorf("%s: the page was saved, so the next run would skip it", name) + } + } +} + +// A renamed column hides a table: the run must fail, not store a shorter list. +func TestRetirementsRefuseAPageThatLostMostOfItsTables(t *testing.T) { + ctx, s, calls := context.Background(), openStore(t), 0 + withPage(t, deprecations, fakeArchive{content: deprecations, calls: &calls}) + if _, err := retirements(ctx, s, retire.OpenAI); err != nil { + t.Fatal(err) + } + renamed := strings.Replace(deprecations, "Substitute model", "Successor", 1) + strings.Replace(strings.Replace(deprecations, "gpt-4-0613` \\| `gpt-4", "gpt-4o-old", 1), "Substitute model", "Recommended replacement", 1) + withPage(t, renamed, fakeArchive{content: renamed, calls: &calls}) + if _, err := retirements(ctx, s, retire.OpenAI); err == nil || !strings.Contains(err.Error(), "shape may have changed") { + t.Fatalf("want the shape error, got %v", err) + } + if events, _ := s.All(); len(events) != 2 { + t.Errorf("%d events, want only the first run's 2", len(events)) + } +} diff --git a/plugins/notices/testdata/README.md b/plugins/notices/testdata/README.md new file mode 100644 index 0000000..9e9ae85 --- /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/vertex-ai-models.json` and `golden/cloudflare.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 100% rename from plugins/retirements/testdata/golden/anthropic-models.json rename to plugins/notices/testdata/golden/anthropic-models.json diff --git a/plugins/feed/testdata/golden/cloudflare.json b/plugins/notices/testdata/golden/cloudflare.json similarity index 100% rename from plugins/feed/testdata/golden/cloudflare.json rename to plugins/notices/testdata/golden/cloudflare.json diff --git a/plugins/feed/testdata/golden/github-actions.json b/plugins/notices/testdata/golden/github-actions.json similarity index 100% rename from plugins/feed/testdata/golden/github-actions.json rename to plugins/notices/testdata/golden/github-actions.json diff --git a/plugins/retirements/testdata/golden/openai-models.json b/plugins/notices/testdata/golden/openai-models.json similarity index 100% rename from plugins/retirements/testdata/golden/openai-models.json rename to plugins/notices/testdata/golden/openai-models.json diff --git a/plugins/eol/testdata/golden/salesforce.json b/plugins/notices/testdata/golden/salesforce.json similarity index 100% rename from plugins/eol/testdata/golden/salesforce.json rename to plugins/notices/testdata/golden/salesforce.json diff --git a/plugins/feed/testdata/golden/vertex-ai-models.json b/plugins/notices/testdata/golden/vertex-ai-models.json similarity index 100% rename from plugins/feed/testdata/golden/vertex-ai-models.json rename to plugins/notices/testdata/golden/vertex-ai-models.json diff --git a/plugins/retirements/retire/retire.go b/plugins/retirements/retire/retire.go index 1c3d673..200af4c 100644 --- a/plugins/retirements/retire/retire.go +++ b/plugins/retirements/retire/retire.go @@ -1,245 +1,24 @@ -// Package retire reads a model provider's deprecations page and turns every -// retired model into change events: a second kind of source next to the -// OpenAPI differ. There is no spec to diff, only the provider's own table of -// shutdown date, model and named replacement, so this reads the table. +// Package retire is the old import path of github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire, +// the notices kind's deprecations-page reader. // -// Both providers serve the page as markdown at its URL plus ".md" (checked -// 2026-10-13), and both write each announcement as a table whose first column -// is the date the model stops working. The event cites a Wayback Machine -// snapshot of that markdown (kit/), never the live page: the contract -// requires a source that can't change under the event. +// Deprecated: import github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire +// instead. This package only forwards to it, so code written against the old +// path keeps building; it goes once nothing imports it. package retire -import ( - "fmt" - "regexp" - "strings" - "time" +import moved "github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire" - "github.com/patch-it-dev/patch-it-plugins/core/event" +// Deprecated: the types live in github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire. +type ( + Page = moved.Page + Retirement = moved.Retirement ) -// Page is one provider's deprecations page and what its models are sent to. -type Page struct { - API string // the api slug the events carry, e.g. "openai-models" - Vendor string // for sentences: "OpenAI" - URL string // the page as markdown - Operation string // the provider's main call that takes a model name - // Keep says whether a model name belongs to this source: the operations - // above take text models, not image, audio or embedding ones. - Keep func(name string) bool -} - -// Retirement is one model name the provider stops serving on Date, with the -// replacement it names. An alias gets its own Retirement, with the row it -// came from. -type Retirement struct { - Model string - Date string // YYYY-MM-DD - Replacement string // the replacement cell, as written ("`gpt-5.6-sol` (`reasoning.mode: pro`)") - Via []string - Excerpt string // the section heading, the table header and the row -} - +// Deprecated: the functions and values live in github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire. var ( - dateHeader = regexp.MustCompile(`(?i)^(shutdown|retirement) date$`) - ticked = regexp.MustCompile("`([^`]+)`") + Events = moved.Events + First = moved.First + Parse = moved.Parse + Anthropic = moved.Anthropic + OpenAI = moved.OpenAI ) - -var dateLayouts = []string{"January 2, 2006", "Jan 2, 2006", "2006-01-02"} - -// Parse reads every retirement table on the page. A model listed more than -// once keeps its first row: both pages list the most recent announcement -// first, and a later one supersedes an earlier date, including a later row -// that withdraws the date ("To be announced"). A replacement that is -// itself retired is followed to the model that replaces it, so a hint never -// points at a model that no longer works. -func Parse(page []byte, keep func(string) bool) ([]Retirement, error) { - lines := strings.Split(strings.ReplaceAll(string(page), "\r\n", "\n"), "\n") - var out []Retirement - seen := map[string]bool{} - heading := "" - for i := 0; i < len(lines); i++ { - line := strings.TrimSpace(lines[i]) - if strings.HasPrefix(line, "#") { - heading = line - continue - } - header := cells(line) - if len(header) < 3 || !dateHeader.MatchString(header[0]) { - continue - } - model, repl := column(header, "model"), column(header, "replacement", "substitute") - if model < 0 || repl < 0 { - continue // an endpoint ("System") or a training-price table: no model to replace - } - i++ // the |---| row - for i+1 < len(lines) && strings.HasPrefix(strings.TrimSpace(lines[i+1]), "|") { - i++ - row := strings.TrimSpace(lines[i]) - c := cells(row) - if len(c) <= model || len(c) <= repl { - return nil, fmt.Errorf("a short row under %q: %s", heading, row) - } - names := ticked.FindAllStringSubmatch(c[model], -1) - date, err := parseDate(c[0]) - if err != nil { - // "To be announced": not a retirement yet, and the newer word on - // these names, so an older row's date for them doesn't count. - for _, m := range names { - seen[m[1]] = true - } - continue - } - excerpt := strings.Join([]string{heading, strings.TrimSpace(lines[headerLine(lines, i)]), row}, "\n") - for _, m := range names { - name := m[1] - if seen[name] || !keep(name) { - continue - } - seen[name] = true - out = append(out, Retirement{Model: name, Date: date, Replacement: c[repl], Excerpt: excerpt}) - } - } - } - if len(out) == 0 { - return nil, fmt.Errorf("no retirement tables found: the page's shape may have changed") - } - follow(out) - return out, nil -} - -// headerLine walks back from a row to its table's header. -func headerLine(lines []string, i int) int { - for i > 0 && strings.HasPrefix(strings.TrimSpace(lines[i-1]), "|") { - i-- - } - return i -} - -// follow replaces a replacement that is itself retired with its own -// replacement, recording the hops: gpt-3.5-turbo-0613's named replacement is -// gpt-3.5-turbo, which shuts down on 2026-10-23 for gpt-5.6-terra. -func follow(rs []Retirement) { - by := map[string]Retirement{} - for _, r := range rs { - by[r.Model] = r - } - for i := range rs { - for hops := 0; hops < 10; hops++ { - next, ok := by[First(rs[i].Replacement)] - if !ok || next.Model == rs[i].Model { - break - } - rs[i].Via = append(rs[i].Via, next.Model) - rs[i].Replacement = next.Replacement - } - } -} - -// First is the first model name a replacement cell gives, "" when it names -// none ("The most capable cyber model available to you."). -func First(replacement string) string { - if m := ticked.FindStringSubmatch(replacement); m != nil { - return m[1] - } - return "" -} - -// cells splits a markdown table row on its unescaped pipes. A cell can hold -// an escaped one: "`gpt-4-0613` \| `gpt-4`". -func cells(row string) []string { - if !strings.HasPrefix(row, "|") { - return nil - } - row = strings.Trim(row, "|") - var out []string - var cur strings.Builder - for i := 0; i < len(row); i++ { - if row[i] == '\\' && i+1 < len(row) && row[i+1] == '|' { - cur.WriteString(`\|`) - i++ - continue - } - if row[i] == '|' { - out = append(out, strings.TrimSpace(cur.String())) - cur.Reset() - continue - } - cur.WriteByte(row[i]) - } - return append(out, strings.TrimSpace(cur.String())) -} - -func column(header []string, words ...string) int { - for i, h := range header { - for _, w := range words { - if strings.Contains(strings.ToLower(h), w) { - return i - } - } - } - return -1 -} - -func parseDate(s string) (string, error) { - for _, layout := range dateLayouts { - if t, err := time.Parse(layout, strings.TrimSpace(s)); err == nil { - return t.Format("2006-01-02"), nil - } - } - return "", fmt.Errorf("not a date: %q", s) -} - -// Events turns retirements into change events, one per model name: the -// `model` parameter can no longer take that name, in any of the provider's -// calls. affected.operation is the provider's main one; the patch-it client -// looks for the name wherever it reaches the provider's SDK, so one event per -// name gives one fix per repo, not one per operation for the same line. -// version is the shutdown date, so a provider moving the date is a new event. -// sourceURL is the snapshot the retirements were read from. -func Events(p Page, rs []Retirement, sourceURL string, now time.Time) ([]event.ChangeEvent, []error) { - var events []event.ChangeEvent - var errs []error - for _, r := range rs { - affected := event.Affected{ - Kind: event.AffectedKindRequestParameter, - Side: event.SideRequest, - Operation: p.Operation, - Property: "model", - Value: r.Model, - } - e := event.ChangeEvent{ - Fingerprint: event.Fingerprint(p.API, r.Date, event.ChangeTypeBreaking, affected, r.Model), - API: p.API, - Version: r.Date, - ChangeType: event.ChangeTypeBreaking, - Breaking: true, - Affected: affected, - Description: fmt.Sprintf("Model %q is shut down on %s: %s requests naming it fail from that date.", r.Model, r.Date, p.Vendor), - MigrationHint: hint(p.Vendor, r), - SourceURL: sourceURL, - SourceExcerpt: r.Excerpt, - Confidence: 1.0, - DetectedAt: now, - } - if err := e.Validate(); err != nil { - errs = append(errs, fmt.Errorf("%s %s: %w", p.API, r.Model, err)) - continue - } - events = append(events, e) - } - return events, errs -} - -func hint(vendor string, r Retirement) string { - repl := strings.TrimSpace(r.Replacement) - if First(repl) == "" { - return fmt.Sprintf("%s names no replacement model: %s", vendor, repl) - } - h := fmt.Sprintf("Use %s instead: %s's recommended replacement.", repl, vendor) - if len(r.Via) > 0 { - h += fmt.Sprintf(" (%s first named %s, which is itself retired.)", vendor, strings.Join(r.Via, ", then ")) - } - return h -} diff --git a/plugins/retirements/retirements.go b/plugins/retirements/retirements.go index d4d200a..6e4ff50 100644 --- a/plugins/retirements/retirements.go +++ b/plugins/retirements/retirements.go @@ -1,92 +1,13 @@ -// 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 is the old import path of the notices kind for a +// model provider's deprecations page, kept so code that imports it still +// builds. +// +// Deprecated: use plugins/notices: notices.Plugin{Page: retire.OpenAI}. This +// package only forwards there and registers nothing; it goes once nothing +// imports it. package retirements -import ( - "context" - "fmt" - "log" +import "github.com/patch-it-dev/patch-it-plugins/plugins/notices" - "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 -} +// Plugin is notices.Plugin: set Page and Archiver, as before. +type Plugin = notices.Plugin diff --git a/plugins/retirements/retirements_test.go b/plugins/retirements/retirements_test.go index fe89d4d..80e9b99 100644 --- a/plugins/retirements/retirements_test.go +++ b/plugins/retirements/retirements_test.go @@ -1,133 +1,17 @@ package retirements import ( - "context" - "fmt" - "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/plugins/retirements/retire" ) -const deprecations = `### 2026-04-22: Legacy GPT model snapshots - -| Shutdown date | Model snapshot | Substitute model | -| ---------------- | -------------------------- | ---------------- | -| October 23, 2026 | ` + "`gpt-4-0613` \\| `gpt-4`" + ` | ` + "`gpt-5.6-sol`" + ` | -` - -// fakeArchive is the Wayback Machine without the network: it serves what it -// was given and counts the snapshots it was asked for. -type fakeArchive struct { - content string - err error - calls *int -} - -func (f fakeArchive) Snapshot(_ context.Context, page string) (string, []byte, error) { - *f.calls++ - if f.err != nil { - return "", nil, f.err - } - return "https://web.archive.org/web/20261013115538/" + page, []byte(f.content), nil -} - -// page is what the provider's page says now, and what the archive holds. -type page struct { - live string - archive fakeArchive -} - -var current page - -func withPage(t *testing.T, live string, archive fakeArchive) { - t.Helper() - current = page{live, archive} -} - -func openStore(*testing.T) *kittest.Mem { return kittest.NewMem() } - -// retirements runs OpenAI's plugin over the current page through the same core -// the command uses. -func retirements(ctx context.Context, s *kittest.Mem, p retire.Page) (bool, error) { - env := plugin.Env{ - Baselines: s, - Get: func(context.Context, string) ([]byte, error) { return []byte(current.live), nil }, - Now: time.Now, - } - return kittest.Run(ctx, env, s, Plugin{Page: p, Archiver: current.archive}) -} - -func TestRetirementsStoreOneEventPerModel(t *testing.T) { - ctx, s, calls := context.Background(), openStore(t), 0 - withPage(t, deprecations, fakeArchive{content: deprecations, calls: &calls}) - - if rejected, err := retirements(ctx, s, retire.OpenAI); err != nil || rejected { - t.Fatalf("rejected=%v err=%v", rejected, err) - } - events, err := s.All() - if err != nil { - t.Fatal(err) - } - got := map[string]bool{} - for _, e := range events { - got[e.Subject.Provider+" "+e.Version+" "+e.Subject.Name] = true - if !strings.HasPrefix(e.SourceURL, "https://web.archive.org/web/20261013115538/") { - t.Errorf("cites %s, want the snapshot", e.SourceURL) - } - } - if len(events) != 2 || !got["openai 2026-10-23 gpt-4-0613"] || !got["openai 2026-10-23 gpt-4"] { - t.Errorf("want one event per model name, got %v", got) - } - - // Same page again: no snapshot, nothing new. - if _, err := retirements(ctx, s, retire.OpenAI); err != nil { - t.Fatal(err) - } - if calls != 1 { - t.Errorf("%d snapshots for an unchanged page, want 1", calls) - } - if again, _ := s.All(); len(again) != 2 { - t.Errorf("%d events after a rerun, want 2", len(again)) - } -} - -func TestRetirementsStoreNothingWithoutASnapshotThatHoldsThem(t *testing.T) { - for name, archive := range map[string]fakeArchive{ - "the archive refused": {err: fmt.Errorf("429 too many requests")}, - "the page moved since": {content: strings.Replace(deprecations, "October 23", "November 23", 1)}, - } { - ctx, s, calls := context.Background(), openStore(t), 0 - archive.calls = &calls - withPage(t, deprecations, archive) - if _, err := retirements(ctx, s, retire.OpenAI); err == nil { - t.Errorf("%s: want an error", name) - } - if events, _ := s.All(); len(events) != 0 { - t.Errorf("%s: stored %d events with nothing to cite", name, len(events)) - } - if last, _ := s.LastSpec(retire.OpenAI.API); last != nil { - t.Errorf("%s: the page was saved, so the next run would skip it", name) - } - } -} - -// A renamed column hides a table: the run must fail, not store a shorter list. -func TestRetirementsRefuseAPageThatLostMostOfItsTables(t *testing.T) { - ctx, s, calls := context.Background(), openStore(t), 0 - withPage(t, deprecations, fakeArchive{content: deprecations, calls: &calls}) - if _, err := retirements(ctx, s, retire.OpenAI); err != nil { - t.Fatal(err) - } - renamed := strings.Replace(deprecations, "Substitute model", "Successor", 1) + strings.Replace(strings.Replace(deprecations, "gpt-4-0613` \\| `gpt-4", "gpt-4o-old", 1), "Substitute model", "Recommended replacement", 1) - withPage(t, renamed, fakeArchive{content: renamed, calls: &calls}) - if _, err := retirements(ctx, s, retire.OpenAI); err == nil || !strings.Contains(err.Error(), "shape may have changed") { - t.Fatalf("want the shape error, got %v", err) - } - if events, _ := s.All(); len(events) != 2 { - t.Errorf("%d events, want only the first run's 2", len(events)) +// Code written against the old paths still builds and runs the same source. +func TestTheOldPathStillWorks(t *testing.T) { + p := Plugin{Page: retire.OpenAI} + kittest.Registered(t, p) + if p.Name() != "openai-models" { + t.Errorf("Plugin{Page: retire.OpenAI} is %q", p.Name()) } } 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/anthropic-models.md b/providers/anthropic-models.md index 77b50db..d13782e 100644 --- a/providers/anthropic-models.md +++ b/providers/anthropic-models.md @@ -4,7 +4,7 @@ Claude models that are retired or have a retirement date on the Claude API, with the replacement Anthropic recommends. One breaking event per model name. -Format plugin: `retirements` (`plugins/retirements`), reading with `plugins/retirements/retire/`. +Kind: `notices` (`plugins/notices`), reading with the deprecations-page reader, `plugins/notices/retire/`. ## Why this source diff --git a/providers/cloudflare.md b/providers/cloudflare.md index e70607f..9a91803 100644 --- a/providers/cloudflare.md +++ b/providers/cloudflare.md @@ -4,7 +4,7 @@ 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/github-actions.md b/providers/github-actions.md index 3fa321f..c9adb20 100644 --- a/providers/github-actions.md +++ b/providers/github-actions.md @@ -4,7 +4,7 @@ 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/openai-models.md b/providers/openai-models.md index ae73355..9ddceb7 100644 --- a/providers/openai-models.md +++ b/providers/openai-models.md @@ -4,7 +4,7 @@ OpenAI models that are being shut down: every text model name code sends to the Chat Completions or Responses API, with its shutdown date and the replacement OpenAI recommends. One breaking event per model name. -Format plugin: `retirements` (`plugins/retirements`), reading with `plugins/retirements/retire/`. +Kind: `notices` (`plugins/notices`), reading with the deprecations-page reader, `plugins/notices/retire/`. ## Why this source diff --git a/providers/salesforce.md b/providers/salesforce.md index 1396a1b..0d27ada 100644 --- a/providers/salesforce.md +++ b/providers/salesforce.md @@ -4,7 +4,7 @@ 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/vertex-ai-models.md b/providers/vertex-ai-models.md index d167ad0..eb00d3c 100644 --- a/providers/vertex-ai-models.md +++ b/providers/vertex-ai-models.md @@ -4,7 +4,7 @@ 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 index e519a3e..ff9477b 100644 --- a/retire/retire.go +++ b/retire/retire.go @@ -1,19 +1,19 @@ -// Package retire is the old import path of github.com/patch-it-dev/patch-it-plugins/plugins/retirements/retire. +// Package retire is the old import path of github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire. // -// Deprecated: import github.com/patch-it-dev/patch-it-plugins/plugins/retirements/retire +// Deprecated: import github.com/patch-it-dev/patch-it-plugins/plugins/notices/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" +import moved "github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire" -// Deprecated: the types live in 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/notices/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. +// Deprecated: the functions and values live in github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire. var ( Events = moved.Events First = moved.First From d502df1551613f71f2c788009bf7a9abfce5cab9 Mon Sep 17 00:00:00 2001 From: adssib <75389300+adssib@users.noreply.github.com> Date: Fri, 20 Nov 2026 17:58:40 -0500 Subject: [PATCH 04/16] list every version: six more spec adapters and living pages by capture GitHub, GitLab, Elasticsearch, Sentry, Algolia and Appwrite list every version of their spec, tested on recorded responses. versions.WaybackCaptures lists a living page's distinct Web Archive captures (CDX), and the notices kind reads and extracts them pair by pair, so a page's history can be backfilled by date. Co-Authored-By: Claude Opus 5.5 Signed-off-by: adssib <75389300+adssib@users.noreply.github.com> --- AGENTS.md | 2 +- core/versions/versions.go | 68 ++- core/versions/versions_test.go | 49 ++ docs/how-it-works.md | 4 +- docs/writing-a-plugin.md | 4 +- plugins/notices/notices.go | 66 +++ plugins/notices/versions_test.go | 110 ++++ plugins/openapi/adapter/algolia.go | 36 +- plugins/openapi/adapter/elasticsearch.go | 34 +- plugins/openapi/adapter/testdata/README.md | 18 + ...-commit-released-2024-09-18-45edcd844.json | 8 + ...-commit-released-2024-09-18-cc190fae3.json | 8 + ...-commit-released-2024-09-19-6e91dbf55.json | 8 + ...-commit-released-2024-09-19-a62c27d3b.json | 8 + ...-commit-released-2024-09-19-e47df6533.json | 8 + .../testdata/versions/algolia-refs.json | 29 + .../testdata/versions/appwrite-commits.json | 42 ++ .../testdata/versions/es-branches.json | 101 ++++ .../testdata/versions/es-releases.json | 502 ++++++++++++++++++ .../testdata/versions/github-versions.json | 1 + .../testdata/versions/gitlab-tags-1.json | 102 ++++ .../testdata/versions/gitlab-tags-2.json | 86 +++ .../versions/sentry-api-releases.json | 382 +++++++++++++ .../versions/sentry-schema-releases.json | 14 + plugins/openapi/adapter/versions.go | 206 ++++++- plugins/openapi/adapter/versions_test.go | 169 ++++++ 26 files changed, 2031 insertions(+), 34 deletions(-) create mode 100644 plugins/notices/versions_test.go create mode 100644 plugins/openapi/adapter/testdata/README.md create mode 100644 plugins/openapi/adapter/testdata/versions/algolia-commit-released-2024-09-18-45edcd844.json create mode 100644 plugins/openapi/adapter/testdata/versions/algolia-commit-released-2024-09-18-cc190fae3.json create mode 100644 plugins/openapi/adapter/testdata/versions/algolia-commit-released-2024-09-19-6e91dbf55.json create mode 100644 plugins/openapi/adapter/testdata/versions/algolia-commit-released-2024-09-19-a62c27d3b.json create mode 100644 plugins/openapi/adapter/testdata/versions/algolia-commit-released-2024-09-19-e47df6533.json create mode 100644 plugins/openapi/adapter/testdata/versions/algolia-refs.json create mode 100644 plugins/openapi/adapter/testdata/versions/appwrite-commits.json create mode 100644 plugins/openapi/adapter/testdata/versions/es-branches.json create mode 100644 plugins/openapi/adapter/testdata/versions/es-releases.json create mode 100644 plugins/openapi/adapter/testdata/versions/github-versions.json create mode 100644 plugins/openapi/adapter/testdata/versions/gitlab-tags-1.json create mode 100644 plugins/openapi/adapter/testdata/versions/gitlab-tags-2.json create mode 100644 plugins/openapi/adapter/testdata/versions/sentry-api-releases.json create mode 100644 plugins/openapi/adapter/testdata/versions/sentry-schema-releases.json create mode 100644 plugins/openapi/adapter/versions_test.go diff --git a/AGENTS.md b/AGENTS.md index 2292472..5b6ef22 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -52,7 +52,7 @@ 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/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/ core/migrate/ the change-event types from patch-it's contract (v1 + v2), v1 -> v2 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 9bacfff..eee82d1 100644 --- a/docs/how-it-works.md +++ b/docs/how-it-works.md @@ -4,7 +4,7 @@ A **provider** (Stripe, OpenAI, GitHub…) has one category and one or more **so ## 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,7 +20,7 @@ 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 | +| [`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; `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/), [`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) | diff --git a/docs/writing-a-plugin.md b/docs/writing-a-plugin.md index b27dd55..6be55f3 100644 --- a/docs/writing-a-plugin.md +++ b/docs/writing-a-plugin.md @@ -117,12 +117,12 @@ 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. -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. +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. ### Register the provider and its source diff --git a/plugins/notices/notices.go b/plugins/notices/notices.go index cfdea5f..56c051a 100644 --- a/plugins/notices/notices.go +++ b/plugins/notices/notices.go @@ -14,6 +14,7 @@ package notices import ( + "cmp" "context" "errors" "fmt" @@ -25,6 +26,7 @@ import ( "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/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" @@ -199,3 +201,67 @@ func (p Plugin) fetch(ctx context.Context, env plugin.Env, pageURL string) (body } 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 v2 events citing it. +func (p Plugin) events(s plugin.Snapshot, now time.Time) ([]event.EventV2, []error, error) { + found, err := p.Page.Find(s.Content) + if err != nil { + return nil, nil, fmt.Errorf("reading %s: %w", s.SourceURL, err) + } + v1, v2, rejected := p.Page.Events(found, s.SourceURL, now) + converted, invalid := migrate.Fresh(v1) + return append(converted, v2...), append(rejected, invalid...), nil +} + +var _ plugin.Versioned = Plugin{} 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/algolia.go b/plugins/openapi/adapter/algolia.go index 37a70d0..2628fb8 100644 --- a/plugins/openapi/adapter/algolia.go +++ b/plugins/openapi/adapter/algolia.go @@ -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/elasticsearch.go b/plugins/openapi/adapter/elasticsearch.go index e14b571..9bd8aaf 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" @@ -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/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/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]) + } + } +} From 04190eb07b357a646fb8d82f3e7d825b2d58726b Mon Sep 17 00:00:00 2001 From: adssib <75389300+adssib@users.noreply.github.com> Date: Fri, 20 Nov 2026 17:59:59 -0500 Subject: [PATCH 05/16] registry: packages, first name and aliases per source Each source lists the packages it covers (ecosystem:name) and plugin.ForPackage finds a package's sources; the list prints them with each source's first name and aliases, for the contract switch to source ids. Co-Authored-By: Claude Opus 5.5 Signed-off-by: adssib <75389300+adssib@users.noreply.github.com> --- AGENTS.md | 2 +- core/plugin/provider.go | 36 +++++++++++++++++ core/plugin/provider_test.go | 19 +++++++++ docs/plugins.schema.json | 5 ++- docs/writing-a-plugin.md | 5 ++- internal/pluginlist/pluginlist.go | 23 ++++++----- plugins/changelog/changelog.go | 14 ++++--- plugins/migrationguide/migrationguide.go | 28 ++++++++------ plugins/notices/notices.go | 21 +++++----- plugins/openapi/openapi.go | 49 ++++++++++++++---------- 10 files changed, 142 insertions(+), 60 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 5b6ef22..565d096 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. diff --git a/core/plugin/provider.go b/core/plugin/provider.go index 4a02323..9d6cd7d 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,6 +108,13 @@ 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 + // 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 old slug ("algolia-search"): // what `--api` selects and every event's `api` carries until patch-it's // change-event contract switches to source ids. @@ -212,6 +224,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 @@ -279,6 +297,24 @@ func Sources() []SourceInfo { return out } +// Aliases are the other names a source answers to (Lookup, LookupSource): +// today its first name, the old slug ("algolia-search"), which events carry +// in `api` and fingerprints hash. +func (s SourceInfo) Aliases() []string { return []string{s.Alias()} } + +// 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 full id ("algolia/search-api") or its // old slug ("algolia-search"). func LookupSource(id string) (SourceInfo, bool) { diff --git a/core/plugin/provider_test.go b/core/plugin/provider_test.go index cc2bdf6..6d42186 100644 --- a/core/plugin/provider_test.go +++ b/core/plugin/provider_test.go @@ -59,6 +59,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" @@ -95,3 +100,17 @@ func TestMergedKindsKeepWorking(t *testing.T) { t.Errorf("CanonicalKind(openapi) = %q", got) } } + +// A package names its sources, and a source answers to its first name. +func TestForPackage(t *testing.T) { + s := src("pkg", "acme-test-pkg") + 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" || strings.Join(got[0].Aliases(), ",") != "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/docs/plugins.schema.json b/docs/plugins.schema.json index d59ddc8..d935a39 100644 --- a/docs/plugins.schema.json +++ b/docs/plugins.schema.json @@ -32,11 +32,14 @@ "type": "array", "items": { "type": "object", - "required": ["id", "alias", "kind", "layer", "watches", "urls", "page"], + "required": ["id", "alias", "first_name", "aliases", "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." }, + "first_name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9.-]*$", "description": "The source's first name, its old slug: what fingerprints keep hashing after the contract switches to source ids." }, + "aliases": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9.-]*$" }, "description": "Every other name the source answers to." }, + "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"] }, "layer": { "type": "string", "enum": ["api", "sdk", "package", "runtime", "ci", "ai-models", "infra"] }, "watches": { "type": "string", "minLength": 1 }, diff --git a/docs/writing-a-plugin.md b/docs/writing-a-plugin.md index 6be55f3..ca73552 100644 --- a/docs/writing-a-plugin.md +++ b/docs/writing-a-plugin.md @@ -136,13 +136,16 @@ 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 `provider/source` or by its old slug (its first name, which events carry in `api` and fingerprints hash). + +`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/` diff --git a/internal/pluginlist/pluginlist.go b/internal/pluginlist/pluginlist.go index e9a9aa8..d4bb2e5 100644 --- a/internal/pluginlist/pluginlist.go +++ b/internal/pluginlist/pluginlist.go @@ -38,13 +38,16 @@ 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 + Alias string `json:"alias"` // the old slug: --api and every event's api until the contract switches to source ids + FirstName string `json:"first_name"` // the same old slug, by the name fingerprints keep hashing after the switch + Aliases []string `json:"aliases"` // every other name the source answers to + 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 +67,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(), Alias: info.Alias(), FirstName: info.Alias(), Aliases: info.Aliases(), + 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/plugins/changelog/changelog.go b/plugins/changelog/changelog.go index ff3f790..bfbc293 100644 --- a/plugins/changelog/changelog.go +++ b/plugins/changelog/changelog.go @@ -34,18 +34,20 @@ 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{ diff --git a/plugins/migrationguide/migrationguide.go b/plugins/migrationguide/migrationguide.go index d0ba2fd..15e8fa6 100644 --- a/plugins/migrationguide/migrationguide.go +++ b/plugins/migrationguide/migrationguide.go @@ -28,36 +28,40 @@ 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"}, - Plugin: Plugin{Guide: members.NumPy2}, + 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"}, - Plugin: Plugin{Guide: members.PostHog8}, + 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"}, - Plugin: Plugin{Guide: members.NewRelic11}, + 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}, }}, }) } diff --git a/plugins/notices/notices.go b/plugins/notices/notices.go index 56c051a..03f160c 100644 --- a/plugins/notices/notices.go +++ b/plugins/notices/notices.go @@ -37,18 +37,20 @@ func init() { 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{}}, + 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"}, - Plugin: Plugin{Page: retire.Anthropic, Archiver: kit.Wayback{}}, + 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{ @@ -73,9 +75,10 @@ func init() { 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{Page: feed.CloudflareAPI, Archiver: kit.Wayback{}}, + 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{ diff --git a/plugins/openapi/openapi.go b/plugins/openapi/openapi.go index 61eeda4..65d686f 100644 --- a/plugins/openapi/openapi.go +++ b/plugins/openapi/openapi.go @@ -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 @@ -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 From ab212be8943506958afeb0bb0eb1361b5ea7820b Mon Sep 17 00:00:00 2001 From: adssib <75389300+adssib@users.noreply.github.com> Date: Fri, 20 Nov 2026 18:07:18 -0500 Subject: [PATCH 06/16] add the apisurface kind: a package's public API between releases Python first: every release on PyPI, its wheel (or sdist) read in memory as text by pysurface (no import, no execution, no new dependency), and consecutive surfaces compared into removed and renamed symbols, removed parameters and parameters that lost their default. Registers openai/python-sdk, with a golden over two trimmed real wheels. Co-Authored-By: Claude Opus 5.5 Signed-off-by: adssib <75389300+adssib@users.noreply.github.com> --- AGENTS.md | 2 +- docs/how-it-works.md | 2 +- docs/plugins.schema.json | 2 +- docs/writing-a-plugin.md | 7 + plugins/all/all.go | 1 + plugins/apisurface/apisurface.go | 349 +++++++++++++ plugins/apisurface/apisurface_test.go | 179 +++++++ plugins/apisurface/artifact.go | 187 +++++++ plugins/apisurface/pysurface/lines.go | 170 ++++++ plugins/apisurface/pysurface/pysurface.go | 485 ++++++++++++++++++ .../apisurface/pysurface/pysurface_test.go | 117 +++++ plugins/apisurface/testdata/README.md | 10 + .../testdata/golden/openai-1.1.2.json | 50 ++ .../openai-1.1.1-py3-none-any.trimmed.whl | Bin 0 -> 41474 bytes .../openai-1.1.2-py3-none-any.trimmed.whl | Bin 0 -> 41470 bytes .../testdata/pypi-openai-1.1.1.json | 20 + .../testdata/pypi-openai-1.1.2.json | 20 + .../testdata/pypi-openai-excerpt.json | 63 +++ providers/openai-python-sdk.md | 32 ++ 19 files changed, 1693 insertions(+), 3 deletions(-) create mode 100644 plugins/apisurface/apisurface.go create mode 100644 plugins/apisurface/apisurface_test.go create mode 100644 plugins/apisurface/artifact.go create mode 100644 plugins/apisurface/pysurface/lines.go create mode 100644 plugins/apisurface/pysurface/pysurface.go create mode 100644 plugins/apisurface/pysurface/pysurface_test.go create mode 100644 plugins/apisurface/testdata/README.md create mode 100644 plugins/apisurface/testdata/golden/openai-1.1.2.json create mode 100644 plugins/apisurface/testdata/openai-1.1.1-py3-none-any.trimmed.whl create mode 100644 plugins/apisurface/testdata/openai-1.1.2-py3-none-any.trimmed.whl create mode 100644 plugins/apisurface/testdata/pypi-openai-1.1.1.json create mode 100644 plugins/apisurface/testdata/pypi-openai-1.1.2.json create mode 100644 plugins/apisurface/testdata/pypi-openai-excerpt.json create mode 100644 providers/openai-python-sdk.md diff --git a/AGENTS.md b/AGENTS.md index 565d096..c37e6bc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -59,7 +59,7 @@ core/event/ core/migrate/ the change-event types from patch-it's contract ( 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), notices (+ retire/, feed/, eol/), migrationguide (+ sdkguide/, - members/), changelog (Markdown, RST or JSON), catalog; + members/), changelog (Markdown, RST or JSON), catalog, apisurface (+ pysurface/); plugins/all imports every one plugins/removedmembers/ apichangelog/ retirements/ feed/ eol/ deprecated: merged into migrationguide, changelog and notices, they only forward there diff --git a/docs/how-it-works.md b/docs/how-it-works.md index eee82d1..642e17b 100644 --- a/docs/how-it-works.md +++ b/docs/how-it-works.md @@ -21,7 +21,7 @@ There's no list in this repo: `make plugins` prints every provider and source fr |---|---| | [`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, a page's Web Archive captures (all, or the one at a date) | -| [`plugins/`](../plugins/) | One package per kind, with its providers; `plugins/all` imports every one | +| [`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/), [`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/), [`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 | diff --git a/docs/plugins.schema.json b/docs/plugins.schema.json index d935a39..c5af222 100644 --- a/docs/plugins.schema.json +++ b/docs/plugins.schema.json @@ -40,7 +40,7 @@ "first_name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9.-]*$", "description": "The source's first name, its old slug: what fingerprints keep hashing after the contract switches to source ids." }, "aliases": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9.-]*$" }, "description": "Every other name the source answers to." }, "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"] }, + "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/writing-a-plugin.md b/docs/writing-a-plugin.md index ca73552..62de359 100644 --- a/docs/writing-a-plugin.md +++ b/docs/writing-a-plugin.md @@ -80,6 +80,7 @@ Write the numbers on the provider page, as `providers/vercel.md` does for its sp | `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/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 @@ -124,6 +125,12 @@ Extract(ctx, env, from, to Snapshot) (Result, error) // the changes fro 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. +### 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 In the kind's package `init`, with the metadata ([AGENTS.md](../AGENTS.md) rule 1): diff --git a/plugins/all/all.go b/plugins/all/all.go index 834349d..051a892 100644 --- a/plugins/all/all.go +++ b/plugins/all/all.go @@ -4,6 +4,7 @@ package all import ( + _ "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/migrationguide" diff --git a/plugins/apisurface/apisurface.go b/plugins/apisurface/apisurface.go new file mode 100644 index 0000000..b300ebf --- /dev/null +++ b/plugins/apisurface/apisurface.go @@ -0,0 +1,349 @@ +// 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 { + Name string // on the registry, and the events' api: "openai" + Ecosystem string // "pypi" + Module string // the top-level import name: "openai" +} + +// OpenAIPython is the openai package on PyPI. +var OpenAIPython = Package{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.Name } + +// 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.Name) + 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.Name, v.ID, v.Ref, to.SourceURL, to.Content, false, 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) + } +} + +// snapshot is what ReadAt keeps of a release: its public surface, and +// what couldn't be read. +type snapshot struct { + Artifact string `json:"artifact"` + Surface pysurface.Surface `json:"surface"` + 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(snapshot{Artifact: a.Filename, Surface: pysurface.Read(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 snapshot + 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.EventV2 + var rejected []error + for _, c := range Compare(a.Surface, b.Surface) { + 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.FingerprintV2(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.EventV2 { + 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.EventV2{ + API: pkg.Name, + 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; anything less sure +// is a removal. +func Compare(a, b pysurface.Surface) []Change { + 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(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] + 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 +} + +// 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..5723fa8 --- /dev/null +++ b/plugins/apisurface/apisurface_test.go @@ -0,0 +1,179 @@ +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.EventV2 { + 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(a, 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")) + } +} + +// 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..9a84a43 --- /dev/null +++ b/plugins/apisurface/pysurface/pysurface.go @@ -0,0 +1,485 @@ +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 +} + +// 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 *" +} + +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+`) +) + +// 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 { + 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 + } + 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 +} + +// 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{}} + 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, ":") + 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) + } + 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..b8402ca --- /dev/null +++ b/plugins/apisurface/pysurface/pysurface_test.go @@ -0,0 +1,117 @@ +package pysurface + +import ( + "encoding/json" + "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) + } +} 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..903bdff --- /dev/null +++ b/plugins/apisurface/testdata/golden/openai-1.1.2.json @@ -0,0 +1,50 @@ +[ + { + "id": 0, + "fingerprint": "sha256:9e40f3b8a0940e9ffbdd4aca7642c5bfd240930d6ed176767a90b0a44de567b2", + "api": "openai", + "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:a709e97cddd82b737c84fe4ec727bc040aff0ece129f5517f30da8925b3fcdd9", + "api": "openai", + "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 0000000000000000000000000000000000000000..8b93cc652291a0d230b3cb7f6bc8148d6ae43445 GIT binary patch literal 41474 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 literal 0 HcmV?d00001 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 0000000000000000000000000000000000000000..966486be25e98b2130ade9a58ce86b8b5b2a5f31 GIT binary patch literal 41470 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
    j(3v8EE8nG=* zje*pRozWn*!rqxBLls$y=T38L~?~*6+6OOsP_6<#eyh)+p@O)IY1po_W6?Ia~G`zF06#;P@|1Ie;g%3ebKC z3-bu!dOlcz>0Nq;?OI_b##=^<;~>5k3P->o%AHYuK7L+yHRGEwXUqsb)v2eV%#Y-r z(}OxtEg3(F0Zp-(bGSeWsa6_RbZkN(3f-Z#P0Fl*0Aa3*B5Hh*-<{^2q#?cDZ6Hl3 zsYo&#JA8E$L6_vFgL31~pK^SX`bG?$Ac11a)LaCSp4Fk!eATz(mqUApEHe#=h@T7Y z9U?IF=x`~?F8=W@`fVRJYUh3S5j17t1%f3O)?t~CO zy@H}=di~xSuXEl7LGYZ#y$pQYCclkNv;A1rf}KsO4eMXoG86jipOIoaKQUn|Y!F{Z z5zwRpJW}Ad9KRMVUk680c&#LgRXtl2?_D#h>A%FRuLjz5NPllV)Cy8d2uoaWLCZyR zt)=%*T_#>}7in|*DuE!S6bB$V9VKjObpMu6&}G}q_l45B%3aq(Gsd@@jX4g&S?nlx z2JTYcMHa9GINhCGWhcifK_0h6no*%^s<@G{wZ0CAjW#)!odPH<#NKbD^bvGnjC~OUJ zkZZP~2w#pidKXGgoY|t9-tsf;yUiFga^QaYrCVom*C0k0t-t?#T@QEq`Gr|Xuz~EO z@&3ccD{Yubj&9#>TNa2d;jv=N$a3B0VS*Z1rthd_`7Gj{Y)Uwi+m42rv_v@(ScltE ze*v4AdEmhwy^^vco7H-VzT;^u*~fuv9LN~#C~+kGss)YFLa-_eR;pXw#%Y|XVLlkU zy6kDwEkK9$bYEU6RJ}z>7Tp%!eck7-EW)(emSmZrZdc^eoW~J4nBe-ouqF>wO0=t9 zk<&hFU$_NxAp{Wk3F39pz%_KhQUP}Kj>VnVI@h=VB`wf_BTCD$nDFL-iC2v*y!({9~O#XYa@&C6q z(*I8#`TvfT|Ak3?V<%HX7gK!)LnlL9=YP=5QQx)SWJBL0bf=aR)8Mab(e= z6HP_@!(N90`2A-#yNE>SvlZ=J4L=mM9h?0AZX> zB-N)3U%QFMUaTl#D#V!q;#<^t9fU_QySp7BW3b3mA_4ixW=EmXVP|J(>+t@VGadGg zR*d=~Y=JN(ezrFqsd(-yM0TJNG>sgqGYeh&7MeY8I!fj(rv80NK^=lMg)FZ`tRsVB zY3Klq)+(~`jBS!)2+`ru138FGBp-<}8TU1{4Veo0vP$R}iGdAc-caP8FQ3)j;ud9x zA5bEt5(t;$aFFxRt_(htvr}a<+a(9rlQ@Rl39q9Iw z^U{Y;+WiZlR*Ve;S#+x#fpU30u<0)z=Q2P-A*r}-p|B0wM(< zROc-^uVbYeSxh@@V9-+|lF)yWbwVuoLirs|!7jZ&q%UvcF=xt@Ay)tL8dV3YyIi=r z++EC)VK zZotjl)j9366i+#hsU?zFl(P`h(kz@(1*TM^k5E}`St(ooRETPod<}M<)jc`Cq&}!y zJ2Bn}WA3_G_1VFSTOY|uI~K8&J_cIjfUQ>z{f0LYo^c|)R^g4T>^6lHx~=r>u~j#< zw?f`npO;5NmkVxKvdlK4+_ctiVF_Qp_(f-y(TZ$kemV?MH{hB()PV&)gI5X)8Lnaw z8EdhAeZUFOf{kVNEv3Ma4t49z$Kv6QSLkxi@qGu`%vb5C8*r3S7?V5dGR-{3XEgRXH zA?jW#?gA&TUevs-9v)*7zy9>nkMttdFWnDrTU*WktT%#bvaHV(Fr3EKWf_7J!Y{ep zOh2{d33oJc%s_u434R?v>QKit1|nebcEKpBX&u?-h*Ds}UU zU1ABsy`3IA^A>x1VG77V<>n+w6b}D{{`oIzs5`dQS@(~1Fn|C6Wd9BGOiXP|T}(~> z(M~sZ8friQCgj#LN`c;M9h|~LK?DH>G)^?tmOVAarPYS$Y*X8RBe;EfYShH64OV7N zsrV|HN6-0!VVfDxJF0RKuA~g?l00`gbd1CZfG?i!6G2-VzJ!8Mw14iIlKLhX&h%^W z4`YjTuE)fx+}WKQK$Yv%$^lZP5h;?0?h-5`ta21I0Lzug9e<`gYBZ8V+nzMa^c~_4 zbc#mVkUsS?yHyiTnQACDc1&JR_kVep_kz4+@cnPSMgLe&_1~=7=ARb-Z^|zx&s%RY zAdKvOtK;lUf|V9~!yFYT0EPBJZEI7u(BvW8K8!EsY#jIQO1f<@LIroz#%m6pr;~`gqN78ytLgGN4nl|1c>K)q01QEWD?1z<-Pq79n# z5T`4FBKngY{jr;?7k&NX(7j&O-3C}J2ssd)q?~IrijcX`Fy?r{NgW@c>hU4GvG~EV zm+0AAGrl5(!$5_Dp?Fo!LAsrRgH8CyvoHef6I~8E0uL4W2e{94-(Sjs@fSVBdB_|c z3H^_#li)j^*ew~kHfkb!lquXmV%EZvHL$A2^{F1O6$7tj$Y9j7!iq`d{2U{83c5(p zrI6qvyJ=N+B^SRPTeB5QC_AZcSLnGp2XCdoC zV4LK5mSxY7UQBN;L5r@Zh)dng5K$_uTl=yTcbs4Euh}#Df96!f`AF@%{{jdY?!T7> zR|k{-A`6QDQx+wQXMxg0q+)`q8QI&RA{|9AX8I@O;WF6eyU4y%Z;O_1a9D=)B zaCdhI?(XjH?(QxjxO`8#d!{Fuce?xgao2)>&plPAPVHTLpZlD|1OQuckvzQSOp+AP zX)yC_S-XCs=S$L_HyOA7vLCOY-YN6@X?#|-e6ZYcVGr!HQM+AWYJsLEuX;G3iR<3K z7{Iq*2im$b?iqv~qhd(0Rrww0Suge~l_eFf#*(#Z%JiIjsOWa@AWe`iSfrl6H zS|&~NCJ&uorOw99loAYv)iN_8v|B;^Y`?J~4BESWj=id)tFmP(K36@^h2HEE?V92z z;CZ=7h}Xu$?dKqksF1T6F+5Ay^hJJr%;=zCn~5{K=N^ng6*Cblb4e+m(qM_K7b1XT=#gJW+E6a`E`dpBPrMW}ObO4X)TC>5NzpeQ zNw#!Ar(=5v12h02(;l#1TN8LRl|QmHoBfz@WsMPMie&o~UnQ2mKMmFqPDmOj|_}gZs0EutBmfA>>_8m(qFQlwMR~zBRkoglqy- z)k-uVcU`+Tn9JWCSl=ypd2?gMNIVXRgbX@iLkA&-qg8N-&8 z8XbEzbx7iM-`{pHvgo!(Efw$+KCnh?EBO=ZDo( z;TE<)Q2kbsabh&Co4svXtCNN-zX(S}wa#j6(mkh;ZsxDb)1CCLxAN^#Z_-=(w*ZJP z(iwOn6>*UCF+LT%L^5JuPf8#as`0?TA+|-~c7^2umUzui^U6I0W~iQz`97Sh7_`&< z_?aYw22wcn@BM{%-;4*w)$@1|?{?r<1v&s>5AFxqd)5)Ztf&v)C;*(YhJX{7;$NS(zmdL{QT)(742Z(_-2L9q8`%`TgcNSx3=N7aPa z&!3_;WBjE>>a;0C^05r!Qd#ol9Q#Mr%;+c1Q$m-S_cs9F7w@ttTN(c27`2uUp%h@RWX8DUq67ClK-DD5k;gx9c) z-(xcI^&UZ2K955PFuRBW%gjHrm72F5J^K6AE|?}1yOrPd*FogN*BUPN(ja_1B3Wb# zA}iqHx`Axc6`h+HR=?{BNh7#Tv90k^mXbEIXSogapuvAboWzIw5tP9RS!T_-NV1FY z`{JW0=G1Tk7Jm=$F#Ws5|Fz`*3&d;1$XfR>!1iB0qN+FpnVMgU;Z7kU7iPb55Y4$2 zOXlW_e{EfTxPvjWQG*XLC)L9EE zrk}$#dpbU?x*3jSIt_givtXVk|-($E_0`$LKDHof({NWPnb%BAbiAznQ`%as#^LIRZ9RaJmiX7>2RR zuC5;U@kK6NBetTm2m_j0dEr;wdy!rY?)*IzDFfYbEr1Z9146;_ABE!Y*h0t7$lk^p zV1@zg2BXMsGhlv1q03jaaW}@KS8p(cP*7kfB>Q-Vv5Q2e8BS&?XTEoy-2s%f?(kJ9PipuN8K{k(`^HQ0I^(K!%AEou<5AFAN!i|g%2WX&tWEl3Z& zcCUhtb1y5mQ^Y2U>KdTtv4W4W*Y4xczRqrDT^7(?60`@)c_ho>Z=>R+PeK@z6#arW z5IGM$-uub8bhePxOXXw|v+ViO*@TL{=+Wf7dS>-m-1F&=n!ur*di?-chZI1w$nYPn z#UGeMN#_^l@VYPj)RqJ%C4P@NB$y2f?St0Rs9>SaL%y;XSIAjE+V~4{Si*w4YZ8VK zufM(xCplL+<8KH1PeZ~p3^4GEA@PihvEMs)F>4%6UJ(w&h#r)dPzhUdl8Ga&qOY+8 zQRoKyV%qw+l*jxyJ6hUt=HF@aqU8Q0FR*46$f$uuC@I-oS*^iXf#}+27orc{Wse1B>xB6D4AEUIF-wUzr&3rOqf07{Ve@kE4vzH zLRZP^Gk!G>#Z7Fjy;gz&C7yj;_^iV2WgbF5uqw1p-(y}!@`TO()K>; zbPbMM+l8i`8vzrT_cmC4$CvBOqRU5c6~oy4{EYPrZtx13=YiP96<8NM>bs-8edf1l zy$L?jZw~>ZfjMKEw@X*$&FU0?{ezoa8|G?L1Z0mo;359YEHW_BbNHV#FT4>(Xm18s zu&MUKhph{|FQDXL2y!I_3Ps}LGu^8&9glFyk{{Rl@`jHER9p$Qs@Zl-HFYCoaOs_7 z1E^CXh+ZfM*4nB2gKt>mMfK5Twf$*5e&6KXIlQZNfW#&MOyF?-@+Uc%09ew$@dXOf zQF9Ei?T4yr`!&@3`NCB}F`v4Cpnx>;v}AIX7p2!M2?>;Un3&)3*_UBS+$1bJ@6U`o zeJ2-?xD>zpOMw@la`&-zuM2GNM$t!O%rInbWln>Oa@PB@fD1N<#`2r*PwRZG& z?XJ%<)WnI?WKDN(`y!l5kaob$*au~0wauQf@xtGTOk<*m4z$OH#*~|BL>5UHGcv7O z9khI)()cx1MHPD-ceX*CWncl{P)Xcn?d`*0lO0xGtfiISHcFxDxcSONQT+W?f{ZZ~ zXq4!wYG=LYGyH8hRQ(yRUs#$pgWP~guz-d<+U?uH`Fl~vvb<;s?fHtUU3GC% z$38{zx;LiJh4;*vqA*uN#tYc*!ESdIJyQVt@PQVfjb!{6!Tzr^RnN*$$Ij8}pVY~@ z+CQg?lCWiYO(q~p-Uz;csp9VEstidm!JI@A`ndJ|#Jv?2znA-o=x0jF(Deh%-srM@ zn}hMI@!cWb?q&(33r0~ATnROt3?DkUFKEe=JYT$N83O0Qt zztHd*1+c*jWtx+x&oq}?tQE*TdbWQn(8uU@H#+`lAoCSTSkFGjX&mEWkD>9bVB=An zqbEtkCc-OebZFD~ndVjv@IZvXO;2(iOYvIGF>qzagxyh6gLy{w zm{s}+ENUE+nI1N`Gd(AY$ec$B6rMzY4m&1AB}8#rJKvZQ1Rf%(kLx zb~sNgK+`-ff|XIY$hNFDWUe|RSRewnVpa?;|n3GxXc)NtANL z(Wb=zDQBL@&P`IIZT5PCW;SEpg^tuEj&;%5hALKkReASL;9xZ&C zH9)st17;NNB_IzB9zfWoA%Rj{6x34~&zw8?(h=MBPxxVq4_ul-vqaiSu0}7R)4p-P zxw$&2QqXTKC8}7ieAtC;1PWE2+5j8pj(I+_=M-Cg!#(178@O13K{Pw zno#haGu`}$?zdw#S13;w`wOmcd(e<1x88PLpimw!!l9l*0hP$`?#OsTWrR@4ehVotrdm72{r_Y9cqUT zg-zTggHok5W-ZD$(<%c;sGO^%IHo*#N@G_QhoREuyn70dEs9z8F!tT2hNqZBU8bhN zHFWE87q>NrgOVEtqrUXr#-wVqhEKO`G>HE6G<vKbOU+>hHGPw-Jl9&K05sX0BR_ZS+`qR(AsGoq&B=)bRbs5 z&8b^F)R8a9(gv0c!R@GQ+x{<@^G<@HkL{9evYVKiHZX5JeV{dXQ(xRg@Rg;PcyFB~ z>0wT-GkcKy<(|;cRHhUkUJp)Wn}{-ogmj3l7{XV)dp+wmIU~I5NpR2M#IpQQ_{`n?#ACI;Zws|v95i^hqo&+uG2DeD|OW5;?McR^kGK+e{F2eZNDbgJ8|d0xSWA|)J&U);P%f1~ zBc#HXk>8VY8vHp^zjzjz{dhn2RBFX97EGOZhI==j#{OgD0PPEoq>U`AtKp2Ci>i+~ zw})9#M^n4cRJ89a&;_QnB|yq6{#h;)gSIjA23KnS)1JN-%yKPWRKazk&PHZAJCjx80ox)Tev$#aE@FOyt$Mo5mhp-#`&7gCuUgAztMM% zU^M}=k$AW(F|q5_e_=y!w&@s2KSP!-_)+k zcDsL;qD7?gU{Tf-UN*MoPtcEzMFp**yDMdNFbGG(Gu4^LXy^3&QDfH7Km_g=<#ngs ztN}b+O6iG%#9Qt}+Y1-G#5VCcIawOq)!0;pr_VKRgxIsiQv@xWBuWmO=N7&He6Vi7 zXwv-_j!u*QQP2H@>ZmbBh;ubropc+2o{msKbXq13_kkM1{KCT_0i_3lChfWS-grh}y)65CPr-(4%v1qLRS-ZEN%F5!_Md|%<;d<| zgD0WO$G;7p5dJZEY7e1VwVM0;;AvB{6n%^~E-3|Tn~7mNfY_*T?>b%4?>N(TRU!Rc zg@SfojoY@8PKXQ%WJ>VKLa9YbUyqGUp1g22-7?%*NORyS5VKc17hZUp>>8yIa5@`oI2 ziahyH2?FJdO2$y(cA2IkM}6*i#3!~0YGHjvIw^>b^{$~&JbjEWWRd(6BMYR@<(@CV zTZTDJw%3-Ph$fXWHx)v?=g%6_PC+RPF1Osi4SHZSH4a`KwFm8zyCPzL&j7#DR>>P*fq!K2#8b7~_xcr)l8_gs0a(N3CH zGH$u&6siEPgq;q1a<=FfwLVu`$d>2|-8Y}eTSR7cWz^&wS+lT?;hrF*=5m<`CwPGQ z=sx*bsDZf%Z?XAp)Mnxjg6Q$*xF#wf3dewl{a;4G(#YOk<efSz9?6SvlyKTK@X) zAB?FZU}y9(AOdhD>~#&y$_5O+3P$!;&iBR|Lj%rp@Ec*WoY#A@<$CU5d-0ot{dRVH z5LpQlDHFz_V36=`ESoGKZLXDdbC|vApeU@393>SJ`F=H`{$*-TsFz3+aSqAv;m$-o zwV~otI;P50dTZWpL|kG$f+CnG0%o+JYl4Fa;$LJQjw}?y%f;_;BR7F{2t)_eDnBC8 zEPb6`WrJ0SfI>Ah@z$sKaM+f9Y3xtu#bGtU=w^1ZVvZ$>A+^{ZHxV)n(XdFJO_$0d2v*!fp2Se=f9xk;^YN=s2J~SOq}$ zQ&q$bBM{%04qybsE*Mzm2UvbZ0H3blauVCMNt5Aa7v8+7Dc35on*>1h#^2<`; zbU&#$N*H#lelj4Hq^%W987=<27|j9d!7t0+ouj0j&8Q5PrB}=+V@m?Jm0FRGrq+RR ztDneaeF={B7IaakyS~c~X60CAQG8Fg*je|xXS^F72Nl`-%BKR@Q*Xre@0LPP35o};D27^b zmQz(@WyP5xg6@V_(S z53QS}VztD(6?b0J{nWmD=6oUH+NQyWXyi~uq zeYtVh_ zh5&b%V6M5QyI|mgAK*Se-IUr(K{N(kF%XiZm!dnEP-O`F$my4LOP<2#1|GG`_cTCJ zQPLo6F8qj`_|us&K-K|IjI3$U+p|nnS(!47v4?X$4rCfu4R>`^vo1yk18qpum0a7! z7ExOSzEq*)^vPDz9rOWS?d>j3fMmX;%eT>Ct|QG*y-+M$yFGhkiW|^N;qQ|(B|}ni zP8{QzO93xZg7U8-wZ#p7Mya%yl@f%Ha;U{f!TzjnXYTMN9!Rl;vm~$x#x~$X&A(zhS7$hGS!41c9{PrfuduM6ZD)^i9xj zr3^4n%YcHUA|hxQ_3WzSO5wJ0^H}}JB>&=uM^l5~dR34SdML zpFQtAd4<10aGpZK?@{JVeK3GU@kibMA@%ljf$l;E@(OhUR_@&AA+MZYWI0Gmsj%vs zaexRm^-M^?=Av!B$D-+FavT(W$mK=1t~ni8;X_}T5{P4-SF(bhp;%AtQp9UY!Zo!~ zv!>SoygR|gyUX<60N98OoBR;qXb|K8P2?9`_!0dh$RP}u&n zqV{K#Z3(c5^f92WA5z0R=6(kWZNao53MM2DjhZLim$BnSk&a7U3x0KYjOT zh_JZ8$acmNTg8te7#2-(!FiX2z%GVoUgpjPrGEJ-KR|(`xFU^)!%nNWK`R*eh6geP zj_1`T@3L%j?7@>=cki14s~6NW3!up+@iN3&#@%VYT>7F;D>2W?p_)TiRdOK#vvMVA zEU^y}I#+O_Oqq|D@9#DBnlVk3r{sXKxQ9$YgEkUpX~ zMpd?{HhK!Fs{FIhcWUba_i~NEGj=pQ(n6{~1vHgw0T!94ofbxtLQwBUO$uvLGwrLk z%$i{knGh+IZE{q2wIWLyJs+nPtVR&cM?bGIXh`f=iRZGQPR8UTm^Hi3Fv7Z9qt!L| z`bpXBMx&3kU$9#l_FVn0!_^s6WlF>yoIGw+>yr=VHh+&1Ra%v$51`kZ06c#^9RFj# z|JH&lM@T~hGs248a|;7}?%ffD6!0$Ih^%rG zuN08umA6zl2o9M|_Q|<6Y}lbWYEJgn$cUciRrG`)i_sasr-#J^#5#UbGy|dy@92a* zZ>c>`zIBc)8pZU(Rza3{f@`%ib=fdAe-C;7;}ms5+J8j=BwIJ2c(MH_4Xi!=-$u@V zlrW|4P{3>taFT-G&-g+umXSkZZOK8(uA{( zpB_uQ&t!4~R4~NIBStC_5J6ZHKn0uif4kepHxYn)#llxtzl=6fR{mIQ8PrFqzv_!u zh=>(`?}N6wWjeh5!|=7bpCCNb?j^RRkp@l+Bzcew>jWbIM*23G+B04 zcmgI8qrjrYh2dLRb(mE2^xXB5;Kt*t`DBVP)4Hgqx_k?TJ#(YYM$3?TLq5P7M>-y< z5l8YCJzfkpbT6`a>BH~+J(N4Oa3P@)V0H~Rv^W`fwAP@(I$AW0khNA>1KQY-Jp#P< zC-VNoxNa+w14*S|A0pc3f*Qni~uJWb>Mh^pwqq85m7cMFdQu@ zM@kizxp6y6UF?*U&C7kl9>D%cKQFBBayj0{-r}q21nPbhFK6n_7=YEI>AM;8@-vGw zS`6Ju)J4wlQY??P!1oq&`O@7@^`@sA<_cF(;h{gZe+}4t^!Sh=nv=vz?x;g4{Mg;0 z;&L0pBJH^>(wz#0b#egnR1TD`q?FmVoiQ2#0S8g~=Q_*yu28d(wyUAU<`zSBMpsS{ z9)C^@vTK@jO^|-X3nGYn0-L=wT6Ks7EcXdn?ybVZ@DEOkNzzbze`R!}nr?)eK*qea za4r+@i9#Penqho79wFXVn&7w5ho5xi7vBUhOBbAccq+-}Dbgy!;8`2fR--Ze*H##u z1*>NC_AZU1)_dX{(dMCk=BetxSXb|mwi*`e7lk^FFq)Z6<}QjZwa1PR)AH)B9>td< zoHI#rX0o{>orK80A$yjEflc9EQC!_1JV{Dl)Bhg52InK+TtM_x0XzfXGg<$FXRtG} zbu_gzGStyCa4@yD()sFW_4hv8405HrG5XxOZr8uPqzswI<=zwrLvVuZ& zI<6U~MOCdHtma!V$wxAM>o8cBsWB{OKp$&!&AtEH(Y>PP&;1!TwK{-q>O(wmn~OtK zXBLs0g|4%|>cW6}c(oFh-@{SF>f%H9Q4SGCH*6+wuWYZtS7SBGLi{3OcVLf2B(Dgh z{1XjL&Bdz^t2+p9(qy{NOI1_laijNvLvM(3wh;Zu)En^%5%Y{a$SoW(8x^QS(|TFp z4!Ej_9D8!|sA>3!FvzwB+lZ* z*x(i7Z6i~p8ay*%k|-ESNbj9ynV*|VsH|C?Q3GQQ)$1s6uuBqC)l97~WY4LKL+0mP zm7bWY*AIA(G-L;Cn@!T|Xb#F{Kss)9hXukiY!5cOhqOm@4?eD;ue%!4VT#Dz*T6#kt`Qfnht>n?^V}Ma%w$5D)>9pThY2did^7sza@miFG#}t=*+_(4QglT56TbG3XXs&D=*_G|J`t-_p zh(vwlVe|)ai8#e+q!${z_Jg>Om(U6XPXe<58SLGoFl^thNUtfxX>eHAlT(#AY(V78D+Pvv}7~CzubF}c1 zU^)4oh~&Oa5OR3lHb7sczM}Y4;MeAX*$EVBD8Z-qhyiW6)J$gt~KAY=-z z5|Lh2PQB@w}@!-Cj9y`n&G3G2I2QgRhq{m!|%UrrhLkL=SJC_@JhGc+*0b7L$03~ZW&Xv3zyoP zIbRAl-**-WRoE!1p%dnRnz{6qD)PL0#UGN;AQV89*XC+p=;A#6y4GW{p>QBdbj~3n z@zk^pKG>drcYi9jH6lO>f*!#DIKS^_gY9Lrn;E zIxcNY_vY{oVdw)y9s({c{OZJHC$dsW0TuzoeQ-2!COgCLeU-5TAXosa&0My!K2R-N|Zvq%GBEcY~{BjNkL_$;kHx-%?+JZ+7_ z5BUC?T?f(X*?M&;_W1c%a3td$?Idq$EL&%ZJRL{sbL@feoZ#p+$jYh~m$~mQz`c0c zI{S2}(q}n(99?tmBKAjncXU7=N|o<7B^u2j%1gN#!qM-pJGo`rpVpPsl-CYnRFj$H z)#yFKUJt_DD4=mExERV>*Y6fQQl9oa4B_~0Zu(v;mpx?#3>sWD2fH1e zx8W%D8{eQArb9g1m|%g|*A+#!zs@wh*sC(8Kx3>{!8-Kx>!eGW$P`zE5u;H#poew) z^TK9#T?9HKMui0?f$ZN~f*YgSZ67mVBdkyK&h!Njap_=QG*y$CF*B2u~{yXAef~SP`NB!H3>CZCRMJ8Qr7dFN}cl z3C3JnPmLfkNLOSO3CC$GREn4D)hf%J-a{{}jk7%!><9I}^6k7Xl`}9pA%4`sKqXi9 zDiV9sb~q-);$nLxIXD(eN1tQK9i3%NISO-IZoPEra9VG=2pRjCg$Ie=BuJM<=S#F{ z9$lcB$GMwmQ1AC`Eos*MwqD8%-H6t{Dx2+9f5;`)%-!6tQaP~TS;Y1hYuinDHZMf* z;amr+dZ&?9Ev0Vd_lXz^YZyY<`~}Q0@O%Z=rwI-S6pBCjAhL42Az5%6`4l@Qh1B6T z9Oxy!4eB^@b>N0L=DqCogjie@O$VCoF$^R?st>{iRx&J2yn>t}S(l#|?K$4Osbf)e ziY&kXVeh(vvF()qMfAb`JIwVpTvR6eH{E5f}iBPi@ z)%MOvWNT_}SpS!)wcj@E?S5UpQpJEA3mr63dSldn@DTq5qDhXU2c1=8o6%=36 zyF|$I?HKt>2r`?ynp?I*FK6^9K4S8Ey(S^xX&+6q)WEW%{hWMqer={OR`=F0a2UyzVAIh5*t>u$mT2&`JhqPjSz(v!{9 zEHCd?)@6nYf(jHmuE=3>&L9Zx>yGwx%{1Y6A8JLpoVMb6Z*`mL;#l zFdMKAtVaRkW7tFrBSCV!zP@yS!7?P%_Ku^lYWfaC=p-Yni?az;NJMs&r|d&rX!!17 zGKA<%Bjd4V8V8Q-M^`}}Y;~VG#v;SS9Jo|BDp$+pADprrK-*%9uoJ#iChQ~XZ9C}F zs_X*~6_7u@HN=J6{bI21fmnH*ggH^@)qk~nyNDT_KV$L@$wz{mRAfeNhBmQEs3{x< z8f3{_JJRj67Lj>q6Vhr}l@?_Pj?exQ%XLlcd^`J|4ni3bnzH&9G~4Pm5S!Wr?VG0d zE0AOh9JH+q5>0jH(R@SB_P0P>a89@QZyN;}cB{cI#ze%j>^#9aW6fx5i5Ck5IY*@R zlaI>)>uH1WfYqU+dq^G>SQfm~p>cZtK~9Xa&q@@1(E+;I?V!W!ckNr_2@i|UB6gpT z%+^XAgV9L2KwF-%uiJ!Sf=}o~7=;WaLif==YrH?5uddsZp1Q^@2;d>^9&dB&O7NP| zKyNE#{jBj4GS?_f5|ciirGO*Jb>6-Te1-g~a`q4}#?!Ej@$d&kx;@qseF8wFBtU`s zYrp+}5kkL;)Bj>l%m7yc{TFkRhL2$f=^xM~AULZD*+3KJJU>FB$}G|1wHb3Jy@E_} ztKw(r%Jt)*ojhu@d&1Qpi?1Jo|)%a((%=_H@No_FKBirP_rQ3(8`Yva-5$@^<6HbJ7mD5a)Ag z#@}_(dLow909`cxX-fxq8gUS0Ze|D)Znp(|B((8-!jBe(MIVECknHzRm90DQJrhuH zTs)#)N=_Dc1DHTuq_!FW@e9nU&uCZ;#Evc`9XRYE$nX({_?zs|as~e)`Z`L_{@2>O z9q?#yN4U%kT>C0K!Cx%NVDVu%AFvACER3n_>8y9yL1{gJB?0K74*mGOEd7(4>Aa<;{3u5v3^Un^^X(-2;Tr!sB;bUI_Ji zn(T52MfZdDC!YAz!i_TD0?#b^Uc5{q90;ux?#EfOj4Jzd$bv0Zd62ZqIIF#ld;!F7 z8-OI)>{NJ#`W?QxsRJ*JF!~S>xgd!lVM5(dLQFr`tIy=6N!h$UOY2)2C9P|(0PywYxTKD5K1&Z6 z+-H6@{&Nc$wogkACg`iI5AYx3*_YzvL~`#H2bh9?e3r8r;wWmUjpV~L5Ra}IxW{a9 z9QlI(>b!s4JaHX1_2BQt=k$OT-)jaOq!~1?Ag&*7pY0f*(p$X*R*PU%dZb&v0eS-b zSZ{@S-2|!KtE$nVm(F|6 zP1u~xAfH~sIO#q`CSazoIGs5s6e$xk*a~F2A}zWXY=PsmYLN%xM4fSCZjYJ*DPKOd z@=($lJ}FMG_%6aB6LLXaJS>uT)0HF2v9lhnCAk+aRT2B+xZJFd%Nq=f~>jb(dMJwLKQ zbRtnMhcj#Z%jnMwOLs2lH5;}PF!>@1TI}j}do6*Mt%zWIo`}de9#6Yso9Y023BtN} z%yZQI3(48+_Y_mvmjp{g`_QBg1AFs&3gyMUFCi@h1#Tm6fX`oEkO-S8{w#=}iB#wT zvTI}i6cBHA;U-OYJuH#UwJc1gs9C!rY8BhJ!}gsP28~?f+}yh7&ab{L!bVwnk_Hkk zQT1W(?JVufR|i7_stMAmy=tRq$YU*a6#*>BxIz69m*r)aA9g!roGe7d;=#QZhT$1G zdY(WlwwhCHhLl(@#wvVMN2)8v+%F;BLONTS&z_*!`2?#6PDP%MK<(7jrrR@10YsBH z;l^X3(+&#KIivfJ*=CHB+28)~8t|tBTU`P6k|-cLf9;R|A9eXRlHM_9+6;sUQF!y7 z8vH3%V3^mR)<-~6F!o;WWCFZfdAfS4v(k#iqPAGp?O=m5lBZi6ClE#xo|LN#a}AUZ z?BUkJIfy+t6V2nbOI%E|m(i-#3Y{oYTtQc8D$beTyUbA_CnG|+7H(J{^-kJO>P{&V zb+rLH0SB|6!!I=4^oD2FKG0Kdxt2@SKwLC8_j@6qqQye&Yv%Q~MC~Je@g1YOvQ^tf zdu4*ryZb_cAyjJTaG7Fcd0n`AcdEVp;N!H-)(e1@QcxUZ8a6NAZxU@IlX>ht>L~)A zB>2JLJj<_5plYg<;LQD2+2Js`{>OR7?)c4s0I+7d0NUrToj$*nV=z+eix{`1iw5Kw70u#Xe>sK;&@UWLdyHm}&yje*G~&AUAC6rQ#>di( zy?ievNY19dqu@&xrI&Z(JyWPYRb#*VMz?xClTpB9V%C=PowD3XF#)KWdsTT0C9 zw<)4-@A+kmH!2V_Uo!7d^_XNN^?9s;e#qP?V-L+b4!-2Qhmv%YeNSUM z)NW0hc9T}M$Pq}me2RR}epLRXC40BQ9zS^)f!1%Y>^;84&hIrZ$Q<7LCxpT~#=4jR@FUIvm$dbnlO1@G&WG zua&ol(exju-35O@{*i~v!?$?+K=Av)2Tn!9odzhOHUNJ4uPt`JCEH(;%8m;EE#$bL z0WS4quj*~c;qyVmt6KBzlDGIgO(^Lr#y-9oRYNkEtlEvi+kP*`eFL9a&;Kc>|2wAU zk?(0Y9MA^Wigl;9Hy4{tQ@GVfNEz+5JK_@!9!uMNgMzM2)3Hk49 z#|0C7aM2z~TX2b0j;Jng&nftZp9Zm7V=j9@bbmm$rdjbXhEA-SM@-)mbwm zz?L*3vAB94cTe%4j1E*314CzlROTbcIX`gXlfZM7H1x$EmF0Wh#{DgzBCh}f{%?i} zj#mF11N{xp{~9USI~dvM7y>RuG`0A3S(T&Q_%EYz$1|nB^Rn(95HP0$wV%K!_oPg*Xi4|dTQ;~-pCDCtUa0K zF!&)<`CpNvh66UX*bN9VKzwi%#$YuE^$##KSQD`HgWg758vI*LbK)5n+zqy%;N8eC z8U~ZX6Z>r@lNTt=xsOFD6Y(iWD~;^smPji0Xt8nh=N^kKz0{>G1eI@EW?3ixd>s%=_sF`cJsuYtq*@+oB0TJ$i!v zj~a(xz1^?O1Y~5nisY~9N5^F)W)TKXw5r(j0pWKDc2l44PzrN&ZiwMpp`0~KcEeyC zIIHg+%zGWAoF*Vk7_P%9mudG`oDcJA{_YN#sCpnlTbfs%-jjGOr<=TdXL7x7P*!4C z#*70s6jG~?d{vhbA9wX*;*W}%FYp6fc{8r9#wq$bN9cs9JV+g4CU+@brxAaw5{D%K z6bv2woZ>HK#NT4$`2E`&6I2!ksF0nM{VXYE_)Bl^^bv{4zV76pOP9Bdy(JEW!t_z<1dgaJJXl}3UwJ8=7SY$w1U0rE}%^5+6tBs7-vpG=UOQAK5%-KVkgc<-mS)_q%)^dP6u)!R>RW{N%+Zp*UxUE6n@W>^z2%J5(uDj45hF zd1Y`sPfg06k1W%G?p8S__s~zk{*-16+w-$voM$0h?V6|1$`HXSYQLoHXYm^rlZT2j z7O5;wVllo({?=ObT8}`C%&BsZBd3HGAJ@UcGP*hwwS|%QxW#*WQ9ym`pfC( zSS$+La`a-StaB*E9)>e+8GNT9$(4qh2x~u?8xIbL(G%%ogsBD(N0;f+e+Y}JAHS0u zso$j4Ce8=uC$`8HRK-seb1GPd;bwFWkV5@fy{OX`Rvvp9DIj3Bflt{KU^c1P`SV&u zSOU@&L_k~oODglPwON3IU{C+Iv+945J%25eDQK)(s$r3t8;LE&I%oSu_MH8NOh)D} zWinv!Wo6D{btNUSa}9z!sMVI;k&3~vBhOu-mREIqS4K5&b2|tkvK-%}*EJIXLchre z?&aVDANnMy@r?N|%9f?+C~LI1ry#p^jeQ7IB{3%ewO^g0(AD$6bJ7jCnp)Gj3`Y+_ z8uZ?_y^xWHIU7A()W6cn)coH%nI^-(>tvY!txg8zf9PZ~X|n(f(7)Ho9R9A8@%$^D zOx*vcPDVC`f|um~(8(-{b1(cuCqqzK9KA`WLRi4_x~z8_jo9?KaP*fVyTog zjEW^C*T`no)Rc@%X-q_vqzei=E=%rqo3b`+AyV$S%%&x@n@eF)u`aV?^|Q-TnKG}W zCS6}h%I|5zsjo55toe)A>v@01Gv}P=%sJoB=kQi|Eefd*Rvh`u)YW6v`z0We>SRp* zys7GjJ;%9N8(WM2ET68b2!zujhJBmudzZ(6?#_GS_9^m(H**!$)tQ^FWNNrq4^~{} z^(1vMTKax93b0=gd3g<){6@L2KG{S@`pQGc`lb9@@-cE)s85GMUk-D3@&4Y1bt@Tj z70&D;Zprm2-*A*t!I2K_P?R0L((}*bvihe-Q5=ax1B= zfA}rPG|t=Er1^JT$K2z(O;Y#Yxj(Kif55w-{z9wa;4_u>R<<$4{_wVzXs(S+)ek!K zm6s$c5}MnLQj`quzjjJxeWi7?(V7{IAF^$;boqvK`7hc()H$)^oBmHpR;>&{c zpfUgK0UNp2h`*S$2B0d>7SXt*;xAyS~{yM{h@U9V?>2V(cqN3N4Ku zm=^y?hNqb9kuxFj>0Ckl?9~SpY_2dD%YN4t`l)^R9^*DyjgCzgSdKOcy{6do)oK2q zhin0dllMfuUUjTqyur6aJS+Pc^F}k<`H~(%ZcvAtW)4VTX$|MK)V{ue<7+|Za(%$6XVt0#LWm}9&og5lh|T~mt^(sQ@L zf24F?O^n}8ay3yeRV$sf-$H(yNpsk_C}-z$8X0F^6zz6OPMdT0;CcFU_p-y^&%0~K z%3P#Z;%sQuOMg9N{@b;r46V$d#dWrJF@4vD?ngOXT=}!?$%{Ipa>GR#O$+}%K8Q^d z8X}LlDBdXQUM@CFCzO0=ZeJtkVJKN8h2X3D-yA>EB&R>_m zNcEtU9y3I(A?v=&>TbGqrPJI%r3&o1o=E3ZvXV9PM$9H)O+a zRK14s2Y+RqwB3Ao#E9K$X`jrSuhNyFGPY@Xq+HM=T3$P+g`o0w+3CXG4N2yGg1I0-J9clf; z+IOClFJA3&({2fROZ@iF*JsL}e7>%e!se+;mnRyvF5#~*>DkxSzEv`q;%i#$leN}b zmpW+lt(dB7`%G@E24%l=i+ee|rci2wj-7*hh*9>5tXs+( zUN~!(@?Sj|YyW+3!mGBFivGAerKXIt0i+TGPY>>@i1a3!#A^Rsd- zB<(oA*P0&b_DHNM8qM^%73MUeb8_^{70V+l6qCu+^Agr#^A>il_V$|?X;S#{kbKH$ z^ZL)1T?iT*sOh@BEiufi(RWKg_MSbv*pE6))UGA&%XykZGpJ^Txt)5m&HUQR;8=Ea z2I(zUWGE)CD1lWa5wM;|@N{alEtA_#BoIQeFP3W9U#5NvupxD-Y)#+Dz{p^=fjbt4 zsqf|M>9>kz;b2BJb1;K2cmy|soy8>l{5^d4d(D9TdmuL?!Nao=NlR%~5+~3i@$|3cMa3Sb?s$#uofO{Cksm(H|XO0V(k40z`?%=0~4U;6Vlu1(W>|s?1mr zYC3Za8%7}u#$O{=m#I+JjJg3xh9R?v+_phD899F;6Nb1VW*tR1^V7K{CJ^$}p`5fnL&Q z2Tk?k8QDGXeZs5>gimqA$4@6uKrGAyKv*khA=uf+2ZIn%`J$k0NL zur<49#|rJm&<~A}oA(GqPFpkuxufCzgZwll?zXalI`UvBT~pQgNKzfh#Vh|M;2N~18)y3_CP{rk$6IQy$Y5pAa-9A4qIrCf?N5BtMnZ%cgDs( zyd!Y$7SW@bxO9O#xljRa7$Sv$&aBUiK4dQUQ0#>RaAFfRz{;3~v`LnN7LK(Q2hGeLxgvrcUTH9{(nbiA>4Y1eJ M`2<2+()-{357@r+$^ZZW literal 0 HcmV?d00001 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/providers/openai-python-sdk.md b/providers/openai-python-sdk.md new file mode 100644 index 0000000..3083449 --- /dev/null +++ b/providers/openai-python-sdk.md @@ -0,0 +1,32 @@ +# OpenAI Python SDK (`openai`) + +## 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; anything less sure is a removal. + +## 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. +- Inherited methods aren't followed to the base class. +- Type changes (an annotation narrowed) aren't events. From 3d0b90a1f2aac99e2915c1fa1c6dbaf68f8927f4 Mon Sep 17 00:00:00 2001 From: adssib <75389300+adssib@users.noreply.github.com> Date: Fri, 20 Nov 2026 18:12:40 -0500 Subject: [PATCH 07/16] new-plugin scaffolds a provider's source on a kind; which-kind guide --provider/--name/--category/--homepage, --source/--kind/--reader/--layer, --url and --package (repeatable), asked for in a terminal when missing; every kind and reader scaffolds (apisurface included, an OpenAPI adapter gets its Versions stub), plugins/all gets a new kind's import, and the old --format flags keep working for one release. make new-plugin ARGS=. docs/which-kind.md asks which kind a source is; a test checks every registered source's kind is one of its answers. Co-Authored-By: Claude Opus 5.5 Signed-off-by: adssib <75389300+adssib@users.noreply.github.com> --- AGENTS.md | 5 +- CONTRIBUTING.md | 8 +- Makefile | 9 +- README.md | 10 +- cmd/new-plugin/formats.go | 125 +++++++++++++++- cmd/new-plugin/main.go | 289 +++++++++++++++++++++++++++++------- cmd/new-plugin/main_test.go | 71 ++++++--- cmd/new-plugin/resolve.go | 170 +++++++++++++++++++++ docs/which-kind.md | 24 +++ docs/writing-a-plugin.md | 33 ++-- plugins/all/all_test.go | 14 ++ providers/algolia.md | 2 +- providers/anthropic.md | 2 +- providers/appwrite.md | 2 +- providers/convex.md | 2 +- providers/datadog.md | 2 +- providers/elasticsearch.md | 2 +- providers/flagsmith.md | 2 +- providers/github.md | 2 +- providers/gitlab.md | 2 +- providers/neon.md | 2 +- providers/planetscale.md | 2 +- providers/redis.md | 2 +- providers/sentry.md | 2 +- providers/stripe.md | 2 +- providers/supabase.md | 2 +- providers/textual.md | 2 +- providers/urllib3.md | 2 +- providers/vercel.md | 2 +- 29 files changed, 671 insertions(+), 123 deletions(-) create mode 100644 cmd/new-plugin/resolve.go create mode 100644 docs/which-kind.md diff --git a/AGENTS.md b/AGENTS.md index c37e6bc..249fac1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,7 +23,7 @@ Refer to the service that runs these plugins as "patch-it's hosted ingestion ser ## Rules for plugin code -- **Start a new provider with `go run ./cmd/new-plugin --api --provider --format `**, then fill in every `TODO(new-plugin)`; `make todos` (part of `make check` and CI_go) fails while one is left. +- **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. - **Precision over recall.** When unsure whether something is a change, don't emit an event. @@ -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. @@ -66,7 +67,7 @@ plugins/removedmembers/ apichangelog/ retirements/ feed/ eol/ deprecated: merg 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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8554f02..10dfee1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,7 @@ 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 @@ -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..3cd0e17 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" @@ -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 9b8da30..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/notices -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/new-plugin/formats.go b/cmd/new-plugin/formats.go index a14761b..69e29c6 100644 --- a/cmd/new-plugin/formats.go +++ b/cmd/new-plugin/formats.go @@ -29,8 +29,27 @@ type mapEntry struct { const todo = "TODO(new-plugin)" +// legacyFormats are the old --format names, each the template it is now. +var legacyFormats = map[string]string{ + "feed": "notices/feed", + "retirements": "notices/deprecations", + "migrationguide": "migrationguide/sdk", + "removedmembers": "migrationguide/members", + "changelog": "changelog/markdown", + "apichangelog": "changelog/json", + "catalog": "catalog", + "openapi": "openapi", +} + +// 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/notices/feed", @@ -81,7 +100,7 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { 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/notices/retire", @@ -155,7 +174,7 @@ 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/notices/retire"}, }, - "migrationguide": { + "migrationguide/sdk": { kind: "migrationguide", layer: "sdk", defDir: "plugins/migrationguide/sdkguide", @@ -222,7 +241,7 @@ 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/migrationguide/members", @@ -298,7 +317,7 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { 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", @@ -340,7 +359,7 @@ 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/changelog", @@ -437,6 +456,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. @@ -460,6 +481,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}}{}}`, @@ -501,7 +530,89 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { } `, 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{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.EventV2 { + 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.", }, } diff --git a/cmd/new-plugin/main.go b/cmd/new-plugin/main.go index 7fc2db6..bc2b712 100644 --- a/cmd/new-plugin/main.go +++ b/cmd/new-plugin/main.go @@ -1,23 +1,36 @@ -// 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 or the first name is +// taken, or a file it would write exists. The old flags (--api, --provider +// as the name, --format, --source as the URL) still work for one release. package main import ( + "bufio" "bytes" "flag" "fmt" @@ -42,31 +55,75 @@ 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 the first name. An existing page is shared, not rewritten + API string // its first name, the old slug events carry in api; "" is - (or the provider's id when they're the same) + + // Deprecated: Format is a template ("openapi", "notices/feed") or an old + // format name ("feed"); Kind and Reader replace it. Source is the first + // URL (URLs replaces it). + Format string + Source string + + Today time.Time // Go runs the go command afterwards: the golden file from the placeholders // (go test -update). Go bool } +// 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 + var provider, source string 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(&provider, "provider", "", "the provider's id, e.g. acme (with --format: its name, the old meaning)") + 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(&source, "source", "", "the source's id within the provider, e.g. api or python-sdk (with --format: its URL, the old meaning)") + 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: the first name); a second source of a provider may share the existing page") + flag.StringVar(&o.API, "api", "", "the source's first name, the slug events carry in api (default: -)") + flag.StringVar(&o.Format, "format", "", "deprecated, for one release: the old format names ("+strings.Join(legacyNames(), ", ")+"), with --api, --provider and --source ") flag.Parse() + o.URLs, o.Packages = urls, packages + if o.Format != "" { + o.Provider, o.Source = provider, source + } else { + o.ProviderID, o.SourceID = provider, source + 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 +132,7 @@ func main() { } } +// formatNames are the templates: a kind, or kind/reader. func formatNames() []string { var names []string for n := range formats { @@ -84,6 +142,77 @@ 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 legacyNames() []string { + var names []string + for n := range legacyFormats { + names = append(names, n) + } + slices.Sort(names) + return names +} + +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, or the +// deprecated --format. +func (o Options) template() (string, error) { + if o.Format != "" { + if t, ok := legacyFormats[o.Format]; ok { + return t, nil + } + if _, ok := formats[o.Format]; ok { + return o.Format, nil + } + return "", fmt.Errorf("--format %q: want one of %s", o.Format, strings.Join(legacyNames(), ", ")) + } + 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,17 +223,22 @@ var ( // data is what the templates fill in. type data struct { - ID, Ident, Lower, Provider, Source, File, Format, Kind string - Slug string // the provider, lowercase: a model subject's provider - SourceFile, DropFile, PluginOf, Ingest, Drop string - Imports []string + ID, Ident, Lower, 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.Format = 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) @@ -118,10 +252,28 @@ 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 == "" && len(o.URLs) > 0 { + o.Source = o.URLs[0] + } 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{o.Source} + } + 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" @@ -140,10 +292,20 @@ 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) + return fmt.Errorf("a source named %q is already registered: pick another --api (the first name)", o.API) + } + if _, ok := plugin.LookupSource(o.ProviderID + "/" + o.SourceID); ok { + return fmt.Errorf("source %s/%s is already registered: pick another --source", o.ProviderID, o.SourceID) } - d := data{ID: o.API, Provider: o.Provider, Source: o.Source, Format: o.Format, Kind: f.kind} + d := data{ID: o.API, Provider: o.Provider, Source: o.Source, Format: o.Format, Kind: f.kind, PyPI: o.API} + 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.API) d.Lower = string(unicode.ToLower(rune(d.Ident[0]))) + d.Ident[1:] d.File = fileBase(o.API) @@ -207,6 +369,11 @@ func Run(o Options, out io.Writer) error { return err } edits := map[string][]byte{mainFile: registered} + if all, ok, err := importInAll(o.Root, f.kind); err != nil { + return err + } else if ok { + edits[filepath.Join("plugins", "all", "all.go")] = all + } 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 @@ -240,7 +407,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 (%s, first name %s, kind %s):\n", o.ProviderID, o.SourceID, o.Provider, o.API, o.Format) for _, p := range paths { fmt.Fprintln(out, " "+p) } @@ -360,30 +527,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 diff --git a/cmd/new-plugin/main_test.go b/cmd/new-plugin/main_test.go index 3092ef5..087e8f6 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()) @@ -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) } @@ -90,16 +100,24 @@ 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"}}, + "first name taken": {ProviderID: "acme", Provider: "Acme", SourceID: "api", Kind: "openapi", API: "stripe"}, + "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"}, } { o.Root, o.Today = root, today if err := Run(o, io.Discard); err == nil { @@ -187,3 +205,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..7b3ab38 --- /dev/null +++ b/cmd/new-plugin/resolve.go @@ -0,0 +1,170 @@ +package main + +import ( + "bufio" + "bytes" + "fmt" + "go/format" + "io" + "os" + "path/filepath" + "regexp" + "slices" + "strings" + + "github.com/patch-it-dev/patch-it-plugins/core/plugin" +) + +// resolve fills in the provider and source from the registry and the +// flags: a registered provider's name, category and homepage, the first +// name, and, for the deprecated flags, the ids from the name and --api. +func (o *Options) resolve() error { + if o.ProviderID == "" && o.Provider != "" { // the old flags: --provider is the name + o.ProviderID = strings.Trim(regexp.MustCompile(`[^a-z0-9]+`).ReplaceAllString(strings.ToLower(o.Provider), "-"), "-") + for _, p := range plugin.Providers() { + if strings.EqualFold(p.Name, o.Provider) { + o.ProviderID = p.ID + } + } + if o.SourceID == "" { + o.SourceID = strings.TrimPrefix(o.API, o.ProviderID+"-") + } + } + 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) + } + } + if o.API == "" { + o.API = o.ProviderID + "-" + o.SourceID + if o.SourceID == o.ProviderID { + o.API = o.ProviderID + } + } + 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/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 62de359..bc7f703 100644 --- a/docs/writing-a-plugin.md +++ b/docs/writing-a-plugin.md @@ -1,29 +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 and feed (notices sources), migrationguide, removedmembers (a migrationguide source), -# changelog, apichangelog (a JSON changelog source), 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), --api acme-api (the first name; 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/notices/retire/`, `plugins/notices/feed/`, `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 the deprecations-page and SDK-guide readers 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` (plus the `core/migrate/` map entry that the deprecations-page and SDK-guide readers need), 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 or a first name that's taken, or a file it would write that exists, and then changes nothing. The old flags (`--api acme --provider Acme --format feed --source `) still work for one release. ## 2. Pick the source @@ -73,10 +78,12 @@ 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/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/` (`--format` doesn't scaffold this one yet) | +| `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 | diff --git a/plugins/all/all_test.go b/plugins/all/all_test.go index e4402a0..dc94d93 100644 --- a/plugins/all/all_test.go +++ b/plugins/all/all_test.go @@ -104,3 +104,17 @@ func TestEveryPluginIsASourceWithMetadata(t *testing.T) { } } } + +// 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) + } + } +} diff --git a/providers/algolia.md b/providers/algolia.md index 9158969..3b53b17 100644 --- a/providers/algolia.md +++ b/providers/algolia.md @@ -4,7 +4,7 @@ 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.md b/providers/anthropic.md index cac9358..d67f50f 100644 --- a/providers/anthropic.md +++ b/providers/anthropic.md @@ -4,7 +4,7 @@ Request parameters removed from `messages.create()` and its siblings in anthropic-sdk-python 1.0.0 (`temperature`, `top_p`, `top_k`): passing one is a `TypeError`. One breaking event per parameter. Pinned to that release. -Format plugin: `migrationguide` (`plugins/migrationguide`), reading with `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..ea502e7 100644 --- a/providers/appwrite.md +++ b/providers/appwrite.md @@ -4,7 +4,7 @@ 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 diff --git a/providers/convex.md b/providers/convex.md index c848d5c..fb9e7db 100644 --- a/providers/convex.md +++ b/providers/convex.md @@ -4,7 +4,7 @@ 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 diff --git a/providers/datadog.md b/providers/datadog.md index 9451a82..3de454b 100644 --- a/providers/datadog.md +++ b/providers/datadog.md @@ -4,7 +4,7 @@ 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 diff --git a/providers/elasticsearch.md b/providers/elasticsearch.md index c1dcdbf..36d6509 100644 --- a/providers/elasticsearch.md +++ b/providers/elasticsearch.md @@ -4,7 +4,7 @@ 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 diff --git a/providers/flagsmith.md b/providers/flagsmith.md index 40ff7ae..89ad8d0 100644 --- a/providers/flagsmith.md +++ b/providers/flagsmith.md @@ -4,7 +4,7 @@ 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.md b/providers/github.md index 3bd5c02..f47fd93 100644 --- a/providers/github.md +++ b/providers/github.md @@ -4,7 +4,7 @@ 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..7556c13 100644 --- a/providers/gitlab.md +++ b/providers/gitlab.md @@ -4,7 +4,7 @@ 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 diff --git a/providers/neon.md b/providers/neon.md index 15bb787..1724564 100644 --- a/providers/neon.md +++ b/providers/neon.md @@ -4,7 +4,7 @@ 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 diff --git a/providers/planetscale.md b/providers/planetscale.md index 4ff0a46..c1e9658 100644 --- a/providers/planetscale.md +++ b/providers/planetscale.md @@ -4,7 +4,7 @@ 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 diff --git a/providers/redis.md b/providers/redis.md index 98808be..b7b9a84 100644 --- a/providers/redis.md +++ b/providers/redis.md @@ -4,7 +4,7 @@ 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 diff --git a/providers/sentry.md b/providers/sentry.md index c851d03..d61f373 100644 --- a/providers/sentry.md +++ b/providers/sentry.md @@ -4,7 +4,7 @@ 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 diff --git a/providers/stripe.md b/providers/stripe.md index 6c94bd1..46aee8f 100644 --- a/providers/stripe.md +++ b/providers/stripe.md @@ -4,7 +4,7 @@ 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 diff --git a/providers/supabase.md b/providers/supabase.md index 87ec785..86dae18 100644 --- a/providers/supabase.md +++ b/providers/supabase.md @@ -4,7 +4,7 @@ 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 diff --git a/providers/textual.md b/providers/textual.md index 4b13089..ec6488b 100644 --- a/providers/textual.md +++ b/providers/textual.md @@ -4,7 +4,7 @@ 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..d6c7e3d 100644 --- a/providers/urllib3.md +++ b/providers/urllib3.md @@ -4,7 +4,7 @@ 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..4aec983 100644 --- a/providers/vercel.md +++ b/providers/vercel.md @@ -4,7 +4,7 @@ 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 From 99a99ac1c6681656c1c221978fa6db34797a4055 Mon Sep 17 00:00:00 2001 From: adssib <75389300+adssib@users.noreply.github.com> Date: Fri, 20 Nov 2026 18:13:25 -0500 Subject: [PATCH 08/16] remove the top-level forwarding packages plugin/, event/, fetch/, migrate/, kit/ (and kit/kittest/), retire/ and sdkguide/ only forwarded to core/ and plugins/. Code importing them moves to core/plugin, core/event, core/fetch, core/migrate, core/kit, plugins/notices/retire and plugins/migrationguide/sdkguide. Co-Authored-By: Claude Opus 5.5 Signed-off-by: adssib <75389300+adssib@users.noreply.github.com> --- .github/pull_request_template.md | 2 +- AGENTS.md | 2 -- docs/how-it-works.md | 2 +- event/event.go | 50 -------------------------------- fetch/fetch.go | 19 ------------ kit/kit.go | 30 ------------------- kit/kittest/kittest.go | 33 --------------------- migrate/migrate.go | 14 --------- plugin/plugin.go | 27 ----------------- retire/retire.go | 23 --------------- sdkguide/sdkguide.go | 21 -------------- 11 files changed, 2 insertions(+), 221 deletions(-) delete mode 100644 event/event.go delete mode 100644 fetch/fetch.go delete mode 100644 kit/kit.go delete mode 100644 kit/kittest/kittest.go delete mode 100644 migrate/migrate.go delete mode 100644 plugin/plugin.go delete mode 100644 retire/retire.go delete mode 100644 sdkguide/sdkguide.go diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 5e14f73..2517da6 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -4,7 +4,7 @@ ## 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`) - [ ] `testdata/README.md` lists each file: URL, date fetched, license, quote of the part the plugin reads diff --git a/AGENTS.md b/AGENTS.md index 249fac1..03d508d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -64,8 +64,6 @@ plugins// one package per kind, with its providers: openapi (+ adap plugins/all imports every one plugins/removedmembers/ apichangelog/ retirements/ feed/ eol/ deprecated: merged into migrationguide, changelog and notices, they only forward there -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'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) diff --git a/docs/how-it-works.md b/docs/how-it-works.md index 642e17b..9e3150a 100644 --- a/docs/how-it-works.md +++ b/docs/how-it-works.md @@ -28,7 +28,7 @@ There's no list in this repo: `make plugins` prints every provider and source fr | [`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/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/`, `plugins/removedmembers/`, `plugins/apichangelog/`, `plugins/retirements/`, `plugins/feed/`, `plugins/eol/` | Deprecated: the old import paths, forwarding to the packages above until code that imports them moves | +| `plugins/removedmembers/`, `plugins/apichangelog/`, `plugins/retirements/`, `plugins/feed/`, `plugins/eol/` | 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/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/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/retire/retire.go b/retire/retire.go deleted file mode 100644 index ff9477b..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/notices/retire. -// -// Deprecated: import github.com/patch-it-dev/patch-it-plugins/plugins/notices/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/notices/retire" - -// Deprecated: the types live in github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire. -type ( - Page = moved.Page - Retirement = moved.Retirement -) - -// Deprecated: the functions and values live in github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire. -var ( - Events = moved.Events - First = moved.First - Parse = moved.Parse - Anthropic = moved.Anthropic - OpenAI = moved.OpenAI -) 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 -) From 00cf5748dd06bcff9ebfcf57e0f575e8eb0845f1 Mon Sep 17 00:00:00 2001 From: adssib <75389300+adssib@users.noreply.github.com> Date: Fri, 20 Nov 2026 18:26:54 -0500 Subject: [PATCH 09/16] apisurface: no rename on self alone, no removal from a skipped file or a method moved up Co-Authored-By: Claude Opus 5.5 Signed-off-by: adssib <75389300+adssib@users.noreply.github.com> --- plugins/apisurface/apisurface.go | 91 +++++++++-- plugins/apisurface/apisurface_test.go | 99 +++++++++++- plugins/apisurface/pysurface/pysurface.go | 147 ++++++++++++++++-- .../apisurface/pysurface/pysurface_test.go | 18 +++ providers/openai-python-sdk.md | 5 +- 5 files changed, 334 insertions(+), 26 deletions(-) diff --git a/plugins/apisurface/apisurface.go b/plugins/apisurface/apisurface.go index b300ebf..66f9114 100644 --- a/plugins/apisurface/apisurface.go +++ b/plugins/apisurface/apisurface.go @@ -109,11 +109,12 @@ func (p Plugin) ListVersions(ctx context.Context, env plugin.Env) ([]plugin.Vers } } -// snapshot is what ReadAt keeps of a release: its public surface, and -// what couldn't be read. -type snapshot struct { +// 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 } @@ -140,7 +141,7 @@ func (p Plugin) ReadAt(ctx context.Context, env plugin.Env, v plugin.Version) (p for _, s := range skipped { log.Printf("%s %s: %s skipped: over %d bytes", pkg.Name, v.ID, s, MaxFileBytes) } - content, err := json.Marshal(snapshot{Artifact: a.Filename, Surface: pysurface.Read(files), Skipped: skipped}) + 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 } @@ -155,7 +156,7 @@ func (p Plugin) Extract(_ context.Context, env plugin.Env, from, to plugin.Snaps if from.IsZero() { return plugin.Result{Label: to.Version.ID}, nil } - var a, b snapshot + 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) } @@ -165,7 +166,7 @@ func (p Plugin) Extract(_ context.Context, env plugin.Env, from, to plugin.Snaps now := env.Now().UTC() var events []event.EventV2 var rejected []error - for _, c := range Compare(a.Surface, b.Surface) { + 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 @@ -260,9 +261,16 @@ type Change struct { // 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; anything less sure -// is a removal. -func Compare(a, b pysurface.Surface) []Change { +// 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 @@ -287,7 +295,7 @@ func Compare(a, b pysurface.Surface) []Change { 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(old.Params) > 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] } } @@ -297,6 +305,10 @@ func Compare(a, b pysurface.Surface) []Change { 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] @@ -340,6 +352,65 @@ func Compare(a, b pysurface.Surface) []Change { 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 { diff --git a/plugins/apisurface/apisurface_test.go b/plugins/apisurface/apisurface_test.go index 5723fa8..eb182ba 100644 --- a/plugins/apisurface/apisurface_test.go +++ b/plugins/apisurface/apisurface_test.go @@ -128,7 +128,7 @@ func TestCompare(t *testing.T) { "acme.Kept.with_kwargs": sym("method", prm("self", "either", ""), prm("kw", "kwargs", "")), } var got []string - for _, c := range Compare(a, b) { + for _, c := range Compare(Release{Surface: a}, Release{Surface: b}) { if c.Change == "" { got = append(got, "note "+c.Symbol) continue @@ -148,6 +148,103 @@ func TestCompare(t *testing.T) { } } +// 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. +func TestAMethodMovedUpIsNotRemoved(t *testing.T) { + self := prm("self", "either", "") + a := Release{Surface: pysurface.Surface{ + "acme.Completions": cls("class Completions(SyncAPIResource):"), + "acme.Completions.create": sym("method", self), + "acme.Completions.list": sym("method", self), + "acme.Completions.models": sym("method", self), + "acme.Completions.gone": sym("method", self), + "acme.Files": cls("class Files(SyncAPIResource):"), + "acme.Files.upload": sym("method", self), + }} + b := Release{ + Surface: pysurface.Surface{ + "acme.Completions": cls("class Completions(SyncAPIResource):"), + "acme.Files": cls("class Files(SyncAPIResource, _Uploads):"), + }, + Classes: pysurface.Classes{ + "Completions": {Bases: []string{"SyncAPIResource"}, Members: []string{"models"}}, + "SyncAPIResource": {Bases: []string{"_Base"}, Members: []string{"create"}}, + "_Base": {Members: []string{"list"}}, + }, + } + 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) { diff --git a/plugins/apisurface/pysurface/pysurface.go b/plugins/apisurface/pysurface/pysurface.go index 9a84a43..e934db5 100644 --- a/plugins/apisurface/pysurface/pysurface.go +++ b/plugins/apisurface/pysurface/pysurface.go @@ -43,6 +43,22 @@ type File struct { 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 classes a method could have moved to, by name: every +// module-level class in the package (private modules and names included) +// that another class names as 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" @@ -53,6 +69,7 @@ type module struct { 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 ( @@ -63,6 +80,8 @@ var ( 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 @@ -73,6 +92,99 @@ var ( // 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 named as +// another class's base. +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...) + } + } + named := map[string]bool{} + for _, c := range all { + for _, b := range c.Bases { + named[b] = true + } + } + out := Classes{} + for n, c := range all { + if named[n] { + 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 @@ -90,18 +202,7 @@ func Read(files []File) Surface { m := parse(f) mods[m.name] = m } - 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 + return mods } // moduleName is "openai.types.chat" for "openai/types/chat/__init__.py". @@ -222,7 +323,7 @@ type block struct { // 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{}} + 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) { @@ -243,6 +344,22 @@ func parse(f File) *module { 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:])) @@ -266,6 +383,10 @@ func parse(f File) *module { 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 { diff --git a/plugins/apisurface/pysurface/pysurface_test.go b/plugins/apisurface/pysurface/pysurface_test.go index b8402ca..168e80a 100644 --- a/plugins/apisurface/pysurface/pysurface_test.go +++ b/plugins/apisurface/pysurface/pysurface_test.go @@ -2,6 +2,7 @@ package pysurface import ( "encoding/json" + "strings" "testing" ) @@ -115,3 +116,20 @@ func TestRead(t *testing.T) { t.Errorf("helper: %+v", h) } } + +// The class index: classes named as a base, with their bases and every name +// their bodies define; 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 pass\n"}, + }) + got, _ := json.Marshal(c) + want := `{"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/providers/openai-python-sdk.md b/providers/openai-python-sdk.md index 3083449..d99a51c 100644 --- a/providers/openai-python-sdk.md +++ b/providers/openai-python-sdk.md @@ -23,10 +23,11 @@ Kind: `apisurface` (`plugins/apisurface`), with the Python reader (`plugins/apis - 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; anything less sure is a removal. +- 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. -- Inherited methods aren't followed to the base class. +- 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. From 999aceddb746bd1e939882fdf4e9d6e5e6861c19 Mon Sep 17 00:00:00 2001 From: adssib <75389300+adssib@users.noreply.github.com> Date: Fri, 20 Nov 2026 18:29:25 -0500 Subject: [PATCH 10/16] delete the merged kinds' forwarding packages and CanonicalKind Co-Authored-By: Claude Opus 5.5 Signed-off-by: adssib <75389300+adssib@users.noreply.github.com> --- AGENTS.md | 2 - core/plugin/provider.go | 22 +----- core/plugin/provider_test.go | 13 ---- docs/how-it-works.md | 1 - internal/pluginlist/schema_test.go | 3 +- plugins/all/all_test.go | 77 +++++++++++++++++++ plugins/apichangelog/apichangelog.go | 18 ----- plugins/apichangelog/apichangelog_test.go | 16 ---- plugins/eol/eol.go | 26 ------- plugins/eol/eol_test.go | 16 ---- plugins/feed/feed.go | 51 ------------ plugins/feed/feed_test.go | 16 ---- plugins/openapi/openapi.go | 2 +- plugins/removedmembers/removedmembers.go | 36 --------- plugins/removedmembers/removedmembers_test.go | 16 ---- plugins/retirements/retire/retire.go | 24 ------ plugins/retirements/retirements.go | 13 ---- plugins/retirements/retirements_test.go | 17 ---- 18 files changed, 80 insertions(+), 289 deletions(-) delete mode 100644 plugins/apichangelog/apichangelog.go delete mode 100644 plugins/apichangelog/apichangelog_test.go delete mode 100644 plugins/eol/eol.go delete mode 100644 plugins/eol/eol_test.go delete mode 100644 plugins/feed/feed.go delete mode 100644 plugins/feed/feed_test.go delete mode 100644 plugins/removedmembers/removedmembers.go delete mode 100644 plugins/removedmembers/removedmembers_test.go delete mode 100644 plugins/retirements/retire/retire.go delete mode 100644 plugins/retirements/retirements.go delete mode 100644 plugins/retirements/retirements_test.go diff --git a/AGENTS.md b/AGENTS.md index 03d508d..74fbfbf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -62,8 +62,6 @@ plugins// one package per kind, with its providers: openapi (+ adap per provider), notices (+ retire/, feed/, eol/), migrationguide (+ sdkguide/, members/), changelog (Markdown, RST or JSON), catalog, apisurface (+ pysurface/); plugins/all imports every one -plugins/removedmembers/ apichangelog/ retirements/ feed/ eol/ deprecated: merged into - migrationguide, changelog and notices, they only forward there cmd/list-plugins/ prints the list from the registry (make plugins); internal/pluginlist/ is its logic 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) diff --git a/core/plugin/provider.go b/core/plugin/provider.go index 9d6cd7d..085b8f7 100644 --- a/core/plugin/provider.go +++ b/core/plugin/provider.go @@ -216,7 +216,7 @@ func (p Provider) check() error { return fmt.Errorf("source %q has no URLs", id) case !strings.HasPrefix(s.Page, "providers/") || !strings.HasSuffix(s.Page, ".md"): return fmt.Errorf("source %q: Page %q isn't providers/.md", id, s.Page) - case s.Kind != "" && CanonicalKind(s.Kind) != KindOf(s.Plugin): + case s.Kind != "" && s.Kind != KindOf(s.Plugin): return fmt.Errorf("source %q: Kind %q, but its plugin is in plugins/%s", id, s.Kind, KindOf(s.Plugin)) } for _, u := range s.URLs { @@ -250,26 +250,6 @@ func KindOf(p Plugin) string { return path.Base(t.PkgPath()) } -// mergedKinds are the kinds merged into another, by their old name: what -// they read is read by the new kind, with the same events. -var mergedKinds = map[string]string{ - "removedmembers": "migrationguide", - "apichangelog": "changelog", - "retirements": "notices", - "feed": "notices", - "eol": "notices", -} - -// CanonicalKind is the kind name means now: name itself, or, for a kind -// merged into another ("removedmembers"), the kind that reads its sources -// now ("migrationguide"). Code that still says an old kind keeps working. -func CanonicalKind(name string) string { - if k, ok := mergedKinds[name]; ok { - return k - } - return name -} - // Providers are the registered providers with their sources, sorted by id // (sources by id within each). func Providers() []Provider { diff --git a/core/plugin/provider_test.go b/core/plugin/provider_test.go index 6d42186..6311bf4 100644 --- a/core/plugin/provider_test.go +++ b/core/plugin/provider_test.go @@ -88,19 +88,6 @@ func TestRegisterProviderRefusesConflictingProvider(t *testing.T) { RegisterProvider(p) } -// A kind merged into another still names it: a source registered with the -// old name passes the check, and the old name reads as the new one. -func TestMergedKindsKeepWorking(t *testing.T) { - for old, now := range mergedKinds { - if got := CanonicalKind(old); got != now { - t.Errorf("CanonicalKind(%q) = %q, want %q", old, got, now) - } - } - if got := CanonicalKind("openapi"); got != "openapi" { - t.Errorf("CanonicalKind(openapi) = %q", got) - } -} - // A package names its sources, and a source answers to its first name. func TestForPackage(t *testing.T) { s := src("pkg", "acme-test-pkg") diff --git a/docs/how-it-works.md b/docs/how-it-works.md index 9e3150a..ba0a6f3 100644 --- a/docs/how-it-works.md +++ b/docs/how-it-works.md @@ -28,7 +28,6 @@ There's no list in this repo: `make plugins` prints every provider and source fr | [`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/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 | -| `plugins/removedmembers/`, `plugins/apichangelog/`, `plugins/retirements/`, `plugins/feed/`, `plugins/eol/` | 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/internal/pluginlist/schema_test.go b/internal/pluginlist/schema_test.go index 65cb7ea..4b7df50 100644 --- a/internal/pluginlist/schema_test.go +++ b/internal/pluginlist/schema_test.go @@ -95,8 +95,7 @@ func TestSchemaEnumsMatchTheRegistry(t *testing.T) { t.Fatal(err) } for _, k := range kinds { - // A merged kind's old package only forwards: no source has its name. - if name := filepath.Base(k); name != "all" && plugin.CanonicalKind(name) == name && !slices.Contains(src["kind"].Enum, name) { + if name := filepath.Base(k); name != "all" && !slices.Contains(src["kind"].Enum, name) { t.Errorf("kind %s is missing from the schema's kind enum", name) } } diff --git a/plugins/all/all_test.go b/plugins/all/all_test.go index dc94d93..998da1c 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" @@ -118,3 +120,78 @@ func TestWhichKindNamesEveryKind(t *testing.T) { } } } + +// 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) + } + 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/apichangelog.go b/plugins/apichangelog/apichangelog.go deleted file mode 100644 index 1013b47..0000000 --- a/plugins/apichangelog/apichangelog.go +++ /dev/null @@ -1,18 +0,0 @@ -// Package apichangelog is the old import path of the changelog kind's JSON -// parser, kept so code that imports it still builds. -// -// Deprecated: use plugins/changelog: Plugin{Log: changelog.MongoDBAtlas}. -// This package only forwards there and registers nothing; it goes once -// nothing imports it. -package apichangelog - -import "github.com/patch-it-dev/patch-it-plugins/plugins/changelog" - -type ( - // Plugin is changelog.Plugin: set Log, as before. - Plugin = changelog.Plugin - Log = changelog.Log - Finding = changelog.LogFinding -) - -var MongoDBAtlas = changelog.MongoDBAtlas diff --git a/plugins/apichangelog/apichangelog_test.go b/plugins/apichangelog/apichangelog_test.go deleted file mode 100644 index ed0bdad..0000000 --- a/plugins/apichangelog/apichangelog_test.go +++ /dev/null @@ -1,16 +0,0 @@ -package apichangelog - -import ( - "testing" - - "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" -) - -// Code written against the old path still builds and runs the same source. -func TestTheOldPathStillWorks(t *testing.T) { - p := Plugin{Log: MongoDBAtlas} - kittest.Registered(t, p) - if p.Name() != "mongodb-atlas" { - t.Errorf("Plugin{Log: MongoDBAtlas} is %q", p.Name()) - } -} diff --git a/plugins/eol/eol.go b/plugins/eol/eol.go deleted file mode 100644 index 906b2ab..0000000 --- a/plugins/eol/eol.go +++ /dev/null @@ -1,26 +0,0 @@ -// Package eol is the old import path of the notices kind's end-of-life -// page reader, kept so code that imports it still builds. -// -// Deprecated: use plugins/notices (Plugin) and plugins/notices/eol (the -// reader: Page, Salesforce, Findings). This package only forwards to them -// and registers nothing; it goes once nothing imports it. -package eol - -import ( - "github.com/patch-it-dev/patch-it-plugins/plugins/notices" - moved "github.com/patch-it-dev/patch-it-plugins/plugins/notices/eol" -) - -type ( - // Plugin is notices.Plugin: set Page and Archiver, as before. - Plugin = notices.Plugin - Page = moved.Page - Row = moved.Row - Finding = moved.Finding -) - -var ( - Salesforce = moved.Salesforce - Parse = moved.Parse - Findings = moved.Findings -) diff --git a/plugins/eol/eol_test.go b/plugins/eol/eol_test.go deleted file mode 100644 index 27019ea..0000000 --- a/plugins/eol/eol_test.go +++ /dev/null @@ -1,16 +0,0 @@ -package eol - -import ( - "testing" - - "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" -) - -// Code written against the old path still builds and runs the same source. -func TestTheOldPathStillWorks(t *testing.T) { - p := Plugin{Page: Salesforce} - kittest.Registered(t, p) - if p.Name() != "salesforce" { - t.Errorf("Plugin{Page: Salesforce} is %q", p.Name()) - } -} diff --git a/plugins/feed/feed.go b/plugins/feed/feed.go deleted file mode 100644 index 7690531..0000000 --- a/plugins/feed/feed.go +++ /dev/null @@ -1,51 +0,0 @@ -// Package feed is the old import path of the notices kind's RSS and Atom -// feed reader, kept so code that imports it still builds. -// -// Deprecated: use plugins/notices (notices.Plugin{Page: feed.GitHubActions}) -// and plugins/notices/feed (the reader). This package only forwards to them -// and registers nothing; it goes once nothing imports it. -package feed - -import ( - "context" - - "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/plugins/notices" - moved "github.com/patch-it-dev/patch-it-plugins/plugins/notices/feed" -) - -type ( - Feed = moved.Feed - Reader = moved.Reader - Finding = moved.Finding - Entry = moved.Entry - Section = moved.Section -) - -var ( - GitHubActions = moved.GitHubActions - VertexAIModels = moved.VertexAIModels - CloudflareAPI = moved.CloudflareAPI - Parse = moved.Parse - Text = moved.Text - Lines = moved.Lines - SplitBy = moved.SplitBy - Date = moved.Date - Codes = moved.Codes -) - -// Plugin reads one feed: notices.Plugin{Page: Feed, Archiver: Archiver}. -type Plugin struct { - Feed Feed - Archiver kit.Archiver -} - -func (p Plugin) notices() notices.Plugin { return notices.Plugin{Page: p.Feed, Archiver: p.Archiver} } - -func (p Plugin) Name() string { return p.notices().Name() } - -// Run is notices.Plugin's Run. -func (p Plugin) Run(ctx context.Context, env plugin.Env) (plugin.Result, error) { - return p.notices().Run(ctx, env) -} diff --git a/plugins/feed/feed_test.go b/plugins/feed/feed_test.go deleted file mode 100644 index 610dd33..0000000 --- a/plugins/feed/feed_test.go +++ /dev/null @@ -1,16 +0,0 @@ -package feed - -import ( - "testing" - - "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" -) - -// Code written against the old path still builds and runs the same feed -// with the same events. -func TestTheOldPathStillWorks(t *testing.T) { - saved := kittest.Pages{GitHubActions.URL: "../notices/feed/testdata/github-changelog-actions.rss.xml"} - archive := &kittest.Archive{T: t, Pages: saved} - got := kittest.IngestWith(t, kittest.Env(t, saved), Plugin{Feed: GitHubActions, Archiver: archive}) - kittest.CompareGolden(t, "../notices/testdata/golden/github-actions.json", got) -} diff --git a/plugins/openapi/openapi.go b/plugins/openapi/openapi.go index 65d686f..ef0cceb 100644 --- a/plugins/openapi/openapi.go +++ b/plugins/openapi/openapi.go @@ -56,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{{ diff --git a/plugins/removedmembers/removedmembers.go b/plugins/removedmembers/removedmembers.go deleted file mode 100644 index d012195..0000000 --- a/plugins/removedmembers/removedmembers.go +++ /dev/null @@ -1,36 +0,0 @@ -// Package removedmembers is the old import path of the migration-guide -// kind's removed-members reader, kept so code that imports it still builds. -// -// Deprecated: use plugins/migrationguide (the kind: Plugin) and -// plugins/migrationguide/members (the reader: Guide, NumPy2, Parse). This -// package only forwards to them and registers nothing; it goes once nothing -// imports it. -package removedmembers - -import ( - "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide" - "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/members" -) - -type ( - // Plugin is migrationguide.Plugin: its Guide is now any reader, a - // members.Guide among them. - Plugin = migrationguide.Plugin - Guide = members.Guide - Format = members.Format - Removal = members.Removal -) - -const ( - FormatRST = members.FormatRST - FormatMarkdown = members.FormatMarkdown -) - -var ( - NumPy2 = members.NumPy2 - PostHog8 = members.PostHog8 - NewRelic11 = members.NewRelic11 -) - -// Parse is members.Parse. -func Parse(page []byte, g Guide) ([]Removal, error) { return members.Parse(page, g) } diff --git a/plugins/removedmembers/removedmembers_test.go b/plugins/removedmembers/removedmembers_test.go deleted file mode 100644 index 480bbdb..0000000 --- a/plugins/removedmembers/removedmembers_test.go +++ /dev/null @@ -1,16 +0,0 @@ -package removedmembers - -import ( - "testing" - - "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" -) - -// Code written against the old path still builds and runs the same source. -func TestTheOldPathStillWorks(t *testing.T) { - p := Plugin{Guide: NumPy2} - kittest.Registered(t, p) - if p.Name() != "numpy" || NumPy2.URL() == "" { - t.Errorf("Plugin{Guide: NumPy2} is %q at %q", p.Name(), NumPy2.URL()) - } -} diff --git a/plugins/retirements/retire/retire.go b/plugins/retirements/retire/retire.go deleted file mode 100644 index 200af4c..0000000 --- a/plugins/retirements/retire/retire.go +++ /dev/null @@ -1,24 +0,0 @@ -// Package retire is the old import path of github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire, -// the notices kind's deprecations-page reader. -// -// Deprecated: import github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire -// instead. This package only forwards to it, so code written against the old -// path keeps building; it goes once nothing imports it. -package retire - -import moved "github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire" - -// Deprecated: the types live in github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire. -type ( - Page = moved.Page - Retirement = moved.Retirement -) - -// Deprecated: the functions and values live in github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire. -var ( - Events = moved.Events - First = moved.First - Parse = moved.Parse - Anthropic = moved.Anthropic - OpenAI = moved.OpenAI -) diff --git a/plugins/retirements/retirements.go b/plugins/retirements/retirements.go deleted file mode 100644 index 6e4ff50..0000000 --- a/plugins/retirements/retirements.go +++ /dev/null @@ -1,13 +0,0 @@ -// Package retirements is the old import path of the notices kind for a -// model provider's deprecations page, kept so code that imports it still -// builds. -// -// Deprecated: use plugins/notices: notices.Plugin{Page: retire.OpenAI}. This -// package only forwards there and registers nothing; it goes once nothing -// imports it. -package retirements - -import "github.com/patch-it-dev/patch-it-plugins/plugins/notices" - -// Plugin is notices.Plugin: set Page and Archiver, as before. -type Plugin = notices.Plugin diff --git a/plugins/retirements/retirements_test.go b/plugins/retirements/retirements_test.go deleted file mode 100644 index 80e9b99..0000000 --- a/plugins/retirements/retirements_test.go +++ /dev/null @@ -1,17 +0,0 @@ -package retirements - -import ( - "testing" - - "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" - "github.com/patch-it-dev/patch-it-plugins/plugins/retirements/retire" -) - -// Code written against the old paths still builds and runs the same source. -func TestTheOldPathStillWorks(t *testing.T) { - p := Plugin{Page: retire.OpenAI} - kittest.Registered(t, p) - if p.Name() != "openai-models" { - t.Errorf("Plugin{Page: retire.OpenAI} is %q", p.Name()) - } -} From a36eb227e6863ab32077db856be43fe59079b9ae Mon Sep 17 00:00:00 2001 From: adssib <75389300+adssib@users.noreply.github.com> Date: Fri, 20 Nov 2026 18:40:31 -0500 Subject: [PATCH 11/16] one event type, sources named by their id, no replay, no legacy flags - core/event: the v1 ChangeEvent, its fingerprint and core/migrate are gone; every reader builds event.Event (was EventV2) directly. api_operation's kind type is event.Kind. - A source's plugin is named by its id, provider/source, and its events carry that id in api. The old slugs, Alias/Aliases/first_name, Register by slug and Lookup by slug are gone; RegisterProvider refuses a plugin whose Name isn't its source's id. plugins.json drops alias, first_name and aliases. - Replay, Replayer and Spec.Replay are gone: a version pair is ReadAt twice and Extract (kittest.Pair in tests). catalog gains ListVersions, ReadAt and Extract, so every kind is read version by version. - new-plugin: --format, --api and the old meanings of --provider and --source are gone; files are named -. Goldens regenerated on purpose: api is now the source id, and since the fingerprint hashes api, every fingerprint changed with it. Checked with a script: old and new goldens are identical once api and fingerprint are set aside (three normalize goldens also move from v1's affected to subject). Two notices goldens are renamed to their id (cloudflare-api.json, google-vertex-ai-models.json). Co-Authored-By: Claude Opus 5.5 Signed-off-by: adssib <75389300+adssib@users.noreply.github.com> --- .github/workflows/CI_contract.yml | 2 +- Makefile | 2 +- cmd/list-plugins/main.go | 2 +- cmd/new-plugin/formats.go | 100 ++-- cmd/new-plugin/main.go | 166 ++----- cmd/new-plugin/main_test.go | 22 +- cmd/new-plugin/resolve.go | 23 +- core/event/event.go | 331 ++++++++++--- core/event/event_test.go | 320 +++++------- core/event/v2.go | 262 ---------- core/event/v2_test.go | 147 ------ core/hint/hint.go | 6 +- core/hint/hint_test.go | 16 +- core/kit/kit_test.go | 2 +- core/kit/kittest/checksink.go | 42 +- core/kit/kittest/kittest.go | 14 +- core/kit/kittest/mem.go | 59 +-- core/kit/kittest/mem_test.go | 6 +- core/migrate/migrate.go | 120 ----- core/migrate/migrate_test.go | 137 ------ core/normalize/golden_test.go | 2 +- core/normalize/normalize.go | 29 +- core/normalize/normalize_test.go | 12 +- .../breaking-property-removed/events.json | 7 +- .../testdata/golden/deprecation/events.json | 7 +- .../testdata/golden/new-endpoint/events.json | 7 +- core/plugin/plugin.go | 58 +-- core/plugin/plugin_test.go | 50 +- core/plugin/provider.go | 45 +- core/plugin/provider_test.go | 43 +- core/plugin/versions.go | 9 +- docs/plugins.schema.json | 7 +- internal/pluginlist/pluginlist.go | 19 +- internal/pluginlist/pluginlist_test.go | 8 +- plugins/all/all_test.go | 25 +- plugins/apisurface/apisurface.go | 21 +- plugins/apisurface/apisurface_test.go | 2 +- .../testdata/golden/openai-1.1.2.json | 8 +- plugins/catalog/catalog.go | 61 +-- plugins/catalog/catalog_test.go | 8 +- plugins/changelog/changelog.go | 19 +- plugins/changelog/json.go | 14 +- .../testdata/golden/mongodb-atlas.json | 324 ++++++------- .../testdata/golden/textual-0.86.0.json | 8 +- .../testdata/golden/urllib3-2.0.0.json | 48 +- plugins/migrationguide/members/members.go | 20 +- .../migrationguide/members/members_test.go | 4 +- plugins/migrationguide/members/newrelic.go | 1 + .../migrationguide/members/newrelic_test.go | 6 +- plugins/migrationguide/members/posthog.go | 1 + .../migrationguide/members/posthog_test.go | 4 +- plugins/migrationguide/migrationguide.go | 16 +- plugins/migrationguide/sdkguide/sdkguide.go | 45 +- .../migrationguide/sdkguide/sdkguide_test.go | 5 +- plugins/migrationguide/sdkguide/versions.go | 16 +- .../testdata/golden/anthropic-1.0.0.json | 12 +- .../testdata/golden/newrelic-11.0.0.json | 28 +- .../testdata/golden/numpy-2.0.0.json | 224 ++++----- .../testdata/golden/posthog-8.0.0.json | 28 +- plugins/notices/eol/eol.go | 18 +- plugins/notices/feed/cloudflare_test.go | 2 +- plugins/notices/feed/feed.go | 14 +- plugins/notices/feed/readers.go | 8 +- plugins/notices/feed_golden_test.go | 3 +- plugins/notices/notices.go | 26 +- plugins/notices/retire/notices.go | 11 +- plugins/notices/retire/providers.go | 20 +- plugins/notices/retire/retire.go | 55 ++- plugins/notices/retire/retire_test.go | 18 +- plugins/notices/retirements_golden_test.go | 3 +- .../testdata/golden/anthropic-models.json | 80 +-- .../{cloudflare.json => cloudflare-api.json} | 456 +++++++++--------- .../testdata/golden/github-actions.json | 12 +- ...dels.json => google-vertex-ai-models.json} | 140 +++--- .../testdata/golden/openai-models.json | 240 ++++----- .../notices/testdata/golden/salesforce.json | 136 +++--- plugins/openapi/adapter/adapter.go | 2 +- plugins/openapi/adapter/algolia.go | 2 +- plugins/openapi/adapter/algolia_test.go | 2 +- plugins/openapi/adapter/appwrite.go | 4 +- plugins/openapi/adapter/convex.go | 2 +- plugins/openapi/adapter/datadog.go | 2 +- plugins/openapi/adapter/elasticsearch.go | 2 +- plugins/openapi/adapter/flagsmith.go | 2 +- plugins/openapi/adapter/github.go | 2 +- plugins/openapi/adapter/gitlab.go | 2 +- plugins/openapi/adapter/neon.go | 2 +- plugins/openapi/adapter/planetscale.go | 2 +- plugins/openapi/adapter/sentry.go | 2 +- plugins/openapi/adapter/stripe.go | 2 +- plugins/openapi/adapter/supabase.go | 2 +- plugins/openapi/adapter/vercel.go | 2 +- plugins/openapi/algolia_test.go | 12 +- plugins/openapi/appwrite_test.go | 6 +- plugins/openapi/convex_test.go | 8 +- plugins/openapi/datadog_test.go | 6 +- plugins/openapi/elasticsearch_test.go | 10 +- plugins/openapi/flagsmith_test.go | 6 +- plugins/openapi/github_test.go | 6 +- plugins/openapi/gitlab_test.go | 2 +- plugins/openapi/neon_test.go | 12 +- plugins/openapi/openapi.go | 35 +- plugins/openapi/openapi_test.go | 10 +- plugins/openapi/planetscale_test.go | 6 +- plugins/openapi/sentry_test.go | 10 +- plugins/openapi/supabase_test.go | 12 +- .../testdata/golden/algolia-ingestion.json | 32 +- .../testdata/golden/algolia-search.json | 36 +- plugins/openapi/testdata/golden/appwrite.json | 56 +-- plugins/openapi/testdata/golden/convex.json | 24 +- .../testdata/golden/elasticsearch.json | 32 +- .../openapi/testdata/golden/flagsmith.json | 12 +- plugins/openapi/testdata/golden/neon.json | 4 +- .../openapi/testdata/golden/planetscale.json | 20 +- plugins/openapi/testdata/golden/sentry.json | 48 +- plugins/openapi/testdata/golden/supabase.json | 8 +- plugins/openapi/testdata/golden/vercel.json | 24 +- plugins/openapi/vercel_test.go | 16 +- scripts/check_contract.py | 4 +- 119 files changed, 1996 insertions(+), 2767 deletions(-) delete mode 100644 core/event/v2.go delete mode 100644 core/event/v2_test.go delete mode 100644 core/migrate/migrate.go delete mode 100644 core/migrate/migrate_test.go rename plugins/notices/testdata/golden/{cloudflare.json => cloudflare-api.json} (89%) rename plugins/notices/testdata/golden/{vertex-ai-models.json => google-vertex-ai-models.json} (89%) 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/Makefile b/Makefile index 3cd0e17..b95da4f 100644 --- a/Makefile +++ b/Makefile @@ -65,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 \ 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 69e29c6..9e3bd44 100644 --- a/cmd/new-plugin/formats.go +++ b/cmd/new-plugin/formats.go @@ -18,29 +18,10 @@ 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)" -// legacyFormats are the old --format names, each the template it is now. -var legacyFormats = map[string]string{ - "feed": "notices/feed", - "retirements": "notices/deprecations", - "migrationguide": "migrationguide/sdk", - "removedmembers": "migrationguide/members", - "changelog": "changelog/markdown", - "apichangelog": "changelog/json", - "catalog": "catalog", - "openapi": "openapi", -} - // defaultReaders are the reader --kind picks when --reader is left out. var defaultReaders = map[string]string{ "notices": "deprecations", @@ -90,7 +71,7 @@ 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{feed.{{.Ident}}.URL: file} archive := &kittest.Archive{T: t, Pages: saved} @@ -115,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 @@ -164,7 +143,7 @@ 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} @@ -183,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 @@ -233,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}) } @@ -254,8 +231,9 @@ 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", @@ -272,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. @@ -283,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 @@ -309,7 +287,7 @@ func Test{{.Ident}}DropsANonChange(t *testing.T) { `, 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: members.{{.Ident}}}, kittest.Pages{members.{{.Ident}}.URL(): file}) } @@ -330,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", } @@ -351,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}) } @@ -386,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", @@ -410,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", } @@ -429,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", @@ -438,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) } @@ -517,14 +495,14 @@ 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) } @@ -545,7 +523,7 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { // 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{Name: "{{.PyPI}}", Ecosystem: "pypi", Module: "{{.Module}}"} +var {{.Ident}} = Package{ID: "{{.ID}}", Name: "{{.PyPI}}", Ecosystem: "pypi", Module: "{{.Module}}"} `, register: `plugin.Register(Plugin{Package: {{.Ident}}})`, pluginOf: `Plugin{Package: {{.Ident}}}`, @@ -561,7 +539,7 @@ var {{.Ident}} = Package{Name: "{{.PyPI}}", Ecosystem: "pypi", Module: "{{.Modul // 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.EventV2 { +func {{.Lower}}Ingest(t *testing.T, file string) []event.Event { t.Helper() wheel := func(src string) []byte { var buf bytes.Buffer @@ -640,10 +618,10 @@ func Test{{.Ident}}RegistersItself(t *testing.T) { // // 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 bc2b712..f508721 100644 --- a/cmd/new-plugin/main.go +++ b/cmd/new-plugin/main.go @@ -24,9 +24,8 @@ // there. `go test ./...` passes right after; every place to fill in says // TODO(new-plugin). // -// It changes nothing when the provider/source id or the first name is -// taken, or a file it would write exists. The old flags (--api, --provider -// as the name, --format, --source as the URL) still work for one release. +// It changes nothing when the provider/source id is taken, or a file it +// would write exists. package main import ( @@ -71,19 +70,16 @@ type Options struct { 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 the first name. An existing page is shared, not rewritten - API string // its first name, the old slug events carry in api; "" is - (or the provider's id when they're the same) - - // Deprecated: Format is a template ("openapi", "notices/feed") or an old - // format name ("feed"); Kind and Reader replace it. Source is the first - // URL (URLs replaces it). - Format string - Source string + 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. @@ -95,33 +91,25 @@ func (l *list) Set(v string) error { *l = append(*l, v); return nil } func main() { var o Options var urls, packages list - var provider, source string flag.StringVar(&o.Root, "root", ".", "the repo root") - flag.StringVar(&provider, "provider", "", "the provider's id, e.g. acme (with --format: its name, the old meaning)") + 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(&source, "source", "", "the source's id within the provider, e.g. api or python-sdk (with --format: its URL, the old meaning)") + 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 first name); a second source of a provider may share the existing page") - flag.StringVar(&o.API, "api", "", "the source's first name, the slug events carry in api (default: -)") - flag.StringVar(&o.Format, "format", "", "deprecated, for one release: the old format names ("+strings.Join(legacyNames(), ", ")+"), with --api, --provider and --source ") + 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 o.Format != "" { - o.Provider, o.Source = provider, source - } else { - o.ProviderID, o.SourceID = provider, source - if term() { - if err := ask(&o, bufio.NewReader(os.Stdin), os.Stdout); err != nil { - fmt.Fprintln(os.Stderr, "new-plugin:", err) - os.Exit(1) - } + 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() @@ -171,15 +159,6 @@ func readerHelp() string { return strings.Join(parts, "; ") } -func legacyNames() []string { - var names []string - for n := range legacyFormats { - names = append(names, n) - } - slices.Sort(names) - return names -} - func categories() []string { var out []string for _, c := range plugin.Categories() { @@ -188,18 +167,8 @@ func categories() []string { return out } -// template is the template o asks for: from --kind and --reader, or the -// deprecated --format. +// template is the template o asks for: from --kind and --reader. func (o Options) template() (string, error) { - if o.Format != "" { - if t, ok := legacyFormats[o.Format]; ok { - return t, nil - } - if _, ok := formats[o.Format]; ok { - return o.Format, nil - } - return "", fmt.Errorf("--format %q: want one of %s", o.Format, strings.Join(legacyNames(), ", ")) - } if !slices.Contains(kindNames(), o.Kind) { return "", fmt.Errorf("--kind %q: want one of %s", o.Kind, strings.Join(kindNames(), ", ")) } @@ -223,10 +192,10 @@ var ( // data is what the templates fill in. type data struct { - ID, Ident, Lower, 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 + 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 source, or changes nothing and says why. @@ -235,13 +204,15 @@ func Run(o Options, out io.Writer) error { if err != nil { return err } - o.Format = tmpl + 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) @@ -252,15 +223,10 @@ 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 == "" && len(o.URLs) > 0 { - o.Source = o.URLs[0] - } - if o.Source == "" { - o.Source = "https://example.com/TODO-" + o.API + "-source" - } if len(o.URLs) == 0 { - o.URLs = []string{o.Source} + 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) @@ -283,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 { @@ -291,14 +257,11 @@ 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 source named %q is already registered: pick another --api (the first name)", o.API) - } - if _, ok := plugin.LookupSource(o.ProviderID + "/" + o.SourceID); ok { - return fmt.Errorf("source %s/%s is already registered: pick another --source", o.ProviderID, o.SourceID) + 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, Kind: f.kind, PyPI: 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 @@ -306,9 +269,9 @@ func Run(o Options, out io.Writer) error { } } d.Module = strings.ReplaceAll(strings.ToLower(d.PyPI), "-", "_") - d.Ident = ident(o.API) + 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) @@ -324,7 +287,7 @@ func Run(o Options, out io.Writer) error { 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)) @@ -342,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) @@ -354,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} { @@ -374,17 +337,12 @@ func Run(o Options, out io.Writer) error { } else if ok { edits[filepath.Join("plugins", "all", "all.go")] = all } - 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 - } - } 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) } @@ -407,7 +365,7 @@ func Run(o Options, out io.Writer) error { paths = append(paths, path) } slices.Sort(paths) - fmt.Fprintf(out, "Scaffolded %s/%s (%s, first name %s, kind %s):\n", o.ProviderID, o.SourceID, o.Provider, o.API, o.Format) + fmt.Fprintf(out, "Scaffolded %s (%s, kind %s):\n", id, o.Provider, o.tmpl) for _, p := range paths { fmt.Fprintln(out, " "+p) } @@ -421,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 @@ -495,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) } } } @@ -606,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) { @@ -690,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")) @@ -705,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 087e8f6..1ee9952 100644 --- a/cmd/new-plugin/main_test.go +++ b/cmd/new-plugin/main_test.go @@ -47,7 +47,7 @@ func TestScaffoldEveryKind(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 { @@ -81,7 +81,7 @@ func TestScaffoldEveryKind(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) } @@ -107,17 +107,13 @@ func TestRefusesBadInput(t *testing.T) { "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"}}, - "first name taken": {ProviderID: "acme", Provider: "Acme", SourceID: "api", Kind: "openapi", API: "stripe"}, - "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"}, + "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 { diff --git a/cmd/new-plugin/resolve.go b/cmd/new-plugin/resolve.go index 7b3ab38..99612db 100644 --- a/cmd/new-plugin/resolve.go +++ b/cmd/new-plugin/resolve.go @@ -8,28 +8,15 @@ import ( "io" "os" "path/filepath" - "regexp" "slices" "strings" "github.com/patch-it-dev/patch-it-plugins/core/plugin" ) -// resolve fills in the provider and source from the registry and the -// flags: a registered provider's name, category and homepage, the first -// name, and, for the deprecated flags, the ids from the name and --api. +// resolve fills in the provider from the registry: a registered provider's +// name, category and homepage. func (o *Options) resolve() error { - if o.ProviderID == "" && o.Provider != "" { // the old flags: --provider is the name - o.ProviderID = strings.Trim(regexp.MustCompile(`[^a-z0-9]+`).ReplaceAllString(strings.ToLower(o.Provider), "-"), "-") - for _, p := range plugin.Providers() { - if strings.EqualFold(p.Name, o.Provider) { - o.ProviderID = p.ID - } - } - if o.SourceID == "" { - o.SourceID = strings.TrimPrefix(o.API, o.ProviderID+"-") - } - } if !validID.MatchString(o.ProviderID) { return fmt.Errorf("--provider %q: want the provider's id, lowercase letters, digits and single hyphens (acme)", o.ProviderID) } @@ -55,12 +42,6 @@ func (o *Options) resolve() error { return fmt.Errorf("--homepage %q: want an https URL", o.Homepage) } } - if o.API == "" { - o.API = o.ProviderID + "-" + o.SourceID - if o.SourceID == o.ProviderID { - o.API = o.ProviderID - } - } return nil } 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/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..f17770c 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 { @@ -110,19 +110,19 @@ 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) { +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/migrate/migrate.go b/core/migrate/migrate.go deleted file mode 100644 index 4cc5b0f..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/notices/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..cc34ef6 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 v2 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 085b8f7..f0a4644 100644 --- a/core/plugin/provider.go +++ b/core/plugin/provider.go @@ -115,9 +115,8 @@ type Source struct { // 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 old slug ("algolia-search"): - // what `--api` selects and every event's `api` carries until patch-it's - // change-event contract switches to source ids. + // Plugin runs it. Its Name is the source's id ("algolia/search-api"), + // which every event's `api` carries. Plugin Plugin } @@ -130,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()) @@ -151,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 @@ -180,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 } } @@ -208,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) == "": @@ -277,11 +263,6 @@ func Sources() []SourceInfo { return out } -// Aliases are the other names a source answers to (Lookup, LookupSource): -// today its first name, the old slug ("algolia-search"), which events carry -// in `api` and fingerprints hash. -func (s SourceInfo) Aliases() []string { return []string{s.Alias()} } - // 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. @@ -295,14 +276,10 @@ func ForPackage(pkg string) []SourceInfo { return out } -// LookupSource finds a source by its full id ("algolia/search-api") or its -// old slug ("algolia-search"). +// 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 6311bf4..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")}}, @@ -77,24 +84,24 @@ 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, and a source answers to its first name. +// A package names its sources. func TestForPackage(t *testing.T) { - s := src("pkg", "acme-test-pkg") + 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" || strings.Join(got[0].Aliases(), ",") != "acme-test-pkg" { + if len(got) != 1 || got[0].FullID() != "acme-test/pkg" { t.Errorf("ForPackage = %+v", got) } if got := ForPackage("pypi:nobody"); len(got) != 0 { 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/docs/plugins.schema.json b/docs/plugins.schema.json index c5af222..7b1ab8d 100644 --- a/docs/plugins.schema.json +++ b/docs/plugins.schema.json @@ -32,13 +32,10 @@ "type": "array", "items": { "type": "object", - "required": ["id", "alias", "first_name", "aliases", "kind", "layer", "watches", "urls", "packages", "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." }, - "first_name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9.-]*$", "description": "The source's first name, its old slug: what fingerprints keep hashing after the contract switches to source ids." }, - "aliases": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9.-]*$" }, "description": "Every other name the source answers to." }, + "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"] }, diff --git a/internal/pluginlist/pluginlist.go b/internal/pluginlist/pluginlist.go index d4bb2e5..bde7fda 100644 --- a/internal/pluginlist/pluginlist.go +++ b/internal/pluginlist/pluginlist.go @@ -38,16 +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 - FirstName string `json:"first_name"` // the same old slug, by the name fingerprints keep hashing after the switch - Aliases []string `json:"aliases"` // every other name the source answers to - 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 + 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 @@ -69,7 +66,7 @@ func Build(ref string) File { for _, s := range p.Sources { info := plugin.SourceInfo{Provider: p, Source: s} out.Sources = append(out.Sources, Source{ - ID: info.FullID(), Alias: info.Alias(), FirstName: info.Alias(), Aliases: info.Aliases(), + 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, }) 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/plugins/all/all_test.go b/plugins/all/all_test.go index 998da1c..27cbde5 100644 --- a/plugins/all/all_test.go +++ b/plugins/all/all_test.go @@ -80,30 +80,19 @@ 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()) } } - 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) - } + if len(plugin.Names()) != len(plugin.Sources()) { + t.Errorf("%d plugins, %d sources", len(plugin.Names()), len(plugin.Sources())) } } diff --git a/plugins/apisurface/apisurface.go b/plugins/apisurface/apisurface.go index 66f9114..1894165 100644 --- a/plugins/apisurface/apisurface.go +++ b/plugins/apisurface/apisurface.go @@ -48,20 +48,21 @@ func init() { // Package is one published package. type Package struct { - Name string // on the registry, and the events' api: "openai" + 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{Name: "openai", Ecosystem: "pypi", Module: "openai"} +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.Name } +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 @@ -75,7 +76,7 @@ func (p Plugin) Run(ctx context.Context, env plugin.Env) (plugin.Result, error) return plugin.Result{}, fmt.Errorf("%s: no release listed", p.Package.Name) } v := vs[len(vs)-1] - last, err := env.Baselines.LastSpec(p.Package.Name) + 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) } @@ -95,7 +96,7 @@ 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.Package.Name, v.ID, v.Ref, to.SourceURL, to.Content, false, env.Now().UTC())} + res.Baselines = []plugin.Spec{plugin.Baseline(p.Package.ID, v.ID, v.Ref, to.SourceURL, to.Content, env.Now().UTC())} return res, nil } @@ -164,7 +165,7 @@ func (p Plugin) Extract(_ context.Context, env plugin.Env, from, to plugin.Snaps 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.EventV2 + var events []event.Event var rejected []error for _, c := range Compare(a, b) { if c.Change == "" { @@ -172,7 +173,7 @@ func (p Plugin) Extract(_ context.Context, env plugin.Env, from, to plugin.Snaps continue } e := p.event(c, from, to, a.Artifact, b.Artifact, 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", p.Package.Name, to.Version.ID, c.Symbol, err)) continue @@ -185,7 +186,7 @@ func (p Plugin) Extract(_ context.Context, env plugin.Env, from, to plugin.Snaps 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.EventV2 { +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}} @@ -207,8 +208,8 @@ func (p Plugin) event(c Change, from, to plugin.Snapshot, fromFile, toFile strin 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.EventV2{ - API: pkg.Name, + return event.Event{ + API: pkg.ID, Version: to.Version.ID, PreviousVersion: from.Version.ID, ChangeType: event.ChangeTypeBreaking, diff --git a/plugins/apisurface/apisurface_test.go b/plugins/apisurface/apisurface_test.go index eb182ba..abfcbe7 100644 --- a/plugins/apisurface/apisurface_test.go +++ b/plugins/apisurface/apisurface_test.go @@ -30,7 +30,7 @@ var saved = kittest.Pages{ } // pair lists the releases, reads 1.1.1 and 1.1.2 and extracts the pair. -func pair(t *testing.T) []event.EventV2 { +func pair(t *testing.T) []event.Event { t.Helper() ctx, env := context.Background(), kittest.Env(t, saved) p := Plugin{Package: OpenAIPython} diff --git a/plugins/apisurface/testdata/golden/openai-1.1.2.json b/plugins/apisurface/testdata/golden/openai-1.1.2.json index 903bdff..6390e70 100644 --- a/plugins/apisurface/testdata/golden/openai-1.1.2.json +++ b/plugins/apisurface/testdata/golden/openai-1.1.2.json @@ -1,8 +1,8 @@ [ { "id": 0, - "fingerprint": "sha256:9e40f3b8a0940e9ffbdd4aca7642c5bfd240930d6ed176767a90b0a44de567b2", - "api": "openai", + "fingerprint": "sha256:7c2703dd5112b040c64fd384b102f560a1205f2f540f4ec31cd8310e6a604902", + "api": "openai/python-sdk", "version": "1.1.2", "previous_version": "1.1.1", "change_type": "breaking", @@ -25,8 +25,8 @@ }, { "id": 0, - "fingerprint": "sha256:a709e97cddd82b737c84fe4ec727bc040aff0ece129f5517f30da8925b3fcdd9", - "api": "openai", + "fingerprint": "sha256:54fc59ce604c0f5bfa1b1f3886d8d79ea37963f05f2fa694ea4d7b68ad720dbd", + "api": "openai/python-sdk", "version": "1.1.2", "previous_version": "1.1.1", "change_type": "breaking", 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..7d24792 100644 --- a/plugins/catalog/catalog_test.go +++ b/plugins/catalog/catalog_test.go @@ -44,7 +44,7 @@ func TestReplayRecreatesTheRealFunctionCommandRemoval(t *testing.T) { 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) } @@ -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 { @@ -91,7 +91,7 @@ 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 { + if _, err := kittest.Pair(ctx, e, s, Plugin{Catalog: Redis}, oldRef, newRef); err != nil { t.Fatalf("second replay: %v", err) } if again, _ := s.All(); len(again) != len(events) { diff --git a/plugins/changelog/changelog.go b/plugins/changelog/changelog.go index bfbc293..d7bde86 100644 --- a/plugins/changelog/changelog.go +++ b/plugins/changelog/changelog.go @@ -65,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 @@ -85,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", } @@ -93,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", } @@ -178,7 +179,7 @@ func (p Plugin) Name() string { if p.isLog() { return p.Log.API } - return p.File.Package + return p.File.API } // Run reads the pinned release, or the newest one on the registry, and @@ -207,7 +208,7 @@ 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 } @@ -269,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 != "" { @@ -281,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, @@ -295,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/changelog/json.go b/plugins/changelog/json.go index 421bfff..dd340af 100644 --- a/plugins/changelog/json.go +++ b/plugins/changelog/json.go @@ -35,7 +35,7 @@ import ( // 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 @@ -50,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", } @@ -223,7 +223,7 @@ func (p Plugin) runLog(ctx context.Context, env plugin.Env) (plugin.Result, erro if err != nil { return plugin.Result{}, err } - res.Baselines = []plugin.Spec{plugin.Baseline(l.API, sha, sha, to.SourceURL, to.Content, false, env.Now().UTC())} + res.Baselines = []plugin.Spec{plugin.Baseline(l.API, sha, sha, to.SourceURL, to.Content, env.Now().UTC())} return res, nil } @@ -270,15 +270,15 @@ func (p Plugin) extractLog(env plugin.Env, from, to plugin.Snapshot) (plugin.Res 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}, + 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, @@ -286,7 +286,7 @@ func (p Plugin) extractLog(env plugin.Env, from, to plugin.Snapshot) (plugin.Res 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 diff --git a/plugins/changelog/testdata/golden/mongodb-atlas.json b/plugins/changelog/testdata/golden/mongodb-atlas.json index 16b42fe..cacc1ea 100644 --- a/plugins/changelog/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/migrationguide/members/members.go b/plugins/migrationguide/members/members.go index ddd25f3..7344699 100644 --- a/plugins/migrationguide/members/members.go +++ b/plugins/migrationguide/members/members.go @@ -36,7 +36,8 @@ import ( // 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 @@ -139,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", @@ -240,8 +242,8 @@ func parseRST(page []byte, g Guide) ([]Removal, error) { return out, nil } -// Slug is the events' api and the source's old slug: the PyPI name. -func (g Guide) Slug() string { return g.Package } +// Slug is the source id the events carry: "numpy/numpy". +func (g Guide) Slug() string { return g.API } // Current is the release the guide documents: what a plain run reads. func (g Guide) Current(context.Context, plugin.Env) (plugin.Version, error) { @@ -272,10 +274,10 @@ func (g Guide) GuideURL(v plugin.Version) string { // 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) (_ []event.ChangeEvent, events []event.EventV2, rejected []error, err error) { +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 nil, nil, nil, err + return nil, nil, err } for _, r := range removals { if r.Dropped != "" { @@ -293,8 +295,8 @@ func (g Guide) Read(page []byte, from, _ plugin.Version, now time.Time) (_ []eve 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, + e := event.Event{ + API: g.API, PreviousVersion: from.ID, Version: g.Release, ChangeType: event.ChangeTypeBreaking, @@ -307,14 +309,14 @@ func (g Guide) Read(page []byte, from, _ plugin.Version, now time.Time) (_ []eve 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 nil, events, rejected, nil + return events, rejected, nil } // absoluteLinks prefixes LinkBase to every Markdown link target in s that diff --git a/plugins/migrationguide/members/members_test.go b/plugins/migrationguide/members/members_test.go index 2cd1247..c413c77 100644 --- a/plugins/migrationguide/members/members_test.go +++ b/plugins/migrationguide/members/members_test.go @@ -78,14 +78,14 @@ func TestTheGuideStoresOneEventPerMemberAndARerunNothing(t *testing.T) { 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/migrationguide/members/newrelic.go b/plugins/migrationguide/members/newrelic.go index 7a3baf0..a4bc4fb 100644 --- a/plugins/migrationguide/members/newrelic.go +++ b/plugins/migrationguide/members/newrelic.go @@ -62,6 +62,7 @@ package members // 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/migrationguide/members/newrelic_test.go b/plugins/migrationguide/members/newrelic_test.go index 9115acb..bf00468 100644 --- a/plugins/migrationguide/members/newrelic_test.go +++ b/plugins/migrationguide/members/newrelic_test.go @@ -42,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) @@ -190,7 +190,7 @@ 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 { @@ -234,7 +234,7 @@ 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, migrationguide.Plugin{Guide: NewRelic11}, kittest.Pages{NewRelic11.URL(): newrelicSource}) } diff --git a/plugins/migrationguide/members/posthog.go b/plugins/migrationguide/members/posthog.go index d35b74e..c22c1f3 100644 --- a/plugins/migrationguide/members/posthog.go +++ b/plugins/migrationguide/members/posthog.go @@ -56,6 +56,7 @@ package members // 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/migrationguide/members/posthog_test.go b/plugins/migrationguide/members/posthog_test.go index 44b8dee..f082ee4 100644 --- a/plugins/migrationguide/members/posthog_test.go +++ b/plugins/migrationguide/members/posthog_test.go @@ -38,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) } @@ -234,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, migrationguide.Plugin{Guide: PostHog8}, kittest.Pages{PostHog8.URL(): posthogSource}) } diff --git a/plugins/migrationguide/migrationguide.go b/plugins/migrationguide/migrationguide.go index 15e8fa6..ab63625 100644 --- a/plugins/migrationguide/migrationguide.go +++ b/plugins/migrationguide/migrationguide.go @@ -17,7 +17,6 @@ import ( "time" "github.com/patch-it-dev/patch-it-plugins/core/event" - "github.com/patch-it-dev/patch-it-plugins/core/migrate" "github.com/patch-it-dev/patch-it-plugins/core/plugin" "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/members" "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/sdkguide" @@ -70,7 +69,7 @@ func init() { // guide is at each, and how its table reads. sdkguide.Guide and // members.Guide are the two readers. type Guide interface { - // Slug is the events' api and the source's old slug: "anthropic". + // 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. @@ -81,9 +80,9 @@ type Guide interface { // 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: v1 events (converted here) or v2 ones, 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) (v1 []event.ChangeEvent, v2 []event.EventV2, rejected []error, err error) + // 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. @@ -107,7 +106,7 @@ 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.Name(), 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 } @@ -136,12 +135,11 @@ func (p Plugin) Extract(_ context.Context, env plugin.Env, from, to plugin.Snaps if to.Content == nil { return plugin.Result{Label: to.Version.ID}, nil } - v1, v2, rejected, err := p.Guide.Read(to.Content, from.Version, to.Version, env.Now().UTC()) + 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", to.SourceURL, err) } - converted, invalid := migrate.Fresh(v1) - return plugin.Result{Label: to.SourceURL, Events: append(converted, v2...), Rejected: append(rejected, invalid...)}, nil + 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 index 592daab..4174213 100644 --- a/plugins/migrationguide/sdkguide/versions.go +++ b/plugins/migrationguide/sdkguide/versions.go @@ -12,7 +12,7 @@ import ( // What the migration-guide kind (plugins/migrationguide) asks of a guide. -// Slug is the events' api and the source's old slug: the SDK's PyPI name. +// 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 @@ -21,7 +21,7 @@ func (g Guide) Releases(ctx context.Context, env plugin.Env) ([]plugin.Version, if g.Major != 0 { return []plugin.Version{{ID: g.Version(), Ref: "v" + g.Version()}}, nil } - vs, err := versions.PyPIReleases(ctx, env.Get, g.API) + vs, err := versions.PyPIReleases(ctx, env.Get, g.Package) if err != nil { return nil, err } @@ -62,21 +62,19 @@ func (g Guide) GuideURL(v plugin.Version) string { return g.At(versions.Major(v.ID)).URL() } -// Read is an event per request parameter the to major removed, read from -// its guide, with previous_version from's release. They're v1 events -// (the kind converts them to v2: core/migrate reads this package, so it -// can't be called from here). -func (g Guide) Read(page []byte, from, to plugin.Version, now time.Time) (v1 []event.ChangeEvent, _ []event.EventV2, rejected []error, err error) { +// 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, nil, err + return nil, nil, err } events, errs := Events(g, removals, now) for i := range events { events[i].PreviousVersion = from.ID } - return events, nil, errs, nil + return events, errs, nil } // FirstOfMajor is true for X.0.0, the release a major's guide is tagged at. 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/migrationguide/testdata/golden/newrelic-11.0.0.json b/plugins/migrationguide/testdata/golden/newrelic-11.0.0.json index 4d1544f..0cd06f3 100644 --- a/plugins/migrationguide/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/migrationguide/testdata/golden/numpy-2.0.0.json b/plugins/migrationguide/testdata/golden/numpy-2.0.0.json index aaddc0d..991600d 100644 --- a/plugins/migrationguide/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/migrationguide/testdata/golden/posthog-8.0.0.json b/plugins/migrationguide/testdata/golden/posthog-8.0.0.json index 4439b59..83330ff 100644 --- a/plugins/migrationguide/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/notices/eol/eol.go b/plugins/notices/eol/eol.go index 823b707..76d85d8 100644 --- a/plugins/notices/eol/eol.go +++ b/plugins/notices/eol/eol.go @@ -38,7 +38,7 @@ import ( // 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 @@ -58,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 + "/" }, } @@ -178,7 +178,7 @@ type Read []Finding // Count is how many findings the page gave. func (r Read) Count() int { return len(r) } -// Slug is the events' api: "salesforce". +// Slug is the source id the events carry: "salesforce/rest-api". func (pg Page) Slug() string { return pg.API } // PageURL is the page, as HTML. @@ -197,22 +197,22 @@ 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.ChangeEvent, []event.EventV2, []error) { - var events []event.EventV2 +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 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), }, @@ -223,14 +223,14 @@ func (pg Page) Events(found kit.Notices, citeURL string, now time.Time) ([]event 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) } - return nil, events, rejected + return events, rejected } func describe(pg Page, f Finding) string { diff --git a/plugins/notices/feed/cloudflare_test.go b/plugins/notices/feed/cloudflare_test.go index 83d23fe..2989a10 100644 --- a/plugins/notices/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/feed.go b/plugins/notices/feed/feed.go index a4a40d7..59f5deb 100644 --- a/plugins/notices/feed/feed.go +++ b/plugins/notices/feed/feed.go @@ -31,7 +31,7 @@ import ( // Feed is one vendor feed and how to read its entries. type Feed struct { - API string // the events' api: "github-actions" + API string // the source id the events carry: "github/actions" Vendor string // for sentences: "GitHub" URL string // the feed itself Read Reader @@ -75,7 +75,7 @@ type Findings []Finding // Count is how many findings the feed gave. func (fs Findings) Count() int { return len(fs) } -// Slug is the events' api: "github-actions". +// Slug is the source id the events carry: "github/actions". func (f Feed) Slug() string { return f.API } // PageURL is the feed itself. @@ -89,15 +89,15 @@ func (f Feed) Find(b []byte) (kit.Notices, error) { // 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.ChangeEvent, []event.EventV2, []error) { - var events []event.EventV2 +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.EventV2{ + e := event.Event{ API: f.API, Version: fd.Version, ChangeType: fd.ChangeType, @@ -110,12 +110,12 @@ func (f Feed) Events(found kit.Notices, citeURL string, now time.Time) ([]event. 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", f.API, fd.Entry, err)) continue } events = append(events, e) } - return nil, events, rejected + return events, rejected } diff --git a/plugins/notices/feed/readers.go b/plugins/notices/feed/readers.go index b343708..2e69318 100644 --- a/plugins/notices/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/notices/feed_golden_test.go b/plugins/notices/feed_golden_test.go index 05a986e..40953b0 100644 --- a/plugins/notices/feed_golden_test.go +++ b/plugins/notices/feed_golden_test.go @@ -1,6 +1,7 @@ package notices import ( + "strings" "testing" "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" @@ -27,7 +28,7 @@ func TestFeedsGolden(t *testing.T) { if archive.Calls != 1 { t.Errorf("%d snapshots, want 1", archive.Calls) } - kittest.Golden(t, "testdata/golden/"+c.feed.API+".json", got) + kittest.Golden(t, "testdata/golden/"+strings.ReplaceAll(c.feed.API, "/", "-")+".json", got) }) } } diff --git a/plugins/notices/notices.go b/plugins/notices/notices.go index 03f160c..a01d8a9 100644 --- a/plugins/notices/notices.go +++ b/plugins/notices/notices.go @@ -24,7 +24,6 @@ import ( "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/migrate" "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" @@ -95,16 +94,15 @@ func init() { // Page is one live page of notices and how it reads: retire.Page, // feed.Feed and eol.Page. type Page interface { - // Slug is the events' api and the source's old slug: "openai-models". + // 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: v1 events - // (converted here) or v2 ones, and the notices that failed to become - // events. - Events(found kit.Notices, citeURL string, now time.Time) (v1 []event.ChangeEvent, v2 []event.EventV2, rejected []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 @@ -165,12 +163,11 @@ func (p Plugin) Run(ctx context.Context, env plugin.Env) (plugin.Result, error) } now := env.Now().UTC() - v1, v2, rejected := pg.Events(got, snapURL, now) - converted, invalid := migrate.Fresh(v1) + 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, false, now) + baseline := plugin.Baseline(api, now.Format("2006-01-02"), snapURL, snapURL, snap, now) baseline.SHA256 = hash - return plugin.Result{Label: snapURL, Events: append(converted, v2...), Rejected: append(rejected, invalid...), Baselines: []plugin.Spec{baseline}}, nil + 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 @@ -256,15 +253,14 @@ func (p Plugin) Extract(_ context.Context, env plugin.Env, from, to plugin.Snaps return plugin.Result{Label: to.SourceURL, Events: events, Rejected: rejected}, nil } -// events reads one snapshot's notices into v2 events citing it. -func (p Plugin) events(s plugin.Snapshot, now time.Time) ([]event.EventV2, []error, error) { +// 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) } - v1, v2, rejected := p.Page.Events(found, s.SourceURL, now) - converted, invalid := migrate.Fresh(v1) - return append(converted, v2...), append(rejected, invalid...), nil + 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 index 3fb2ced..dc365f8 100644 --- a/plugins/notices/retire/notices.go +++ b/plugins/notices/retire/notices.go @@ -15,7 +15,7 @@ type Retirements []Retirement // Count is how many retirements the page lists. func (rs Retirements) Count() int { return len(rs) } -// Slug is the events' api: "openai-models". +// Slug is the source id the events carry: "openai/models". func (p Page) Slug() string { return p.API } // PageURL is the page, as markdown. @@ -27,12 +27,9 @@ func (p Page) Find(page []byte) (kit.Notices, error) { return Retirements(rs), err } -// Events are a v1 event per retired model, citing citeURL (the kind -// converts them to v2: core/migrate reads this package, so it can't be -// called from here). -func (p Page) Events(found kit.Notices, citeURL string, now time.Time) ([]event.ChangeEvent, []event.EventV2, []error) { - v1, errs := Events(p, found.(Retirements), citeURL, now) - return v1, nil, errs +// 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 diff --git a/plugins/notices/retire/providers.go b/plugins/notices/retire/providers.go index 9495561..61fbc03 100644 --- a/plugins/notices/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/notices/retire/retire.go b/plugins/notices/retire/retire.go index 1c3d673..4b5960d 100644 --- a/plugins/notices/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/notices/retire/retire_test.go b/plugins/notices/retire/retire_test.go index 02f3c20..505108e 100644 --- a/plugins/notices/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/notices/retirements_golden_test.go b/plugins/notices/retirements_golden_test.go index e3b356d..2ec3eb0 100644 --- a/plugins/notices/retirements_golden_test.go +++ b/plugins/notices/retirements_golden_test.go @@ -1,6 +1,7 @@ package notices import ( + "strings" "testing" "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" @@ -22,7 +23,7 @@ func TestRetirementsGolden(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/notices/testdata/golden/anthropic-models.json b/plugins/notices/testdata/golden/anthropic-models.json index 39f5393..911286f 100644 --- a/plugins/notices/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/notices/testdata/golden/cloudflare.json b/plugins/notices/testdata/golden/cloudflare-api.json similarity index 89% rename from plugins/notices/testdata/golden/cloudflare.json rename to plugins/notices/testdata/golden/cloudflare-api.json index ea3315b..8f49629 100644 --- a/plugins/notices/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/notices/testdata/golden/github-actions.json b/plugins/notices/testdata/golden/github-actions.json index 0892839..4b5cda7 100644 --- a/plugins/notices/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/notices/testdata/golden/vertex-ai-models.json b/plugins/notices/testdata/golden/google-vertex-ai-models.json similarity index 89% rename from plugins/notices/testdata/golden/vertex-ai-models.json rename to plugins/notices/testdata/golden/google-vertex-ai-models.json index ae9f8ec..ed7b170 100644 --- a/plugins/notices/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/notices/testdata/golden/openai-models.json b/plugins/notices/testdata/golden/openai-models.json index 49db9a7..c55deda 100644 --- a/plugins/notices/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/notices/testdata/golden/salesforce.json b/plugins/notices/testdata/golden/salesforce.json index 4d9140c..4d0c678 100644 --- a/plugins/notices/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/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 2628fb8..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]+)?$`) 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 9bd8aaf..288d249 100644 --- a/plugins/openapi/adapter/elasticsearch.go +++ b/plugins/openapi/adapter/elasticsearch.go @@ -38,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+)$`) 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..95b6191 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 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/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/algolia_test.go b/plugins/openapi/algolia_test.go index 6689e85..6fa3494 100644 --- a/plugins/openapi/algolia_test.go +++ b/plugins/openapi/algolia_test.go @@ -20,7 +20,7 @@ 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") @@ -76,7 +76,7 @@ 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 { + if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, algoliaPlugin(c.spec), c.from, c.to); err != nil || rejected { t.Fatalf("replay: rejected=%v err=%v", rejected, err) } events := kittest.Stored(t, s) @@ -113,7 +113,7 @@ 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 { + if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, algoliaPlugin("ingestion"), from, to); err != nil || rejected { t.Fatalf("replay: rejected=%v err=%v", rejected, err) } if events := kittest.Stored(t, s); len(events) != 0 { @@ -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,7 +165,7 @@ 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 { + if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, algoliaPlugin("recommend"), from, to); err != nil || rejected { t.Fatalf("replay: rejected=%v err=%v", rejected, err) } if events := kittest.Stored(t, s); len(events) != 0 { @@ -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..2a0ac82 100644 --- a/plugins/openapi/appwrite_test.go +++ b/plugins/openapi/appwrite_test.go @@ -98,10 +98,10 @@ 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 replayAppwrite(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 { + if rejected, err := kittest.Pair(context.Background(), vercelEnv(s), s, p, from, to); err != nil || rejected { t.Fatalf("replay %s -> %s: rejected=%v err=%v", from, to, rejected, err) } return kittest.Stored(t, s) @@ -160,7 +160,7 @@ func TestAppwriteDropsRemovals(t *testing.T) { p.Keep = nil var removed int for _, e := range replayAppwrite(t, p, appwrite24Old, appwrite24New) { - if e.ChangeType == event.ChangeTypeBreaking && e.Subject.Kind == event.AffectedKindOperation { + if e.ChangeType == event.ChangeTypeBreaking && e.Subject.Kind == event.KindOperation { removed++ } } diff --git a/plugins/openapi/convex_test.go b/plugins/openapi/convex_test.go index 21c7613..c548fbd 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,7 +84,7 @@ 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 { + if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, convexPlugin(""), "f35879bb", "5e5159cb"); err != nil || rejected { t.Fatalf("replay: rejected=%v err=%v", rejected, err) } events := kittest.Stored(t, s) @@ -137,7 +137,7 @@ 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 { + if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, convexPlugin(""), "3f6edf7a", "3ead9091"); err != nil || rejected { t.Fatalf("replay: rejected=%v err=%v", rejected, err) } if events := kittest.Stored(t, s); len(events) != 0 { @@ -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..e1b0c0c 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 } @@ -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 == "" { diff --git a/plugins/openapi/elasticsearch_test.go b/plugins/openapi/elasticsearch_test.go index 402ad23..9103f4e 100644 --- a/plugins/openapi/elasticsearch_test.go +++ b/plugins/openapi/elasticsearch_test.go @@ -24,7 +24,7 @@ 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") } @@ -71,7 +71,7 @@ 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 { + if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, p, "8.19", "9.0"); err != nil || rejected { t.Fatalf("replay: rejected=%v err=%v", rejected, err) } n := map[event.ChangeType]int{} @@ -92,7 +92,7 @@ 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 { + if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, esPlugin(), "8.19", "9.0"); err != nil || rejected { t.Fatalf("replay: rejected=%v err=%v", rejected, err) } events := kittest.Stored(t, s) @@ -142,7 +142,7 @@ 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 { + if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, esPlugin(), "9.1", "9.2"); err != nil || rejected { t.Fatalf("replay: rejected=%v err=%v", rejected, err) } if events := kittest.Stored(t, s); len(events) != 0 { @@ -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..921b805 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 } @@ -79,7 +79,7 @@ func TestFlagsmithGolden(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, "v2.286.0", "v2.287.0"); err != nil || rejected { + if rejected, err := kittest.Pair(ctx, env, sink, p, "v2.286.0", "v2.287.0"); err != nil || rejected { t.Fatalf("replay: rejected=%v err=%v", rejected, err) } kittest.Golden(t, "testdata/golden/flagsmith.json", kittest.Stored(t, sink)) @@ -92,7 +92,7 @@ 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 { + if rejected, err := kittest.Pair(ctx, env, sink, p, "c3ef832", "f504f16"); err != nil || rejected { t.Fatalf("replay: rejected=%v err=%v", rejected, err) } if got := kittest.Stored(t, sink); len(got) != 0 { diff --git a/plugins/openapi/github_test.go b/plugins/openapi/github_test.go index 4496f7a..00e7ea1 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 } @@ -59,8 +59,8 @@ 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 == "" { diff --git a/plugins/openapi/gitlab_test.go b/plugins/openapi/gitlab_test.go index a61851f..da2a8c6 100644 --- a/plugins/openapi/gitlab_test.go +++ b/plugins/openapi/gitlab_test.go @@ -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 { diff --git a/plugins/openapi/neon_test.go b/plugins/openapi/neon_test.go index ac726f6..aff90c4 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 } @@ -77,7 +77,7 @@ 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 { + if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, neonPlugin(fakeNeonAdapter{}), "5c57d009", "93b93dc9"); err != nil || rejected { t.Fatalf("replay: rejected=%v err=%v", rejected, err) } events := kittest.Stored(t, s) @@ -117,7 +117,7 @@ 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 { + if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, neonPlugin(fakeNeonAdapter{}), "4c6b3be4", "4497de89"); err != nil || rejected { t.Fatalf("replay: rejected=%v err=%v", rejected, err) } if events := kittest.Stored(t, s); len(events) != 0 { @@ -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,7 +178,7 @@ 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 { + if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, neonPlugin(neonAPIClient{}), "2.7.2", "2.7.3"); err != nil || rejected { t.Fatalf("replay: rejected=%v err=%v", rejected, err) } events := kittest.Stored(t, s) diff --git a/plugins/openapi/openapi.go b/plugins/openapi/openapi.go index ef0cceb..a0e3ac7 100644 --- a/plugins/openapi/openapi.go +++ b/plugins/openapi/openapi.go @@ -14,7 +14,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" @@ -250,32 +249,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 } @@ -326,15 +300,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] @@ -380,7 +353,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..0b041cd 100644 --- a/plugins/openapi/openapi_test.go +++ b/plugins/openapi/openapi_test.go @@ -48,7 +48,7 @@ func replay(ctx context.Context, s *kittest.Mem, a adapter.Adapter, from, to str } 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) + 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) } @@ -157,7 +157,7 @@ func TestReplayStoresEventsWithoutMovingTheBaseline(t *testing.T) { if got := storedEvents(t, s); len(got) != 2 { t.Errorf("replay stored %d events, want 2: %v", len(got), got) } - if last, _ := s.LastSpec("stripe"); last != nil { + if last, _ := s.LastSpec("stripe/api"); last != nil { t.Errorf("replay moved the baseline to %s; replays must never set it", last.Version) } @@ -200,7 +200,7 @@ func TestReplayAttachesMigrationHintsFromTheChangelog(t *testing.T) { t.Fatalf("replay: %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..19318c3 100644 --- a/plugins/openapi/planetscale_test.go +++ b/plugins/openapi/planetscale_test.go @@ -56,10 +56,10 @@ 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 replayPlanetScale(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 { + if rejected, err := kittest.Pair(context.Background(), vercelEnv(s), s, p, from, to); err != nil || rejected { t.Fatalf("replay %s -> %s: rejected=%v err=%v", from, to, rejected, err) } return kittest.Stored(t, s) @@ -133,7 +133,7 @@ func TestPlanetScaleDropsRemovalsThatWerentDeprecated(t *testing.T) { 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.") { + 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..6e02f4f 100644 --- a/plugins/openapi/sentry_test.go +++ b/plugins/openapi/sentry_test.go @@ -80,11 +80,11 @@ 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 replaySentry(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 { + if rejected, err := kittest.Pair(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) } } @@ -173,7 +173,7 @@ func TestSentryFlagAfterWordsIsNotNew(t *testing.T) { // moving /api/0 into the paths. type rawSentry struct{} -func (rawSentry) API() string { return "sentry" } +func (rawSentry) API() string { return "sentry/api" } func (rawSentry) LatestTag(context.Context) (string, error) { return "", fmt.Errorf("replay only") } func (rawSentry) Fetch(_ context.Context, tag string) (adapter.Spec, error) { body, err := os.ReadFile(sentryFile(tag)) @@ -195,7 +195,7 @@ func TestSentryBasePathMoveIsNoChange(t *testing.T) { // 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 { + 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") @@ -208,7 +208,7 @@ func TestSentryBasePathMoveIsNoChange(t *testing.T) { 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 { + if e.ChangeType == event.ChangeTypeBreaking && e.Subject.Kind == event.KindOperation { removed = append(removed, e.Subject.Operation) } } diff --git a/plugins/openapi/supabase_test.go b/plugins/openapi/supabase_test.go index a9ae173..52d0f27 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 } @@ -75,7 +75,7 @@ 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 { + if rejected, err := kittest.Pair(ctx, env, s, supabasePlugin(""), "693bdc38", "eb21ae25"); err != nil || rejected { t.Fatalf("replay: rejected=%v err=%v", rejected, err) } @@ -123,7 +123,7 @@ 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 { + if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, supabasePlugin(""), "8aef4a08", "90b71e3e"); err != nil || rejected { t.Fatalf("replay: rejected=%v err=%v", rejected, err) } if events := kittest.Stored(t, s); len(events) != 0 { @@ -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..9293627 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 } @@ -73,7 +73,7 @@ func TestVercelGolden(t *testing.T) { } } // The removal, replayed. - if rejected, err := kittest.Replay(ctx, env, s, vercelPlugin(""), "v1.18.6", "v1.18.7"); err != nil || rejected { + if rejected, err := kittest.Pair(ctx, env, s, vercelPlugin(""), "v1.18.6", "v1.18.7"); err != nil || rejected { t.Fatalf("replay: rejected=%v err=%v", rejected, err) } @@ -117,7 +117,7 @@ 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 { + if _, err := kittest.Pair(ctx, env, s, vercelPlugin(""), "v1.18.6", "v1.18.7"); err != nil { t.Fatalf("second replay: %v", err) } if again := kittest.Stored(t, s); len(again) != len(events) { @@ -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,7 +153,7 @@ 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 { + if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, vercelPlugin(""), "v1.6.2", "v1.6.3"); err != nil || rejected { t.Fatalf("replay: rejected=%v err=%v", rejected, err) } if events := kittest.Stored(t, s); len(events) != 0 { @@ -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 @@ -188,7 +188,7 @@ 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 { + if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, vercelPlugin(""), "v1.28.64", "v1.28.65"); err != nil || rejected { t.Fatalf("replay: rejected=%v err=%v", rejected, err) } if events := kittest.Stored(t, s); len(events) != 0 { @@ -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/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. From 04813a857c67a9c2120497583592b9218f2c0545 Mon Sep 17 00:00:00 2001 From: adssib <75389300+adssib@users.noreply.github.com> Date: Fri, 20 Nov 2026 18:40:31 -0500 Subject: [PATCH 12/16] docs: ids only, no forwarders, no v1, no replay Co-Authored-By: Claude Opus 5.5 Signed-off-by: adssib <75389300+adssib@users.noreply.github.com> --- .github/pull_request_template.md | 4 ++-- AGENTS.md | 8 ++++---- CONTRIBUTING.md | 4 ++-- docs/how-it-works.md | 4 ++-- docs/writing-a-plugin.md | 22 +++++++++++----------- plugins/notices/feed/testdata/README.md | 2 +- plugins/notices/testdata/README.md | 2 +- providers/README.md | 2 +- providers/_template.md | 4 ++-- providers/algolia.md | 2 +- providers/anthropic-models.md | 2 +- providers/anthropic.md | 2 +- providers/appwrite.md | 2 +- providers/cloudflare.md | 2 +- providers/convex.md | 2 +- providers/datadog.md | 2 +- providers/elasticsearch.md | 2 +- providers/flagsmith.md | 2 +- providers/github-actions.md | 2 +- providers/github.md | 2 +- providers/gitlab.md | 2 +- providers/mongodb-atlas.md | 2 +- providers/neon.md | 2 +- providers/newrelic.md | 2 +- providers/numpy.md | 2 +- providers/openai-models.md | 2 +- providers/openai-python-sdk.md | 2 +- providers/planetscale.md | 2 +- providers/posthog.md | 2 +- providers/redis.md | 2 +- providers/salesforce.md | 2 +- providers/sentry.md | 2 +- providers/stripe.md | 2 +- providers/supabase.md | 2 +- providers/textual.md | 2 +- providers/urllib3.md | 2 +- providers/vercel.md | 2 +- providers/vertex-ai-models.md | 2 +- 38 files changed, 55 insertions(+), 55 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 2517da6..dcf6f53 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -6,10 +6,10 @@ - [ ] **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/AGENTS.md b/AGENTS.md index 74fbfbf..d23d094 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,10 +25,10 @@ Refer to the service that runs these plugins as "patch-it's hosted ingestion ser - **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. @@ -56,7 +56,7 @@ core/github/ the newest release / commit on GitHub, and a commit's SHA 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/ core/migrate/ the change-event types from patch-it's contract (v1 + v2), v1 -> v2 +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), notices (+ retire/, feed/, eol/), migrationguide (+ sdkguide/, @@ -67,7 +67,7 @@ cmd/new-plugin/ scaffolds a provider's source on a kind (make new-plugin 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 10dfee1..f7ede16 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,10 +8,10 @@ Thanks for helping patch-it watch more APIs. This file is the rulebook; [docs/wr 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) diff --git a/docs/how-it-works.md b/docs/how-it-works.md index ba0a6f3..139265d 100644 --- a/docs/how-it-works.md +++ b/docs/how-it-works.md @@ -1,6 +1,6 @@ # 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 @@ -24,7 +24,7 @@ There's no list in this repo: `make plugins` prints every provider and source fr | [`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/), [`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/), [`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/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/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 | diff --git a/docs/writing-a-plugin.md b/docs/writing-a-plugin.md index bc7f703..4a59766 100644 --- a/docs/writing-a-plugin.md +++ b/docs/writing-a-plugin.md @@ -15,7 +15,7 @@ make new-plugin ARGS='--provider acme --name Acme --category devtools --homepage # --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), --api acme-api (the first name; default -) +# --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. @@ -23,12 +23,12 @@ Run in a terminal without the flags, it asks for them: the provider's id, then ( It writes, and lists: - 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` (plus the `core/migrate/` map entry that the deprecations-page and SDK-guide readers need), 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; +- 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 a `provider/source` id or a first name that's taken, or a file it would write that exists, and then changes nothing. The old flags (`--api acme --provider Acme --format feed --source `) still work for one release. +`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 @@ -95,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 } @@ -107,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 } @@ -129,6 +129,7 @@ Extract(ctx, env, from, to Snapshot) (Result, error) // the changes fro - **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. @@ -157,7 +158,7 @@ func init() { } ``` -`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 (its first name, which events carry in `api` and fingerprints hash). +`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. @@ -166,13 +167,12 @@ func init() { - 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 diff --git a/plugins/notices/feed/testdata/README.md b/plugins/notices/feed/testdata/README.md index d6115b7..47ec016 100644 --- a/plugins/notices/feed/testdata/README.md +++ b/plugins/notices/feed/testdata/README.md @@ -1,6 +1,6 @@ # Saved feeds -Real copies, saved once with `curl`. The golden files, `../../testdata/golden/.json`, +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/notices/testdata/README.md b/plugins/notices/testdata/README.md index 9e9ae85..fb557f5 100644 --- a/plugins/notices/testdata/README.md +++ b/plugins/notices/testdata/README.md @@ -2,6 +2,6 @@ `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/vertex-ai-models.json` and `golden/cloudflare.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). +`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/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 3b53b17..5fbd906 100644 --- a/providers/algolia.md +++ b/providers/algolia.md @@ -1,4 +1,4 @@ -# Algolia (`algolia-search`, `algolia-ingestion`, `algolia-recommend`) +# Algolia (`algolia/search-api`, `algolia/ingestion-api`, `algolia/recommend-api`) ## What it watches diff --git a/providers/anthropic-models.md b/providers/anthropic-models.md index d13782e..56ee9fc 100644 --- a/providers/anthropic-models.md +++ b/providers/anthropic-models.md @@ -1,4 +1,4 @@ -# Anthropic model retirements (`anthropic-models`) +# Anthropic model retirements (`anthropic/models`) ## What it watches diff --git a/providers/anthropic.md b/providers/anthropic.md index d67f50f..6b10823 100644 --- a/providers/anthropic.md +++ b/providers/anthropic.md @@ -1,4 +1,4 @@ -# Anthropic Python SDK (`anthropic`) +# Anthropic Python SDK (`anthropic/python-sdk`) ## What it watches diff --git a/providers/appwrite.md b/providers/appwrite.md index ea502e7..c03f918 100644 --- a/providers/appwrite.md +++ b/providers/appwrite.md @@ -1,4 +1,4 @@ -# Appwrite (`appwrite`) +# Appwrite (`appwrite/api`) ## What it watches diff --git a/providers/cloudflare.md b/providers/cloudflare.md index 9a91803..8937bd7 100644 --- a/providers/cloudflare.md +++ b/providers/cloudflare.md @@ -1,4 +1,4 @@ -# Cloudflare (`cloudflare`) +# Cloudflare (`cloudflare/api`) ## What it watches diff --git a/providers/convex.md b/providers/convex.md index fb9e7db..b6c0d34 100644 --- a/providers/convex.md +++ b/providers/convex.md @@ -1,4 +1,4 @@ -# Convex (`convex`) +# Convex (`convex/deployment-api`) ## What it watches diff --git a/providers/datadog.md b/providers/datadog.md index 3de454b..3e70326 100644 --- a/providers/datadog.md +++ b/providers/datadog.md @@ -1,4 +1,4 @@ -# Datadog (`datadog`) +# Datadog (`datadog/api`) ## What it watches diff --git a/providers/elasticsearch.md b/providers/elasticsearch.md index 36d6509..37147c7 100644 --- a/providers/elasticsearch.md +++ b/providers/elasticsearch.md @@ -1,4 +1,4 @@ -# Elasticsearch (`elasticsearch`) +# Elasticsearch (`elastic/elasticsearch-api`) ## What it watches diff --git a/providers/flagsmith.md b/providers/flagsmith.md index 89ad8d0..555cd71 100644 --- a/providers/flagsmith.md +++ b/providers/flagsmith.md @@ -1,4 +1,4 @@ -# Flagsmith (`flagsmith`) +# Flagsmith (`flagsmith/api`) ## What it watches diff --git a/providers/github-actions.md b/providers/github-actions.md index c9adb20..25076d6 100644 --- a/providers/github-actions.md +++ b/providers/github-actions.md @@ -1,4 +1,4 @@ -# GitHub Actions runner images (`github-actions`) +# GitHub Actions runner images (`github/actions`) ## What it watches diff --git a/providers/github.md b/providers/github.md index f47fd93..aad0118 100644 --- a/providers/github.md +++ b/providers/github.md @@ -1,4 +1,4 @@ -# GitHub REST API (`github`) +# GitHub REST API (`github/rest-api`) ## What it watches diff --git a/providers/gitlab.md b/providers/gitlab.md index 7556c13..354a9c6 100644 --- a/providers/gitlab.md +++ b/providers/gitlab.md @@ -1,4 +1,4 @@ -# GitLab REST API (`gitlab`) +# GitLab REST API (`gitlab/rest-api`) ## What it watches diff --git a/providers/mongodb-atlas.md b/providers/mongodb-atlas.md index c0a5143..d47dc78 100644 --- a/providers/mongodb-atlas.md +++ b/providers/mongodb-atlas.md @@ -1,4 +1,4 @@ -# MongoDB Atlas (`mongodb-atlas`) +# MongoDB Atlas (`mongodb/atlas-admin-api`) ## What it watches diff --git a/providers/neon.md b/providers/neon.md index 1724564..ce45f7e 100644 --- a/providers/neon.md +++ b/providers/neon.md @@ -1,4 +1,4 @@ -# Neon (`neon`) +# Neon (`neon/api`) ## What it watches diff --git a/providers/newrelic.md b/providers/newrelic.md index dcfdb82..9e87fc3 100644 --- a/providers/newrelic.md +++ b/providers/newrelic.md @@ -1,4 +1,4 @@ -# New Relic (`newrelic`) +# New Relic (`newrelic/python-agent`) ## What it watches diff --git a/providers/numpy.md b/providers/numpy.md index 2a0058b..32357a6 100644 --- a/providers/numpy.md +++ b/providers/numpy.md @@ -1,4 +1,4 @@ -# NumPy (`numpy`) +# NumPy (`numpy/numpy`) ## What it watches diff --git a/providers/openai-models.md b/providers/openai-models.md index 9ddceb7..a021144 100644 --- a/providers/openai-models.md +++ b/providers/openai-models.md @@ -1,4 +1,4 @@ -# OpenAI model retirements (`openai-models`) +# OpenAI model retirements (`openai/models`) ## What it watches diff --git a/providers/openai-python-sdk.md b/providers/openai-python-sdk.md index d99a51c..4d233f1 100644 --- a/providers/openai-python-sdk.md +++ b/providers/openai-python-sdk.md @@ -1,4 +1,4 @@ -# OpenAI Python SDK (`openai`) +# OpenAI Python SDK (`openai/python-sdk`) ## What it watches diff --git a/providers/planetscale.md b/providers/planetscale.md index c1e9658..40c2ae0 100644 --- a/providers/planetscale.md +++ b/providers/planetscale.md @@ -1,4 +1,4 @@ -# PlanetScale (`planetscale`) +# PlanetScale (`planetscale/api`) ## What it watches diff --git a/providers/posthog.md b/providers/posthog.md index c822b09..917620c 100644 --- a/providers/posthog.md +++ b/providers/posthog.md @@ -1,4 +1,4 @@ -# PostHog (`posthog`) +# PostHog (`posthog/python-sdk`) ## What it watches diff --git a/providers/redis.md b/providers/redis.md index b7b9a84..f118c89 100644 --- a/providers/redis.md +++ b/providers/redis.md @@ -1,4 +1,4 @@ -# Redis (`redis`) +# Redis (`redis/commands`) ## What it watches diff --git a/providers/salesforce.md b/providers/salesforce.md index 0d27ada..ddb6c19 100644 --- a/providers/salesforce.md +++ b/providers/salesforce.md @@ -1,4 +1,4 @@ -# Salesforce (`salesforce`) +# Salesforce (`salesforce/rest-api`) ## What it watches diff --git a/providers/sentry.md b/providers/sentry.md index d61f373..0d7a4af 100644 --- a/providers/sentry.md +++ b/providers/sentry.md @@ -1,4 +1,4 @@ -# Sentry (`sentry`) +# Sentry (`sentry/api`) ## What it watches diff --git a/providers/stripe.md b/providers/stripe.md index 46aee8f..9fde42b 100644 --- a/providers/stripe.md +++ b/providers/stripe.md @@ -1,4 +1,4 @@ -# Stripe (`stripe`) +# Stripe (`stripe/api`) ## What it watches diff --git a/providers/supabase.md b/providers/supabase.md index 86dae18..880226e 100644 --- a/providers/supabase.md +++ b/providers/supabase.md @@ -1,4 +1,4 @@ -# Supabase (`supabase`) +# Supabase (`supabase/management-api`) ## What it watches diff --git a/providers/textual.md b/providers/textual.md index ec6488b..602855e 100644 --- a/providers/textual.md +++ b/providers/textual.md @@ -1,4 +1,4 @@ -# Textual (`textual`) +# Textual (`textual/textual`) ## What it watches diff --git a/providers/urllib3.md b/providers/urllib3.md index d6c7e3d..7ba3bcc 100644 --- a/providers/urllib3.md +++ b/providers/urllib3.md @@ -1,4 +1,4 @@ -# urllib3 (`urllib3`) +# urllib3 (`urllib3/urllib3`) ## What it watches diff --git a/providers/vercel.md b/providers/vercel.md index 4aec983..2e16b65 100644 --- a/providers/vercel.md +++ b/providers/vercel.md @@ -1,4 +1,4 @@ -# Vercel (`vercel`) +# Vercel (`vercel/api`) ## What it watches diff --git a/providers/vertex-ai-models.md b/providers/vertex-ai-models.md index eb00d3c..b34e22c 100644 --- a/providers/vertex-ai-models.md +++ b/providers/vertex-ai-models.md @@ -1,4 +1,4 @@ -# Vertex AI generative models (`vertex-ai-models`) +# Vertex AI generative models (`google/vertex-ai-models`) ## What it watches From f901430668680e3cd038dbff64f3651e2c06715c Mon Sep 17 00:00:00 2001 From: adssib <75389300+adssib@users.noreply.github.com> Date: Fri, 20 Nov 2026 19:11:45 -0500 Subject: [PATCH 13/16] apisurface: index every class, so a leaf class's new attribute is found Co-Authored-By: Claude Opus 5.5 Signed-off-by: adssib <75389300+adssib@users.noreply.github.com> --- plugins/apisurface/apisurface_test.go | 37 ++++++++----------- plugins/apisurface/pysurface/pysurface.go | 27 +++++--------- .../apisurface/pysurface/pysurface_test.go | 8 ++-- 3 files changed, 29 insertions(+), 43 deletions(-) diff --git a/plugins/apisurface/apisurface_test.go b/plugins/apisurface/apisurface_test.go index eb182ba..c2a390f 100644 --- a/plugins/apisurface/apisurface_test.go +++ b/plugins/apisurface/apisurface_test.go @@ -216,29 +216,24 @@ func TestASkippedFileRemovesNothing(t *testing.T) { // 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. +// 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) { - self := prm("self", "either", "") - a := Release{Surface: pysurface.Surface{ - "acme.Completions": cls("class Completions(SyncAPIResource):"), - "acme.Completions.create": sym("method", self), - "acme.Completions.list": sym("method", self), - "acme.Completions.models": sym("method", self), - "acme.Completions.gone": sym("method", self), - "acme.Files": cls("class Files(SyncAPIResource):"), - "acme.Files.upload": sym("method", self), - }} - b := Release{ - Surface: pysurface.Surface{ - "acme.Completions": cls("class Completions(SyncAPIResource):"), - "acme.Files": cls("class Files(SyncAPIResource, _Uploads):"), - }, - Classes: pysurface.Classes{ - "Completions": {Bases: []string{"SyncAPIResource"}, Members: []string{"models"}}, - "SyncAPIResource": {Bases: []string{"_Base"}, Members: []string{"create"}}, - "_Base": {Members: []string{"list"}}, - }, + 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) diff --git a/plugins/apisurface/pysurface/pysurface.go b/plugins/apisurface/pysurface/pysurface.go index e934db5..61ee7ee 100644 --- a/plugins/apisurface/pysurface/pysurface.go +++ b/plugins/apisurface/pysurface/pysurface.go @@ -52,11 +52,11 @@ type Class struct { Members []string `json:"members,omitempty"` } -// Classes are the classes a method could have moved to, by name: every -// module-level class in the package (private modules and names included) -// that another class names as 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. +// 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. @@ -107,8 +107,7 @@ func Read(files []File) Surface { return out } -// ReadClasses is the package's Classes: every module-level class named as -// another class's base. +// ReadClasses is the package's Classes: every module-level class. func ReadClasses(files []File) Classes { all := map[string]*Class{} for _, m := range parseAll(files) { @@ -122,19 +121,11 @@ func ReadClasses(files []File) Classes { have.Members = appendNew(have.Members, c.Members...) } } - named := map[string]bool{} - for _, c := range all { - for _, b := range c.Bases { - named[b] = true - } - } out := Classes{} for n, c := range all { - if named[n] { - slices.Sort(c.Bases) - slices.Sort(c.Members) - out[n] = *c - } + slices.Sort(c.Bases) + slices.Sort(c.Members) + out[n] = *c } return out } diff --git a/plugins/apisurface/pysurface/pysurface_test.go b/plugins/apisurface/pysurface/pysurface_test.go index 168e80a..880b5cd 100644 --- a/plugins/apisurface/pysurface/pysurface_test.go +++ b/plugins/apisurface/pysurface/pysurface_test.go @@ -117,15 +117,15 @@ func TestRead(t *testing.T) { } } -// The class index: classes named as a base, with their bases and every name -// their bodies define; private modules and names included. +// 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 pass\n"}, + {"acme/completions.py", "from ._resource import SyncAPIResource\n\nclass Completions(base.SyncAPIResource):\n models = _models\n"}, }) got, _ := json.Marshal(c) - want := `{"SyncAPIResource":{"bases":["Generic","_Base"],"members":["_client","_create","_hidden","create"]},"_Base":{"members":["list"]}}` + 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) } From d33aac1719c1a7c51a2d30fbf222946c3569230a Mon Sep 17 00:00:00 2001 From: adssib <75389300+adssib@users.noreply.github.com> Date: Fri, 20 Nov 2026 19:12:47 -0500 Subject: [PATCH 14/16] no replay wording: tests, comments and provider pages say version pair Co-Authored-By: Claude Opus 5.5 Signed-off-by: adssib <75389300+adssib@users.noreply.github.com> --- core/kit/kittest/kittest.go | 2 +- core/plugin/plugin.go | 2 +- plugins/catalog/catalog_test.go | 12 ++++----- plugins/changelog/json_test.go | 2 +- plugins/openapi/algolia_test.go | 8 +++--- plugins/openapi/appwrite_test.go | 14 +++++----- plugins/openapi/convex_test.go | 4 +-- plugins/openapi/datadog_test.go | 18 ++++++------- plugins/openapi/elasticsearch_test.go | 8 +++--- plugins/openapi/flagsmith_test.go | 6 ++--- plugins/openapi/github_test.go | 18 ++++++------- plugins/openapi/gitlab_test.go | 24 ++++++++--------- plugins/openapi/neon_test.go | 8 +++--- plugins/openapi/openapi.go | 3 ++- plugins/openapi/openapi_test.go | 38 +++++++++++++-------------- plugins/openapi/planetscale_test.go | 10 +++---- plugins/openapi/sentry_test.go | 24 ++++++++--------- plugins/openapi/supabase_test.go | 6 ++--- plugins/openapi/vercel_test.go | 18 ++++++------- providers/appwrite.md | 2 +- providers/convex.md | 2 +- providers/datadog.md | 2 +- providers/elasticsearch.md | 2 +- providers/gitlab.md | 2 +- providers/neon.md | 2 +- providers/planetscale.md | 2 +- providers/redis.md | 4 +-- providers/sentry.md | 2 +- providers/stripe.md | 2 +- providers/supabase.md | 2 +- providers/vercel.md | 2 +- 31 files changed, 126 insertions(+), 125 deletions(-) diff --git a/core/kit/kittest/kittest.go b/core/kit/kittest/kittest.go index f17770c..8437690 100644 --- a/core/kit/kittest/kittest.go +++ b/core/kit/kittest/kittest.go @@ -109,7 +109,7 @@ func Stored(t testing.TB, s Sink) []event.Event { } // 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. +// -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) diff --git a/core/plugin/plugin.go b/core/plugin/plugin.go index cc34ef6..f5a623b 100644 --- a/core/plugin/plugin.go +++ b/core/plugin/plugin.go @@ -66,7 +66,7 @@ type Spec struct { // 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.Event // valid v2 events, to store + 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 } diff --git a/plugins/catalog/catalog_test.go b/plugins/catalog/catalog_test.go index 7d24792..c827f76 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) { +func TestPairRecreatesTheRealFunctionCommandRemoval(t *testing.T) { ctx := context.Background() s := kittest.NewMem() e := env(s, fixturePages(), t) 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() @@ -90,12 +90,12 @@ func TestReplayRecreatesTheRealFunctionCommandRemoval(t *testing.T) { } } - // Replaying the same pair again must not duplicate the events. + // 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 replay: %v", err) + 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/json_test.go b/plugins/changelog/json_test.go index e065056..c00d89a 100644 --- a/plugins/changelog/json_test.go +++ b/plugins/changelog/json_test.go @@ -149,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}` } diff --git a/plugins/openapi/algolia_test.go b/plugins/openapi/algolia_test.go index 6fa3494..edc34ef 100644 --- a/plugins/openapi/algolia_test.go +++ b/plugins/openapi/algolia_test.go @@ -23,7 +23,7 @@ type fakeAlgoliaAdapter struct{ spec string } 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) { @@ -77,7 +77,7 @@ func TestAlgoliaGolden(t *testing.T) { ctx := context.Background() s := openStore(t) if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, algoliaPlugin(c.spec), c.from, c.to); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + t.Fatalf("pair: rejected=%v err=%v", rejected, err) } events := kittest.Stored(t, s) if len(events) != c.ops { @@ -114,7 +114,7 @@ func TestAlgoliaDropsRemovalsThatWerentDeprecated(t *testing.T) { const from, to = "released-2024-09-18-cc190fae3", "released-2024-09-19-a62c27d3b" s := openStore(t) if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, algoliaPlugin("ingestion"), from, to); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + 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)) @@ -166,7 +166,7 @@ func TestAlgoliaRecommendCustomRequestMoveIsNoEvent(t *testing.T) { const from, to = "released-2024-03-19-2eac6f410", "released-2024-03-25-30207fcd0" s := openStore(t) if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, algoliaPlugin("recommend"), from, to); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + 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)) diff --git a/plugins/openapi/appwrite_test.go b/plugins/openapi/appwrite_test.go index 2a0ac82..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.Event { +func pairAppwrite(t *testing.T, p Plugin, from, to string) []event.Event { t.Helper() s := openStore(t) if rejected, err := kittest.Pair(context.Background(), vercelEnv(s), s, p, from, to); err != nil || rejected { - t.Fatalf("replay %s -> %s: rejected=%v err=%v", from, to, rejected, err) + 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,13 +153,13 @@ 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) { + 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 c548fbd..098d8ca 100644 --- a/plugins/openapi/convex_test.go +++ b/plugins/openapi/convex_test.go @@ -85,7 +85,7 @@ func TestConvexGolden(t *testing.T) { ctx := context.Background() s := openStore(t) if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, convexPlugin(""), "f35879bb", "5e5159cb"); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + t.Fatalf("pair: rejected=%v err=%v", rejected, err) } events := kittest.Stored(t, s) if len(events) != len(convexReplacements) { @@ -138,7 +138,7 @@ func TestConvexDropsPropertyChangesThatWerentDeprecations(t *testing.T) { ctx := context.Background() s := openStore(t) if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, convexPlugin(""), "3f6edf7a", "3ead9091"); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + 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)) diff --git a/plugins/openapi/datadog_test.go b/plugins/openapi/datadog_test.go index e1b0c0c..fa486e5 100644 --- a/plugins/openapi/datadog_test.go +++ b/plugins/openapi/datadog_test.go @@ -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() @@ -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 9103f4e..10ec11a 100644 --- a/plugins/openapi/elasticsearch_test.go +++ b/plugins/openapi/elasticsearch_test.go @@ -26,7 +26,7 @@ type fakeESAdapter struct{} 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 { @@ -72,7 +72,7 @@ func TestElasticsearchNoRemovalWithinAMinor(t *testing.T) { p := esPlugin() p.Adapter = sameMinor{} if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, p, "8.19", "9.0"); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + t.Fatalf("pair: rejected=%v err=%v", rejected, err) } n := map[event.ChangeType]int{} for _, e := range kittest.Stored(t, s) { @@ -93,7 +93,7 @@ func TestElasticsearchGolden(t *testing.T) { ctx := context.Background() s := openStore(t) if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, esPlugin(), "8.19", "9.0"); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + t.Fatalf("pair: rejected=%v err=%v", rejected, err) } events := kittest.Stored(t, s) byType := map[event.ChangeType][]string{} @@ -143,7 +143,7 @@ func TestElasticsearchDropsUndeprecatedRemovals(t *testing.T) { ctx := context.Background() s := openStore(t) if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, esPlugin(), "9.1", "9.2"); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + 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)) diff --git a/plugins/openapi/flagsmith_test.go b/plugins/openapi/flagsmith_test.go index 921b805..1b91b06 100644 --- a/plugins/openapi/flagsmith_test.go +++ b/plugins/openapi/flagsmith_test.go @@ -72,7 +72,7 @@ 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() @@ -80,7 +80,7 @@ func TestFlagsmithGolden(t *testing.T) { sink := env.Baselines.(kittest.Sink) p := Plugin{Adapter: fakeFlagsmithAdapter{}, Keep: requestSide} if rejected, err := kittest.Pair(ctx, env, sink, p, "v2.286.0", "v2.287.0"); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + t.Fatalf("pair: rejected=%v err=%v", rejected, err) } kittest.Golden(t, "testdata/golden/flagsmith.json", kittest.Stored(t, sink)) } @@ -93,7 +93,7 @@ func TestFlagsmithDropsADescriptionOnlyChange(t *testing.T) { sink := env.Baselines.(kittest.Sink) p := Plugin{Adapter: fakeFlagsmithAdapter{}, Keep: requestSide} if rejected, err := kittest.Pair(ctx, env, sink, p, "c3ef832", "f504f16"); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + 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 00e7ea1..9239b88 100644 --- a/plugins/openapi/github_test.go +++ b/plugins/openapi/github_test.go @@ -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() @@ -67,11 +67,11 @@ func TestGitHubReplayRecreatesTheRealPropertyRemoval(t *testing.T) { 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 da2a8c6..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 { @@ -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 aff90c4..09ed7e0 100644 --- a/plugins/openapi/neon_test.go +++ b/plugins/openapi/neon_test.go @@ -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 @@ -78,7 +78,7 @@ func TestNeonGolden(t *testing.T) { ctx := context.Background() s := openStore(t) if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, neonPlugin(fakeNeonAdapter{}), "5c57d009", "93b93dc9"); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + t.Fatalf("pair: rejected=%v err=%v", rejected, err) } events := kittest.Stored(t, s) if len(events) != 1 { @@ -118,7 +118,7 @@ func TestNeonDropsRemovalsThatWerentDeprecated(t *testing.T) { ctx := context.Background() s := openStore(t) if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, neonPlugin(fakeNeonAdapter{}), "4c6b3be4", "4497de89"); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + 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)) @@ -179,7 +179,7 @@ func TestNeonKeepsTheRemovalOfADeprecatedOperation(t *testing.T) { ctx := context.Background() s := openStore(t) if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, neonPlugin(neonAPIClient{}), "2.7.2", "2.7.3"); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + 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 a0e3ac7..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 ( diff --git a/plugins/openapi/openapi_test.go b/plugins/openapi/openapi_test.go index 0b041cd..ec60e9d 100644 --- a/plugins/openapi/openapi_test.go +++ b/plugins/openapi/openapi_test.go @@ -43,11 +43,11 @@ 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) { +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) } @@ -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/api"); last != nil { - t.Errorf("replay moved the baseline to %s; replays must never set it", last.Version) + 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,8 +196,8 @@ 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.Event diff --git a/plugins/openapi/planetscale_test.go b/plugins/openapi/planetscale_test.go index 19318c3..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.Event { +func pairPlanetScale(t *testing.T, p Plugin, from, to string) []event.Event { t.Helper() s := openStore(t) if rejected, err := kittest.Pair(context.Background(), vercelEnv(s), s, p, from, to); err != nil || rejected { - t.Fatalf("replay %s -> %s: rejected=%v err=%v", from, to, rejected, err) + 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.Event { 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,12 +127,12 @@ 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) { + 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 6e02f4f..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.Event { +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.Pair(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) + 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.Event { // 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`) { @@ -174,7 +174,7 @@ func TestSentryFlagAfterWordsIsNotNew(t *testing.T) { type rawSentry struct{} func (rawSentry) API() string { return "sentry/api" } -func (rawSentry) LatestTag(context.Context) (string, error) { return "", fmt.Errorf("replay only") } +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,14 +187,14 @@ 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"}) { + 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) } @@ -207,7 +207,7 @@ 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"}) { + 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 52d0f27..d2497ad 100644 --- a/plugins/openapi/supabase_test.go +++ b/plugins/openapi/supabase_test.go @@ -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.) @@ -76,7 +76,7 @@ func TestSupabaseGolden(t *testing.T) { } } if rejected, err := kittest.Pair(ctx, env, s, supabasePlugin(""), "693bdc38", "eb21ae25"); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + t.Fatalf("pair: rejected=%v err=%v", rejected, err) } events := kittest.Stored(t, s) @@ -124,7 +124,7 @@ func TestSupabaseDropsRemovalsThatWerentDeprecated(t *testing.T) { ctx := context.Background() s := openStore(t) if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, supabasePlugin(""), "8aef4a08", "90b71e3e"); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + 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)) diff --git a/plugins/openapi/vercel_test.go b/plugins/openapi/vercel_test.go index 9293627..9f76e86 100644 --- a/plugins/openapi/vercel_test.go +++ b/plugins/openapi/vercel_test.go @@ -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. + // 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("replay: rejected=%v err=%v", rejected, err) + 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. + // 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 replay: %v", err) + 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)) } } @@ -154,7 +154,7 @@ func TestVercelDropsRemovalsThatWerentDeprecated(t *testing.T) { ctx := context.Background() s := openStore(t) if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, vercelPlugin(""), "v1.6.2", "v1.6.3"); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + t.Fatalf("pair: rejected=%v err=%v", rejected, err) } if events := kittest.Stored(t, s); len(events) != 0 { for _, e := range events { @@ -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") } } @@ -189,7 +189,7 @@ func TestVercelPathParameterRenameIsNoChange(t *testing.T) { ctx := context.Background() s := openStore(t) if rejected, err := kittest.Pair(ctx, vercelEnv(s), s, vercelPlugin(""), "v1.28.64", "v1.28.65"); err != nil || rejected { - t.Fatalf("replay: rejected=%v err=%v", rejected, err) + t.Fatalf("pair: rejected=%v err=%v", rejected, err) } if events := kittest.Stored(t, s); len(events) != 0 { for _, e := range events { diff --git a/providers/appwrite.md b/providers/appwrite.md index c03f918..0d5e8e2 100644 --- a/providers/appwrite.md +++ b/providers/appwrite.md @@ -38,7 +38,7 @@ Kind: `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/convex.md b/providers/convex.md index b6c0d34..b8898c8 100644 --- a/providers/convex.md +++ b/providers/convex.md @@ -38,7 +38,7 @@ Kind: `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 3e70326..56befde 100644 --- a/providers/datadog.md +++ b/providers/datadog.md @@ -24,7 +24,7 @@ Kind: `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 37147c7..72667ba 100644 --- a/providers/elasticsearch.md +++ b/providers/elasticsearch.md @@ -42,7 +42,7 @@ Kind: `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/gitlab.md b/providers/gitlab.md index 354a9c6..e068267 100644 --- a/providers/gitlab.md +++ b/providers/gitlab.md @@ -24,7 +24,7 @@ Kind: `openapi` (`plugins/openapi`), with `adapter.GitLab` and a request-side fi - **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/neon.md b/providers/neon.md index ce45f7e..91ffd93 100644 --- a/providers/neon.md +++ b/providers/neon.md @@ -40,7 +40,7 @@ Kind: `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/planetscale.md b/providers/planetscale.md index 40c2ae0..9a54a6f 100644 --- a/providers/planetscale.md +++ b/providers/planetscale.md @@ -40,7 +40,7 @@ Kind: `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/redis.md b/providers/redis.md index f118c89..fb28c52 100644 --- a/providers/redis.md +++ b/providers/redis.md @@ -25,10 +25,10 @@ Kind: `catalog` (`plugins/catalog`), new in this change — no existing format p ## 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/sentry.md b/providers/sentry.md index 0d7a4af..06914d5 100644 --- a/providers/sentry.md +++ b/providers/sentry.md @@ -47,7 +47,7 @@ Kind: `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 9fde42b..2f385a7 100644 --- a/providers/stripe.md +++ b/providers/stripe.md @@ -24,7 +24,7 @@ Kind: `openapi` (`plugins/openapi`), with `adapter.Stripe` and the changelog hin - 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 880226e..8d096bd 100644 --- a/providers/supabase.md +++ b/providers/supabase.md @@ -35,7 +35,7 @@ Kind: `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/vercel.md b/providers/vercel.md index 2e16b65..1b01fc9 100644 --- a/providers/vercel.md +++ b/providers/vercel.md @@ -36,7 +36,7 @@ Kind: `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 From ad2ecef706ade3aa0d329f2adee7f77bf9325fdc Mon Sep 17 00:00:00 2001 From: adssib <75389300+adssib@users.noreply.github.com> Date: Fri, 20 Nov 2026 19:14:19 -0500 Subject: [PATCH 15/16] the last two replay comments Co-Authored-By: Claude Opus 5.5 Signed-off-by: adssib <75389300+adssib@users.noreply.github.com> --- plugins/catalog/catalog_test.go | 2 +- plugins/openapi/adapter/gitlab.go | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/catalog/catalog_test.go b/plugins/catalog/catalog_test.go index c827f76..c700cce 100644 --- a/plugins/catalog/catalog_test.go +++ b/plugins/catalog/catalog_test.go @@ -38,7 +38,7 @@ func fixturePages() kittest.Pages { // 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. +// version pair oldRef → newRef (ReadAt both, Extract) recreates. func TestPairRecreatesTheRealFunctionCommandRemoval(t *testing.T) { ctx := context.Background() s := kittest.NewMem() diff --git a/plugins/openapi/adapter/gitlab.go b/plugins/openapi/adapter/gitlab.go index 95b6191..461ddf1 100644 --- a/plugins/openapi/adapter/gitlab.go +++ b/plugins/openapi/adapter/gitlab.go @@ -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) From ed940de837dcfacc582be59a6eda3fe85610cc47 Mon Sep 17 00:00:00 2001 From: adssib <75389300+adssib@users.noreply.github.com> Date: Fri, 20 Nov 2026 19:14:27 -0500 Subject: [PATCH 16/16] catalog test comment reads as a sentence Co-Authored-By: Claude Opus 5.5 Signed-off-by: adssib <75389300+adssib@users.noreply.github.com> --- plugins/catalog/catalog_test.go | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/catalog/catalog_test.go b/plugins/catalog/catalog_test.go index c700cce..e904e23 100644 --- a/plugins/catalog/catalog_test.go +++ b/plugins/catalog/catalog_test.go @@ -37,8 +37,8 @@ func fixturePages() kittest.Pages { // 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 -// version pair oldRef → newRef (ReadAt both, Extract) recreates. +// (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()