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] 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