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 @@ -4,7 +4,7 @@ Rules for AI coding agents (and humans) working in this repo. `CLAUDE.md` import

## Rule 1: every new or changed provider or source has complete metadata in its registration

**A source exists when its kind's package registers it with `plugin.RegisterProvider`, and its metadata lives only there: the provider's id, name, category and homepage, and each source's id, layer, what it watches, the URLs it reads and its page, `providers/<name>.md`.** Adding, changing or removing a source is a change to that registration (and to its page) in the same PR. There is no list to update: nothing in this repo, the docs site or anywhere else keeps one by hand.
**A source exists when its kind's package registers it with `plugin.RegisterProvider`, and its metadata lives only there: the provider's id, name, category and homepage, and each source's id, layer, what it watches, the URLs it reads, the packages it covers (`pypi:stripe`) and its page, `providers/<name>.md`.** Adding, changing or removing a source is a change to that registration (and to its page) in the same PR. There is no list to update: nothing in this repo, the docs site or anywhere else keeps one by hand.

`go run ./cmd/list-plugins` prints the list from the registry (JSON), and the Release workflow attaches it to every release as `plugins.json`; the docs site and patch-it's hosted ingestion service read it from there. `RegisterProvider` refuses incomplete metadata and `go test` fails when a source's page is missing, but no check can tell whether the words are right: you are that check. Say in the PR that you read them.

Expand Down
36 changes: 36 additions & 0 deletions core/plugin/provider.go
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,11 @@ const (
LayerInfra Layer = "infra"
)

// Ecosystems are the package registries a Source's Packages name.
func Ecosystems() []string {
return []string{"pypi", "npm", "go", "maven", "nuget", "rubygems", "cargo", "packagist"}
}

// Layers are every layer.
func Layers() []Layer {
return []Layer{LayerAPI, LayerSDK, LayerPackage, LayerRuntime, LayerCI, LayerAIModels, LayerInfra}
Expand Down Expand Up @@ -103,6 +108,13 @@ type Source struct {
// Page is the source's page in this repo: "providers/algolia.md" (why
// this source, what it reads and ignores, its known gaps).
Page string
// Packages are the published packages whose changes this source
// covers, as "<ecosystem>:<name>" ("pypi:stripe", "npm:@vercel/sdk"):
// the package itself for a package or SDK source, the provider's
// official SDKs for an API source. What lets a lockfile entry find its
// sources without a table kept elsewhere. Only names checked by hand;
// none is fine when no package maps to the source.
Packages []string
// Plugin runs it. Its Name is the source's old slug ("algolia-search"):
// what `--api` selects and every event's `api` carries until patch-it's
// change-event contract switches to source ids.
Expand Down Expand Up @@ -212,6 +224,12 @@ func (p Provider) check() error {
return fmt.Errorf("source %q: URL %q isn't absolute", id, u)
}
}
for _, pkg := range s.Packages {
eco, name, ok := strings.Cut(pkg, ":")
if !ok || !slices.Contains(Ecosystems(), eco) || name == "" || strings.ContainsAny(name, " \t\n") {
return fmt.Errorf("source %q: package %q isn't <ecosystem>:<name>, the ecosystem one of plugin.Ecosystems()", id, pkg)
}
}
seen[s.ID] = true
}
return nil
Expand Down Expand Up @@ -279,6 +297,24 @@ func Sources() []SourceInfo {
return out
}

// Aliases are the other names a source answers to (Lookup, LookupSource):
// today its first name, the old slug ("algolia-search"), which events carry
// in `api` and fingerprints hash.
func (s SourceInfo) Aliases() []string { return []string{s.Alias()} }

// ForPackage are the sources that cover a published package
// ("pypi:stripe"), sorted by full id: how a lockfile entry finds what to
// ask the feed for.
func ForPackage(pkg string) []SourceInfo {
var out []SourceInfo
for _, s := range Sources() {
if slices.Contains(s.Source.Packages, pkg) {
out = append(out, s)
}
}
return out
}

