Skip to content
Open
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
46 changes: 26 additions & 20 deletions cmd/new-plugin/formats.go
Original file line number Diff line number Diff line change
Expand Up @@ -427,40 +427,46 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.Event {
defDir: "plugins/catalog",
def: `package catalog

// {{.Ident}} is {{.Provider}}'s catalog: one JSON object, one key per command
// or endpoint, at a git ref.
import "regexp"

// {{.Ident}} is {{.Provider}}'s command catalog: one JSON file per command in a
// directory of its repo, read at each release tag, as Redis's is (redis.go).
//
// ` + todo + `: the ecosystem and package for the events' subject, the repo,
// the catalog's path and the commits API URL for the newest ref. Say what you
// checked, with the date, as catalog.go does for Redis.
var {{.Ident}} = Catalog{
// the directory and the release tags' shape. Say what you checked, with the
// date, as redis.go does for Redis.
var {{.Ident}} = Commands{
API: "{{.ID}}", Ecosystem: "{{.ProviderID}}", Package: "{{.ProviderID}}",
Repo: "TODO-owner/TODO-repo", Path: "TODO/commands.json",
RefsURL: "https://api.github.com/repos/TODO-owner/TODO-repo/commits/main",
Repo: "TODO-owner/TODO-repo", Dir: "TODO/commands",
Release: regexp.MustCompile(` + "`" + `^v?(\d+\.\d+\.\d+)$` + "`" + `),
}
`,
register: `plugin.Register(Plugin{Catalog: {{.Ident}}})`,
pluginOf: `Plugin{Catalog: {{.Ident}}}`,
register: `plugin.Register({{.Ident}})`,
pluginOf: `{{.Ident}}`,
fixtures: map[string]string{
"{{.File}}-old.json": "{\"PLACEHOLDER\": {}}\n",
"{{.File}}-new.json": "{\"PLACEHOLDER\": {}}\n",
"{{.File}}-old.json": "[{\"name\": \"placeholder.json\", \"type\": \"file\"}, {\"name\": \"kept.json\", \"type\": \"file\"}]\n",
"{{.File}}-new.json": "[{\"name\": \"kept.json\", \"type\": \"file\"}]\n",
"{{.File}}-placeholder.json": "{\"PLACEHOLDER\": {\"summary\": \"a placeholder\"}}\n",
},
source: "{{.File}}-new.json",
ingest: `// The two refs the saved snapshots are at.
// ` + todo + `: the real commits, oldest first.
dropFile: "[{\"name\": \"placeholder.json\", \"type\": \"file\"}, {\"name\": \"kept.json\", \"type\": \"file\"}, {\"name\": \"added.json\", \"type\": \"file\"}]\n",
source: "{{.File}}-new.json",
ingest: `// The two releases the saved listings are at.
// ` + todo + `: the real tags, oldest first.
const (
{{.Lower}}OldRef = "0000000000000000000000000000000000000000"
{{.Lower}}NewRef = "1111111111111111111111111111111111111111"
{{.Lower}}OldRef = "v1.0.0"
{{.Lower}}NewRef = "v2.0.0"
)

// {{.Lower}}Ingest extracts the change from the saved old snapshot to file.
// {{.Lower}}Ingest is the version pair from the saved old listing to file,
// the newer release's listing; a file gone from it is read at the old tag.
func {{.Lower}}Ingest(t *testing.T, file string) []event.Event {
t.Helper()
env := kittest.Env(t, kittest.Pages{
{{.Ident}}.URL({{.Lower}}OldRef): "testdata/{{.File}}-old.json",
{{.Ident}}.URL({{.Lower}}NewRef): file,
{{.Ident}}.listingURL({{.Lower}}OldRef): "testdata/{{.File}}-old.json",
{{.Ident}}.listingURL({{.Lower}}NewRef): file,
{{.Ident}}.FileURL({{.Lower}}OldRef, "placeholder.json"): "testdata/{{.File}}-placeholder.json",
})
return kittest.Versions(t, env, Plugin{Catalog: {{.Ident}}},
return kittest.Versions(t, env, {{.Ident}},
plugin.Version{ID: {{.Lower}}OldRef, Ref: {{.Lower}}OldRef}, plugin.Version{ID: {{.Lower}}NewRef, Ref: {{.Lower}}NewRef})
}
`,
Expand Down
2 changes: 1 addition & 1 deletion docs/which-kind.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Every kind is one of two shapes ([writing-a-plugin.md, step 4](writing-a-plugin.
| Is there a **guide that lists what a release removed**, one per major or per release, in a table? | `migrationguide` | The guide at the release's tag: removed request parameters (reader `sdk`) or removed members of a module (reader `members`, RST or Markdown tables) | `MIGRATION.md` per major; "removed members" tables in a 2.0 migration guide; an API version removal guide |
| Is there a **changelog**: a file per release (`CHANGELOG.md`, `CHANGES.rst`, `HISTORY.rst`), or a machine-readable JSON changelog? | `changelog` | The release's section at its tag (reader `markdown`), or the life-cycle entries a JSON changelog adds commit by commit (reader `json`) | Keep a Changelog files; reStructuredText release notes; an API changelog JSON in a repo; a Terraform provider's changelog |
| Is there a **live page of dated notices**: a deprecations or shutdown table, an end-of-life table, or an **RSS/Atom feed** of announcements? | `notices` | The page as it is now, cited through a Web Archive snapshot, against the snapshot kept from the read before: a living page, with no versions of its own (reader `deprecations`, `feed`, or an end-of-life table) | A model deprecations page; an API end-of-life policy table; a changelog feed with a "deprecation" label; a Kubernetes API removals page |
| Is there a **flat catalog**, one JSON entry per name (a command, an endpoint), with no release tags? | `catalog` | Two snapshots, compared for names that disappeared entirely | A list of commands a server accepts, kept in a repo |
| Is there a **structured catalog** in the provider's repo: one JSON file per command, or one file of upcoming removals? | `catalog` | Each release (or commit) of the catalog, compared with the one before: names that disappeared entirely, or removals newly announced | The command definitions a server is built from, at each release tag |
| Is it a **published package** with no changelog worth reading? | `apisurface` | Each release's files from the registry (PyPI first), compared: removed or renamed classes, functions, methods, and parameters removed or newly required | An SDK generated from a spec, released often, whose changelog says "chore: update types" |

Still no "yes"? Open a [discussion](https://github.com/patch-it-dev/patch-it-plugins/discussions) with the source's link: a new kind is a new package under `plugins/`, and the questions above get one more row.
Expand Down
12 changes: 7 additions & 5 deletions docs/writing-a-plugin.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,7 @@ Write the numbers on the provider page, as `providers/vercel.md` does for its sp
| `plugins/notices` | A live page of dated notices: a model provider's deprecations page (a table of date, model, replacement), a vendor's RSS or Atom feed, a vendor's table of whole API version ranges and their support status | A `retire.Page` in `plugins/notices/retire/providers.go`, a `feed.Feed` with a reader for that vendor's entries in `plugins/notices/feed/`, or an `eol.Page` in `plugins/notices/eol/` (`new-plugin` doesn't scaffold this reader yet) |
| `plugins/migrationguide` | A guide that lists what a release removed, at the release's tag: an SDK's migration guide per new major (removed request parameters), or a package's table of removed members (an RST simple table or a Markdown pipe table) | A `sdkguide.Guide` in `plugins/migrationguide/sdkguide/`, or a `members.Guide` in `plugins/migrationguide/members/` |
| `plugins/changelog` | A changelog: a `CHANGELOG.md` / `CHANGES.rst` / `HISTORY.rst`, each release's section at its tag (releases from PyPI or npm), or a vendor's machine-readable API changelog in JSON (per day, endpoint and API version, oasdiff change codes), commit by commit | A `changelog.File` with its `TagPrefix`, or a `changelog.Log` |
| `plugins/catalog` | A flat JSON catalog, one entry per name, with no release tags to pin — a commit SHA stands in | A `catalog.Catalog`, diffed between two snapshots for names that disappeared entirely |
| `plugins/catalog` | A provider's own structured list of what it offers: a command catalog kept as one JSON file per command in its repo, read at each release tag and compared for commands that disappeared entirely | A `catalog.Commands` (repo, directory, release tag pattern); a catalog of another shape is a new reader type in the package |
| `plugins/apisurface` | A published package's public API, compared between two releases: the classes, functions, methods and parameters in each release's files (Python first: the wheel or sdist from PyPI) | A `apisurface.Package` (registry name, ecosystem, top-level module) and its `plugin.RegisterProvider` block |

## 4. The interface
Expand Down Expand Up @@ -204,11 +204,13 @@ The test kit, `core/kit/kittest`, runs the plugin with no network, no database a
```go
func TestGolden(t *testing.T) {
env := kittest.Env(t, kittest.Pages{
Redis.URL(oldRef): "testdata/redis-doc-cc0427b.json",
Redis.URL(newRef): "testdata/redis-doc-06f3598.json",
Redis.listingURL("8.8-m03"): "testdata/redis-contents-src-commands-8.8-m03.json",
Redis.listingURL("8.8-rc1"): "testdata/redis-contents-src-commands-8.8-rc1.json",
Redis.FileURL("8.8-m03", "gcra.json"): "testdata/redis-8.8-m03-gcra.json",
Redis.FileURL("8.8-m03", "gcrasetvalue.json"): "testdata/redis-8.8-m03-gcrasetvalue.json",
})
got := kittest.Versions(t, env, Plugin{Catalog: Redis},
plugin.Version{ID: oldRef, Ref: oldRef}, plugin.Version{ID: newRef, Ref: newRef})
got := kittest.Versions(t, env, Redis,
plugin.Version{ID: "8.8-m03", Ref: "8.8-m03"}, plugin.Version{ID: "8.8-rc1", Ref: "8.8-rc1"})
kittest.Golden(t, "testdata/golden/redis-commands.json", got)
}
```
Expand Down
185 changes: 22 additions & 163 deletions plugins/catalog/catalog.go
Original file line number Diff line number Diff line change
@@ -1,28 +1,20 @@
// Package catalog is the source plugin for a provider that publishes its
// whole command or endpoint surface as one structured JSON file, one entry
// keyed by name: read it at a commit, compare it with the one read before,
// and report
// every name that disappeared entirely between them. Unlike openapi's typed
// spec, an entry here is opaque: no request or response shape to walk, just
// whether the name is still there. Redis first: its command surface has no
// OpenAPI spec, but redis-doc's commands.json is the real, machine-readable
// file redis.io's own command reference is generated from.
// Package catalog is the kind for a provider's own structured list of what
// it offers or is about to take away: a command catalog, a file of upcoming
// removals. Unlike openapi's typed spec, an entry here is opaque beyond its
// name (and, for a list of upcoming changes, its date and what to use
// instead). Each reader is a plugin of its own in this package, read
// version by version (plugin.Versioned): Redis's commands at each release
// tag (redis.go).
//
// Precision over recall: a name that moves to a different key (a genuine
// rename) reads as one removal and one addition, same as any other. This
// never guesses a rename from two disappearances and appearances landing in
// the same diff; it only ever reports what's gone.
// Precision over recall: a name that moves (a genuine rename) reads as one
// removal and one addition, same as any other. A reader never guesses a
// rename from a disappearance and an appearance landing in the same diff.
package catalog

import (
"context"
"encoding/json"
"fmt"
"sort"
"time"

"github.com/patch-it-dev/patch-it-plugins/core/event"
"github.com/patch-it-dev/patch-it-plugins/core/github"
"github.com/patch-it-dev/patch-it-plugins/core/plugin"
)

Expand All @@ -31,162 +23,29 @@ func init() {
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},
Watches: "Commands removed entirely between two Redis releases, from the command definitions in the server's own source (src/commands/) at each release tag",
URLs: []string{"https://github.com/redis/redis/tree/unstable/src/commands", "https://github.com/redis/redis/releases"},
Plugin: Redis,
}},
})
}

// Catalog is one provider's command or endpoint catalog: a single JSON
// object, one key per entry, fetched at a git ref.
type Catalog struct {
API string // the source id the events carry: "redis/commands"
Ecosystem string // the package_release subject's ecosystem: "redis"
Package string // the package_release subject's package: "redis"
Repo string // owner/name on GitHub the catalog lives in
Path string // the catalog's path in the repo
RefsURL string // GitHub's commits API, for the newest ref: .../commits/<branch>
}

// Redis is redis-doc's commands.json, regenerated from each real Redis
// release and read by redis.io's own command reference (checked 2026-11-18).
// The repo has no tags, so a ref here is a commit SHA, not a release.
var Redis = Catalog{
API: "redis/commands", Ecosystem: "redis", Package: "redis",
Repo: "redis/redis-doc", Path: "commands.json",
RefsURL: "https://api.github.com/repos/redis/redis-doc/commits/master",
}

// URL is the catalog as it was at ref: its own provenance.
func (c Catalog) URL(ref string) string {
return fmt.Sprintf("https://raw.githubusercontent.com/%s/%s/%s", c.Repo, ref, c.Path)
}

// parse reads the catalog as a flat map of name to its raw entry: every
// field of an entry (arity, complexity, ACL categories...) is unread, except
// where an entry's own bytes become an event's excerpt.
func parse(data []byte) (map[string]json.RawMessage, error) {
var out map[string]json.RawMessage
if err := json.Unmarshal(data, &out); err != nil {
return nil, fmt.Errorf("parsing catalog: %w", err)
}
return out, nil
}

// removed is every name of old that new doesn't have, sorted so the result
// (and the fingerprints built from it) don't depend on map order.
func removed(old, new map[string]json.RawMessage) []string {
var out []string
for name := range old {
if _, ok := new[name]; !ok {
out = append(out, name)
}
}
sort.Strings(out)
return out
}

// Plugin reads one catalog.
type Plugin struct {
Catalog Catalog
}

func (p Plugin) Name() string { return p.Catalog.API }

// ListVersions is the catalog repo's newest commit: the catalog has no
// releases, so each commit read is a version, and the change into it is
// extracted against the one read before.
func (p Plugin) ListVersions(ctx context.Context, env plugin.Env) ([]plugin.Version, error) {
ref, err := p.latestRef(ctx, env)
if err != nil {
return nil, err
}
return []plugin.Version{{ID: ref, Ref: ref}}, nil
}

// ReadAt fetches the catalog at v's commit.
func (p Plugin) ReadAt(ctx context.Context, env plugin.Env, v plugin.Version) (plugin.Snapshot, error) {
url := p.Catalog.URL(v.Ref)
body, err := env.Get(ctx, url)
if err != nil {
return plugin.Snapshot{}, fmt.Errorf("fetching %s: %w", url, err)
}
return plugin.Snapshot{Version: v, Content: body, SourceURL: url}, nil
}

// Extract is an event per command in from's catalog that isn't in to's,
// with previous_version from's commit. A zero from has nothing to compare.
func (p Plugin) Extract(_ context.Context, env plugin.Env, from, to plugin.Snapshot) (plugin.Result, error) {
events, rejected, err := p.events(from.Content, to.Content, from.Version.Ref, to.Version.Ref, env.Now())
if err != nil {
return plugin.Result{}, err
}
return plugin.Result{Events: events, Rejected: rejected}, nil
}

var _ plugin.Versioned = Plugin{}

// latestRef asks GitHub for the catalog repo's newest commit.
func (p Plugin) latestRef(ctx context.Context, env plugin.Env) (string, error) {
sha, err := github.Head(ctx, env.Get, p.Catalog.RefsURL)
if err != nil {
return "", fmt.Errorf("looking up the newest commit: %w", err)
}
return sha, nil
}

// events diffs two parsed snapshots into events. oldContent is empty for
// the first version read (nothing before it): diffing against no snapshot
// reports nothing, the same as an unchanged one.
func (p Plugin) events(oldContent, newContent []byte, from, to string, now time.Time) ([]event.Event, []error, error) {
c := p.Catalog
newEntries, err := parse(newContent)
if err != nil {
return nil, nil, fmt.Errorf("parsing %s: %w", c.URL(to), err)
}
var oldEntries map[string]json.RawMessage
if len(oldContent) > 0 {
oldEntries, err = parse(oldContent)
if err != nil {
return nil, nil, fmt.Errorf("parsing %s: %w", c.URL(from), err)
}
}

var events []event.Event
var rejected []error
for _, name := range removed(oldEntries, newEntries) {
subject := event.Subject{
Type: event.SubjectPackageRelease, Ecosystem: c.Ecosystem, Package: c.Package,
Change: event.PackageRemovedSymbol, Symbols: []string{name},
}
e := event.Event{
API: c.API, Version: to, PreviousVersion: from,
ChangeType: event.ChangeTypeBreaking,
Breaking: true,
Subject: subject,
Description: fmt.Sprintf("%s no longer exists: calling it now fails.", name),
SourceURL: c.URL(from),
SourceExcerpt: excerpt(name, oldEntries[name]),
Confidence: 1.0,
DetectedAt: now,
}
e.Fingerprint = event.Fingerprint(e.API, e.Version, e.ChangeType, subject, "")
// finish fingerprints and validates the events a reader made, keeping the
// valid ones and the reasons the others failed.
func finish(api string, made []event.Event) (events []event.Event, rejected []error) {
for _, e := range made {
e.Fingerprint = event.Fingerprint(e.API, e.Version, e.ChangeType, e.Subject, "")
if err := e.Validate(); err != nil {
rejected = append(rejected, fmt.Errorf("%s: %w", name, err))
rejected = append(rejected, fmt.Errorf("%s %s: %w", api, e.Description, err))
continue
}
events = append(events, e)
}
return events, rejected, nil
return events, rejected
}

// excerpt quotes the entry exactly as the old snapshot had it: the evidence
// that name existed, in the catalog's own shape. Capped at the contract's
// 2000-character limit, the entry's closing braces never cut off: nested
// command-line arguments can run long.
func excerpt(name string, raw json.RawMessage) string {
s := fmt.Sprintf("%q: %s", name, string(raw))
// excerpt caps a quote at the contract's 2000 characters.
func excerpt(s string) string {
if r := []rune(s); len(r) > 2000 {
s = string(r[:1999]) + "…"
}
Expand Down
Loading
Loading