diff --git a/AGENTS.md b/AGENTS.md index 8e27cd2..efbd38b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -58,9 +58,10 @@ core/event/ core/migrate/ the change-event types from patch-it's contract ( core/diff/ core/normalize/ core/hint/ the OpenAPI diff engine and its helpers plugins// one package per kind, with its providers: openapi (+ adapter/, one spec adapter per provider), retirements (+ retire/), migrationguide (+ sdkguide/, - members/), changelog, feed, apichangelog, catalog, eol; + members/), changelog (Markdown, RST or JSON), feed, catalog, eol; plugins/all imports every one -plugins/removedmembers/ deprecated: merged into migrationguide, only forwards there +plugins/removedmembers/ plugins/apichangelog/ deprecated: merged into migrationguide and + changelog, they only forward there plugin/ event/ fetch/ migrate/ kit/ retire/ sdkguide/ deprecated old import paths: they only forward to the packages above; don't add to them cmd/list-plugins/ prints the list from the registry (make plugins); internal/pluginlist/ is its logic diff --git a/cmd/new-plugin/formats.go b/cmd/new-plugin/formats.go index 2887c0d..b610c6d 100644 --- a/cmd/new-plugin/formats.go +++ b/cmd/new-plugin/formats.go @@ -341,15 +341,15 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { }, "apichangelog": { - kind: "apichangelog", + kind: "changelog", layer: "api", - defDir: "plugins/apichangelog", - def: `package apichangelog + defDir: "plugins/changelog", + def: `package changelog // {{.Ident}} is {{.Provider}}'s machine-readable API changelog. // // ` + todo + `: the repo and the file's path, and what you checked, with the -// date, as apichangelog.go does for MongoDB Atlas. +// date, as json.go does for MongoDB Atlas. var {{.Ident}} = Log{ API: "{{.ID}}", Vendor: "{{.Provider}}", Name: "TODO: the API's name, for sentences", Repo: "TODO-owner/TODO-repo", Path: "changelog/changelog.json", diff --git a/core/plugin/provider.go b/core/plugin/provider.go index 88e75e9..86f4d83 100644 --- a/core/plugin/provider.go +++ b/core/plugin/provider.go @@ -236,6 +236,7 @@ func KindOf(p Plugin) string { // they read is read by the new kind, with the same events. var mergedKinds = map[string]string{ "removedmembers": "migrationguide", + "apichangelog": "changelog", } // CanonicalKind is the kind name means now: name itself, or, for a kind diff --git a/docs/how-it-works.md b/docs/how-it-works.md index 2ffe84c..551dcfb 100644 --- a/docs/how-it-works.md +++ b/docs/how-it-works.md @@ -28,7 +28,7 @@ There's no list in this repo: `make plugins` prints every provider and source fr | [`core/diff/`](../core/diff/), [`core/normalize/`](../core/normalize/), [`core/hint/`](../core/hint/), [`plugins/openapi/adapter/`](../plugins/openapi/adapter/) | The OpenAPI diff engine: compare two specs, turn the changes into events, attach changelog hints; one adapter per spec provider | | [`plugins/retirements/retire/`](../plugins/retirements/retire/), [`plugins/migrationguide/sdkguide/`](../plugins/migrationguide/sdkguide/), [`plugins/migrationguide/members/`](../plugins/migrationguide/members/), [`core/fetch/`](../core/fetch/) | The deprecations-page and migration-guide readers (removed parameters, removed members); the HTTP fetch and cache | | [`contract/fixtures/`](../contract/) | A copy of patch-it's change-event fixtures | -| `plugin/`, `event/`, `fetch/`, `migrate/`, `kit/`, `kit/kittest/`, `retire/`, `sdkguide/`, `plugins/removedmembers/` | Deprecated: the old import paths, forwarding to the packages above until code that imports them moves | +| `plugin/`, `event/`, `fetch/`, `migrate/`, `kit/`, `kit/kittest/`, `retire/`, `sdkguide/`, `plugins/removedmembers/`, `plugins/apichangelog/` | Deprecated: the old import paths, forwarding to the packages above until code that imports them moves | | [`providers/`](../providers/) | One page per provider: why that source, what the plugin reads | | [`docs/`](./) | [How to write a plugin](writing-a-plugin.md), the [README template](README-template.md) patch-it's public repos share | diff --git a/docs/plugins.schema.json b/docs/plugins.schema.json index 79db6ab..8615cac 100644 --- a/docs/plugins.schema.json +++ b/docs/plugins.schema.json @@ -37,7 +37,7 @@ "properties": { "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*/[a-z0-9][a-z0-9-]*$", "description": "provider/source" }, "alias": { "type": "string", "pattern": "^[a-z0-9][a-z0-9.-]*$", "description": "The old slug: --api and every event's api field until patch-it's change-event contract switches to source ids." }, - "kind": { "type": "string", "enum": ["openapi", "retirements", "migrationguide", "changelog", "feed", "apichangelog", "catalog", "eol"] }, + "kind": { "type": "string", "enum": ["openapi", "retirements", "migrationguide", "changelog", "feed", "catalog", "eol"] }, "layer": { "type": "string", "enum": ["api", "sdk", "package", "runtime", "ci", "ai-models", "infra"] }, "watches": { "type": "string", "minLength": 1 }, "urls": { "type": "array", "items": { "type": "string", "pattern": "^https://" } }, diff --git a/docs/writing-a-plugin.md b/docs/writing-a-plugin.md index 1b6fb89..3fa7024 100644 --- a/docs/writing-a-plugin.md +++ b/docs/writing-a-plugin.md @@ -10,7 +10,7 @@ Pick the source and the kind that reads it (steps 2 and 3), then let the starter ```sh go run ./cmd/new-plugin --api acme --provider Acme --format openapi -# --format: openapi, retirements, migrationguide, removedmembers (a migrationguide source), changelog, feed, apichangelog, catalog +# --format: openapi, retirements, migrationguide, removedmembers (a migrationguide source), changelog, feed, apichangelog (a JSON changelog source), catalog # optional: --source https://... (the provider's source), --watches "...", --layer api|sdk|package|runtime|ci|ai-models|infra, # --page acme (a second source of a provider shares its page in providers/) ``` @@ -77,10 +77,9 @@ Write the numbers on the provider page, as `providers/vercel.md` does for its sp | `plugins/openapi` | An OpenAPI spec per release, diffed with `core/diff/` and turned into events by `core/normalize/` | An `adapter.Adapter` in `plugins/openapi/adapter/` (latest tag, fetch a tag's spec; `Versions` to list every release) and a `plugin.RegisterProvider` block | | `plugins/retirements` | A model provider's deprecations page (a table of date, model, replacement) | A `retire.Page` in `plugins/retirements/retire/providers.go` | | `plugins/migrationguide` | A guide that lists what a release removed, at the release's tag: an SDK's migration guide per new major (removed request parameters), or a package's table of removed members (an RST simple table or a Markdown pipe table) | A `sdkguide.Guide` in `plugins/migrationguide/sdkguide/`, or a `members.Guide` in `plugins/migrationguide/members/` | -| `plugins/changelog` | A `CHANGELOG.md` / `CHANGES.rst` / `HISTORY.rst`, each release's section at its tag (releases from PyPI or npm) | A `changelog.File` with its `TagPrefix` | +| `plugins/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/feed` | An RSS or Atom feed | A `feed.Feed` with a reader for that vendor's entries | | `plugins/catalog` | A flat JSON catalog, one entry per name, with no release tags to pin — a commit SHA stands in | A `catalog.Catalog`, diffed between two snapshots for names that disappeared entirely | -| `plugins/apichangelog` | A vendor's machine-readable API changelog in JSON (per day, endpoint and API version, oasdiff change codes), at the commit that last changed it | An `apichangelog.Log` | | `plugins/eol` | A vendor's own table of whole API version ranges and their support status (supported, deprecated, retired) | An `eol.Page`; `--format` doesn't scaffold this one yet, write it by hand | ## 4. The interface diff --git a/plugins/all/all.go b/plugins/all/all.go index d93ee4d..74a0d2c 100644 --- a/plugins/all/all.go +++ b/plugins/all/all.go @@ -4,7 +4,6 @@ package all import ( - _ "github.com/patch-it-dev/patch-it-plugins/plugins/apichangelog" _ "github.com/patch-it-dev/patch-it-plugins/plugins/catalog" _ "github.com/patch-it-dev/patch-it-plugins/plugins/changelog" _ "github.com/patch-it-dev/patch-it-plugins/plugins/eol" diff --git a/plugins/apichangelog/apichangelog.go b/plugins/apichangelog/apichangelog.go index 271129f..1013b47 100644 --- a/plugins/apichangelog/apichangelog.go +++ b/plugins/apichangelog/apichangelog.go @@ -1,282 +1,18 @@ -// Package apichangelog is the source plugin for a vendor's machine-readable -// API changelog: a JSON file, kept in a repo, that lists per day each -// endpoint's changes per API version, each with a change code (oasdiff's) and -// whether it's backward compatible. MongoDB publishes one for the Atlas -// Administration API. +// Package apichangelog is the old import path of the changelog kind's JSON +// parser, kept so code that imports it still builds. // -// It reads only an endpoint's life cycle, in the vendor's own words: an API -// version deprecated (`deprecation`), unless the vendor reactivates it later, -// and an API version removed at its sunset (`breaking`). The rest of the changelog is property-level, and the vendor's -// "not backward compatible" there is broad (a response enum gaining a value -// counts), so it isn't read: precision over recall. -// -// The file is read at the commit that last changed it, whose URL never -// changes, so that URL is the events' provenance (no snapshot). Every run -// reads the whole file; the fingerprints dedupe. +// Deprecated: use plugins/changelog: Plugin{Log: changelog.MongoDBAtlas}. +// This package only forwards there and registers nothing; it goes once +// nothing imports it. package apichangelog -import ( - "bytes" - "context" - "encoding/json" - "fmt" - "log" - "sort" +import "github.com/patch-it-dev/patch-it-plugins/plugins/changelog" - "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/kit" - "github.com/patch-it-dev/patch-it-plugins/core/plugin" +type ( + // Plugin is changelog.Plugin: set Log, as before. + Plugin = changelog.Plugin + Log = changelog.Log + Finding = changelog.LogFinding ) -func init() { - 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. -type Log struct { - API string // the events' api: "mongodb-atlas" - Vendor string // for sentences: "MongoDB" - Name string // the API, for sentences: "Atlas Administration API" - Repo string // owner/name on GitHub - Path string // the file's path in the repo -} - -// MongoDBAtlas is the Atlas Administration API's changelog, -// changelog/changelog.json in mongodb/openapi (checked 2026-11-19: 188 days -// from 2023-02-01 to 2026-11-18, released by MongoDB's CI, "Release API -// Changelog", a few times a month; the docs page -// https://www.mongodb.com/docs/atlas/reference/api-resources-spec/changelog/ -// is built from it). Atlas versions each resource by date (`2023-01-01`), -// chosen per request in the Accept header. -var MongoDBAtlas = Log{ - API: "mongodb-atlas", Vendor: "MongoDB", Name: "Atlas Administration API", - Repo: "mongodb/openapi", Path: "changelog/changelog.json", -} - -// CommitsURL lists the newest commit that changed the file. -func (l Log) CommitsURL() string { - return fmt.Sprintf("https://api.github.com/repos/%s/commits?path=%s&per_page=1", l.Repo, l.Path) -} - -// URL is the file at one commit: its own provenance. -func (l Log) URL(sha string) string { - return fmt.Sprintf("https://raw.githubusercontent.com/%s/%s/%s", l.Repo, sha, l.Path) -} - -// The file's shape: newest day first. -type day struct { - Date string `json:"date"` - Paths []struct { - Path string `json:"path"` - Method string `json:"httpMethod"` - Versions []struct { - Version string `json:"version"` - Changes []json.RawMessage `json:"changes"` - } `json:"versions"` - } `json:"paths"` -} - -type change struct { - Change string `json:"change"` - ChangeCode string `json:"changeCode"` - BackwardCompatible bool `json:"backwardCompatible"` -} - -// lifecycle is what each change code this plugin reads means, each about a -// whole endpoint at one API version: "endpoint deprecated"; "new resource -// added 2023-02-01. Resource version 2023-01-01 deprecated and marked for -// removal on 2025-06-01"; "endpoint with API Version '2023-01-01' was removed -// as it has reached its sunset date '2026-01-22'". -// -// Not read: "api path removed without deprecation". Its one entry -// (streams/activeVpcPeeringConnections, 2025-01-10) comes with -// `endpoint-added` the same day, and the endpoint changes again later: it -// wasn't removed. -var lifecycle = map[string]event.ChangeType{ - "endpoint-deprecated": event.ChangeTypeDeprecation, - "resource-version-deprecated": event.ChangeTypeDeprecation, - "endpoint-removed": event.ChangeTypeBreaking, -} - -// reactivated withdraws a deprecation: "endpoint reactivated". MongoDB does -// it (13 times by 2026-11-18): GET /api/atlas/v2/groups/{groupId}/clusters -// at 2024-05-30 was deprecated on 2024-06-25 and reactivated the next day. -const reactivated = "endpoint-reactivated" - -// Finding is one life-cycle change. -type Finding struct { - ChangeType event.ChangeType - Date string // the changelog's day - Operation string // "GET /api/atlas/v2/groups/{groupId}/clusters" - Version string // the API version it's about: "2023-01-01" - Code string - Pointer string // RFC 6901, into the file - Excerpt string // the change, as JSON -} - -// Read finds every life-cycle change in the file that still stands, by -// replaying the days oldest first: a reactivation of an endpoint's version -// withdraws its deprecation, and a deprecation after that is a new one. A -// deprecation counts from the first time it's announced since the last -// reactivation; the changelog repeats some. A removal counts from its first -// announcement too, and is withdrawn, with any deprecation before it, if the -// same endpoint and version shows up again on a later day with anything but -// another removal (none of the 38 in the file on 2026-11-18 does). The excerpt is the change as the file writes -// it, whitespace aside. -func (l Log) Read(b []byte) ([]Finding, error) { - var days []day - if err := json.Unmarshal(b, &days); err != nil { - return nil, fmt.Errorf("not a changelog: %w", err) - } - if len(days) == 0 { - return nil, fmt.Errorf("the changelog has no days: it may have moved or changed shape") - } - type item struct { - seq int - f Finding - } - deprecated := map[string]item{} // by operation and version, until reactivated - removed := map[string]item{} - seq := 0 - for di := len(days) - 1; di >= 0; di-- { - d := days[di] - for pi, p := range d.Paths { - for vi, v := range p.Versions { - for ci, raw := range v.Changes { - var c change - if err := json.Unmarshal(raw, &c); err != nil { - return nil, fmt.Errorf("day %s, %s %s: %w", d.Date, p.Method, p.Path, err) - } - op := p.Method + " " + p.Path - key := op + " " + v.Version - if r, ok := removed[key]; ok && r.f.Date < d.Date && lifecycle[c.ChangeCode] != event.ChangeTypeBreaking { - // It came back. Whether its old deprecation still - // applies is unclear, so that goes too. - delete(removed, key) - delete(deprecated, key) - } - if c.ChangeCode == reactivated { - delete(deprecated, key) - continue - } - ct, ok := lifecycle[c.ChangeCode] - if !ok { - continue - } - var ex bytes.Buffer - if err := json.Compact(&ex, raw); err != nil { - return nil, err - } - f := Finding{ - ChangeType: ct, Date: d.Date, Operation: op, Version: v.Version, Code: c.ChangeCode, - Pointer: fmt.Sprintf("/%d/paths/%d/versions/%d/changes/%d", di, pi, vi, ci), - Excerpt: ex.String(), - } - seq++ - target := deprecated - if ct == event.ChangeTypeBreaking { - target = removed - } - if _, dup := target[key]; !dup { - target[key] = item{seq, f} - } - } - } - } - } - all := make([]item, 0, len(deprecated)+len(removed)) - for _, it := range deprecated { - all = append(all, it) - } - for _, it := range removed { - all = append(all, it) - } - sort.Slice(all, func(i, j int) bool { return all[i].seq < all[j].seq }) - out := make([]Finding, len(all)) - for i, it := range all { - out[i] = it.f - } - return out, nil -} - -// Plugin reads one vendor's changelog. -type Plugin struct { - Log Log -} - -func (p Plugin) Name() string { return p.Log.API } - -// Run reads the file at the newest commit that changed it. -func (p Plugin) Run(ctx context.Context, env plugin.Env) (plugin.Result, error) { - l := p.Log - sha, err := github.LatestCommit(ctx, env.Get, l.CommitsURL()) - if err != nil { - return plugin.Result{}, fmt.Errorf("looking up %s's newest changelog commit (%s in %s): %w", l.API, l.Path, l.Repo, err) - } - url := l.URL(sha) - page, err := env.Get(ctx, url) - if err != nil { - return plugin.Result{}, fmt.Errorf("fetching %s: %w", url, err) - } - last, same, err := kit.Unchanged(env, l.API, page) - if err != nil { - return plugin.Result{}, err - } - if same { - log.Printf("%s: no change since %s", l.API, last.SourceURL) - return plugin.Result{}, nil - } - findings, err := l.Read(page) - if err != nil { - return plugin.Result{}, fmt.Errorf("reading %s: %w", url, err) - } - - now := env.Now().UTC() - var events []event.EventV2 - var rejected []error - for _, f := range findings { - e := event.EventV2{ - API: l.API, - Version: f.Version, - ChangeType: f.ChangeType, - Breaking: f.ChangeType == event.ChangeTypeBreaking, - Subject: event.Subject{Type: event.SubjectAPIOperation, Kind: event.AffectedKindOperation, Side: event.SideRequest, Operation: f.Operation}, - Description: describe(l, f), - SourceURL: url, - SourcePointer: f.Pointer, - SourceExcerpt: f.Excerpt, - Confidence: 1.0, - DetectedAt: now, - } - e.Fingerprint = event.FingerprintV2(e.API, e.Version, e.ChangeType, e.Subject, "") - if err := e.Validate(); err != nil { - rejected = append(rejected, fmt.Errorf("%s %s %s: %w", l.API, f.Operation, f.Version, err)) - continue - } - events = append(events, e) - } - return plugin.Result{ - Label: url, - Events: events, - Rejected: rejected, - Baselines: []plugin.Spec{plugin.Baseline(l.API, sha, sha, url, page, false, now)}, - }, nil -} - -func describe(l Log, f Finding) string { - switch f.ChangeType { - case event.ChangeTypeBreaking: - return fmt.Sprintf("%s %s, API version %s, removed on %s (%s's changelog, %s).", l.Name, f.Operation, f.Version, f.Date, l.Vendor, f.Code) - default: - return fmt.Sprintf("%s %s, API version %s, deprecated on %s (%s's changelog, %s).", l.Name, f.Operation, f.Version, f.Date, l.Vendor, f.Code) - } -} +var MongoDBAtlas = changelog.MongoDBAtlas diff --git a/plugins/apichangelog/apichangelog_test.go b/plugins/apichangelog/apichangelog_test.go index 21a0eea..ed0bdad 100644 --- a/plugins/apichangelog/apichangelog_test.go +++ b/plugins/apichangelog/apichangelog_test.go @@ -1,279 +1,16 @@ package apichangelog import ( - "encoding/json" - "reflect" - "strconv" - "strings" "testing" - "github.com/patch-it-dev/patch-it-plugins/core/event" "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" ) -const ( - latestSHA = "c0f99ca9145e5aa74d08ae4451020857e93b5f28" // 2026-11-18 20:15 UTC, "Release API Changelog" - fixture = "testdata/mongodb-atlas-changelog-c0f99ca9.json" -) - -// saved serves the commits lookup and the changelog at that commit. -func saved(commits, sha, file string) kittest.Pages { - return kittest.Pages{MongoDBAtlas.CommitsURL(): commits, MongoDBAtlas.URL(sha): file} -} - -// The golden test: MongoDB's changelog as released at c0f99ca9 (2026-11-18), -// with every change this plugin doesn't read replaced by {} so that every -// pointer is the one in the real file (testdata/README.md). -func TestGolden(t *testing.T) { - pages := saved("testdata/commits-c0f99ca9.json", latestSHA, fixture) - got := kittest.Ingest(t, Plugin{Log: MongoDBAtlas}, pages) - kittest.Golden(t, "testdata/golden/mongodb-atlas.json", got) - - // Every event cites the pinned file, and its excerpt is the change its - // pointer names there. - for _, e := range got { - if e.SourceURL != MongoDBAtlas.URL(latestSHA) { - t.Errorf("%s: source_url %s", e.Subject.Operation, e.SourceURL) - } - if node := nodeAt(t, fixture, e.SourcePointer); !sameJSON(node, e.SourceExcerpt) { - t.Errorf("%s: excerpt %s, but %s holds %s", e.Subject.Operation, e.SourceExcerpt, e.SourcePointer, node) - } - } -} - -// The historical breaking change: on 2026-01-22 Atlas removed API version -// 2023-01-01 of the shared-tier ("tenant") backup endpoints, "as it has -// reached its sunset date '2026-01-22'". -func TestTenantBackupSunset(t *testing.T) { - fs, err := MongoDBAtlas.Read(kittest.Read(t, fixture)) - if err != nil { - t.Fatal(err) - } - var n int - for _, f := range fs { - if !strings.Contains(f.Operation, "/backup/tenant/") || f.Version != "2023-01-01" { - continue - } - n++ - if f.ChangeType != event.ChangeTypeBreaking || f.Date != "2026-01-22" || f.Code != "endpoint-removed" { - t.Errorf("%s: %s %s %s", f.Operation, f.ChangeType, f.Date, f.Code) - } - if !strings.Contains(f.Excerpt, "has reached its sunset date '2026-01-22'") { - t.Errorf("%s: excerpt %s", f.Operation, f.Excerpt) - } - } - if n == 0 { - t.Error("no tenant backup removal read") - } -} - -// The pinned drop test: the changelog's newest day (2026-11-18), whole and -// unchanged: 104 changes, 23 of them marked not backward compatible -// (`request-property-one-of-removed`, …), none an endpoint's life cycle. -// No event. -func TestPropertyChangesMakeNoEvent(t *testing.T) { - const sha = "0000000000000000000000000000000000000001" - file := "testdata/mongodb-atlas-changelog-2026-11-18-day.json" - var days []day - if err := json.Unmarshal(kittest.Read(t, file), &days); err != nil { - t.Fatal(err) - } - var notBC int - for _, p := range days[0].Paths { - for _, v := range p.Versions { - for _, raw := range v.Changes { - var c change - if err := json.Unmarshal(raw, &c); err != nil { - t.Fatal(err) - } - if !c.BackwardCompatible { - notBC++ - } - } - } - } - if notBC != 23 { - t.Fatalf("the fixture has %d changes not backward compatible, want 23", notBC) - } - if got := kittest.Ingest(t, Plugin{Log: MongoDBAtlas}, saved("testdata/commits-day.json", sha, file)); len(got) != 0 { - for _, e := range got { - t.Logf("got: %s", e.Description) - } - t.Fatalf("%d events, want none", len(got)) - } -} - -// MongoDB deprecated GET and POST /api/atlas/v2/groups/{groupId}/clusters at -// API version 2024-05-30 on 2024-06-25 and reactivated them on 2024-06-26 (and -// 2023-11-15 on 2024-05-09, reactivated 2024-05-16): versions still in use. -// No deprecation of either stands. -func TestReactivationWithdrawsTheDeprecation(t *testing.T) { - // The saved file does hold those deprecations and reactivations. - var days []day - if err := json.Unmarshal(kittest.Read(t, fixture), &days); err != nil { - t.Fatal(err) - } - codes := map[string]int{} - for _, d := range days { - for _, p := range d.Paths { - for _, v := range p.Versions { - for _, raw := range v.Changes { - var c change - if err := json.Unmarshal(raw, &c); err != nil { - t.Fatal(err) - } - if p.Path == "/api/atlas/v2/groups/{groupId}/clusters" && v.Version == "2024-05-30" { - codes[c.ChangeCode]++ - } - } - } - } - } - if codes["endpoint-deprecated"] == 0 || codes["endpoint-reactivated"] == 0 { - t.Fatalf("the fixture's clusters 2024-05-30 entries are %v: they no longer show a reactivation", codes) - } - fs, err := MongoDBAtlas.Read(kittest.Read(t, fixture)) - if err != nil { - t.Fatal(err) - } - for _, f := range fs { - if strings.HasSuffix(f.Operation, " /api/atlas/v2/groups/{groupId}/clusters") && (f.Version == "2024-05-30" || f.Version == "2023-11-15") { - t.Errorf("%s %s: %s on %s, but MongoDB reactivated it", f.Operation, f.Version, f.ChangeType, f.Date) - } - } -} - -// Deprecated, reactivated, deprecated again: one deprecation, the second. -// Deprecated, then removed: both. And "api path removed without deprecation" -// isn't read (its one real entry was an endpoint that stayed). -func TestLifeCycleReplay(t *testing.T) { - ch := func(code string) string { - return `{"change":"x","changeCode":"` + code + `","backwardCompatible":true}` - } - day := func(date, path, code string) string { - return `{"date":"` + date + `","paths":[{"path":"` + path + `","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[` + ch(code) + `]}]}]}` - } - b := []byte("[" + strings.Join([]string{ // newest day first, as the file is - day("2026-05-01", "/b", "endpoint-removed"), - day("2026-04-01", "/c", "api-path-removed-without-deprecation"), - day("2026-03-01", "/a", "endpoint-deprecated"), - day("2026-02-01", "/a", "endpoint-reactivated"), - day("2026-01-15", "/b", "resource-version-deprecated"), - day("2026-01-01", "/a", "endpoint-deprecated"), - }, ",") + "]") - fs, err := MongoDBAtlas.Read(b) - if err != nil { - t.Fatal(err) - } - var got []string - for _, f := range fs { - got = append(got, f.Date+" "+f.Operation+" "+string(f.ChangeType)) - } - want := []string{"2026-01-15 GET /b deprecation", "2026-03-01 GET /a deprecation", "2026-05-01 GET /b breaking"} - if strings.Join(got, "; ") != strings.Join(want, "; ") { - t.Errorf("got %q, want %q", got, want) - } -} - -// A removal followed by the same endpoint and version on a later day (an -// `endpoint-added`, any change) didn't happen: no event. And the excerpt -// keeps every field the vendor wrote, in its order. -func TestRemovalUndoneAndRawExcerpt(t *testing.T) { - b := []byte(`[ - {"date":"2026-03-01","paths":[{"path":"/a","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"endpoint added","changeCode":"endpoint-added","backwardCompatible":true}]}]}]}, - {"date":"2026-02-01","paths":[{"path":"/a","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"removed","changeCode":"endpoint-removed","backwardCompatible":false}]}]}, - {"path":"/b","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"removed","changeCode":"endpoint-removed","backwardCompatible":false,"sunset":"2026-02-01"}]}]}]} - ]`) - fs, err := MongoDBAtlas.Read(b) - if err != nil { - t.Fatal(err) - } - if len(fs) != 1 || fs[0].Operation != "GET /b" { - t.Fatalf("got %+v, want only GET /b's removal", fs) - } - if want := `{"change":"removed","changeCode":"endpoint-removed","backwardCompatible":false,"sunset":"2026-02-01"}`; fs[0].Excerpt != want { - t.Errorf("excerpt %s, want %s", fs[0].Excerpt, want) - } -} - -// A removal announced twice keeps its first announcement. A version that's -// deprecated, removed and then back has neither event. -func TestRepeatedRemovalAndReturn(t *testing.T) { - day := func(date, path, code string) string { - return `{"date":"` + date + `","paths":[{"path":"` + path + `","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"x","changeCode":"` + code + `","backwardCompatible":true}]}]}]}` - } - b := []byte("[" + strings.Join([]string{ - day("2026-04-01", "/a", "endpoint-added"), - day("2026-03-01", "/b", "endpoint-removed"), - day("2026-02-01", "/b", "endpoint-removed"), - day("2026-02-01", "/a", "endpoint-removed"), - day("2026-01-01", "/a", "endpoint-deprecated"), - }, ",") + "]") - fs, err := MongoDBAtlas.Read(b) - if err != nil { - t.Fatal(err) - } - if len(fs) != 1 || fs[0].Operation != "GET /b" || fs[0].Date != "2026-02-01" || fs[0].Pointer != "/2/paths/0/versions/0/changes/0" { - t.Errorf("got %+v, want GET /b's removal once, as announced on 2026-02-01", fs) - } -} - -// A change announced again on a later day is one event, as first announced. -func TestRepeatsAreReadOnce(t *testing.T) { - b := []byte(`[ - {"date":"2026-02-01","paths":[{"path":"/a","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"endpoint deprecated","changeCode":"endpoint-deprecated","backwardCompatible":true}]}]}]}, - {"date":"2026-01-01","paths":[{"path":"/a","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"endpoint deprecated","changeCode":"endpoint-deprecated","backwardCompatible":true},{"change":"added the new optional request property","changeCode":"new-optional-request-property","backwardCompatible":true}]}]}]} - ]`) - fs, err := MongoDBAtlas.Read(b) - if err != nil { - t.Fatal(err) - } - if len(fs) != 1 || fs[0].Date != "2026-01-01" || fs[0].Pointer != "/1/paths/0/versions/0/changes/0" { - t.Errorf("got %+v, want the 2026-01-01 announcement once", fs) - } -} - -func TestReadRefusesWhatIsntAChangelog(t *testing.T) { - for name, b := range map[string]string{"html": "moved", "empty": "[]", "object": `{"date":"x"}`} { - if _, err := MongoDBAtlas.Read([]byte(b)); err == nil { - t.Errorf("%s: want an error, never zero events read as a quiet week", name) - } - } -} - -func TestRegistersItself(t *testing.T) { - kittest.Registered(t, Plugin{Log: MongoDBAtlas}) -} - -func sameJSON(a, b string) bool { - var x, y any - if json.Unmarshal([]byte(a), &x) != nil || json.Unmarshal([]byte(b), &y) != nil { - return false - } - return reflect.DeepEqual(x, y) -} - -// nodeAt resolves an RFC 6901 pointer in a JSON file and serializes the node. -func nodeAt(t *testing.T, file, pointer string) string { - t.Helper() - var node any - if err := json.Unmarshal(kittest.Read(t, file), &node); err != nil { - t.Fatal(err) - } - for _, tok := range strings.Split(strings.TrimPrefix(pointer, "/"), "/") { - switch n := node.(type) { - case map[string]any: - node = n[tok] - case []any: - i, err := strconv.Atoi(tok) - if err != nil || i >= len(n) { - return "" - } - node = n[i] - default: - return "" - } +// Code written against the old path still builds and runs the same source. +func TestTheOldPathStillWorks(t *testing.T) { + p := Plugin{Log: MongoDBAtlas} + kittest.Registered(t, p) + if p.Name() != "mongodb-atlas" { + t.Errorf("Plugin{Log: MongoDBAtlas} is %q", p.Name()) } - b, _ := json.Marshal(node) - return string(b) } diff --git a/plugins/apichangelog/testdata/README.md b/plugins/apichangelog/testdata/README.md deleted file mode 100644 index 30f2a0a..0000000 --- a/plugins/apichangelog/testdata/README.md +++ /dev/null @@ -1,9 +0,0 @@ -# Saved changelogs - -| File | URL | Saved | License | Quote | -|---|---|---|---|---| -| `mongodb-atlas-changelog-c0f99ca9.json` | https://raw.githubusercontent.com/mongodb/openapi/c0f99ca9145e5aa74d08ae4451020857e93b5f28/changelog/changelog.json (the "Release API Changelog" commit of 2026-11-18 20:15 UTC; the same file as `main` on 2026-11-19) | 2026-11-19 | Apache-2.0 (mongodb/openapi) | "endpoint with API Version '2023-01-01' was removed as it has reached its sunset date '2026-01-22'" | -| `mongodb-atlas-changelog-2026-11-18-day.json` | The same file's newest day (`2026-11-18`), kept whole and unchanged: the drop test | 2026-11-19 | Apache-2.0 (mongodb/openapi) | `"changeCode": "request-property-one-of-removed"`, `"backwardCompatible": false` | -| `commits-c0f99ca9.json`, `commits-day.json` | Stand-ins for `https://api.github.com/repos/mongodb/openapi/commits?path=changelog/changelog.json&per_page=1`, keeping only the field the plugin reads (`sha`) | 2026-11-19 | n/a (test fixtures) | | - -**Trimmed, positions kept:** the real file is 10 MB. `mongodb-atlas-changelog-c0f99ca9.json` keeps every day, endpoint, API version and change in place. Every change the plugin doesn't read is replaced by `{}`: all but the three life-cycle codes and `endpoint-reactivated`. So is every endpoint or version left with none. So every JSON pointer in `golden/mongodb-atlas.json` names the same change in the real file. The 105 kept changes are copied unchanged. The plugin reads exactly the same 81 findings from this copy as from the real file (checked when the copy was made). The copy is re-indented. diff --git a/plugins/changelog/changelog.go b/plugins/changelog/changelog.go index 25bea03..ff3f790 100644 --- a/plugins/changelog/changelog.go +++ b/plugins/changelog/changelog.go @@ -1,5 +1,9 @@ -// Package changelog is the source plugin for a package's changelog file -// (CHANGELOG.md, CHANGES.rst, HISTORY.rst), read at a release's tag: one +// Package changelog is the kind for a changelog, with a parser for each +// shape: a package's changelog file in Markdown or reStructuredText (File; +// this file, parse.go, classify.go), or a vendor's machine-readable API +// changelog in JSON (Log; json.go). One Plugin reads either. +// +// A changelog file (CHANGELOG.md, CHANGES.rst, HISTORY.rst) is read at a release's tag: one // change event per bullet that plainly removes, renames or deprecates names // code uses. The tag never changes, so its URL is the event's provenance (no // snapshot) and a rerun stores nothing new: the fingerprints dedupe. @@ -44,6 +48,15 @@ func init() { Plugin: Plugin{File: Urllib3}, }}, }) + 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}, + }}, + }) } // File is one package's changelog. Unpinned (Tag and Release empty), it is @@ -147,18 +160,32 @@ func (f File) added(sections []Section) map[string]bool { return out } -// Plugin reads a package's changelog: release by release (ListVersions, -// ReadAt, Extract), or, with a pinned File, that one release. +// Plugin reads one changelog, in one of two shapes: set File for a +// Markdown or RST changelog (read release by release: ListVersions, ReadAt, +// Extract; or, pinned, that one release), or Log for a JSON one (read commit +// by commit: json.go). type Plugin struct { File File + Log Log } -func (p Plugin) Name() string { return p.File.Package } +// isLog is a JSON changelog. +func (p Plugin) isLog() bool { return p.Log.API != "" } + +func (p Plugin) Name() string { + if p.isLog() { + return p.Log.API + } + return p.File.Package +} // Run reads the pinned release, or the newest one on the registry, and // stores its events. A release's tag never changes, so a rerun stores nothing // new: the fingerprints dedupe. func (p Plugin) Run(ctx context.Context, env plugin.Env) (plugin.Result, error) { + if p.isLog() { + return p.runLog(ctx, env) + } v := plugin.Version{ID: p.File.Release, Ref: p.File.Tag} if p.File.Tag == "" { vs, err := p.ListVersions(ctx, env) @@ -185,6 +212,9 @@ func (p Plugin) Run(ctx context.Context, env plugin.Env) (plugin.Result, error) // ListVersions is every final release of the package on its registry, oldest // first, each read at TagPrefix + version; a pinned File has its one release. func (p Plugin) ListVersions(ctx context.Context, env plugin.Env) ([]plugin.Version, error) { + if p.isLog() { + return p.listLog(ctx, env) + } f := p.File if f.Tag != "" { return []plugin.Version{{ID: f.Release, Ref: f.Tag}}, nil @@ -210,6 +240,9 @@ func (p Plugin) ListVersions(ctx context.Context, env plugin.Env) ([]plugin.Vers // ReadAt fetches the changelog at the release's tag. func (p Plugin) ReadAt(ctx context.Context, env plugin.Env, v plugin.Version) (plugin.Snapshot, error) { + if p.isLog() { + return p.readLog(ctx, env, v) + } f := p.File f.Release, f.Tag = v.ID, v.Ref page, err := env.Get(ctx, f.URL()) @@ -224,6 +257,9 @@ func (p Plugin) ReadAt(ctx context.Context, env plugin.Env, v plugin.Version) (p // from's release. Releases are extracted pair by pair, so from is the release // right before to and to's section is everything between them. func (p Plugin) Extract(_ context.Context, env plugin.Env, from, to plugin.Snapshot) (plugin.Result, error) { + if p.isLog() { + return p.extractLog(env, from, to) + } f := p.File f.Release, f.Tag = to.Version.ID, to.Version.Ref heading, findings, err := f.Read(to.Content) diff --git a/plugins/changelog/json.go b/plugins/changelog/json.go new file mode 100644 index 0000000..421bfff --- /dev/null +++ b/plugins/changelog/json.go @@ -0,0 +1,310 @@ +// The JSON parser: a vendor's machine-readable API changelog, a JSON file +// kept in a repo that lists per day each endpoint's changes per API +// version, each with a change code (oasdiff's) and whether it's backward +// compatible. MongoDB publishes one for the Atlas Administration API. +// +// It reads only an endpoint's life cycle, in the vendor's own words: an API +// version deprecated (`deprecation`), unless the vendor reactivates it later, +// and an API version removed at its sunset (`breaking`). The rest of the +// changelog is property-level, and the vendor's "not backward compatible" +// there is broad (a response enum gaining a value counts), so it isn't read: +// precision over recall. +// +// Its versions are the commits that changed the file, whose URLs never +// change, so a commit's URL is the events' provenance (no snapshot). A pair +// of commits gives the findings the newer one has and the older one didn't; +// a plain run reads the whole file at the newest commit, and the +// fingerprints dedupe. + +package changelog + +import ( + "bytes" + "context" + "encoding/json" + "fmt" + "log" + "sort" + + "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/kit" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" + "github.com/patch-it-dev/patch-it-plugins/core/versions" +) + +// Log is one vendor's changelog file. +type Log struct { + API string // the events' api: "mongodb-atlas" + Vendor string // for sentences: "MongoDB" + Name string // the API, for sentences: "Atlas Administration API" + Repo string // owner/name on GitHub + Path string // the file's path in the repo +} + +// MongoDBAtlas is the Atlas Administration API's changelog, +// changelog/changelog.json in mongodb/openapi (checked 2026-11-19: 188 days +// from 2023-02-01 to 2026-11-18, released by MongoDB's CI, "Release API +// Changelog", a few times a month; the docs page +// https://www.mongodb.com/docs/atlas/reference/api-resources-spec/changelog/ +// is built from it). Atlas versions each resource by date (`2023-01-01`), +// chosen per request in the Accept header. +var MongoDBAtlas = Log{ + API: "mongodb-atlas", Vendor: "MongoDB", Name: "Atlas Administration API", + Repo: "mongodb/openapi", Path: "changelog/changelog.json", +} + +// CommitsURL lists the newest commit that changed the file. +func (l Log) CommitsURL() string { + return fmt.Sprintf("https://api.github.com/repos/%s/commits?path=%s&per_page=1", l.Repo, l.Path) +} + +// URL is the file at one commit: its own provenance. +func (l Log) URL(sha string) string { + return fmt.Sprintf("https://raw.githubusercontent.com/%s/%s/%s", l.Repo, sha, l.Path) +} + +// The file's shape: newest day first. +type day struct { + Date string `json:"date"` + Paths []struct { + Path string `json:"path"` + Method string `json:"httpMethod"` + Versions []struct { + Version string `json:"version"` + Changes []json.RawMessage `json:"changes"` + } `json:"versions"` + } `json:"paths"` +} + +type change struct { + Change string `json:"change"` + ChangeCode string `json:"changeCode"` + BackwardCompatible bool `json:"backwardCompatible"` +} + +// lifecycle is what each change code this plugin reads means, each about a +// whole endpoint at one API version: "endpoint deprecated"; "new resource +// added 2023-02-01. Resource version 2023-01-01 deprecated and marked for +// removal on 2025-06-01"; "endpoint with API Version '2023-01-01' was removed +// as it has reached its sunset date '2026-01-22'". +// +// Not read: "api path removed without deprecation". Its one entry +// (streams/activeVpcPeeringConnections, 2025-01-10) comes with +// `endpoint-added` the same day, and the endpoint changes again later: it +// wasn't removed. +var lifecycle = map[string]event.ChangeType{ + "endpoint-deprecated": event.ChangeTypeDeprecation, + "resource-version-deprecated": event.ChangeTypeDeprecation, + "endpoint-removed": event.ChangeTypeBreaking, +} + +// reactivated withdraws a deprecation: "endpoint reactivated". MongoDB does +// it (13 times by 2026-11-18): GET /api/atlas/v2/groups/{groupId}/clusters +// at 2024-05-30 was deprecated on 2024-06-25 and reactivated the next day. +const reactivated = "endpoint-reactivated" + +// LogFinding is one life-cycle change. +type LogFinding struct { + ChangeType event.ChangeType + Date string // the changelog's day + Operation string // "GET /api/atlas/v2/groups/{groupId}/clusters" + Version string // the API version it's about: "2023-01-01" + Code string + Pointer string // RFC 6901, into the file + Excerpt string // the change, as JSON +} + +// Read finds every life-cycle change in the file that still stands, by +// replaying the days oldest first: a reactivation of an endpoint's version +// withdraws its deprecation, and a deprecation after that is a new one. A +// deprecation counts from the first time it's announced since the last +// reactivation; the changelog repeats some. A removal counts from its first +// announcement too, and is withdrawn, with any deprecation before it, if the +// same endpoint and version shows up again on a later day with anything but +// another removal (none of the 38 in the file on 2026-11-18 does). The excerpt is the change as the file writes +// it, whitespace aside. +func (l Log) Read(b []byte) ([]LogFinding, error) { + var days []day + if err := json.Unmarshal(b, &days); err != nil { + return nil, fmt.Errorf("not a changelog: %w", err) + } + if len(days) == 0 { + return nil, fmt.Errorf("the changelog has no days: it may have moved or changed shape") + } + type item struct { + seq int + f LogFinding + } + deprecated := map[string]item{} // by operation and version, until reactivated + removed := map[string]item{} + seq := 0 + for di := len(days) - 1; di >= 0; di-- { + d := days[di] + for pi, p := range d.Paths { + for vi, v := range p.Versions { + for ci, raw := range v.Changes { + var c change + if err := json.Unmarshal(raw, &c); err != nil { + return nil, fmt.Errorf("day %s, %s %s: %w", d.Date, p.Method, p.Path, err) + } + op := p.Method + " " + p.Path + key := op + " " + v.Version + if r, ok := removed[key]; ok && r.f.Date < d.Date && lifecycle[c.ChangeCode] != event.ChangeTypeBreaking { + // It came back. Whether its old deprecation still + // applies is unclear, so that goes too. + delete(removed, key) + delete(deprecated, key) + } + if c.ChangeCode == reactivated { + delete(deprecated, key) + continue + } + ct, ok := lifecycle[c.ChangeCode] + if !ok { + continue + } + var ex bytes.Buffer + if err := json.Compact(&ex, raw); err != nil { + return nil, err + } + f := LogFinding{ + ChangeType: ct, Date: d.Date, Operation: op, Version: v.Version, Code: c.ChangeCode, + Pointer: fmt.Sprintf("/%d/paths/%d/versions/%d/changes/%d", di, pi, vi, ci), + Excerpt: ex.String(), + } + seq++ + target := deprecated + if ct == event.ChangeTypeBreaking { + target = removed + } + if _, dup := target[key]; !dup { + target[key] = item{seq, f} + } + } + } + } + } + all := make([]item, 0, len(deprecated)+len(removed)) + for _, it := range deprecated { + all = append(all, it) + } + for _, it := range removed { + all = append(all, it) + } + sort.Slice(all, func(i, j int) bool { return all[i].seq < all[j].seq }) + out := make([]LogFinding, len(all)) + for i, it := range all { + out[i] = it.f + } + return out, nil +} + +// runLog reads the file at the newest commit that changed it. +func (p Plugin) runLog(ctx context.Context, env plugin.Env) (plugin.Result, error) { + l := p.Log + sha, err := github.LatestCommit(ctx, env.Get, l.CommitsURL()) + if err != nil { + return plugin.Result{}, fmt.Errorf("looking up %s's newest changelog commit (%s in %s): %w", l.API, l.Path, l.Repo, err) + } + to, err := p.readLog(ctx, env, plugin.Version{ID: sha, Ref: sha}) + if err != nil { + return plugin.Result{}, err + } + last, same, err := kit.Unchanged(env, l.API, to.Content) + if err != nil { + return plugin.Result{}, err + } + if same { + log.Printf("%s: no change since %s", l.API, last.SourceURL) + return plugin.Result{}, nil + } + res, err := p.extractLog(env, plugin.Snapshot{}, to) + if err != nil { + return plugin.Result{}, err + } + res.Baselines = []plugin.Spec{plugin.Baseline(l.API, sha, sha, to.SourceURL, to.Content, false, env.Now().UTC())} + return res, nil +} + +// listLog is every commit that changed the file, oldest first: the ID is +// the commit's date, the Ref its SHA. +func (p Plugin) listLog(ctx context.Context, env plugin.Env) ([]plugin.Version, error) { + return versions.GitHubCommits(ctx, env.Get, p.Log.Repo, p.Log.Path) +} + +// readLog fetches the file at the commit v.Ref. +func (p Plugin) readLog(ctx context.Context, env plugin.Env, v plugin.Version) (plugin.Snapshot, error) { + url := p.Log.URL(v.Ref) + page, err := env.Get(ctx, url) + if err != nil { + return plugin.Snapshot{}, fmt.Errorf("fetching %s: %w", url, err) + } + return plugin.Snapshot{Version: v, Content: page, SourceURL: url}, nil +} + +// extractLog is an event per life-cycle change that stands at to and didn't +// at from (every one, when from is zero). The events are about the +// endpoint's API version, so they carry that version, not the commit's. +func (p Plugin) extractLog(env plugin.Env, from, to plugin.Snapshot) (plugin.Result, error) { + l := p.Log + findings, err := l.Read(to.Content) + if err != nil { + return plugin.Result{}, fmt.Errorf("reading %s: %w", to.SourceURL, err) + } + if !from.IsZero() { + before, err := l.Read(from.Content) + if err != nil { + return plugin.Result{}, fmt.Errorf("reading %s: %w", from.SourceURL, err) + } + had := map[string]bool{} + for _, f := range before { + had[f.key()] = true + } + kept := findings[:0:0] + for _, f := range findings { + if !had[f.key()] { + kept = append(kept, f) + } + } + findings = kept + } + now := env.Now().UTC() + var events []event.EventV2 + var rejected []error + for _, f := range findings { + e := event.EventV2{ + API: l.API, + Version: f.Version, + ChangeType: f.ChangeType, + Breaking: f.ChangeType == event.ChangeTypeBreaking, + Subject: event.Subject{Type: event.SubjectAPIOperation, Kind: event.AffectedKindOperation, Side: event.SideRequest, Operation: f.Operation}, + Description: describeLog(l, f), + SourceURL: to.SourceURL, + SourcePointer: f.Pointer, + SourceExcerpt: f.Excerpt, + Confidence: 1.0, + DetectedAt: now, + } + e.Fingerprint = event.FingerprintV2(e.API, e.Version, e.ChangeType, e.Subject, "") + if err := e.Validate(); err != nil { + rejected = append(rejected, fmt.Errorf("%s %s %s: %w", l.API, f.Operation, f.Version, err)) + continue + } + events = append(events, e) + } + return plugin.Result{Label: to.SourceURL, Events: events, Rejected: rejected}, nil +} + +// key is what makes two findings the same change: an endpoint's API version +// deprecated, or removed. +func (f LogFinding) key() string { return string(f.ChangeType) + " " + f.Operation + " " + f.Version } + +func describeLog(l Log, f LogFinding) string { + switch f.ChangeType { + case event.ChangeTypeBreaking: + return fmt.Sprintf("%s %s, API version %s, removed on %s (%s's changelog, %s).", l.Name, f.Operation, f.Version, f.Date, l.Vendor, f.Code) + default: + return fmt.Sprintf("%s %s, API version %s, deprecated on %s (%s's changelog, %s).", l.Name, f.Operation, f.Version, f.Date, l.Vendor, f.Code) + } +} diff --git a/plugins/changelog/json_test.go b/plugins/changelog/json_test.go new file mode 100644 index 0000000..e065056 --- /dev/null +++ b/plugins/changelog/json_test.go @@ -0,0 +1,324 @@ +package changelog + +import ( + "context" + "encoding/json" + "fmt" + "reflect" + "strconv" + "strings" + "testing" + + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" +) + +const ( + atlasSHA = "c0f99ca9145e5aa74d08ae4451020857e93b5f28" // 2026-11-18 20:15 UTC, "Release API Changelog" + atlasFixture = "testdata/mongodb-atlas-changelog-c0f99ca9.json" +) + +// saved serves the commits lookup and the changelog at that commit. +func savedLog(commits, sha, file string) kittest.Pages { + return kittest.Pages{MongoDBAtlas.CommitsURL(): commits, MongoDBAtlas.URL(sha): file} +} + +// The golden test: MongoDB's changelog as released at c0f99ca9 (2026-11-18), +// with every change this plugin doesn't read replaced by {} so that every +// pointer is the one in the real file (testdata/README.md). +func TestJSONGolden(t *testing.T) { + pages := savedLog("testdata/commits-c0f99ca9.json", atlasSHA, atlasFixture) + got := kittest.Ingest(t, Plugin{Log: MongoDBAtlas}, pages) + kittest.Golden(t, "testdata/golden/mongodb-atlas.json", got) + + // Every event cites the pinned file, and its excerpt is the change its + // pointer names there. + for _, e := range got { + if e.SourceURL != MongoDBAtlas.URL(atlasSHA) { + t.Errorf("%s: source_url %s", e.Subject.Operation, e.SourceURL) + } + if node := nodeAt(t, atlasFixture, e.SourcePointer); !sameJSON(node, e.SourceExcerpt) { + t.Errorf("%s: excerpt %s, but %s holds %s", e.Subject.Operation, e.SourceExcerpt, e.SourcePointer, node) + } + } +} + +// The historical breaking change: on 2026-01-22 Atlas removed API version +// 2023-01-01 of the shared-tier ("tenant") backup endpoints, "as it has +// reached its sunset date '2026-01-22'". +func TestTenantBackupSunset(t *testing.T) { + fs, err := MongoDBAtlas.Read(kittest.Read(t, atlasFixture)) + if err != nil { + t.Fatal(err) + } + var n int + for _, f := range fs { + if !strings.Contains(f.Operation, "/backup/tenant/") || f.Version != "2023-01-01" { + continue + } + n++ + if f.ChangeType != event.ChangeTypeBreaking || f.Date != "2026-01-22" || f.Code != "endpoint-removed" { + t.Errorf("%s: %s %s %s", f.Operation, f.ChangeType, f.Date, f.Code) + } + if !strings.Contains(f.Excerpt, "has reached its sunset date '2026-01-22'") { + t.Errorf("%s: excerpt %s", f.Operation, f.Excerpt) + } + } + if n == 0 { + t.Error("no tenant backup removal read") + } +} + +// The pinned drop test: the changelog's newest day (2026-11-18), whole and +// unchanged: 104 changes, 23 of them marked not backward compatible +// (`request-property-one-of-removed`, …), none an endpoint's life cycle. +// No event. +func TestPropertyChangesMakeNoEvent(t *testing.T) { + const sha = "0000000000000000000000000000000000000001" + file := "testdata/mongodb-atlas-changelog-2026-11-18-day.json" + var days []day + if err := json.Unmarshal(kittest.Read(t, file), &days); err != nil { + t.Fatal(err) + } + var notBC int + for _, p := range days[0].Paths { + for _, v := range p.Versions { + for _, raw := range v.Changes { + var c change + if err := json.Unmarshal(raw, &c); err != nil { + t.Fatal(err) + } + if !c.BackwardCompatible { + notBC++ + } + } + } + } + if notBC != 23 { + t.Fatalf("the atlasFixture has %d changes not backward compatible, want 23", notBC) + } + if got := kittest.Ingest(t, Plugin{Log: MongoDBAtlas}, savedLog("testdata/commits-day.json", sha, file)); len(got) != 0 { + for _, e := range got { + t.Logf("got: %s", e.Description) + } + t.Fatalf("%d events, want none", len(got)) + } +} + +// MongoDB deprecated GET and POST /api/atlas/v2/groups/{groupId}/clusters at +// API version 2024-05-30 on 2024-06-25 and reactivated them on 2024-06-26 (and +// 2023-11-15 on 2024-05-09, reactivated 2024-05-16): versions still in use. +// No deprecation of either stands. +func TestReactivationWithdrawsTheDeprecation(t *testing.T) { + // The saved file does hold those deprecations and reactivations. + var days []day + if err := json.Unmarshal(kittest.Read(t, atlasFixture), &days); err != nil { + t.Fatal(err) + } + codes := map[string]int{} + for _, d := range days { + for _, p := range d.Paths { + for _, v := range p.Versions { + for _, raw := range v.Changes { + var c change + if err := json.Unmarshal(raw, &c); err != nil { + t.Fatal(err) + } + if p.Path == "/api/atlas/v2/groups/{groupId}/clusters" && v.Version == "2024-05-30" { + codes[c.ChangeCode]++ + } + } + } + } + } + if codes["endpoint-deprecated"] == 0 || codes["endpoint-reactivated"] == 0 { + t.Fatalf("the atlasFixture's clusters 2024-05-30 entries are %v: they no longer show a reactivation", codes) + } + fs, err := MongoDBAtlas.Read(kittest.Read(t, atlasFixture)) + if err != nil { + t.Fatal(err) + } + for _, f := range fs { + if strings.HasSuffix(f.Operation, " /api/atlas/v2/groups/{groupId}/clusters") && (f.Version == "2024-05-30" || f.Version == "2023-11-15") { + t.Errorf("%s %s: %s on %s, but MongoDB reactivated it", f.Operation, f.Version, f.ChangeType, f.Date) + } + } +} + +// Deprecated, reactivated, deprecated again: one deprecation, the second. +// Deprecated, then removed: both. And "api path removed without deprecation" +// isn't read (its one real entry was an endpoint that stayed). +func TestLifeCycleReplay(t *testing.T) { + ch := func(code string) string { + return `{"change":"x","changeCode":"` + code + `","backwardCompatible":true}` + } + day := func(date, path, code string) string { + return `{"date":"` + date + `","paths":[{"path":"` + path + `","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[` + ch(code) + `]}]}]}` + } + b := []byte("[" + strings.Join([]string{ // newest day first, as the file is + day("2026-05-01", "/b", "endpoint-removed"), + day("2026-04-01", "/c", "api-path-removed-without-deprecation"), + day("2026-03-01", "/a", "endpoint-deprecated"), + day("2026-02-01", "/a", "endpoint-reactivated"), + day("2026-01-15", "/b", "resource-version-deprecated"), + day("2026-01-01", "/a", "endpoint-deprecated"), + }, ",") + "]") + fs, err := MongoDBAtlas.Read(b) + if err != nil { + t.Fatal(err) + } + var got []string + for _, f := range fs { + got = append(got, f.Date+" "+f.Operation+" "+string(f.ChangeType)) + } + want := []string{"2026-01-15 GET /b deprecation", "2026-03-01 GET /a deprecation", "2026-05-01 GET /b breaking"} + if strings.Join(got, "; ") != strings.Join(want, "; ") { + t.Errorf("got %q, want %q", got, want) + } +} + +// A removal followed by the same endpoint and version on a later day (an +// `endpoint-added`, any change) didn't happen: no event. And the excerpt +// keeps every field the vendor wrote, in its order. +func TestRemovalUndoneAndRawExcerpt(t *testing.T) { + b := []byte(`[ + {"date":"2026-03-01","paths":[{"path":"/a","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"endpoint added","changeCode":"endpoint-added","backwardCompatible":true}]}]}]}, + {"date":"2026-02-01","paths":[{"path":"/a","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"removed","changeCode":"endpoint-removed","backwardCompatible":false}]}]}, + {"path":"/b","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"removed","changeCode":"endpoint-removed","backwardCompatible":false,"sunset":"2026-02-01"}]}]}]} + ]`) + fs, err := MongoDBAtlas.Read(b) + if err != nil { + t.Fatal(err) + } + if len(fs) != 1 || fs[0].Operation != "GET /b" { + t.Fatalf("got %+v, want only GET /b's removal", fs) + } + if want := `{"change":"removed","changeCode":"endpoint-removed","backwardCompatible":false,"sunset":"2026-02-01"}`; fs[0].Excerpt != want { + t.Errorf("excerpt %s, want %s", fs[0].Excerpt, want) + } +} + +// A removal announced twice keeps its first announcement. A version that's +// deprecated, removed and then back has neither event. +func TestRepeatedRemovalAndReturn(t *testing.T) { + day := func(date, path, code string) string { + return `{"date":"` + date + `","paths":[{"path":"` + path + `","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"x","changeCode":"` + code + `","backwardCompatible":true}]}]}]}` + } + b := []byte("[" + strings.Join([]string{ + day("2026-04-01", "/a", "endpoint-added"), + day("2026-03-01", "/b", "endpoint-removed"), + day("2026-02-01", "/b", "endpoint-removed"), + day("2026-02-01", "/a", "endpoint-removed"), + day("2026-01-01", "/a", "endpoint-deprecated"), + }, ",") + "]") + fs, err := MongoDBAtlas.Read(b) + if err != nil { + t.Fatal(err) + } + if len(fs) != 1 || fs[0].Operation != "GET /b" || fs[0].Date != "2026-02-01" || fs[0].Pointer != "/2/paths/0/versions/0/changes/0" { + t.Errorf("got %+v, want GET /b's removal once, as announced on 2026-02-01", fs) + } +} + +// A change announced again on a later day is one event, as first announced. +func TestRepeatsAreReadOnce(t *testing.T) { + b := []byte(`[ + {"date":"2026-02-01","paths":[{"path":"/a","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"endpoint deprecated","changeCode":"endpoint-deprecated","backwardCompatible":true}]}]}]}, + {"date":"2026-01-01","paths":[{"path":"/a","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"endpoint deprecated","changeCode":"endpoint-deprecated","backwardCompatible":true},{"change":"added the new optional request property","changeCode":"new-optional-request-property","backwardCompatible":true}]}]}]} + ]`) + fs, err := MongoDBAtlas.Read(b) + if err != nil { + t.Fatal(err) + } + if len(fs) != 1 || fs[0].Date != "2026-01-01" || fs[0].Pointer != "/1/paths/0/versions/0/changes/0" { + t.Errorf("got %+v, want the 2026-01-01 announcement once", fs) + } +} + +func TestReadRefusesWhatIsntAChangelog(t *testing.T) { + for name, b := range map[string]string{"html": "moved", "empty": "[]", "object": `{"date":"x"}`} { + if _, err := MongoDBAtlas.Read([]byte(b)); err == nil { + t.Errorf("%s: want an error, never zero events read as a quiet week", name) + } + } +} + +func sameJSON(a, b string) bool { + var x, y any + if json.Unmarshal([]byte(a), &x) != nil || json.Unmarshal([]byte(b), &y) != nil { + return false + } + return reflect.DeepEqual(x, y) +} + +// nodeAt resolves an RFC 6901 pointer in a JSON file and serializes the node. +func nodeAt(t *testing.T, file, pointer string) string { + t.Helper() + var node any + if err := json.Unmarshal(kittest.Read(t, file), &node); err != nil { + t.Fatal(err) + } + for _, tok := range strings.Split(strings.TrimPrefix(pointer, "/"), "/") { + switch n := node.(type) { + case map[string]any: + node = n[tok] + case []any: + i, err := strconv.Atoi(tok) + if err != nil || i >= len(n) { + return "" + } + node = n[i] + default: + return "" + } + } + b, _ := json.Marshal(node) + return string(b) +} + +// Three commits of a JSON changelog are three versions, oldest first, and +// two consecutive pairs; each pair gives only what the newer commit added. +func TestJSONChangelogPairByPair(t *testing.T) { + sha := func(n int) string { return fmt.Sprintf("%040d", n) } + pages := kittest.Pages{ + "https://api.github.com/repos/mongodb/openapi/commits?path=changelog%2Fchangelog.json&per_page=100&page=1": "testdata/log-history/commits.json", + } + for n := 1; n <= 3; n++ { + pages[MongoDBAtlas.URL(sha(n))] = fmt.Sprintf("testdata/log-history/changelog-%d.json", n) + } + env := kittest.Env(t, pages) + ctx := context.Background() + p := Plugin{Log: MongoDBAtlas} + vs, err := p.ListVersions(ctx, env) + if err != nil { + t.Fatal(err) + } + var ids []string + for _, v := range vs { + ids = append(ids, v.ID) + } + if got := strings.Join(ids, " "); got != "2026-01-01 2026-02-01 2026-03-01" { + t.Fatalf("versions %s", got) + } + var got []string + snaps := make([]plugin.Snapshot, len(vs)) + for i, v := range vs { + if snaps[i], err = p.ReadAt(ctx, env, v); err != nil { + t.Fatal(err) + } + } + for _, pair := range [][2]int{{0, 1}, {1, 2}} { + res, err := p.Extract(ctx, env, snaps[pair[0]], snaps[pair[1]]) + if err != nil || len(res.Rejected) > 0 { + t.Fatalf("%v %v", err, res.Rejected) + } + for _, e := range res.Events { + got = append(got, vs[pair[1]].ID+": "+e.Subject.Operation+" "+string(e.ChangeType)) + } + } + want := "2026-02-01: GET /b deprecation; 2026-03-01: GET /a breaking" + if strings.Join(got, "; ") != want { + t.Errorf("pairs gave %q, want %q", strings.Join(got, "; "), want) + } +} diff --git a/plugins/changelog/registered_test.go b/plugins/changelog/registered_test.go index 0a182c8..df91f1e 100644 --- a/plugins/changelog/registered_test.go +++ b/plugins/changelog/registered_test.go @@ -10,4 +10,5 @@ func TestRegistersItself(t *testing.T) { for _, f := range []File{Textual0860, Urllib3200} { kittest.Registered(t, Plugin{File: f}) } + kittest.Registered(t, Plugin{Log: MongoDBAtlas}) } diff --git a/plugins/changelog/testdata/README.md b/plugins/changelog/testdata/README.md index 8196285..305bf8e 100644 --- a/plugins/changelog/testdata/README.md +++ b/plugins/changelog/testdata/README.md @@ -14,3 +14,19 @@ golden files under `golden/` are what the plugin stores from them | File | URL | Saved | License | Use | |---|---|---|---|---| | `pypi-urllib3-excerpt.json` | https://pypi.org/pypi/urllib3/json (shape only) | written for the test, 2026-11-20 | not a saved copy: four releases in the shape of PyPI's JSON API (`releases` → files with `upload_time_iso_8601`, `yanked`), dates approximate, a pre-release among them | for the version-listing test only (ListVersions, consecutive pairs); no golden reads it | + +## JSON changelogs + +Read with `Plugin{Log: ...}` (json.go); `golden/mongodb-atlas.json` is what it stores from the first file. + +| File | URL | Saved | License | Quote | +|---|---|---|---|---| +| `mongodb-atlas-changelog-c0f99ca9.json` | https://raw.githubusercontent.com/mongodb/openapi/c0f99ca9145e5aa74d08ae4451020857e93b5f28/changelog/changelog.json (the "Release API Changelog" commit of 2026-11-18 20:15 UTC; the same file as `main` on 2026-11-19) | 2026-11-19 | Apache-2.0 (mongodb/openapi) | "endpoint with API Version '2023-01-01' was removed as it has reached its sunset date '2026-01-22'" | +| `mongodb-atlas-changelog-2026-11-18-day.json` | The same file's newest day (`2026-11-18`), kept whole and unchanged: the drop test | 2026-11-19 | Apache-2.0 (mongodb/openapi) | `"changeCode": "request-property-one-of-removed"`, `"backwardCompatible": false` | +| `commits-c0f99ca9.json`, `commits-day.json` | Stand-ins for `https://api.github.com/repos/mongodb/openapi/commits?path=changelog/changelog.json&per_page=1`, keeping only the field the plugin reads (`sha`) | 2026-11-19 | n/a (test fixtures) | | + +**Trimmed, positions kept:** the real file is 10 MB. `mongodb-atlas-changelog-c0f99ca9.json` keeps every day, endpoint, API version and change in place. Every change the plugin doesn't read is replaced by `{}`: all but the three life-cycle codes and `endpoint-reactivated`. So is every endpoint or version left with none. So every JSON pointer in `golden/mongodb-atlas.json` names the same change in the real file. The 105 kept changes are copied unchanged. The plugin reads exactly the same 81 findings from this copy as from the real file (checked when the copy was made). The copy is re-indented. + +| File | URL | Saved | License | Use | +|---|---|---|---|---| +| `log-history/commits.json`, `log-history/changelog-{1,2,3}.json` | Stand-ins for the GitHub commits list of `changelog/changelog.json` and the file at three commits, in the real file's shape | written for the test, 2026-11-20 | n/a (test fixtures) | for the pair-by-pair test only (three versions, two pairs); no golden reads them | diff --git a/plugins/apichangelog/testdata/commits-c0f99ca9.json b/plugins/changelog/testdata/commits-c0f99ca9.json similarity index 100% rename from plugins/apichangelog/testdata/commits-c0f99ca9.json rename to plugins/changelog/testdata/commits-c0f99ca9.json diff --git a/plugins/apichangelog/testdata/commits-day.json b/plugins/changelog/testdata/commits-day.json similarity index 100% rename from plugins/apichangelog/testdata/commits-day.json rename to plugins/changelog/testdata/commits-day.json diff --git a/plugins/apichangelog/testdata/golden/mongodb-atlas.json b/plugins/changelog/testdata/golden/mongodb-atlas.json similarity index 100% rename from plugins/apichangelog/testdata/golden/mongodb-atlas.json rename to plugins/changelog/testdata/golden/mongodb-atlas.json diff --git a/plugins/changelog/testdata/log-history/changelog-1.json b/plugins/changelog/testdata/log-history/changelog-1.json new file mode 100644 index 0000000..07964e1 --- /dev/null +++ b/plugins/changelog/testdata/log-history/changelog-1.json @@ -0,0 +1 @@ +[{"date":"2026-01-01","paths":[{"path":"/a","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"deprecated","changeCode":"endpoint-deprecated","backwardCompatible":true}]}]}]}] diff --git a/plugins/changelog/testdata/log-history/changelog-2.json b/plugins/changelog/testdata/log-history/changelog-2.json new file mode 100644 index 0000000..11e4655 --- /dev/null +++ b/plugins/changelog/testdata/log-history/changelog-2.json @@ -0,0 +1 @@ +[{"date":"2026-02-01","paths":[{"path":"/b","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"deprecated","changeCode":"resource-version-deprecated","backwardCompatible":true}]}]}]},{"date":"2026-01-01","paths":[{"path":"/a","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"deprecated","changeCode":"endpoint-deprecated","backwardCompatible":true}]}]}]}] diff --git a/plugins/changelog/testdata/log-history/changelog-3.json b/plugins/changelog/testdata/log-history/changelog-3.json new file mode 100644 index 0000000..9bb8e06 --- /dev/null +++ b/plugins/changelog/testdata/log-history/changelog-3.json @@ -0,0 +1 @@ +[{"date":"2026-03-01","paths":[{"path":"/a","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"removed","changeCode":"endpoint-removed","backwardCompatible":false}]}]}]},{"date":"2026-02-01","paths":[{"path":"/b","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"deprecated","changeCode":"resource-version-deprecated","backwardCompatible":true}]}]}]},{"date":"2026-01-01","paths":[{"path":"/a","httpMethod":"GET","versions":[{"version":"2023-01-01","changes":[{"change":"deprecated","changeCode":"endpoint-deprecated","backwardCompatible":true}]}]}]}] diff --git a/plugins/changelog/testdata/log-history/commits.json b/plugins/changelog/testdata/log-history/commits.json new file mode 100644 index 0000000..c86fa74 --- /dev/null +++ b/plugins/changelog/testdata/log-history/commits.json @@ -0,0 +1,5 @@ +[ + {"sha":"0000000000000000000000000000000000000003","html_url":"https://github.com/mongodb/openapi/commit/0000000000000000000000000000000000000003","commit":{"committer":{"date":"2026-03-01T00:00:00Z"}}}, + {"sha":"0000000000000000000000000000000000000002","html_url":"https://github.com/mongodb/openapi/commit/0000000000000000000000000000000000000002","commit":{"committer":{"date":"2026-02-01T00:00:00Z"}}}, + {"sha":"0000000000000000000000000000000000000001","html_url":"https://github.com/mongodb/openapi/commit/0000000000000000000000000000000000000001","commit":{"committer":{"date":"2026-01-01T00:00:00Z"}}} +] diff --git a/plugins/apichangelog/testdata/mongodb-atlas-changelog-2026-11-18-day.json b/plugins/changelog/testdata/mongodb-atlas-changelog-2026-11-18-day.json similarity index 100% rename from plugins/apichangelog/testdata/mongodb-atlas-changelog-2026-11-18-day.json rename to plugins/changelog/testdata/mongodb-atlas-changelog-2026-11-18-day.json diff --git a/plugins/apichangelog/testdata/mongodb-atlas-changelog-c0f99ca9.json b/plugins/changelog/testdata/mongodb-atlas-changelog-c0f99ca9.json similarity index 100% rename from plugins/apichangelog/testdata/mongodb-atlas-changelog-c0f99ca9.json rename to plugins/changelog/testdata/mongodb-atlas-changelog-c0f99ca9.json diff --git a/providers/mongodb-atlas.md b/providers/mongodb-atlas.md index 19d14b2..c0a5143 100644 --- a/providers/mongodb-atlas.md +++ b/providers/mongodb-atlas.md @@ -4,7 +4,7 @@ The MongoDB Atlas Administration API (`/api/atlas/v2`): an endpoint's API version deprecated (unless MongoDB reactivates it), and an endpoint's API version removed at its sunset date, as MongoDB lists them in its own machine-readable API changelog. -Format plugin: `apichangelog` (`plugins/apichangelog`), with the `MongoDBAtlas` log. +Kind: `changelog` (`plugins/changelog`), with its JSON parser (`json.go`) and the `MongoDBAtlas` log. ## Why this source