// LookupSource finds a source by its full id ("algolia/search-api") or its
// old slug ("algolia-search").
func LookupSource(id string) (SourceInfo, bool) {
Expand Down
19 changes: 19 additions & 0 deletions core/plugin/provider_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,11 @@ func TestRegisterProviderRefusesIncompleteMetadata(t *testing.T) {
s.Layer = "API"
return s
}()}},
"bad package": {ID: "x7", Name: "X", Category: CategoryAI, Homepage: "https://x.example", Sources: []Source{func() Source {
s := src("api", "x7")
s.Packages = []string{"pip:x"}
return s
}()}},
"wrong kind": {ID: "x6", Name: "X", Category: CategoryAI, Homepage: "https://x.example", Sources: []Source{func() Source {
s := src("api", "x6")
s.Kind = "openapi"
Expand Down Expand Up @@ -95,3 +100,17 @@ func TestMergedKindsKeepWorking(t *testing.T) {
t.Errorf("CanonicalKind(openapi) = %q", got)
}
}

// A package names its sources, and a source answers to its first name.
func TestForPackage(t *testing.T) {
s := src("pkg", "acme-test-pkg")
s.Packages = []string{"pypi:acme-test", "npm:@acme/test"}
RegisterProvider(acme(s))
got := ForPackage("npm:@acme/test")
if len(got) != 1 || got[0].FullID() != "acme-test/pkg" || strings.Join(got[0].Aliases(), ",") != "acme-test-pkg" {
t.Errorf("ForPackage = %+v", got)
}
if got := ForPackage("pypi:nobody"); len(got) != 0 {
t.Errorf("ForPackage(pypi:nobody) = %+v", got)
}
}
5 changes: 4 additions & 1 deletion docs/plugins.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -32,11 +32,14 @@
"type": "array",
"items": {
"type": "object",
"required": ["id", "alias", "kind", "layer", "watches", "urls", "page"],
"required": ["id", "alias", "first_name", "aliases", "kind", "layer", "watches", "urls", "packages", "page"],
"additionalProperties": false,
"properties": {
"id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*/[a-z0-9][a-z0-9-]*$", "description": "provider/source" },
"alias": { "type": "string", "pattern": "^[a-z0-9][a-z0-9.-]*$", "description": "The old slug: --api and every event's api field until patch-it's change-event contract switches to source ids." },
"first_name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9.-]*$", "description": "The source's first name, its old slug: what fingerprints keep hashing after the contract switches to source ids." },
"aliases": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9.-]*$" }, "description": "Every other name the source answers to." },
"packages": { "type": "array", "items": { "type": "string", "pattern": "^(pypi|npm|go|maven|nuget|rubygems|cargo|packagist):[^\\s]+$" }, "description": "The published packages this source covers, as ecosystem:name, so a lockfile entry finds its sources." },
"kind": { "type": "string", "enum": ["openapi", "changelog", "notices", "migrationguide", "catalog"] },
"layer": { "type": "string", "enum": ["api", "sdk", "package", "runtime", "ci", "ai-models", "infra"] },
"watches": { "type": "string", "minLength": 1 },
Expand Down
5 changes: 4 additions & 1 deletion docs/writing-a-plugin.md
Original file line number Diff line number Diff line change
Expand Up @@ -136,13 +136,16 @@ func init() {
ID: "urllib3", Layer: plugin.LayerPackage, Page: "providers/urllib3.md",
Watches: "Names removed or deprecated in each release, …",
URLs: []string{"https://github.com/urllib3/urllib3/blob/main/CHANGES.rst"},
Packages: []string{"pypi:urllib3"},
Plugin: Plugin{File: Urllib3},
}},
})
}
```

`RegisterProvider` panics on missing metadata, a duplicate id, or a provider registered twice with a different name, category or homepage (a provider with sources in two kinds repeats the same ones). `plugin.Lookup` and `plugin.LookupSource` find a source by `provider/source` or by its old slug.
`RegisterProvider` panics on missing metadata, a duplicate id, or a provider registered twice with a different name, category or homepage (a provider with sources in two kinds repeats the same ones). `plugin.Lookup` and `plugin.LookupSource` find a source by `provider/source` or by its old slug (its first name, which events carry in `api` and fingerprints hash).

`Packages` are the published packages the source covers, `<ecosystem>:<name>` (`pypi:stripe`, `npm:@vercel/sdk`): the package itself for a package or SDK source, the provider's official SDKs for an API source. `plugin.ForPackage` finds a package's sources, so a customer's lockfile maps to sources with no table kept anywhere else. List only names you checked; none is fine.

### Fetching: `env.Get` and `core/kit/`

Expand Down
23 changes: 14 additions & 9 deletions internal/pluginlist/pluginlist.go
Original file line number Diff line number Diff line change
Expand Up @@ -38,13 +38,16 @@ type Provider struct {

// Source is one source.
type Source struct {
ID string `json:"id"` // provider/source
Alias string `json:"alias"` // the old slug: --api and every event's api until the contract switches to source ids
Kind string `json:"kind"`
Layer string `json:"layer"`
Watches string `json:"watches"`
URLs []string `json:"urls"`
Page string `json:"page"` // absolute, at Version
ID string `json:"id"` // provider/source
Alias string `json:"alias"` // the old slug: --api and every event's api until the contract switches to source ids
FirstName string `json:"first_name"` // the same old slug, by the name fingerprints keep hashing after the switch
Aliases []string `json:"aliases"` // every other name the source answers to
Kind string `json:"kind"`
Layer string `json:"layer"`
Watches string `json:"watches"`
URLs []string `json:"urls"`
Packages []string `json:"packages"` // "<ecosystem>:<name>"; [] when none
Page string `json:"page"` // absolute, at Version
}

// Build is the list of everything registered, with pages linked at ref (a
Expand All @@ -64,9 +67,11 @@ func Build(ref string) File {
for _, p := range plugin.Providers() {
out := Provider{ID: p.ID, Name: p.Name, Category: string(p.Category), Homepage: p.Homepage}
for _, s := range p.Sources {
info := plugin.SourceInfo{Provider: p, Source: s}
out.Sources = append(out.Sources, Source{
ID: p.ID + "/" + s.ID, Alias: s.Plugin.Name(), Kind: s.Kind, Layer: string(s.Layer),
Watches: s.Watches, URLs: s.URLs, Page: Repo + "/blob/" + ref + "/" + s.Page,
ID: info.FullID(), Alias: info.Alias(), FirstName: info.Alias(), Aliases: info.Aliases(),
Kind: s.Kind, Layer: string(s.Layer), Watches: s.Watches, URLs: s.URLs,
Packages: append([]string{}, s.Packages...), Page: Repo + "/blob/" + ref + "/" + s.Page,
})
}
f.Sources += len(out.Sources)
Expand Down
14 changes: 8 additions & 6 deletions plugins/changelog/changelog.go
Original file line number Diff line number Diff line change
Expand Up @@ -34,18 +34,20 @@ func init() {
ID: "textual", Name: "Textual", Category: plugin.CategoryPackages, Homepage: "https://textual.textualize.io",
Sources: []plugin.Source{{
ID: "textual", Layer: plugin.LayerPackage, Page: "providers/textual.md",
Watches: "Names removed, renamed or deprecated in each release, from the release's section of CHANGELOG.md at its tag",
URLs: []string{"https://github.com/Textualize/textual/blob/main/CHANGELOG.md", "https://pypi.org/project/textual/"},
Plugin: Plugin{File: Textual},
Watches: "Names removed, renamed or deprecated in each release, from the release's section of CHANGELOG.md at its tag",
URLs: []string{"https://github.com/Textualize/textual/blob/main/CHANGELOG.md", "https://pypi.org/project/textual/"},
Packages: []string{"pypi:textual"},
Plugin: Plugin{File: Textual},
}},
})
plugin.RegisterProvider(plugin.Provider{
ID: "urllib3", Name: "urllib3", Category: plugin.CategoryPackages, Homepage: "https://urllib3.readthedocs.io",
Sources: []plugin.Source{{
ID: "urllib3", Layer: plugin.LayerPackage, Page: "providers/urllib3.md",
Watches: "Names removed or deprecated in each release, from the release's section of CHANGES.rst at its tag",
URLs: []string{"https://github.com/urllib3/urllib3/blob/main/CHANGES.rst", "https://pypi.org/project/urllib3/"},
Plugin: Plugin{File: Urllib3},
Watches: "Names removed or deprecated in each release, from the release's section of CHANGES.rst at its tag",
URLs: []string{"https://github.com/urllib3/urllib3/blob/main/CHANGES.rst", "https://pypi.org/project/urllib3/"},
Packages: []string{"pypi:urllib3"},
Plugin: Plugin{File: Urllib3},
}},
})
plugin.RegisterProvider(plugin.Provider{
Expand Down
28 changes: 16 additions & 12 deletions plugins/migrationguide/migrationguide.go
Original file line number Diff line number Diff line change
Expand Up @@ -28,36 +28,40 @@ func init() {
ID: "anthropic", Name: "Anthropic", Category: plugin.CategoryAI, Homepage: "https://www.anthropic.com",
Sources: []plugin.Source{{
ID: "python-sdk", Layer: plugin.LayerSDK, Page: "providers/anthropic.md",
Watches: "Request parameters each new major of the Python SDK removes from `messages.create()` and friends, from MIGRATION.md at the major's tag",
URLs: []string{"https://github.com/anthropics/anthropic-sdk-python/blob/main/MIGRATION.md", "https://pypi.org/project/anthropic/"},
Plugin: Plugin{Guide: sdkguide.Anthropic},
Watches: "Request parameters each new major of the Python SDK removes from `messages.create()` and friends, from MIGRATION.md at the major's tag",
URLs: []string{"https://github.com/anthropics/anthropic-sdk-python/blob/main/MIGRATION.md", "https://pypi.org/project/anthropic/"},
Packages: []string{"pypi:anthropic"},
Plugin: Plugin{Guide: sdkguide.Anthropic},
}},
})
plugin.RegisterProvider(plugin.Provider{
ID: "numpy", Name: "NumPy", Category: plugin.CategoryPackages, Homepage: "https://numpy.org",
Sources: []plugin.Source{{
ID: "numpy", Layer: plugin.LayerPackage, Page: "providers/numpy.md",
Watches: "Members removed or renamed in the main namespace in NumPy 2.0",
URLs: []string{"https://github.com/numpy/numpy/blob/v2.0.0/doc/source/numpy_2_0_migration_guide.rst"},
Plugin: Plugin{Guide: members.NumPy2},
Watches: "Members removed or renamed in the main namespace in NumPy 2.0",
URLs: []string{"https://github.com/numpy/numpy/blob/v2.0.0/doc/source/numpy_2_0_migration_guide.rst"},
Packages: []string{"pypi:numpy"},
Plugin: Plugin{Guide: members.NumPy2},
}},
})
plugin.RegisterProvider(plugin.Provider{
ID: "posthog", Name: "PostHog", Category: plugin.CategoryAnalytics, Homepage: "https://posthog.com",
Sources: []plugin.Source{{
ID: "python-sdk", Layer: plugin.LayerSDK, Page: "providers/posthog.md",
Watches: "Members removed in the posthog Python SDK 8.0.0",
URLs: []string{"https://github.com/PostHog/posthog-python/blob/posthog-v8.0.0/docs/migration-7.x-to-8.0.md"},
Plugin: Plugin{Guide: members.PostHog8},
Watches: "Members removed in the posthog Python SDK 8.0.0",
URLs: []string{"https://github.com/PostHog/posthog-python/blob/posthog-v8.0.0/docs/migration-7.x-to-8.0.md"},
Packages: []string{"pypi:posthog"},
Plugin: Plugin{Guide: members.PostHog8},
}},
})
plugin.RegisterProvider(plugin.Provider{
ID: "newrelic", Name: "New Relic", Category: plugin.CategoryMonitoring, Homepage: "https://newrelic.com",
Sources: []plugin.Source{{
ID: "python-agent", Layer: plugin.LayerSDK, Page: "providers/newrelic.md",
Watches: "Members removed in the New Relic Python agent 11.0.0",
URLs: []string{"https://github.com/newrelic/docs-website/blob/f0b4f817bf9a7b76a78e26609369a8a7ce764c8e/src/content/docs/release-notes/agent-release-notes/python-release-notes/python-agent-110000.mdx"},
Plugin: Plugin{Guide: members.NewRelic11},
Watches: "Members removed in the New Relic Python agent 11.0.0",
URLs: []string{"https://github.com/newrelic/docs-website/blob/f0b4f817bf9a7b76a78e26609369a8a7ce764c8e/src/content/docs/release-notes/agent-release-notes/python-release-notes/python-agent-110000.mdx"},
Packages: []string{"pypi:newrelic"},
Plugin: Plugin{Guide: members.NewRelic11},
}},
})
}
Expand Down
21 changes: 12 additions & 9 deletions plugins/notices/notices.go
Original file line number Diff line number Diff line change
Expand Up @@ -37,18 +37,20 @@ func init() {
ID: "openai", Name: "OpenAI", Category: plugin.CategoryAI, Homepage: "https://openai.com",
Sources: []plugin.Source{{
ID: "models", Layer: plugin.LayerAIModels, Page: "providers/openai-models.md",
Watches: "Model deprecations and shutdown dates (Chat Completions and Responses text models)",
URLs: []string{"https://developers.openai.com/api/docs/deprecations"},
Plugin: Plugin{Page: retire.OpenAI, Archiver: kit.Wayback{}},
Watches: "Model deprecations and shutdown dates (Chat Completions and Responses text models)",
URLs: []string{"https://developers.openai.com/api/docs/deprecations"},
Packages: []string{"pypi:openai", "npm:openai"},
Plugin: Plugin{Page: retire.OpenAI, Archiver: kit.Wayback{}},
}},
})
plugin.RegisterProvider(plugin.Provider{
ID: "anthropic", Name: "Anthropic", Category: plugin.CategoryAI, Homepage: "https://www.anthropic.com",
Sources: []plugin.Source{{
ID: "models", Layer: plugin.LayerAIModels, Page: "providers/anthropic-models.md",
Watches: "Model deprecations and retirement dates (Messages API models)",
URLs: []string{"https://platform.claude.com/docs/en/about-claude/model-deprecations"},
Plugin: Plugin{Page: retire.Anthropic, Archiver: kit.Wayback{}},
Watches: "Model deprecations and retirement dates (Messages API models)",
URLs: []string{"https://platform.claude.com/docs/en/about-claude/model-deprecations"},
Packages: []string{"pypi:anthropic", "npm:@anthropic-ai/sdk"},
Plugin: Plugin{Page: retire.Anthropic, Archiver: kit.Wayback{}},
}},
})
plugin.RegisterProvider(plugin.Provider{
Expand All @@ -73,9 +75,10 @@ func init() {
ID: "cloudflare", Name: "Cloudflare", Category: plugin.CategoryInfrastructure, Homepage: "https://www.cloudflare.com",
Sources: []plugin.Source{{
ID: "api", Layer: plugin.LayerAPI, Page: "providers/cloudflare.md",
Watches: "REST API operations Cloudflare deprecates, breaking on their end-of-life date when it gives one",
URLs: []string{"https://developers.cloudflare.com/fundamentals/api/reference/deprecations/index.xml"},
Plugin: Plugin{Page: feed.CloudflareAPI, Archiver: kit.Wayback{}},
Watches: "REST API operations Cloudflare deprecates, breaking on their end-of-life date when it gives one",
URLs: []string{"https://developers.cloudflare.com/fundamentals/api/reference/deprecations/index.xml"},
Packages: []string{"pypi:cloudflare", "npm:cloudflare"},
Plugin: Plugin{Page: feed.CloudflareAPI, Archiver: kit.Wayback{}},
}},
})
plugin.RegisterProvider(plugin.Provider{
Expand Down
Loading
Loading