Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
32 changes: 29 additions & 3 deletions cmd/new-plugin/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
}
Expand Down Expand Up @@ -378,6 +378,32 @@ func declNames(decl ast.Decl) []string {
return nil
}

// providerBlock turns a format's "plugin.Register(<plugin>)" 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) {
Expand All @@ -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
Expand All @@ -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.
Expand Down
15 changes: 11 additions & 4 deletions core/plugin/plugin.go
Original file line number Diff line number Diff line change
Expand Up @@ -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()
Expand Down
272 changes: 272 additions & 0 deletions core/plugin/provider.go
Original file line number Diff line number Diff line change
@@ -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/<kind> package whose plugin runs it), at one layer of a customer's
// stack. A source's id is "<provider>/<source>": "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/<kind> 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 "<provider>/<source>".
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/<name>.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
}
Loading
Loading