diff --git a/AGENTS.md b/AGENTS.md index 4dedcad..632c195 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -51,7 +51,7 @@ One target at a time: `make tidy`, `make build`, `make fmt`, `make vet`, `make i Go module `github.com/patch-it-dev/patch-it-plugins`; the only dependency is `gopkg.in/yaml.v3`. ``` -core/plugin/ the Plugin interface, the registry, Env, Result, Spec (baselines) +core/plugin/ the Plugin interface, the registry of providers and their sources (metadata), Env, Result, Spec core/fetch/ the HTTP fetch with retries and the ETag / Last-Modified cache core/github/ the newest release / commit on GitHub, and a commit's SHA and date (one place) core/kit/ core/kit/kittest/ Unchanged, Cite, Wayback; the test kit (Mem, Pages, Ingest, Golden) diff --git a/cmd/new-plugin/main.go b/cmd/new-plugin/main.go index a33de7e..43e94cb 100644 --- a/cmd/new-plugin/main.go +++ b/cmd/new-plugin/main.go @@ -217,7 +217,7 @@ func Run(o Options, out io.Writer) error { } // The edits to existing files. - mainFile, registered, err := register(o.Root, pkgDir, fill(f.register, d)) + mainFile, registered, err := register(o.Root, pkgDir, providerBlock(o, d, fill(f.register, d))) if err != nil { return err } @@ -378,6 +378,32 @@ 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). +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, ",") + ")," + } + } + 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}, + Plugin: %s, + }}, + })`, id, o.Provider, category, homepage, source, pluginlist.Layers[o.Layer], "providers/"+o.Page+".md", o.Watches, o.Source, expr) +} + // register adds line at the end of the init func that registers pkgDir's // plugins, next to the others. func register(root, pkgDir, line string) (string, []byte, error) { @@ -400,7 +426,7 @@ func register(root, pkgDir, line string) (string, []byte, error) { } for _, decl := range file.Decls { fn, ok := decl.(*ast.FuncDecl) - if !ok || fn.Name.Name != "init" || fn.Recv != nil || !bytes.Contains(src[fn.Pos()-1:fn.End()-1], []byte("plugin.Register(")) { + if !ok || fn.Name.Name != "init" || fn.Recv != nil || !bytes.Contains(src[fn.Pos()-1:fn.End()-1], []byte("plugin.Register")) { continue } at := fset.Position(fn.Body.Rbrace).Offset @@ -416,7 +442,7 @@ func register(root, pkgDir, line string) (string, []byte, error) { return rel, out, nil } } - return "", nil, fmt.Errorf("found no init in %s that calls plugin.Register", pkgDir) + 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. diff --git a/core/plugin/plugin.go b/core/plugin/plugin.go index 4b0802c..203f092 100644 --- a/core/plugin/plugin.go +++ b/core/plugin/plugin.go @@ -99,15 +99,22 @@ func Register(p Plugin) { registry[p.Name()] = p } -// Lookup finds a registered plugin by name. +// 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) { mu.Lock() defer mu.Unlock() - p, ok := registry[name] - return p, ok + if p, ok := registry[name]; ok { + return p, true + } + if s, ok := sources[name]; ok { + return s.Source.Plugin, true + } + return nil, false } -// Names are the registered plugins, sorted. +// Names are the registered plugins' old slugs, sorted: what `--api all` runs. +// Sources lists them with their full ids and metadata. func Names() []string { mu.Lock() defer mu.Unlock() diff --git a/core/plugin/provider.go b/core/plugin/provider.go new file mode 100644 index 0000000..4546d40 --- /dev/null +++ b/core/plugin/provider.go @@ -0,0 +1,272 @@ +package plugin + +import ( + "cmp" + "fmt" + "net/url" + "path" + "reflect" + "regexp" + "slices" + "strings" +) + +// A provider is whose API, SDK or package it is (Stripe, OpenAI, Kubernetes), +// in one category. It has one or more sources: each one place patch-it reads +// (a spec repo, a deprecations page, a changelog), read by one kind (the +// plugins/ package whose plugin runs it), at one layer of a customer's +// stack. A source's id is "/": "stripe/api", +// "algolia/search-api", "openai/models". +// +// Every source is registered with its metadata, in code, by the kind's +// package (RegisterProvider). That registration is the only list of what +// patch-it watches: `go run ./cmd/list-plugins` prints it, the Release +// workflow attaches it to each release as plugins.json, and patch-it's hosted +// ingestion service serves it. There is no list to keep by hand. + +// Category is what a provider is, for grouping: one per provider. +type Category string + +// The categories. A new one is added here, in review. +const ( + CategoryAI Category = "ai" + CategoryPayments Category = "payments" + CategoryInfrastructure Category = "infrastructure" + CategoryDatabases Category = "databases" + CategoryMonitoring Category = "monitoring" + CategoryAnalytics Category = "analytics" + CategoryAuth Category = "auth" + CategoryMessaging Category = "messaging" + CategoryHosting Category = "hosting" + CategorySearch Category = "search" + CategoryDevTools Category = "devtools" + CategoryCRM Category = "crm" + CategoryPackages Category = "packages" +) + +// Categories are every category, in display order. +func Categories() []Category { + return []Category{ + CategoryAI, CategoryPayments, CategoryInfrastructure, CategoryDatabases, + CategoryMonitoring, CategoryAnalytics, CategoryAuth, CategoryMessaging, + CategoryHosting, CategorySearch, CategoryDevTools, CategoryCRM, CategoryPackages, + } +} + +// Layer is which part of a customer's stack a source covers. +type Layer string + +// The layers. +const ( + LayerAPI Layer = "api" + LayerSDK Layer = "sdk" + LayerPackage Layer = "package" + LayerRuntime Layer = "runtime" + LayerCI Layer = "ci" + LayerAIModels Layer = "ai-models" + LayerInfra Layer = "infra" +) + +// Layers are every layer. +func Layers() []Layer { + return []Layer{LayerAPI, LayerSDK, LayerPackage, LayerRuntime, LayerCI, LayerAIModels, LayerInfra} +} + +// Provider is one provider and the sources a kind's package registers for it. +// A provider with sources in several kinds (Anthropic: a deprecations page and +// an SDK migration guide) is registered by each, with the same ID, Name, +// Category and Homepage; the registry merges them. +type Provider struct { + ID string // lowercase slug: "algolia" + Name string // as the provider writes it: "Algolia" + Category Category // what it is + Homepage string // the provider's own site + Sources []Source +} + +// Source is one place a provider's changes are read from. +type Source struct { + // ID is the source's part of its id, unique within the provider: + // "search-api" in "algolia/search-api". + ID string + // Kind is the kind that reads it: the plugins/ package Plugin is + // defined in. RegisterProvider fills it in; a value set by hand must + // match. + Kind string + // Layer is which part of a customer's stack it covers. + Layer Layer + // Watches is what changes it reports, in a few words. + Watches string + // URLs are the provider's own pages or files it reads, absolute; the + // first is the one a person should look at. + URLs []string + // Page is the source's page in this repo: "providers/algolia.md" (why + // this source, what it reads and ignores, its known gaps). + Page string + // Plugin runs it. Its Name is the source's old slug ("algolia-search"): + // what `--api` selects and every event's `api` carries until patch-it's + // change-event contract switches to source ids. + Plugin Plugin +} + +// SourceInfo is a registered source with its provider: what the list prints. +type SourceInfo struct { + Provider Provider // without Sources + Source Source +} + +// 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. +func RegisterProvider(p Provider) { + if err := p.check(); err != nil { + panic("plugin: " + err.Error()) + } + for i := range p.Sources { + p.Sources[i].Kind = KindOf(p.Sources[i].Plugin) + } + mu.Lock() + 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)) + } + } + 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 + bare := merged + bare.Sources = nil + for _, s := range p.Sources { + id := p.ID + "/" + s.ID + sources[id] = SourceInfo{Provider: bare, Source: s} + aliases[s.Plugin.Name()] = id + } +} + +// check is the metadata every provider and source must have. +func (p Provider) check() error { + switch { + case !slug.MatchString(p.ID): + return fmt.Errorf("provider id %q isn't a lowercase slug", p.ID) + case p.Name == "": + return fmt.Errorf("provider %q has no Name", p.ID) + case !slices.Contains(Categories(), p.Category): + return fmt.Errorf("provider %q: category %q isn't one of plugin.Categories()", p.ID, p.Category) + case !absolute(p.Homepage): + return fmt.Errorf("provider %q: Homepage %q isn't an absolute URL", p.ID, p.Homepage) + case len(p.Sources) == 0: + return fmt.Errorf("provider %q has no sources", p.ID) + } + seen := map[string]bool{} + for _, s := range p.Sources { + id := p.ID + "/" + s.ID + switch { + case !slug.MatchString(s.ID): + return fmt.Errorf("source id %q isn't a lowercase slug", id) + case seen[s.ID]: + return fmt.Errorf("source %q is listed twice", id) + case s.Plugin == nil: + return fmt.Errorf("source %q has no Plugin", id) + 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) == "": + return fmt.Errorf("source %q: Watches is empty", id) + case len(s.URLs) == 0: + 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): + 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 { + if !absolute(u) { + return fmt.Errorf("source %q: URL %q isn't absolute", id, u) + } + } + seen[s.ID] = true + } + return nil +} + +func absolute(u string) bool { + parsed, err := url.Parse(u) + return err == nil && (parsed.Scheme == "https" || parsed.Scheme == "http") && parsed.Host != "" +} + +// KindOf is the kind a plugin is: the name of the package its type is +// defined in (plugins/openapi -> "openapi"). +func KindOf(p Plugin) string { + t := reflect.TypeOf(p) + for t.Kind() == reflect.Pointer { + t = t.Elem() + } + return path.Base(t.PkgPath()) +} + +// Providers are the registered providers with their sources, sorted by id +// (sources by id within each). +func Providers() []Provider { + mu.Lock() + defer mu.Unlock() + out := make([]Provider, 0, len(providers)) + for _, p := range providers { + p.Sources = slices.Clone(p.Sources) + slices.SortFunc(p.Sources, func(a, b Source) int { return cmp.Compare(a.ID, b.ID) }) + out = append(out, p) + } + slices.SortFunc(out, func(a, b Provider) int { return cmp.Compare(a.ID, b.ID) }) + return out +} + +// Sources are the registered sources, sorted by full id. +func Sources() []SourceInfo { + mu.Lock() + defer mu.Unlock() + out := make([]SourceInfo, 0, len(sources)) + for _, s := range sources { + out = append(out, s) + } + slices.SortFunc(out, func(a, b SourceInfo) int { return cmp.Compare(a.FullID(), b.FullID()) }) + 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) { + 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 new file mode 100644 index 0000000..e890f1d --- /dev/null +++ b/core/plugin/provider_test.go @@ -0,0 +1,84 @@ +package plugin + +import ( + "context" + "strings" + "testing" +) + +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}} +} + +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) + } + } + var got []string + for _, p := range Providers() { + if p.ID == "acme-test" { + for _, s := range p.Sources { + got = append(got, s.ID) + } + } + } + if strings.Join(got, ",") != "api,sdk" { + t.Errorf("acme-test's sources = %v", got) + } +} + +func TestRegisterProviderRefusesIncompleteMetadata(t *testing.T) { + for name, p := range map[string]Provider{ + "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")}}, + "no watches": {ID: "x4", Name: "X", Category: CategoryAI, Homepage: "https://x.example", Sources: []Source{func() Source { + s := src("api", "x4") + s.Watches = "" + return s + }()}}, + "bad layer": {ID: "x5", Name: "X", Category: CategoryAI, Homepage: "https://x.example", Sources: []Source{func() Source { + s := src("api", "x5") + s.Layer = "API" + 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" + return s + }()}}, + } { + if err := p.check(); err == nil { + t.Errorf("%s: accepted", name) + } + } +} + +func TestRegisterProviderRefusesConflictingProvider(t *testing.T) { + RegisterProvider(acme(src("one", "acme-test-one"))) + 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.Name = "Acme Corp" + RegisterProvider(p) +} diff --git a/internal/pluginlist/pluginlist.go b/internal/pluginlist/pluginlist.go index 5b75fac..f798d86 100644 --- a/internal/pluginlist/pluginlist.go +++ b/internal/pluginlist/pluginlist.go @@ -187,6 +187,20 @@ func List(root string) ([]Plugin, error) { case ok && format != r.Format: errs = append(errs, fmt.Errorf("%s: %s says format %q, but the plugin is in plugins/%s", Table, r.ID, r.Format, format)) } + // The row says what the source's registration says (moving to the + // registration only: until then, both). + if s, ok := plugin.LookupSource(r.ID); ok { + switch { + case s.Provider.Name != r.Provider: + errs = append(errs, fmt.Errorf("%s: %s: provider %q, but its registration says %q", Table, r.ID, r.Provider, s.Provider.Name)) + case string(s.Source.Layer) != layer: + errs = append(errs, fmt.Errorf("%s: %s: layer %q, but its registration says %q", Table, r.ID, layer, s.Source.Layer)) + case s.Source.Watches != r.Watches: + errs = append(errs, fmt.Errorf("%s: %s: what it watches differs from its registration's Watches", Table, r.ID)) + case "providers/"+r.Page+".md" != s.Source.Page: + errs = append(errs, fmt.Errorf("%s: %s: links providers/%s.md, but its registration's Page is %s", Table, r.ID, r.Page, s.Source.Page)) + } + } // One page per provider: the algolia-* plugins share providers/algolia.md. page := "providers/" + r.Page + ".md" if _, err := os.Stat(filepath.Join(root, page)); err != nil { diff --git a/plugins/all/all_test.go b/plugins/all/all_test.go index 407ebb6..e4402a0 100644 --- a/plugins/all/all_test.go +++ b/plugins/all/all_test.go @@ -44,7 +44,8 @@ func TestEveryPluginIsImported(t *testing.T) { } } -// registers reports whether a package's non-test code calls plugin.Register. +// registers reports whether a package's non-test code calls +// plugin.RegisterProvider (or plugin.Register). func registers(t *testing.T, dir string) bool { t.Helper() files, err := filepath.Glob(filepath.Join(dir, "*.go")) @@ -59,7 +60,7 @@ func registers(t *testing.T, dir string) bool { if err != nil { t.Fatal(err) } - if strings.Contains(string(b), "plugin.Register(") { + if strings.Contains(string(b), "plugin.Register(") || strings.Contains(string(b), "plugin.RegisterProvider(") { return true } } @@ -76,3 +77,30 @@ func TestImportingAllRegistersThePlugins(t *testing.T) { t.Errorf("names %v: want sorted and unique", names) } } + +// 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{} + 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()) + } + } + } + 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) + } + } +} diff --git a/plugins/apichangelog/apichangelog.go b/plugins/apichangelog/apichangelog.go index 1856567..271129f 100644 --- a/plugins/apichangelog/apichangelog.go +++ b/plugins/apichangelog/apichangelog.go @@ -30,7 +30,15 @@ import ( ) func init() { - plugin.Register(Plugin{Log: MongoDBAtlas}) + 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. diff --git a/plugins/catalog/catalog.go b/plugins/catalog/catalog.go index 50b1a62..9c257e4 100644 --- a/plugins/catalog/catalog.go +++ b/plugins/catalog/catalog.go @@ -28,7 +28,15 @@ import ( ) func init() { - plugin.Register(Plugin{Catalog: Redis}) + plugin.RegisterProvider(plugin.Provider{ + ID: "redis", Name: "Redis", Category: plugin.CategoryDatabases, Homepage: "https://redis.io", + Sources: []plugin.Source{{ + ID: "commands", Layer: plugin.LayerRuntime, Page: "providers/redis.md", + Watches: "Commands removed entirely from Redis's own command catalog between two snapshots", + URLs: []string{"https://github.com/redis/redis-doc/blob/master/commands.json"}, + Plugin: Plugin{Catalog: Redis}, + }}, + }) } // Catalog is one provider's command or endpoint catalog: a single JSON diff --git a/plugins/changelog/changelog.go b/plugins/changelog/changelog.go index 2d4b3a6..f5eadea 100644 --- a/plugins/changelog/changelog.go +++ b/plugins/changelog/changelog.go @@ -25,8 +25,24 @@ import ( ) func init() { - plugin.Register(Plugin{File: Textual0860}) - plugin.Register(Plugin{File: Urllib3200}) + plugin.RegisterProvider(plugin.Provider{ + 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: "Removals and breaking changes in release 0.86.0", + URLs: []string{"https://github.com/Textualize/textual/blob/v0.86.0/CHANGELOG.md"}, + Plugin: Plugin{File: Textual0860}, + }}, + }) + 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: "Removals and deprecations in release 2.0.0", + URLs: []string{"https://github.com/urllib3/urllib3/blob/2.0.0/CHANGES.rst"}, + Plugin: Plugin{File: Urllib3200}, + }}, + }) } // File is one package's changelog at one release. diff --git a/plugins/eol/eol.go b/plugins/eol/eol.go index 1d92cf7..4bd1e31 100644 --- a/plugins/eol/eol.go +++ b/plugins/eol/eol.go @@ -38,7 +38,15 @@ import ( ) func init() { - plugin.Register(Plugin{Page: Salesforce, 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: Salesforce, Archiver: kit.Wayback{}}, + }}, + }) } // Page is one vendor's end-of-life table. diff --git a/plugins/feed/feed.go b/plugins/feed/feed.go index a0ad882..dba0f77 100644 --- a/plugins/feed/feed.go +++ b/plugins/feed/feed.go @@ -31,9 +31,33 @@ import ( ) func init() { - plugin.Register(Plugin{Feed: GitHubActions, Archiver: kit.Wayback{}}) - plugin.Register(Plugin{Feed: VertexAIModels, Archiver: kit.Wayback{}}) - plugin.Register(Plugin{Feed: CloudflareAPI, 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{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. diff --git a/plugins/migrationguide/migrationguide.go b/plugins/migrationguide/migrationguide.go index 6fbd950..24b023a 100644 --- a/plugins/migrationguide/migrationguide.go +++ b/plugins/migrationguide/migrationguide.go @@ -14,7 +14,15 @@ import ( ) func init() { - plugin.Register(Plugin{Guide: sdkguide.AnthropicV1}) + plugin.RegisterProvider(plugin.Provider{ + 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: "Parameters removed from `messages.create()` and friends in the Python SDK 1.0", + URLs: []string{"https://github.com/anthropics/anthropic-sdk-python/blob/v1.0.0/MIGRATION.md"}, + Plugin: Plugin{Guide: sdkguide.AnthropicV1}, + }}, + }) } // Plugin reads one SDK's guide to one major release. diff --git a/plugins/openapi/openapi.go b/plugins/openapi/openapi.go index 0428719..19bcded 100644 --- a/plugins/openapi/openapi.go +++ b/plugins/openapi/openapi.go @@ -21,54 +21,166 @@ import ( ) func init() { - plugin.Register(Plugin{Adapter: adapter.Stripe{}, Hints: hint.Stripe{}}) + plugin.RegisterProvider(plugin.Provider{ + 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{}}, + }}, + }) // No Hints yet: Datadog's changelog isn't Stripe's per-parameter table // shape, so there's no hint.Source for it to read. - plugin.Register(Plugin{Adapter: adapter.Datadog{}}) + plugin.RegisterProvider(plugin.Provider{ + 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{}}, + }}, + }) // No Hints: GitLab's deprecations are prose per feature, not a changelog // keyed by API version, so there's nothing for hint.Source to look up. - plugin.Register(Plugin{Adapter: adapter.GitLab{}, Keep: requestSide}) + plugin.RegisterProvider(plugin.Provider{ + ID: "gitlab", Name: "GitLab", Category: plugin.CategoryDevTools, Homepage: "https://about.gitlab.com", + Sources: []plugin.Source{{ + ID: "rest-api", Layer: plugin.LayerAPI, Page: "providers/gitlab.md", + Watches: "REST API changes between releases, request side only (what callers send)", + URLs: []string{"https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/api/openapi"}, + Plugin: Plugin{Adapter: adapter.GitLab{}, Keep: requestSide}, + }}, + }) // 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. - plugin.Register(Plugin{Adapter: adapter.GitHub{}}) + // at all, so there's nothing for hint.Source to key on. (GitHub's Actions + // source is registered by plugins/feed.) + plugin.RegisterProvider(plugin.Provider{ + ID: "github", Name: "GitHub", Category: plugin.CategoryDevTools, Homepage: "https://github.com", + Sources: []plugin.Source{{ + ID: "rest-api", Layer: plugin.LayerAPI, Page: "providers/github.md", + Watches: "REST API changes between dated API versions", + URLs: []string{"https://github.com/github/rest-api-description"}, + Plugin: Plugin{Adapter: adapter.GitHub{}}, + }}, + }) // No Hints: Vercel's changelog is product news, not keyed by API change. // Only operation deprecations and removals are kept: see vercelKeep. - plugin.Register(Plugin{Adapter: adapter.Vercel{}, Diff: vercelDiff, Keep: vercelKeep}) + plugin.RegisterProvider(plugin.Provider{ + 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}, + }}, + }) // No Hints: Supabase's changelog is platform news, not keyed by // operation. Only operation deprecations and removals: see supabase.go. - plugin.Register(Plugin{Adapter: adapter.Supabase{}, Diff: supabaseDiff, Keep: supabaseKeep}) + plugin.RegisterProvider(plugin.Provider{ + ID: "supabase", Name: "Supabase", Category: plugin.CategoryDatabases, Homepage: "https://supabase.com", + Sources: []plugin.Source{{ + ID: "management-api", Layer: plugin.LayerAPI, Page: "providers/supabase.md", + Watches: "Management API operations deprecated, and deprecated operations removed, between commits of the spec", + URLs: []string{"https://github.com/supabase/supabase"}, + Plugin: Plugin{Adapter: adapter.Supabase{}, Diff: supabaseDiff, Keep: supabaseKeep}, + }}, + }) // No Hints: Algolia's changelog is a hosted product feed, not keyed by - // operation. One plugin per API spec: see algolia.go. - for _, spec := range []string{"search", "ingestion", "recommend"} { - plugin.Register(Plugin{Adapter: adapter.Algolia{Spec: spec}, Diff: algoliaDiff, Keep: algoliaKeep}) + // operation. One source per API spec: see algolia.go. + algolia := plugin.Provider{ID: "algolia", Name: "Algolia", Category: plugin.CategorySearch, Homepage: "https://www.algolia.com"} + 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}, + }) } + plugin.RegisterProvider(algolia) // No Hints: Elastic's breaking-changes page is prose per area, not keyed // by operation. See elasticsearch.go. - plugin.Register(Plugin{Adapter: adapter.Elasticsearch{}, Diff: elasticsearchDiff, Keep: elasticsearchKeep, RemovalsNeedANewVersion: true}) + plugin.RegisterProvider(plugin.Provider{ + 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}, + }}, + }) // No Hints: Sentry's changelog is product news, not keyed by operation. // Operation deprecations only, most said in the description: see // sentry.go. - plugin.Register(Plugin{Adapter: adapter.Sentry{}, Diff: sentryDiff, Keep: sentryKeep}) + plugin.RegisterProvider(plugin.Provider{ + ID: "sentry", Name: "Sentry", Category: plugin.CategoryMonitoring, Homepage: "https://sentry.io", + Sources: []plugin.Source{{ + ID: "api", Layer: plugin.LayerAPI, Page: "providers/sentry.md", + Watches: "REST API operations deprecated between releases of the spec, most of them in the operation's description", + URLs: []string{"https://github.com/getsentry/sentry/releases"}, + Plugin: Plugin{Adapter: adapter.Sentry{}, Diff: sentryDiff, Keep: sentryKeep}, + }}, + }) // No Hints: Neon's changelog is a weekly digest, not keyed by operation. // Only operation deprecations and removals: see neon.go. - plugin.Register(Plugin{Adapter: adapter.Neon{}, Diff: neonDiff, Keep: neonKeep}) + plugin.RegisterProvider(plugin.Provider{ + 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}, + }}, + }) // No Hints: Convex has no API changelog; its news feed is product news. // Only operation deprecations and removals: see convex.go. - plugin.Register(Plugin{Adapter: adapter.Convex{}, Diff: convexDiff, Keep: convexKeep}) + plugin.RegisterProvider(plugin.Provider{ + ID: "convex", Name: "Convex", Category: plugin.CategoryDatabases, Homepage: "https://www.convex.dev", + Sources: []plugin.Source{{ + ID: "deployment-api", Layer: plugin.LayerAPI, Page: "providers/convex.md", + Watches: "Deployment API operations deprecated, and deprecated operations removed, between commits of the spec", + URLs: []string{"https://github.com/get-convex/convex-backend"}, + Plugin: Plugin{Adapter: adapter.Convex{}, Diff: convexDiff, Keep: convexKeep}, + }}, + }) // No Hints: PlanetScale's changelog is product news, not keyed by // operation. Operation deprecations only, said in the description: see // planetscale.go. - plugin.Register(Plugin{Adapter: adapter.PlanetScale{}, Diff: planetscaleDiff, Keep: planetscaleKeep}) + plugin.RegisterProvider(plugin.Provider{ + ID: "planetscale", Name: "PlanetScale", Category: plugin.CategoryDatabases, Homepage: "https://planetscale.com", + Sources: []plugin.Source{{ + ID: "api", Layer: plugin.LayerAPI, Page: "providers/planetscale.md", + Watches: "API operations deprecated, and deprecated operations removed, between commits of the spec, said in the operation's description", + URLs: []string{"https://github.com/planetscale/terraform-provider-planetscale"}, + Plugin: Plugin{Adapter: adapter.PlanetScale{}, Diff: planetscaleDiff, Keep: planetscaleKeep}, + }}, + }) // No Hints: Appwrite's changelog is product news, not keyed by operation. // Operation deprecations only, SDK method renames left out: see // appwrite.go. - plugin.Register(Plugin{Adapter: adapter.Appwrite{}, Diff: appwriteDiff, Keep: appwriteKeep}) + plugin.RegisterProvider(plugin.Provider{ + 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}, + }}, + }) // No Hints: Flagsmith's release notes are product news, not keyed by // operation. requestSide, same reason as GitLab's: a named request-body // schema shared by several operations (FeatureValue, SegmentOverride) // reads as its own removal, side "response" by the differ's default, // whether or not any operation that used it is actually gone. - plugin.Register(Plugin{Adapter: adapter.Flagsmith{}, Keep: requestSide}) + plugin.RegisterProvider(plugin.Provider{ + ID: "flagsmith", Name: "Flagsmith", Category: plugin.CategoryDevTools, Homepage: "https://www.flagsmith.com", + Sources: []plugin.Source{{ + ID: "api", Layer: plugin.LayerAPI, Page: "providers/flagsmith.md", + Watches: "REST API changes between releases of Flagsmith's own OpenAPI spec (removed endpoints and request parameters)", + URLs: []string{"https://github.com/Flagsmith/flagsmith/blob/main/openapi.yaml"}, + Plugin: Plugin{Adapter: adapter.Flagsmith{}, Keep: requestSide}, + }}, + }) } // requestSide keeps the changes to what callers send. GitLab's response diff --git a/plugins/removedmembers/removedmembers.go b/plugins/removedmembers/removedmembers.go index c60b49a..b0ab908 100644 --- a/plugins/removedmembers/removedmembers.go +++ b/plugins/removedmembers/removedmembers.go @@ -32,9 +32,33 @@ import ( ) func init() { - plugin.Register(Plugin{Guide: NumPy2}) - plugin.Register(Plugin{Guide: PostHog8}) - plugin.Register(Plugin{Guide: NewRelic11}) + 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. diff --git a/plugins/retirements/retirements.go b/plugins/retirements/retirements.go index dae4cfb..d4d200a 100644 --- a/plugins/retirements/retirements.go +++ b/plugins/retirements/retirements.go @@ -16,8 +16,24 @@ import ( ) func init() { - plugin.Register(Plugin{Page: retire.OpenAI, Archiver: kit.Wayback{}}) - plugin.Register(Plugin{Page: retire.Anthropic, Archiver: kit.Wayback{}}) + 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.