diff --git a/AGENTS.md b/AGENTS.md index efbd38b..2292472 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -53,15 +53,16 @@ core/plugin/ the Plugin interface (Run; ListVersions, ReadAt, Extract) core/fetch/ the HTTP fetch with retries and the ETag / Last-Modified cache core/github/ the newest release / commit on GitHub, and a commit's SHA and date (one place) core/versions/ every version of a source: GitHub releases, tags and commits, PyPI, npm, the Web Archive at a date -core/kit/ core/kit/kittest/ Unchanged, Cite, Wayback; the test kit (Mem, Pages, Ingest, Golden) +core/kit/ core/kit/kittest/ Unchanged, Cite, Wayback, Notices; the test kit (Mem, Pages, Ingest, Golden) +core/extract/ what readers of prose share: RSS/Atom entries, HTML as text, dates, code spans core/event/ core/migrate/ the change-event types from patch-it's contract (v1 + v2), v1 -> v2 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 (Markdown, RST or JSON), feed, catalog, eol; + per provider), notices (+ retire/, feed/, eol/), migrationguide (+ sdkguide/, + members/), changelog (Markdown, RST or JSON), catalog; plugins/all imports every one -plugins/removedmembers/ plugins/apichangelog/ deprecated: merged into migrationguide and - changelog, they only forward there +plugins/removedmembers/ apichangelog/ retirements/ feed/ eol/ deprecated: merged into + migrationguide, changelog and notices, 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/README.md b/README.md index ab32e15..9b8da30 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ You need Go (the version in `go.mod`), `make` and Python 3. ``` 2. **Fill in every `TODO(new-plugin)`**: the reader, the provider and source metadata in its `plugin.RegisterProvider` block, a saved copy of the source in `testdata/`, and "Why this source" in `providers/acme.md`. Then write the golden file and read it like code: ```sh - go test ./plugins/feed -run TestAcme -update + go test ./plugins/notices -run TestAcme -update ``` 3. **Check it the way CI will, and open the PR** (`git commit -s`, one provider per PR): ```sh diff --git a/cmd/new-plugin/formats.go b/cmd/new-plugin/formats.go index b610c6d..a14761b 100644 --- a/cmd/new-plugin/formats.go +++ b/cmd/new-plugin/formats.go @@ -31,9 +31,9 @@ const todo = "TODO(new-plugin)" var formats = map[string]formatSpec{ "feed": { - kind: "feed", + kind: "notices", layer: "api", - defDir: "plugins/feed", + defDir: "plugins/notices/feed", def: `package feed // {{.Ident}} is {{.Provider}}'s feed of changes. @@ -60,8 +60,8 @@ func read{{.Ident}}(e Entry) []Finding { return nil } `, - register: `plugin.Register(Plugin{Feed: {{.Ident}}, Archiver: kit.Wayback{}})`, - pluginOf: `Plugin{Feed: {{.Ident}}}`, + register: `plugin.Register(Plugin{Page: feed.{{.Ident}}, Archiver: kit.Wayback{}})`, + pluginOf: `Plugin{Page: feed.{{.Ident}}}`, fixtures: map[string]string{"{{.File}}.rss.xml": ` placeholderhttps://example.com/placeholder @@ -73,18 +73,18 @@ func read{{.Ident}}(e Entry) []Finding { // through a test archive that serves the same copy. func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { t.Helper() - saved := kittest.Pages{ {{.Ident}}.URL: file} + saved := kittest.Pages{feed.{{.Ident}}.URL: file} archive := &kittest.Archive{T: t, Pages: saved} - return kittest.IngestWith(t, kittest.Env(t, saved), Plugin{Feed: {{.Ident}}, Archiver: archive}) + return kittest.IngestWith(t, kittest.Env(t, saved), Plugin{Page: feed.{{.Ident}}, Archiver: archive}) } `, - imports: []string{"github.com/patch-it-dev/patch-it-plugins/core/event"}, + imports: []string{"github.com/patch-it-dev/patch-it-plugins/core/event", "github.com/patch-it-dev/patch-it-plugins/plugins/notices/feed"}, }, "retirements": { - kind: "retirements", + kind: "notices", layer: "ai-models", - defDir: "plugins/retirements/retire", + defDir: "plugins/notices/retire", def: `package retire import "strings" @@ -152,7 +152,7 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { return kittest.IngestWith(t, kittest.Env(t, saved), Plugin{Page: retire.{{.Ident}}, Archiver: archive}) } `, - imports: []string{"encoding/json", "strings", "github.com/patch-it-dev/patch-it-plugins/core/event", "github.com/patch-it-dev/patch-it-plugins/plugins/retirements/retire"}, + imports: []string{"encoding/json", "strings", "github.com/patch-it-dev/patch-it-plugins/core/event", "github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire"}, }, "migrationguide": { diff --git a/plugins/feed/parse.go b/core/extract/feed.go similarity index 93% rename from plugins/feed/parse.go rename to core/extract/feed.go index f49d035..22b0d02 100644 --- a/plugins/feed/parse.go +++ b/core/extract/feed.go @@ -1,4 +1,8 @@ -package feed +// Package extract is what readers of prose share: an RSS or Atom feed's +// entries, an HTML fragment as plain text or lines, its sections by +// heading, a "Month D, YYYY" date, the code spans in it. A reader of any +// kind uses it; it knows no vendor. +package extract import ( "bytes" @@ -53,10 +57,10 @@ type atom struct { } `xml:"entry"` } -// Parse reads an RSS 2.0 or Atom feed, whichever the root element says. A +// ParseFeed reads an RSS 2.0 or Atom feed, whichever the root element says. A // feed with no entries is an error: a feed that moved or changed shape must // not read as a quiet week. -func Parse(b []byte) ([]Entry, error) { +func ParseFeed(b []byte) ([]Entry, error) { var root struct{ XMLName xml.Name } if err := xml.NewDecoder(bytes.NewReader(b)).Decode(&root); err != nil { return nil, fmt.Errorf("not a feed: %w", err) diff --git a/core/kit/notices.go b/core/kit/notices.go new file mode 100644 index 0000000..a2c3a2b --- /dev/null +++ b/core/kit/notices.go @@ -0,0 +1,11 @@ +package kit + +// Notices is what a reader of a live page of dated notices (a deprecations +// table, an end-of-life table, a feed: plugins/notices) found on one read +// of it. The kind compares what the live page and its snapshot give with +// reflect.DeepEqual (Cite), so a Notices holds plain values, never a func. +type Notices interface { + // Count is how many notices were read: what the shape guard compares + // with the last read. + Count() int +} diff --git a/core/migrate/migrate.go b/core/migrate/migrate.go index 3ffa523..4cc5b0f 100644 --- a/core/migrate/migrate.go +++ b/core/migrate/migrate.go @@ -16,7 +16,7 @@ import ( "github.com/patch-it-dev/patch-it-plugins/core/event" "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/sdkguide" - "github.com/patch-it-dev/patch-it-plugins/plugins/retirements/retire" + "github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire" ) // providers are the model retirement slugs and who retires the models. diff --git a/core/plugin/provider.go b/core/plugin/provider.go index 86f4d83..4a02323 100644 --- a/core/plugin/provider.go +++ b/core/plugin/provider.go @@ -237,6 +237,9 @@ func KindOf(p Plugin) string { var mergedKinds = map[string]string{ "removedmembers": "migrationguide", "apichangelog": "changelog", + "retirements": "notices", + "feed": "notices", + "eol": "notices", } // 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 551dcfb..9bacfff 100644 --- a/docs/how-it-works.md +++ b/docs/how-it-works.md @@ -23,12 +23,12 @@ There's no list in this repo: `make plugins` prints every provider and source fr | [`core/versions/`](../core/versions/) | Every version of a source: GitHub releases, tags and commits, PyPI, npm, the Web Archive at a date | | [`plugins/`](../plugins/) | One package per kind, with its providers; `plugins/all` imports every one | | [`cmd/new-plugin/`](../cmd/new-plugin/), [`cmd/list-plugins/`](../cmd/list-plugins/) | The starter for a new provider; the list of providers and sources, printed from the registry | -| [`core/kit/`](../core/kit/), [`core/kit/kittest/`](../core/kit/kittest/), [`core/github/`](../core/github/) | What plugins share (the unchanged-page check, Wayback citing, the newest release or commit on GitHub) and the test kit (in-memory store, saved pages, golden files) | +| [`core/kit/`](../core/kit/), [`core/kit/kittest/`](../core/kit/kittest/), [`core/github/`](../core/github/), [`core/extract/`](../core/extract/) | What plugins share (the unchanged-page check, Wayback citing, the newest release or commit on GitHub, RSS/Atom and HTML text helpers) and the test kit (in-memory store, saved pages, golden files) | | [`core/event/`](../core/event/), [`core/migrate/`](../core/migrate/) | The change-event types of [patch-it's contract](https://github.com/patch-it-dev/patch-it/tree/main/docs/contract), and the v1 → v2 conversion | | [`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 | +| [`plugins/notices/retire/`](../plugins/notices/retire/), [`plugins/notices/feed/`](../plugins/notices/feed/), [`plugins/notices/eol/`](../plugins/notices/eol/), [`plugins/migrationguide/sdkguide/`](../plugins/migrationguide/sdkguide/), [`plugins/migrationguide/members/`](../plugins/migrationguide/members/), [`core/fetch/`](../core/fetch/) | The notices readers (deprecations pages, feeds, end-of-life tables) and the 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/`, `plugins/apichangelog/` | 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/`, `plugins/retirements/`, `plugins/feed/`, `plugins/eol/` | 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 8615cac..d59ddc8 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", "catalog", "eol"] }, + "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 }, "urls": { "type": "array", "items": { "type": "string", "pattern": "^https://" } }, diff --git a/docs/writing-a-plugin.md b/docs/writing-a-plugin.md index 3fa7024..b27dd55 100644 --- a/docs/writing-a-plugin.md +++ b/docs/writing-a-plugin.md @@ -10,14 +10,15 @@ 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 (a JSON changelog source), catalog +# --format: openapi, retirements and feed (notices sources), migrationguide, removedmembers (a migrationguide source), +# changelog, 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/) ``` It writes, and lists: -- the provider's definition, in the package the format reads it from (`plugins/openapi/adapter/`, `plugins/retirements/retire/`, `plugins/migrationguide/sdkguide/` or `plugins//`), and its `plugin.RegisterProvider` block (the provider and the source with their metadata) in that format's `init` (plus the `core/migrate/` map entry that `retirements` and `migrationguide` need); +- the provider's definition, in the package the format reads it from (`plugins/openapi/adapter/`, `plugins/notices/retire/`, `plugins/notices/feed/`, `plugins/migrationguide/sdkguide/` or `plugins//`), and its `plugin.RegisterProvider` block (the provider and the source with their metadata) in that format's `init` (plus the `core/migrate/` map entry that the deprecations-page and SDK-guide readers need); - `plugins//_test.go`: the registration test, a golden test and a pinned drop test, over placeholder sources in `testdata/`, with the golden file written from them; - a row per saved file in that `testdata/README.md` (URL, date, license, quote to fill in); - `providers/.md` from the template (or nothing, with `--page`, when the provider already has one); @@ -75,12 +76,10 @@ Write the numbers on the provider page, as `providers/vercel.md` does for its sp | Kind | Reads | Add a source by | |---|---|---| | `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/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/` (`--format` doesn't scaffold this one 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/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/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 @@ -160,7 +159,7 @@ The event format is [patch-it's change-event contract](https://github.com/patch- ## 5. Save the source -Save a real copy of what the plugin reads under your package's `testdata/` (or the reader package's, like `plugins/retirements/retire/testdata/`). Add a row to that directory's `README.md`: file, URL, date fetched, license, and a short quote of the part the plugin reads. +Save a real copy of what the plugin reads under your package's `testdata/` (or the reader package's, like `plugins/notices/retire/testdata/`). Add a row to that directory's `README.md`: file, URL, date fetched, license, and a short quote of the part the plugin reads. - **Openly licensed files** (MIT, BSD, Apache, CC BY): keep them whole. - **Vendor documentation pages**: trim to what the plugin reads (the tables, the sections), copy every kept line unchanged, mark it "excerpt for testing; © the vendor", and say what you left out. diff --git a/plugins/all/all.go b/plugins/all/all.go index 74a0d2c..834349d 100644 --- a/plugins/all/all.go +++ b/plugins/all/all.go @@ -6,9 +6,7 @@ package all import ( _ "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" - _ "github.com/patch-it-dev/patch-it-plugins/plugins/feed" _ "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide" + _ "github.com/patch-it-dev/patch-it-plugins/plugins/notices" _ "github.com/patch-it-dev/patch-it-plugins/plugins/openapi" - _ "github.com/patch-it-dev/patch-it-plugins/plugins/retirements" ) diff --git a/plugins/eol/eol.go b/plugins/eol/eol.go index 4bd1e31..906b2ab 100644 --- a/plugins/eol/eol.go +++ b/plugins/eol/eol.go @@ -1,298 +1,26 @@ -// Package eol is the source plugin for a vendor's own API end-of-life page: a -// table of whole version ranges, each with a support status. One event per -// version number a row says is already retired (breaking) or scheduled to be -// (deprecation); a row that only says "Supported." names nothing to report. +// Package eol is the old import path of the notices kind's end-of-life +// page reader, kept so code that imports it still builds. // -// There is no spec to diff, like retirements and feed: the page is read as it -// is now, and (as with them) the events cite a Wayback Machine snapshot of -// it, taken after a successful read of the live page, so the citation always -// says what the plugin actually saw. -// -// Salesforce's docs site is the one difference from retirements and feed: it -// answers 403 to a plain GET (checked 2026-11-20, including with a browser -// User-Agent), so Run's direct read of the live page fails every time. The -// Wayback Machine's own save-page-now request succeeds against it anyway, -// and its capture parses to the same findings the live page would (checked -// the same day), so Run falls back to a fresh snapshot on a 401 or 403, -// used directly as both the content and its own citation, kit.Cite's -// double-check skipped: there is no separate live read left to agree with. -// -// Unlike retirements (one named model per row) and feed (an RSS or Atom -// entry), a row here names a whole range of version numbers and no -// replacement: moving up to any newer version clears it. +// Deprecated: use plugins/notices (Plugin) and plugins/notices/eol (the +// reader: Page, Salesforce, Findings). This package only forwards to them +// and registers nothing; it goes once nothing imports it. package eol import ( - "context" - "errors" - "fmt" - "log" - "regexp" - "strconv" - "strings" - - "github.com/patch-it-dev/patch-it-plugins/core/event" - "github.com/patch-it-dev/patch-it-plugins/core/fetch" - "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/plugins/notices" + moved "github.com/patch-it-dev/patch-it-plugins/plugins/notices/eol" ) -func init() { - plugin.RegisterProvider(plugin.Provider{ - ID: "salesforce", Name: "Salesforce", Category: plugin.CategoryCRM, Homepage: "https://www.salesforce.com", - Sources: []plugin.Source{{ - ID: "rest-api", Layer: plugin.LayerAPI, Page: "providers/salesforce.md", - Watches: "REST API version ranges deprecated and retired, from Salesforce's own API end-of-life policy page", - URLs: []string{"https://developer.salesforce.com/docs/platform/api-rest/guide/api-rest-eol.html"}, - Plugin: Plugin{Page: Salesforce, Archiver: kit.Wayback{}}, - }}, - }) -} - -// Page is one vendor's end-of-life table. -type Page struct { - API string // the events' api: "salesforce" - Vendor string // for sentences: "Salesforce" - URL string // the page, as HTML - // Operation names the one real, documented, version-rooted resource a - // retired version takes down: Salesforce's "List Available REST - // Resources" call, GET /services/data/vXX.X/. Every other resource under - // that version is gone too (the page says so), but this is the one this - // plugin can point at honestly, without inventing a wildcard operation - // nothing calls. - Operation func(version string) string -} - -// Salesforce is the REST API's end-of-life policy page (checked 2026-11-20): -// a table of version ranges, each "Supported.", already retired ("As of -// Summer '25, these versions are retired and unavailable."), or scheduled -// ("Deprecated and unsupported from Summer '27. Retired from Summer '28."). -// Salesforce gives no exact date, only the named release ("Summer '27"); the -// policy text above the table says the notice is at least a year ahead of -// retirement. -var Salesforce = Page{ - API: "salesforce", Vendor: "Salesforce", - URL: "https://developer.salesforce.com/docs/platform/api-rest/guide/api-rest-eol.html", - Operation: func(v string) string { return "GET /services/data/v" + v + "/" }, -} - -// Row is one version range and what its status cell says, cleaned of HTML. -type Row struct { - From, To int // inclusive, both ends; From == To for a single version - Label string // the first cell's own text, word for word ("Versions 31.0 through 40.0") - Status string // every

in the status cell, joined with a space -} - -// Finding is one version number a row's status names, or a row that names -// none (Dropped set). -type Finding struct { - ChangeType event.ChangeType - Version string // "21.0" - Season string // "Summer ’25", or "Summer ’27, retired from Summer ’28" - Excerpt string - Row string // the row's version-range text, for Dropped's log line - Dropped string -} +type ( + // Plugin is notices.Plugin: set Page and Archiver, as before. + Plugin = notices.Plugin + Page = moved.Page + Row = moved.Row + Finding = moved.Finding +) var ( - table = regexp.MustCompile(`(?is)(.*?)`) - row = regexp.MustCompile(`(?is)(.*?)`) - // cell tolerates an attribute (): a future style change - // shouldn't make every row unreadable. - cell = regexp.MustCompile(`(?is)]*>(.*?)`) - tag = regexp.MustCompile(`<[^>]+>`) - // versions reads only the whole-number part of a version ("31.0 through - // 40.0" -> 31, 40): every version on the page today is a whole number. - // Salesforce has never shipped a minor REST API version, but this would - // silently drop one ("31.5") rather than fail loudly if that changed. - versions = regexp.MustCompile(`(?i)Versions?\s+(\d+)(?:\.\d+)?(?:\s+through\s+(\d+)(?:\.\d+)?)?`) - retired = regexp.MustCompile(`(?i)As of ([^,]+), these versions are retired and unavailable\.`) - deprecd = regexp.MustCompile(`(?i)Deprecated and unsupported from ([^.]+)\.\s*Retired from ([^.]+)\.`) + Salesforce = moved.Salesforce + Parse = moved.Parse + Findings = moved.Findings ) - -// text strips tags and normalizes whitespace, the way a 's content (bare -// text, or several

s) reads as one sentence. -func text(fragment string) string { - return strings.Join(strings.Fields(tag.ReplaceAllString(fragment, " ")), " ") -} - -// Parse reads every row of the page's first table. -func Parse(page []byte) ([]Row, error) { - m := table.FindStringSubmatch(string(page)) - if m == nil { - return nil, fmt.Errorf("no table found: the page's shape may have changed") - } - var out []Row - for _, r := range row.FindAllStringSubmatch(m[1], -1) { - cells := cell.FindAllStringSubmatch(r[1], -1) - if len(cells) < 2 { - continue - } - label := text(cells[0][1]) - vm := versions.FindStringSubmatch(label) - if vm == nil { - continue - } - from, _ := strconv.Atoi(vm[1]) - to := from - if vm[2] != "" { - to, _ = strconv.Atoi(vm[2]) - } - out = append(out, Row{From: from, To: to, Label: label, Status: text(cells[1][1])}) - } - if len(out) == 0 { - return nil, fmt.Errorf("no version rows found: the page's shape may have changed") - } - return out, nil -} - -// Findings classifies every row and names every version number a breaking or -// deprecated row covers. A row that's merely "Supported." names none. -func Findings(page []byte) ([]Finding, error) { - rows, err := Parse(page) - if err != nil { - return nil, err - } - var out []Finding - for _, r := range rows { - label := r.Label - excerpt := label + " | " + r.Status - - var ct event.ChangeType - var season string - switch { - case retired.MatchString(r.Status): - ct, season = event.ChangeTypeBreaking, retired.FindStringSubmatch(r.Status)[1] - case deprecd.MatchString(r.Status): - m := deprecd.FindStringSubmatch(r.Status) - ct, season = event.ChangeTypeDeprecation, m[1]+", retired from "+m[2] - default: - out = append(out, Finding{Row: label, Dropped: fmt.Sprintf("status %q names neither a retirement nor a deprecation", r.Status)}) - continue - } - for v := r.From; v <= r.To; v++ { - out = append(out, Finding{ - ChangeType: ct, - Version: fmt.Sprintf("%d.0", v), - Season: season, - Excerpt: excerpt, - Row: label, - }) - } - } - return out, nil -} - -// Plugin reads one vendor's end-of-life page. -type Plugin struct { - Page Page - Archiver kit.Archiver -} - -func (p Plugin) Name() string { return p.Page.API } - -// Run reads the page as it is now. An unchanged page since the last run costs -// one GET and no snapshot, unless the live page is blocked: see liveOrArchived. -func (p Plugin) Run(ctx context.Context, env plugin.Env) (plugin.Result, error) { - pg := p.Page - live, archived, err := liveOrArchived(ctx, env, p.Archiver, pg.URL) - if err != nil { - return plugin.Result{}, fmt.Errorf("fetching %s: %w", pg.URL, err) - } - hash := plugin.SHA256(live) - last, same, err := kit.Unchanged(env, pg.API, live) - if err != nil { - return plugin.Result{}, err - } - if same { - log.Printf("%s: no change since %s", pg.API, last.SourceURL) - return plugin.Result{}, nil - } - - want, err := Findings(live) - if err != nil { - return plugin.Result{}, fmt.Errorf("reading %s: %w", pg.URL, err) - } - - snapURL, snap, got := archived, live, want - if snapURL == "" { - snapURL, snap, got, err = kit.Cite(ctx, p.Archiver, pg.URL, Findings, want) - if err != nil { - return plugin.Result{}, err - } - } - - now := env.Now().UTC() - var events []event.EventV2 - var rejected []error - for _, f := range got { - if f.Dropped != "" { - log.Printf("%s: dropped %s: %s", pg.API, f.Row, f.Dropped) - continue - } - e := event.EventV2{ - API: pg.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: pg.Operation(f.Version), - }, - Description: describe(pg, f), - MigrationHint: fmt.Sprintf("Pin a newer %s REST API version: %s names which ones are still supported.", pg.Vendor, snapURL), - SourceURL: snapURL, - 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: %w", pg.API, f.Version, err)) - continue - } - events = append(events, e) - } - baseline := plugin.Baseline(pg.API, now.Format("2006-01-02"), snapURL, snapURL, snap, false, now) - baseline.SHA256 = hash - return plugin.Result{Label: snapURL, Events: events, Rejected: rejected, Baselines: []plugin.Spec{baseline}}, nil -} - -// liveOrArchived reads pageURL directly. When the provider's own site -// blocks a plain fetch with 401 or 403 (Salesforce's docs site, every time, -// checked 2026-11-20; confirmed the same day that a real Wayback Machine -// save-page-now capture of this exact page parses to the same findings as -// the live page would), it falls back to a fresh Wayback Machine snapshot, -// taken right now by the archive's own crawler rather than patch-it's, and -// returns that content with its own permanent URL in archivedURL: it needs -// no further citation step, having come from the archive already. -// -// Only 401 and 403 fall back. A 404 or 410 means the page moved, not that -// it's blocked: asking the archive to snapshot a page that's gone would -// waste the call and hide the real cause behind the archive's own error. -// A 429 or a 5xx is returned as is: retrying it against the archive would -// hide a transient failure as a real page, not fix one. -func liveOrArchived(ctx context.Context, env plugin.Env, a kit.Archiver, pageURL string) (body []byte, archivedURL string, err error) { - body, err = env.Get(ctx, pageURL) - if err == nil { - return body, "", nil - } - var se *fetch.StatusError - if !errors.As(err, &se) || (se.StatusCode != 401 && se.StatusCode != 403) { - return nil, "", err - } - archivedURL, body, archErr := a.Snapshot(ctx, pageURL) - if archErr != nil { - return nil, "", fmt.Errorf("fetching it directly failed (%w), and so did asking the Wayback Machine to: %w", err, archErr) - } - return body, archivedURL, nil -} - -func describe(pg Page, f Finding) string { - if f.ChangeType == event.ChangeTypeBreaking { - return fmt.Sprintf("%s REST API version %s is retired, as of %s: it returns 410:GONE for every resource.", pg.Vendor, f.Version, f.Season) - } - return fmt.Sprintf("%s REST API version %s is deprecated and scheduled for retirement: unsupported from %s.", pg.Vendor, f.Version, f.Season) -} diff --git a/plugins/eol/eol_test.go b/plugins/eol/eol_test.go index 6ceac40..27019ea 100644 --- a/plugins/eol/eol_test.go +++ b/plugins/eol/eol_test.go @@ -1,120 +1,16 @@ package eol import ( - "context" - "fmt" "testing" - "time" - "github.com/patch-it-dev/patch-it-plugins/core/fetch" "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" - "github.com/patch-it-dev/patch-it-plugins/core/plugin" ) -func TestRegistersItself(t *testing.T) { - kittest.Registered(t, Plugin{Page: Salesforce}) -} - -// The golden test: Salesforce's own end-of-life policy page (checked -// 2026-11-20, saved 2026-10-31), real and unedited but for dropping the -// surrounding navigation chrome. It already holds two real, past retirements -// (versions 7.0 through 20.0, retired as of Summer '22; versions 21.0 -// through 30.0, retired as of Summer '25) and one real, scheduled one -// (versions 31.0 through 40.0, deprecated from Summer '27, retired from -// Summer '28): 34 events, and the still-"Supported." 41.0 through 67.0 band -// names none, the pinned drop test. -func TestGolden(t *testing.T) { - saved := kittest.Pages{Salesforce.URL: "testdata/salesforce-api-rest-eol-2026-10-31.html"} - archive := &kittest.Archive{T: t, Pages: saved} - got := kittest.IngestWith(t, kittest.Env(t, saved), Plugin{Page: Salesforce, Archiver: archive}) - if archive.Calls != 1 { - t.Errorf("%d snapshots, want 1: the second run's page is unchanged", archive.Calls) - } - kittest.Golden(t, "testdata/golden/salesforce.json", got) -} - -// The pinned drop test: "Versions 41.0 through 67.0: Supported." is a real -// row on the page, and it must name no version. -func TestDropsAStillSupportedBand(t *testing.T) { - page := kittest.Read(t, "testdata/salesforce-api-rest-eol-2026-10-31.html") - found, err := Findings(page) - if err != nil { - t.Fatal(err) - } - supported := map[string]bool{} - for v := 41; v <= 67; v++ { - supported[fmt.Sprintf("%d.0", v)] = true - } - var dropped bool - for _, f := range found { - if f.Dropped == "" && supported[f.Version] { - t.Errorf("version %s got an event, want none: it's still Supported", f.Version) - } - if f.Dropped != "" && f.Row == "Versions 41.0 through 67.0" { - dropped = true - } - } - if !dropped { - t.Error("the still-supported band wasn't found and dropped") - } -} - -// Salesforce's docs site answers 403 to a plain GET; the live page is never -// reachable through env.Get. Run must fall back to the Wayback Machine's own -// fetch and use its snapshot directly, not fail outright. 401 falls back the -// same way. -func TestFallsBackToTheArchiveWhenTheLiveFetchIsBlocked(t *testing.T) { - for _, code := range []int{401, 403} { - t.Run(fmt.Sprint(code), func(t *testing.T) { - saved := kittest.Pages{Salesforce.URL: "testdata/salesforce-api-rest-eol-2026-10-31.html"} - archive := &kittest.Archive{T: t, Pages: saved} - env := plugin.Env{ - Baselines: kittest.NewMem(), - Get: func(context.Context, string) ([]byte, error) { - return nil, &fetch.StatusError{URL: Salesforce.URL, StatusCode: code} - }, - Now: func() time.Time { return kittest.Clock }, - } - got := kittest.IngestWith(t, env, Plugin{Page: Salesforce, Archiver: archive}) - if len(got) == 0 { - t.Fatal("no events: the archive fallback didn't run") - } - // Unlike the normal path, a permanently blocked live page has no - // cheap way to check "did it change": liveOrArchived needs the - // archive's own fetch just to get bytes to hash, on every run, - // not only a changed one. The second run still stores nothing - // new: the hash matches. - if archive.Calls != 2 { - t.Errorf("%d snapshots, want 2: the live page is blocked every run", archive.Calls) - } - for _, e := range got { - if e.SourceURL == Salesforce.URL { - t.Errorf("%s: source_url is the blocked live page, want the archive's snapshot", e.Fingerprint) - } - } - }) - } -} - -// A real failure (not the provider blocking a plain fetch) must stay a -// failure: falling back to the archive for a timeout or a 5xx would hide it -// as a real page. -func TestDoesNotFallBackOnATransientError(t *testing.T) { - for _, code := range []int{404, 429, 503} { - t.Run(fmt.Sprint(code), func(t *testing.T) { - env := plugin.Env{ - Baselines: kittest.NewMem(), - Get: func(context.Context, string) ([]byte, error) { - return nil, &fetch.StatusError{URL: Salesforce.URL, StatusCode: code} - }, - Now: func() time.Time { return kittest.Clock }, - } - // No Pages: a fallback here would fail the test by asking the - // archive for a snapshot it was never given. - _, err := Plugin{Page: Salesforce, Archiver: &kittest.Archive{T: t}}.Run(context.Background(), env) - if err == nil { - t.Fatalf("want an error for a %d, got none", code) - } - }) +// Code written against the old path still builds and runs the same source. +func TestTheOldPathStillWorks(t *testing.T) { + p := Plugin{Page: Salesforce} + kittest.Registered(t, p) + if p.Name() != "salesforce" { + t.Errorf("Plugin{Page: Salesforce} is %q", p.Name()) } } diff --git a/plugins/feed/feed.go b/plugins/feed/feed.go index dba0f77..7690531 100644 --- a/plugins/feed/feed.go +++ b/plugins/feed/feed.go @@ -1,165 +1,51 @@ -// Package feed is the source plugin for a vendor's RSS or Atom changelog -// feed: one event per breaking or deprecation entry (or per name such an -// entry lists), quoting the line that says so. Rung 3 of the source ladder. +// Package feed is the old import path of the notices kind's RSS and Atom +// feed reader, kept so code that imports it still builds. // -// A feed is prose, so each feed comes with a Reader that knows what its -// vendor's entries look like and which subject they describe. The rules are -// the same for every reader (precision over recall): -// -// - An entry the vendor doesn't mark as breaking or deprecation (a category, -// a heading) is skipped. -// - A marked entry becomes an event only when the reader finds a typed -// subject in it (a runner label, a model id in code) and a dated -// sentence. Otherwise it is dropped, logged with why, never guessed. -// - `breaking` needs the vendor to say the thing stops on a date ("will be -// retired on", "will be shut down on"). Anything softer ("we recommend -// updating before") is downgraded to `deprecation`. -// -// A feed is a live document, so the events cite a Wayback Machine snapshot -// of it, read back and checked against the live feed (kit.Cite), like the -// retirements plugin. +// Deprecated: use plugins/notices (notices.Plugin{Page: feed.GitHubActions}) +// and plugins/notices/feed (the reader). This package only forwards to them +// and registers nothing; it goes once nothing imports it. package feed import ( "context" - "fmt" - "log" - "github.com/patch-it-dev/patch-it-plugins/core/event" "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/plugins/notices" + moved "github.com/patch-it-dev/patch-it-plugins/plugins/notices/feed" ) -func init() { - plugin.RegisterProvider(plugin.Provider{ - ID: "github", Name: "GitHub", Category: plugin.CategoryDevTools, Homepage: "https://github.com", - Sources: []plugin.Source{{ - ID: "actions", Layer: plugin.LayerCI, Page: "providers/github-actions.md", - Watches: "GitHub Actions retirements, such as runner images and the `runs-on` labels they remove", - URLs: []string{"https://github.blog/changelog/label/actions/feed/"}, - Plugin: Plugin{Feed: GitHubActions, Archiver: kit.Wayback{}}, - }}, - }) - plugin.RegisterProvider(plugin.Provider{ - ID: "google", Name: "Google", Category: plugin.CategoryAI, Homepage: "https://cloud.google.com", - Sources: []plugin.Source{{ - ID: "vertex-ai-models", Layer: plugin.LayerAIModels, Page: "providers/vertex-ai-models.md", - Watches: "Generative AI model deprecations on Vertex AI", - URLs: []string{"https://docs.cloud.google.com/feeds/generative-ai-on-vertex-ai-release-notes.xml"}, - Plugin: Plugin{Feed: VertexAIModels, Archiver: kit.Wayback{}}, - }}, - }) - plugin.RegisterProvider(plugin.Provider{ - ID: "cloudflare", Name: "Cloudflare", Category: plugin.CategoryInfrastructure, Homepage: "https://www.cloudflare.com", - Sources: []plugin.Source{{ - ID: "api", Layer: plugin.LayerAPI, Page: "providers/cloudflare.md", - Watches: "REST API operations Cloudflare deprecates, breaking on their end-of-life date when it gives one", - URLs: []string{"https://developers.cloudflare.com/fundamentals/api/reference/deprecations/index.xml"}, - Plugin: Plugin{Feed: CloudflareAPI, Archiver: kit.Wayback{}}, - }}, - }) -} - -// Feed is one vendor feed and how to read its entries. -type Feed struct { - API string // the events' api: "github-actions" - Vendor string // for sentences: "GitHub" - URL string // the feed itself - Read Reader -} - -// Reader turns one entry into findings: what it can name for sure, and what -// it drops. It returns nothing for an entry that isn't breaking or a -// deprecation. -type Reader func(e Entry) []Finding - -// Finding is one change a reader found in an entry, or one it dropped. -type Finding struct { - ChangeType event.ChangeType // breaking or deprecation - Version string // per the subject's type: the removal or shutdown date - Subject event.Subject - Description string - Hint string - Excerpt string // the entry's own lines that say so - Entry string // the entry's link, for the log - Dropped string // set: the entry was marked but this is why no event -} +type ( + Feed = moved.Feed + Reader = moved.Reader + Finding = moved.Finding + Entry = moved.Entry + Section = moved.Section +) -// Findings reads every entry of a feed. -func (f Feed) Findings(b []byte) ([]Finding, error) { - entries, err := Parse(b) - if err != nil { - return nil, err - } - var out []Finding - for _, e := range entries { - out = append(out, f.Read(e)...) - } - return out, nil -} +var ( + GitHubActions = moved.GitHubActions + VertexAIModels = moved.VertexAIModels + CloudflareAPI = moved.CloudflareAPI + Parse = moved.Parse + Text = moved.Text + Lines = moved.Lines + SplitBy = moved.SplitBy + Date = moved.Date + Codes = moved.Codes +) -// Plugin reads one feed. +// Plugin reads one feed: notices.Plugin{Page: Feed, Archiver: Archiver}. type Plugin struct { Feed Feed Archiver kit.Archiver } -func (p Plugin) Name() string { return p.Feed.API } +func (p Plugin) notices() notices.Plugin { return notices.Plugin{Page: p.Feed, Archiver: p.Archiver} } -// Run reads the feed as it is now. An unchanged feed since the last run costs -// one GET (a 304 with the HTTP cache) and no snapshot. -func (p Plugin) Run(ctx context.Context, env plugin.Env) (plugin.Result, error) { - f := p.Feed - live, err := env.Get(ctx, f.URL) - if err != nil { - return plugin.Result{}, fmt.Errorf("fetching %s: %w", f.URL, err) - } - last, same, err := kit.Unchanged(env, f.API, live) - if err != nil { - return plugin.Result{}, err - } - if same { - log.Printf("%s: no change since %s", f.API, last.SourceURL) - return plugin.Result{}, nil - } - want, err := f.Findings(live) - if err != nil { - return plugin.Result{}, fmt.Errorf("reading %s: %w", f.URL, err) - } - snapURL, snap, got, err := kit.Cite(ctx, p.Archiver, f.URL, f.Findings, want) - if err != nil { - return plugin.Result{}, err - } +func (p Plugin) Name() string { return p.notices().Name() } - now := env.Now().UTC() - var events []event.EventV2 - var rejected []error - for _, fd := range got { - if fd.Dropped != "" { - log.Printf("%s: dropped %s: %s", f.API, fd.Entry, fd.Dropped) - continue - } - e := event.EventV2{ - API: f.API, - Version: fd.Version, - ChangeType: fd.ChangeType, - Breaking: fd.ChangeType == event.ChangeTypeBreaking, - Subject: fd.Subject, - Description: fd.Description, - MigrationHint: fd.Hint, - SourceURL: snapURL, - SourceExcerpt: fd.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: %w", f.API, fd.Entry, err)) - continue - } - events = append(events, e) - } - baseline := plugin.Baseline(f.API, now.Format("2006-01-02"), snapURL, snapURL, snap, false, now) - baseline.SHA256 = plugin.SHA256(live) // so the next run compares like with like - return plugin.Result{Label: snapURL, Events: events, Rejected: rejected, Baselines: []plugin.Spec{baseline}}, nil +// Run is notices.Plugin's Run. +func (p Plugin) Run(ctx context.Context, env plugin.Env) (plugin.Result, error) { + return p.notices().Run(ctx, env) } diff --git a/plugins/feed/feed_test.go b/plugins/feed/feed_test.go index fe58a89..610dd33 100644 --- a/plugins/feed/feed_test.go +++ b/plugins/feed/feed_test.go @@ -1,132 +1,16 @@ package feed import ( - "strings" "testing" "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" ) -// The two feeds as saved on 2026-11-14 (testdata/README.md), each through the -// whole plugin: live feed and snapshot are the same copy, so the events cite -// the snapshot, and kittest's second run over the unchanged feed asks for no -// second snapshot and stores nothing new. -func TestGolden(t *testing.T) { - for _, c := range []struct { - feed Feed - file string - }{ - {GitHubActions, "testdata/github-changelog-actions.rss.xml"}, - {VertexAIModels, "testdata/vertex-ai-generative-ai.atom.xml"}, - {CloudflareAPI, "testdata/cloudflare-api-deprecations.rss.xml"}, - } { - t.Run(c.feed.API, func(t *testing.T) { - saved := kittest.Pages{c.feed.URL: c.file} - archive := &kittest.Archive{T: t, Pages: saved} - got := kittest.IngestWith(t, kittest.Env(t, saved), Plugin{Feed: c.feed, Archiver: archive}) - if archive.Calls != 1 { - t.Errorf("%d snapshots, want 1", archive.Calls) - } - kittest.Golden(t, "testdata/golden/"+c.feed.API+".json", got) - }) - } -} - -// What each feed's marked entries came to, kept and dropped: the golden files -// pin the events, this pins that the unsure ones were dropped, not guessed. -func TestUnsureEntriesAreDropped(t *testing.T) { - for _, c := range []struct { - feed Feed - file string - dropped []string // a substring of each drop reason, in order - }{ - {GitHubActions, "testdata/github-changelog-actions.rss.xml", []string{ - "arm32-linux-windows-retirement", // no runner label: no ci_runtime to name - "pull_request_target-blocked-by-default-december-2", // a behavior change, no subject type fits - }}, - {VertexAIModels, "testdata/vertex-ai-generative-ai.atom.xml", []string{ - "Vertex AI Extensions deprecation", - "Anthropic's Claude 3 Haiku", // a product name in prose, not a model id - "Anthropic's Claude 3.5 Haiku", - }}, - } { - fs, err := c.feed.Findings(kittest.Read(t, c.file)) - if err != nil { - t.Fatal(err) - } - var drops []string - for _, f := range fs { - if f.Dropped != "" { - drops = append(drops, f.Entry+" "+f.Dropped) - } - } - if len(drops) != len(c.dropped) { - t.Errorf("%s: dropped %d, want %d:\n%s", c.feed.API, len(drops), len(c.dropped), strings.Join(drops, "\n")) - continue - } - for i, want := range c.dropped { - if !strings.Contains(drops[i], want) { - t.Errorf("%s: drop %d is %q, want %q", c.feed.API, i, drops[i], want) - } - } - } -} - -func TestParseRefusesWhatIsntAFeed(t *testing.T) { - for name, b := range map[string]string{ - "html": "moved", - "no items": `x`, - "no entry": `x`, - } { - if _, err := Parse([]byte(b)); err == nil { - t.Errorf("%s: want an error, never zero events read as a quiet week", name) - } - } -} - -// RSS without content:encoded falls back to description; Atom takes the -// alternate link and the category terms. -func TestParseReadsBothFormats(t *testing.T) { - r, err := Parse([]byte(`A & Bhttps://x.test/a - Retired<p>text</p>`)) - if err != nil || r[0].Title != "A & B" || r[0].HTML != "

text

" || r[0].Categories[0] != "Retired" || r[0].ID != "https://x.test/a" { - t.Errorf("rss: %+v %v", r, err) - } - a, err := Parse([]byte(`iT - - <b>s</b>`)) - if err != nil || a[0].Link != "https://x.test/e" || a[0].HTML != "s" || a[0].Categories[0] != "Deprecated" { - t.Errorf("atom: %+v %v", a, err) - } -} - -// Breaking only when the vendor says the thing stops on the date; softer -// words downgrade to a deprecation, and no date drops the entry. -func TestBreakingNeedsTheVendorToSayItStops(t *testing.T) { - entry := func(sentence string) Entry { - return Entry{Title: "Ubuntu 22.04 runner image retirement", Link: "https://x.test/e", Categories: []string{"Retired"}, - HTML: "

" + sentence + "

This deprecation includes the following labels:

  • ubuntu-22.04
"} - } - for sentence, want := range map[string]string{ - "The Ubuntu 22.04 runner image will be retired on March 1, 2027.": "breaking 2027-03-01", - "The Ubuntu 22.04 runner image will be removed on March 1, 2027.": "breaking 2027-03-01", - "The Ubuntu 22.04 runner image will be deprecated on March 1, 2027.": "deprecation 2027-03-01", - "Please move off the Ubuntu 22.04 runner image before March 1, 2027.": "deprecation 2027-03-01", - "The Ubuntu 22.04 runner image will be retired in the coming months.": "dropped", - "Announced March 1, 2027: the Ubuntu 22.04 image is being looked at.": "dropped", - } { - fs := readGitHubActions(entry(sentence)) - got := "dropped" - if len(fs) == 1 && fs[0].Dropped == "" { - got = string(fs[0].ChangeType) + " " + fs[0].Version - } - if got != want { - t.Errorf("%q: %s, want %s", sentence, got, want) - } - } - unmarked := entry("The Ubuntu 22.04 runner image will be retired on March 1, 2027.") - unmarked.Categories = []string{"Improvement"} - if fs := readGitHubActions(unmarked); len(fs) != 0 { - t.Errorf("an entry the vendor didn't mark: %+v", fs) - } +// Code written against the old path still builds and runs the same feed +// with the same events. +func TestTheOldPathStillWorks(t *testing.T) { + saved := kittest.Pages{GitHubActions.URL: "../notices/feed/testdata/github-changelog-actions.rss.xml"} + archive := &kittest.Archive{T: t, Pages: saved} + got := kittest.IngestWith(t, kittest.Env(t, saved), Plugin{Feed: GitHubActions, Archiver: archive}) + kittest.CompareGolden(t, "../notices/testdata/golden/github-actions.json", got) } diff --git a/plugins/feed/registered_test.go b/plugins/feed/registered_test.go deleted file mode 100644 index 83c9671..0000000 --- a/plugins/feed/registered_test.go +++ /dev/null @@ -1,13 +0,0 @@ -package feed - -import ( - "testing" - - "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" -) - -func TestRegistersItself(t *testing.T) { - for _, f := range []Feed{GitHubActions, VertexAIModels, CloudflareAPI} { - kittest.Registered(t, Plugin{Feed: f}) - } -} diff --git a/plugins/notices/eol/eol.go b/plugins/notices/eol/eol.go new file mode 100644 index 0000000..823b707 --- /dev/null +++ b/plugins/notices/eol/eol.go @@ -0,0 +1,241 @@ +// Package eol is the notices kind's reader for a vendor's own API +// end-of-life page (plugins/notices reads it, snapshots and cites it): a +// table of whole version ranges, each with a support status. One event per +// version number a row says is already retired (breaking) or scheduled to be +// (deprecation); a row that only says "Supported." names nothing to report. +// +// There is no spec to diff, like retirements and feed: the page is read as it +// is now, and (as with them) the events cite a Wayback Machine snapshot of +// it, taken after a successful read of the live page, so the citation always +// says what the plugin actually saw. +// +// Salesforce's docs site is the one difference from the other notices +// readers: it answers 403 to a plain GET (checked 2026-11-20, including with +// a browser User-Agent), so a direct read of the live page fails every time. The +// Wayback Machine's own save-page-now request succeeds against it anyway, +// and its capture parses to the same findings the live page would (checked +// the same day), so the kind falls back to a fresh snapshot on a 401 or 403 +// (ArchiveWhenBlocked), +// used directly as both the content and its own citation, kit.Cite's +// double-check skipped: there is no separate live read left to agree with. +// +// Unlike retirements (one named model per row) and feed (an RSS or Atom +// entry), a row here names a whole range of version numbers and no +// replacement: moving up to any newer version clears it. +package eol + +import ( + "fmt" + "log" + "regexp" + "strconv" + "strings" + "time" + + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/kit" +) + +// Page is one vendor's end-of-life table. +type Page struct { + API string // the events' api: "salesforce" + Vendor string // for sentences: "Salesforce" + URL string // the page, as HTML + // Operation names the one real, documented, version-rooted resource a + // retired version takes down: Salesforce's "List Available REST + // Resources" call, GET /services/data/vXX.X/. Every other resource under + // that version is gone too (the page says so), but this is the one this + // plugin can point at honestly, without inventing a wildcard operation + // nothing calls. + Operation func(version string) string +} + +// Salesforce is the REST API's end-of-life policy page (checked 2026-11-20): +// a table of version ranges, each "Supported.", already retired ("As of +// Summer '25, these versions are retired and unavailable."), or scheduled +// ("Deprecated and unsupported from Summer '27. Retired from Summer '28."). +// Salesforce gives no exact date, only the named release ("Summer '27"); the +// policy text above the table says the notice is at least a year ahead of +// retirement. +var Salesforce = Page{ + API: "salesforce", Vendor: "Salesforce", + URL: "https://developer.salesforce.com/docs/platform/api-rest/guide/api-rest-eol.html", + Operation: func(v string) string { return "GET /services/data/v" + v + "/" }, +} + +// Row is one version range and what its status cell says, cleaned of HTML. +type Row struct { + From, To int // inclusive, both ends; From == To for a single version + Label string // the first cell's own text, word for word ("Versions 31.0 through 40.0") + Status string // every

in the status cell, joined with a space +} + +// Finding is one version number a row's status names, or a row that names +// none (Dropped set). +type Finding struct { + ChangeType event.ChangeType + Version string // "21.0" + Season string // "Summer ’25", or "Summer ’27, retired from Summer ’28" + Excerpt string + Row string // the row's version-range text, for Dropped's log line + Dropped string +} + +var ( + table = regexp.MustCompile(`(?is)(.*?)`) + row = regexp.MustCompile(`(?is)(.*?)`) + // cell tolerates an attribute (): a future style change + // shouldn't make every row unreadable. + cell = regexp.MustCompile(`(?is)]*>(.*?)`) + tag = regexp.MustCompile(`<[^>]+>`) + // versions reads only the whole-number part of a version ("31.0 through + // 40.0" -> 31, 40): every version on the page today is a whole number. + // Salesforce has never shipped a minor REST API version, but this would + // silently drop one ("31.5") rather than fail loudly if that changed. + versions = regexp.MustCompile(`(?i)Versions?\s+(\d+)(?:\.\d+)?(?:\s+through\s+(\d+)(?:\.\d+)?)?`) + retired = regexp.MustCompile(`(?i)As of ([^,]+), these versions are retired and unavailable\.`) + deprecd = regexp.MustCompile(`(?i)Deprecated and unsupported from ([^.]+)\.\s*Retired from ([^.]+)\.`) +) + +// text strips tags and normalizes whitespace, the way a 's content (bare +// text, or several

s) reads as one sentence. +func text(fragment string) string { + return strings.Join(strings.Fields(tag.ReplaceAllString(fragment, " ")), " ") +} + +// Parse reads every row of the page's first table. +func Parse(page []byte) ([]Row, error) { + m := table.FindStringSubmatch(string(page)) + if m == nil { + return nil, fmt.Errorf("no table found: the page's shape may have changed") + } + var out []Row + for _, r := range row.FindAllStringSubmatch(m[1], -1) { + cells := cell.FindAllStringSubmatch(r[1], -1) + if len(cells) < 2 { + continue + } + label := text(cells[0][1]) + vm := versions.FindStringSubmatch(label) + if vm == nil { + continue + } + from, _ := strconv.Atoi(vm[1]) + to := from + if vm[2] != "" { + to, _ = strconv.Atoi(vm[2]) + } + out = append(out, Row{From: from, To: to, Label: label, Status: text(cells[1][1])}) + } + if len(out) == 0 { + return nil, fmt.Errorf("no version rows found: the page's shape may have changed") + } + return out, nil +} + +// Findings classifies every row and names every version number a breaking or +// deprecated row covers. A row that's merely "Supported." names none. +func Findings(page []byte) ([]Finding, error) { + rows, err := Parse(page) + if err != nil { + return nil, err + } + var out []Finding + for _, r := range rows { + label := r.Label + excerpt := label + " | " + r.Status + + var ct event.ChangeType + var season string + switch { + case retired.MatchString(r.Status): + ct, season = event.ChangeTypeBreaking, retired.FindStringSubmatch(r.Status)[1] + case deprecd.MatchString(r.Status): + m := deprecd.FindStringSubmatch(r.Status) + ct, season = event.ChangeTypeDeprecation, m[1]+", retired from "+m[2] + default: + out = append(out, Finding{Row: label, Dropped: fmt.Sprintf("status %q names neither a retirement nor a deprecation", r.Status)}) + continue + } + for v := r.From; v <= r.To; v++ { + out = append(out, Finding{ + ChangeType: ct, + Version: fmt.Sprintf("%d.0", v), + Season: season, + Excerpt: excerpt, + Row: label, + }) + } + } + return out, nil +} + +// What the notices kind (plugins/notices) asks of an end-of-life page. + +// Read is what one read of a page found, dropped rows included. +type Read []Finding + +// Count is how many findings the page gave. +func (r Read) Count() int { return len(r) } + +// Slug is the events' api: "salesforce". +func (pg Page) Slug() string { return pg.API } + +// PageURL is the page, as HTML. +func (pg Page) PageURL() string { return pg.URL } + +// Find reads every row of the page. +func (pg Page) Find(page []byte) (kit.Notices, error) { + fs, err := Findings(page) + return Read(fs), err +} + +// ArchiveWhenBlocked is on: Salesforce's docs site answers 403 to a plain +// GET, so the kind reads a fresh Wayback Machine snapshot instead (see the +// package comment). +func (Page) ArchiveWhenBlocked() bool { return true } + +// Events are an event per version number a row retires or deprecates, +// citing citeURL; a dropped row is logged with why. +func (pg Page) Events(found kit.Notices, citeURL string, now time.Time) ([]event.ChangeEvent, []event.EventV2, []error) { + var events []event.EventV2 + var rejected []error + for _, f := range found.(Read) { + if f.Dropped != "" { + log.Printf("%s: dropped %s: %s", pg.API, f.Row, f.Dropped) + continue + } + e := event.EventV2{ + API: pg.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: pg.Operation(f.Version), + }, + Description: describe(pg, f), + MigrationHint: fmt.Sprintf("Pin a newer %s REST API version: %s names which ones are still supported.", pg.Vendor, citeURL), + SourceURL: citeURL, + 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: %w", pg.API, f.Version, err)) + continue + } + events = append(events, e) + } + return nil, events, rejected +} + +func describe(pg Page, f Finding) string { + if f.ChangeType == event.ChangeTypeBreaking { + return fmt.Sprintf("%s REST API version %s is retired, as of %s: it returns 410:GONE for every resource.", pg.Vendor, f.Version, f.Season) + } + return fmt.Sprintf("%s REST API version %s is deprecated and scheduled for retirement: unsupported from %s.", pg.Vendor, f.Version, f.Season) +} diff --git a/plugins/eol/testdata/README.md b/plugins/notices/eol/testdata/README.md similarity index 100% rename from plugins/eol/testdata/README.md rename to plugins/notices/eol/testdata/README.md diff --git a/plugins/eol/testdata/salesforce-api-rest-eol-2026-10-31.html b/plugins/notices/eol/testdata/salesforce-api-rest-eol-2026-10-31.html similarity index 100% rename from plugins/eol/testdata/salesforce-api-rest-eol-2026-10-31.html rename to plugins/notices/eol/testdata/salesforce-api-rest-eol-2026-10-31.html diff --git a/plugins/notices/eol_test.go b/plugins/notices/eol_test.go new file mode 100644 index 0000000..eea4725 --- /dev/null +++ b/plugins/notices/eol_test.go @@ -0,0 +1,121 @@ +package notices + +import ( + "context" + "fmt" + "testing" + "time" + + "github.com/patch-it-dev/patch-it-plugins/core/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" + "github.com/patch-it-dev/patch-it-plugins/plugins/notices/eol" +) + +func TestEOLRegistersItself(t *testing.T) { + kittest.Registered(t, Plugin{Page: eol.Salesforce}) +} + +// The golden test: eol.Salesforce's own end-of-life policy page (checked +// 2026-11-20, saved 2026-10-31), real and unedited but for dropping the +// surrounding navigation chrome. It already holds two real, past retirements +// (versions 7.0 through 20.0, retired as of Summer '22; versions 21.0 +// through 30.0, retired as of Summer '25) and one real, scheduled one +// (versions 31.0 through 40.0, deprecated from Summer '27, retired from +// Summer '28): 34 events, and the still-"Supported." 41.0 through 67.0 band +// names none, the pinned drop test. +func TestEOLGolden(t *testing.T) { + saved := kittest.Pages{eol.Salesforce.URL: "eol/testdata/salesforce-api-rest-eol-2026-10-31.html"} + archive := &kittest.Archive{T: t, Pages: saved} + got := kittest.IngestWith(t, kittest.Env(t, saved), Plugin{Page: eol.Salesforce, Archiver: archive}) + if archive.Calls != 1 { + t.Errorf("%d snapshots, want 1: the second run's page is unchanged", archive.Calls) + } + kittest.Golden(t, "testdata/golden/salesforce.json", got) +} + +// The pinned drop test: "Versions 41.0 through 67.0: Supported." is a real +// row on the page, and it must name no version. +func TestDropsAStillSupportedBand(t *testing.T) { + page := kittest.Read(t, "eol/testdata/salesforce-api-rest-eol-2026-10-31.html") + found, err := eol.Findings(page) + if err != nil { + t.Fatal(err) + } + supported := map[string]bool{} + for v := 41; v <= 67; v++ { + supported[fmt.Sprintf("%d.0", v)] = true + } + var dropped bool + for _, f := range found { + if f.Dropped == "" && supported[f.Version] { + t.Errorf("version %s got an event, want none: it's still Supported", f.Version) + } + if f.Dropped != "" && f.Row == "Versions 41.0 through 67.0" { + dropped = true + } + } + if !dropped { + t.Error("the still-supported band wasn't found and dropped") + } +} + +// eol.Salesforce's docs site answers 403 to a plain GET; the live page is never +// reachable through env.Get. Run must fall back to the Wayback Machine's own +// fetch and use its snapshot directly, not fail outright. 401 falls back the +// same way. +func TestFallsBackToTheArchiveWhenTheLiveFetchIsBlocked(t *testing.T) { + for _, code := range []int{401, 403} { + t.Run(fmt.Sprint(code), func(t *testing.T) { + saved := kittest.Pages{eol.Salesforce.URL: "eol/testdata/salesforce-api-rest-eol-2026-10-31.html"} + archive := &kittest.Archive{T: t, Pages: saved} + env := plugin.Env{ + Baselines: kittest.NewMem(), + Get: func(context.Context, string) ([]byte, error) { + return nil, &fetch.StatusError{URL: eol.Salesforce.URL, StatusCode: code} + }, + Now: func() time.Time { return kittest.Clock }, + } + got := kittest.IngestWith(t, env, Plugin{Page: eol.Salesforce, Archiver: archive}) + if len(got) == 0 { + t.Fatal("no events: the archive fallback didn't run") + } + // Unlike the normal path, a permanently blocked live page has no + // cheap way to check "did it change": liveOrArchived needs the + // archive's own fetch just to get bytes to hash, on every run, + // not only a changed one. The second run still stores nothing + // new: the hash matches. + if archive.Calls != 2 { + t.Errorf("%d snapshots, want 2: the live page is blocked every run", archive.Calls) + } + for _, e := range got { + if e.SourceURL == eol.Salesforce.URL { + t.Errorf("%s: source_url is the blocked live page, want the archive's snapshot", e.Fingerprint) + } + } + }) + } +} + +// A real failure (not the provider blocking a plain fetch) must stay a +// failure: falling back to the archive for a timeout or a 5xx would hide it +// as a real page. +func TestDoesNotFallBackOnATransientError(t *testing.T) { + for _, code := range []int{404, 429, 503} { + t.Run(fmt.Sprint(code), func(t *testing.T) { + env := plugin.Env{ + Baselines: kittest.NewMem(), + Get: func(context.Context, string) ([]byte, error) { + return nil, &fetch.StatusError{URL: eol.Salesforce.URL, StatusCode: code} + }, + Now: func() time.Time { return kittest.Clock }, + } + // No Pages: a fallback here would fail the test by asking the + // archive for a snapshot it was never given. + _, err := Plugin{Page: eol.Salesforce, Archiver: &kittest.Archive{T: t}}.Run(context.Background(), env) + if err == nil { + t.Fatalf("want an error for a %d, got none", code) + } + }) + } +} diff --git a/plugins/feed/cloudflare_test.go b/plugins/notices/feed/cloudflare_test.go similarity index 100% rename from plugins/feed/cloudflare_test.go rename to plugins/notices/feed/cloudflare_test.go diff --git a/plugins/notices/feed/extract.go b/plugins/notices/feed/extract.go new file mode 100644 index 0000000..c7d14fe --- /dev/null +++ b/plugins/notices/feed/extract.go @@ -0,0 +1,19 @@ +package feed + +import "github.com/patch-it-dev/patch-it-plugins/core/extract" + +// The feed and HTML helpers live in core/extract, for every reader; these +// names keep the readers here (and code that imports them) as they were. +type ( + Entry = extract.Entry + Section = extract.Section +) + +var ( + Parse = extract.ParseFeed + Text = extract.Text + Lines = extract.Lines + SplitBy = extract.SplitBy + Date = extract.Date + Codes = extract.Codes +) diff --git a/plugins/notices/feed/feed.go b/plugins/notices/feed/feed.go new file mode 100644 index 0000000..a4a40d7 --- /dev/null +++ b/plugins/notices/feed/feed.go @@ -0,0 +1,121 @@ +// Package feed is the notices kind's reader for a vendor's RSS or Atom +// changelog feed (plugins/notices reads it, snapshots and cites it): one event per breaking or deprecation entry (or per name such an +// entry lists), quoting the line that says so. Rung 3 of the source ladder. +// +// A feed is prose, so each feed comes with a Reader that knows what its +// vendor's entries look like and which subject they describe. The rules are +// the same for every reader (precision over recall): +// +// - An entry the vendor doesn't mark as breaking or deprecation (a category, +// a heading) is skipped. +// - A marked entry becomes an event only when the reader finds a typed +// subject in it (a runner label, a model id in code) and a dated +// sentence. Otherwise it is dropped, logged with why, never guessed. +// - `breaking` needs the vendor to say the thing stops on a date ("will be +// retired on", "will be shut down on"). Anything softer ("we recommend +// updating before") is downgraded to `deprecation`. +// +// A feed is a live document, so the events cite a Wayback Machine snapshot +// of it, read back and checked against the live feed (kit.Cite), like every +// notices source. +package feed + +import ( + "fmt" + "log" + "time" + + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/kit" +) + +// Feed is one vendor feed and how to read its entries. +type Feed struct { + API string // the events' api: "github-actions" + Vendor string // for sentences: "GitHub" + URL string // the feed itself + Read Reader +} + +// Reader turns one entry into findings: what it can name for sure, and what +// it drops. It returns nothing for an entry that isn't breaking or a +// deprecation. +type Reader func(e Entry) []Finding + +// Finding is one change a reader found in an entry, or one it dropped. +type Finding struct { + ChangeType event.ChangeType // breaking or deprecation + Version string // per the subject's type: the removal or shutdown date + Subject event.Subject + Description string + Hint string + Excerpt string // the entry's own lines that say so + Entry string // the entry's link, for the log + Dropped string // set: the entry was marked but this is why no event +} + +// Findings reads every entry of a feed. +func (f Feed) Findings(b []byte) ([]Finding, error) { + entries, err := Parse(b) + if err != nil { + return nil, err + } + var out []Finding + for _, e := range entries { + out = append(out, f.Read(e)...) + } + return out, nil +} + +// What the notices kind (plugins/notices) asks of a feed. + +// Findings are what one read of a feed found, dropped entries included. +type Findings []Finding + +// Count is how many findings the feed gave. +func (fs Findings) Count() int { return len(fs) } + +// Slug is the events' api: "github-actions". +func (f Feed) Slug() string { return f.API } + +// PageURL is the feed itself. +func (f Feed) PageURL() string { return f.URL } + +// Find reads every entry of the feed. +func (f Feed) Find(b []byte) (kit.Notices, error) { + fs, err := f.Findings(b) + return Findings(fs), err +} + +// Events are an event per finding, citing citeURL; a dropped finding is +// logged with why. +func (f Feed) Events(found kit.Notices, citeURL string, now time.Time) ([]event.ChangeEvent, []event.EventV2, []error) { + var events []event.EventV2 + var rejected []error + for _, fd := range found.(Findings) { + if fd.Dropped != "" { + log.Printf("%s: dropped %s: %s", f.API, fd.Entry, fd.Dropped) + continue + } + e := event.EventV2{ + API: f.API, + Version: fd.Version, + ChangeType: fd.ChangeType, + Breaking: fd.ChangeType == event.ChangeTypeBreaking, + Subject: fd.Subject, + Description: fd.Description, + MigrationHint: fd.Hint, + SourceURL: citeURL, + SourceExcerpt: fd.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: %w", f.API, fd.Entry, err)) + continue + } + events = append(events, e) + } + return nil, events, rejected +} diff --git a/plugins/notices/feed/feed_test.go b/plugins/notices/feed/feed_test.go new file mode 100644 index 0000000..01158cd --- /dev/null +++ b/plugins/notices/feed/feed_test.go @@ -0,0 +1,107 @@ +package feed + +import ( + "strings" + "testing" + + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" +) + +// What each feed's marked entries came to, kept and dropped: the golden files +// pin the events, this pins that the unsure ones were dropped, not guessed. +func TestUnsureEntriesAreDropped(t *testing.T) { + for _, c := range []struct { + feed Feed + file string + dropped []string // a substring of each drop reason, in order + }{ + {GitHubActions, "testdata/github-changelog-actions.rss.xml", []string{ + "arm32-linux-windows-retirement", // no runner label: no ci_runtime to name + "pull_request_target-blocked-by-default-december-2", // a behavior change, no subject type fits + }}, + {VertexAIModels, "testdata/vertex-ai-generative-ai.atom.xml", []string{ + "Vertex AI Extensions deprecation", + "Anthropic's Claude 3 Haiku", // a product name in prose, not a model id + "Anthropic's Claude 3.5 Haiku", + }}, + } { + fs, err := c.feed.Findings(kittest.Read(t, c.file)) + if err != nil { + t.Fatal(err) + } + var drops []string + for _, f := range fs { + if f.Dropped != "" { + drops = append(drops, f.Entry+" "+f.Dropped) + } + } + if len(drops) != len(c.dropped) { + t.Errorf("%s: dropped %d, want %d:\n%s", c.feed.API, len(drops), len(c.dropped), strings.Join(drops, "\n")) + continue + } + for i, want := range c.dropped { + if !strings.Contains(drops[i], want) { + t.Errorf("%s: drop %d is %q, want %q", c.feed.API, i, drops[i], want) + } + } + } +} + +func TestParseRefusesWhatIsntAFeed(t *testing.T) { + for name, b := range map[string]string{ + "html": "moved", + "no items": `x`, + "no entry": `x`, + } { + if _, err := Parse([]byte(b)); err == nil { + t.Errorf("%s: want an error, never zero events read as a quiet week", name) + } + } +} + +// RSS without content:encoded falls back to description; Atom takes the +// alternate link and the category terms. +func TestParseReadsBothFormats(t *testing.T) { + r, err := Parse([]byte(`A & Bhttps://x.test/a + Retired<p>text</p>`)) + if err != nil || r[0].Title != "A & B" || r[0].HTML != "

text

" || r[0].Categories[0] != "Retired" || r[0].ID != "https://x.test/a" { + t.Errorf("rss: %+v %v", r, err) + } + a, err := Parse([]byte(`iT + + <b>s</b>`)) + if err != nil || a[0].Link != "https://x.test/e" || a[0].HTML != "s" || a[0].Categories[0] != "Deprecated" { + t.Errorf("atom: %+v %v", a, err) + } +} + +// Breaking only when the vendor says the thing stops on the date; softer +// words downgrade to a deprecation, and no date drops the entry. +func TestBreakingNeedsTheVendorToSayItStops(t *testing.T) { + entry := func(sentence string) Entry { + return Entry{Title: "Ubuntu 22.04 runner image retirement", Link: "https://x.test/e", Categories: []string{"Retired"}, + HTML: "

" + sentence + "

This deprecation includes the following labels:

  • ubuntu-22.04
"} + } + for sentence, want := range map[string]string{ + "The Ubuntu 22.04 runner image will be retired on March 1, 2027.": "breaking 2027-03-01", + "The Ubuntu 22.04 runner image will be removed on March 1, 2027.": "breaking 2027-03-01", + "The Ubuntu 22.04 runner image will be deprecated on March 1, 2027.": "deprecation 2027-03-01", + "Please move off the Ubuntu 22.04 runner image before March 1, 2027.": "deprecation 2027-03-01", + "The Ubuntu 22.04 runner image will be retired in the coming months.": "dropped", + "Announced March 1, 2027: the Ubuntu 22.04 image is being looked at.": "dropped", + } { + fs := readGitHubActions(entry(sentence)) + got := "dropped" + if len(fs) == 1 && fs[0].Dropped == "" { + got = string(fs[0].ChangeType) + " " + fs[0].Version + } + if got != want { + t.Errorf("%q: %s, want %s", sentence, got, want) + } + } + unmarked := entry("The Ubuntu 22.04 runner image will be retired on March 1, 2027.") + unmarked.Categories = []string{"Improvement"} + if fs := readGitHubActions(unmarked); len(fs) != 0 { + t.Errorf("an entry the vendor didn't mark: %+v", fs) + } +} diff --git a/plugins/feed/readers.go b/plugins/notices/feed/readers.go similarity index 100% rename from plugins/feed/readers.go rename to plugins/notices/feed/readers.go diff --git a/plugins/feed/testdata/README.md b/plugins/notices/feed/testdata/README.md similarity index 89% rename from plugins/feed/testdata/README.md rename to plugins/notices/feed/testdata/README.md index eff3f6f..d6115b7 100644 --- a/plugins/feed/testdata/README.md +++ b/plugins/notices/feed/testdata/README.md @@ -1,7 +1,7 @@ # Saved feeds -Real copies, saved once with `curl`. The golden files under `golden/` are what -the plugin stores from them (`go test ./plugins/feed -update`). +Real copies, saved once with `curl`. The golden files, `../../testdata/golden/.json`, +are what the notices kind stores from them (`go test ./plugins/notices -update`). | File | URL | Saved | License | Quote | |---|---|---|---|---| diff --git a/plugins/feed/testdata/cloudflare-api-deprecations.rss.xml b/plugins/notices/feed/testdata/cloudflare-api-deprecations.rss.xml similarity index 100% rename from plugins/feed/testdata/cloudflare-api-deprecations.rss.xml rename to plugins/notices/feed/testdata/cloudflare-api-deprecations.rss.xml diff --git a/plugins/feed/testdata/github-changelog-actions.rss.xml b/plugins/notices/feed/testdata/github-changelog-actions.rss.xml similarity index 100% rename from plugins/feed/testdata/github-changelog-actions.rss.xml rename to plugins/notices/feed/testdata/github-changelog-actions.rss.xml diff --git a/plugins/feed/testdata/vertex-ai-generative-ai.atom.xml b/plugins/notices/feed/testdata/vertex-ai-generative-ai.atom.xml similarity index 100% rename from plugins/feed/testdata/vertex-ai-generative-ai.atom.xml rename to plugins/notices/feed/testdata/vertex-ai-generative-ai.atom.xml diff --git a/plugins/notices/feed_golden_test.go b/plugins/notices/feed_golden_test.go new file mode 100644 index 0000000..05a986e --- /dev/null +++ b/plugins/notices/feed_golden_test.go @@ -0,0 +1,33 @@ +package notices + +import ( + "testing" + + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/plugins/notices/feed" +) + +// The two feeds as saved on 2026-11-14 (feed/testdata/README.md), each through the +// whole plugin: live feed and snapshot are the same copy, so the events cite +// the snapshot, and kittest's second run over the unchanged feed asks for no +// second snapshot and stores nothing new. +func TestFeedsGolden(t *testing.T) { + for _, c := range []struct { + feed feed.Feed + file string + }{ + {feed.GitHubActions, "feed/testdata/github-changelog-actions.rss.xml"}, + {feed.VertexAIModels, "feed/testdata/vertex-ai-generative-ai.atom.xml"}, + {feed.CloudflareAPI, "feed/testdata/cloudflare-api-deprecations.rss.xml"}, + } { + t.Run(c.feed.API, func(t *testing.T) { + saved := kittest.Pages{c.feed.URL: c.file} + archive := &kittest.Archive{T: t, Pages: saved} + got := kittest.IngestWith(t, kittest.Env(t, saved), Plugin{Page: c.feed, Archiver: archive}) + if archive.Calls != 1 { + t.Errorf("%d snapshots, want 1", archive.Calls) + } + kittest.Golden(t, "testdata/golden/"+c.feed.API+".json", got) + }) + } +} diff --git a/plugins/notices/feed_registered_test.go b/plugins/notices/feed_registered_test.go new file mode 100644 index 0000000..646800c --- /dev/null +++ b/plugins/notices/feed_registered_test.go @@ -0,0 +1,14 @@ +package notices + +import ( + "testing" + + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/plugins/notices/feed" +) + +func TestFeedsRegisterThemselves(t *testing.T) { + for _, f := range []feed.Feed{feed.GitHubActions, feed.VertexAIModels, feed.CloudflareAPI} { + kittest.Registered(t, Plugin{Page: f}) + } +} diff --git a/plugins/notices/notices.go b/plugins/notices/notices.go new file mode 100644 index 0000000..cfdea5f --- /dev/null +++ b/plugins/notices/notices.go @@ -0,0 +1,201 @@ +// Package notices is the kind for a live page of dated notices: something +// stops, or is deprecated, on a date. A model provider's deprecations table +// (retire/), a vendor's RSS or Atom changelog feed (feed/), a vendor's API +// end-of-life table (eol/). Each Page reader knows how its page reads; the +// steps around it are written once, here: fetch the live page, stop when it +// hasn't changed since the last run, read it, snapshot it in the Wayback +// Machine and check the snapshot says the same (kit.Cite), make the events +// from the snapshot so each cites what it quotes, and save the baseline. +// +// Two options a reader turns on with a method: ShapeGuard (a read with fewer +// than 90% of the last one's notices is an error: the page changed shape), +// and ArchiveWhenBlocked (a live page that answers 401 or 403 is read from a +// fresh Wayback Machine snapshot instead). +package notices + +import ( + "context" + "errors" + "fmt" + "log" + "time" + + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/kit" + "github.com/patch-it-dev/patch-it-plugins/core/migrate" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" + "github.com/patch-it-dev/patch-it-plugins/plugins/notices/eol" + "github.com/patch-it-dev/patch-it-plugins/plugins/notices/feed" + "github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire" +) + +func init() { + plugin.RegisterProvider(plugin.Provider{ + ID: "openai", Name: "OpenAI", Category: plugin.CategoryAI, Homepage: "https://openai.com", + Sources: []plugin.Source{{ + ID: "models", Layer: plugin.LayerAIModels, Page: "providers/openai-models.md", + Watches: "Model deprecations and shutdown dates (Chat Completions and Responses text models)", + URLs: []string{"https://developers.openai.com/api/docs/deprecations"}, + Plugin: Plugin{Page: retire.OpenAI, Archiver: kit.Wayback{}}, + }}, + }) + plugin.RegisterProvider(plugin.Provider{ + ID: "anthropic", Name: "Anthropic", Category: plugin.CategoryAI, Homepage: "https://www.anthropic.com", + Sources: []plugin.Source{{ + ID: "models", Layer: plugin.LayerAIModels, Page: "providers/anthropic-models.md", + Watches: "Model deprecations and retirement dates (Messages API models)", + URLs: []string{"https://platform.claude.com/docs/en/about-claude/model-deprecations"}, + Plugin: Plugin{Page: retire.Anthropic, Archiver: kit.Wayback{}}, + }}, + }) + plugin.RegisterProvider(plugin.Provider{ + ID: "github", Name: "GitHub", Category: plugin.CategoryDevTools, Homepage: "https://github.com", + Sources: []plugin.Source{{ + ID: "actions", Layer: plugin.LayerCI, Page: "providers/github-actions.md", + Watches: "GitHub Actions retirements, such as runner images and the `runs-on` labels they remove", + URLs: []string{"https://github.blog/changelog/label/actions/feed/"}, + Plugin: Plugin{Page: feed.GitHubActions, Archiver: kit.Wayback{}}, + }}, + }) + plugin.RegisterProvider(plugin.Provider{ + ID: "google", Name: "Google", Category: plugin.CategoryAI, Homepage: "https://cloud.google.com", + Sources: []plugin.Source{{ + ID: "vertex-ai-models", Layer: plugin.LayerAIModels, Page: "providers/vertex-ai-models.md", + Watches: "Generative AI model deprecations on Vertex AI", + URLs: []string{"https://docs.cloud.google.com/feeds/generative-ai-on-vertex-ai-release-notes.xml"}, + Plugin: Plugin{Page: feed.VertexAIModels, Archiver: kit.Wayback{}}, + }}, + }) + plugin.RegisterProvider(plugin.Provider{ + ID: "cloudflare", Name: "Cloudflare", Category: plugin.CategoryInfrastructure, Homepage: "https://www.cloudflare.com", + Sources: []plugin.Source{{ + ID: "api", Layer: plugin.LayerAPI, Page: "providers/cloudflare.md", + Watches: "REST API operations Cloudflare deprecates, breaking on their end-of-life date when it gives one", + URLs: []string{"https://developers.cloudflare.com/fundamentals/api/reference/deprecations/index.xml"}, + Plugin: Plugin{Page: feed.CloudflareAPI, Archiver: kit.Wayback{}}, + }}, + }) + plugin.RegisterProvider(plugin.Provider{ + ID: "salesforce", Name: "Salesforce", Category: plugin.CategoryCRM, Homepage: "https://www.salesforce.com", + Sources: []plugin.Source{{ + ID: "rest-api", Layer: plugin.LayerAPI, Page: "providers/salesforce.md", + Watches: "REST API version ranges deprecated and retired, from Salesforce's own API end-of-life policy page", + URLs: []string{"https://developer.salesforce.com/docs/platform/api-rest/guide/api-rest-eol.html"}, + Plugin: Plugin{Page: eol.Salesforce, Archiver: kit.Wayback{}}, + }}, + }) +} + +// Page is one live page of notices and how it reads: retire.Page, +// feed.Feed and eol.Page. +type Page interface { + // Slug is the events' api and the source's old slug: "openai-models". + Slug() string + // PageURL is the live page. + PageURL() string + // Find reads the page's notices. + Find(page []byte) (kit.Notices, error) + // Events turn what Find read into events citing citeURL: v1 events + // (converted here) or v2 ones, and the notices that failed to become + // events. + Events(found kit.Notices, citeURL string, now time.Time) (v1 []event.ChangeEvent, v2 []event.EventV2, rejected []error) +} + +// shapeGuarded is a Page whose read with far fewer notices than the last +// is an error. +type shapeGuarded interface{ ShapeGuard() bool } + +// archivedWhenBlocked is a Page read from a fresh Wayback Machine snapshot +// when the live page refuses a plain fetch. +type archivedWhenBlocked interface{ ArchiveWhenBlocked() bool } + +// Plugin reads one page. +type Plugin struct { + Page Page + Archiver kit.Archiver +} + +func (p Plugin) Name() string { return p.Page.Slug() } + +// Run stores an event per notice on the page. The events are read from the +// snapshot itself, so every excerpt is on the page it cites; a snapshot that +// doesn't hold what the live page says (the page changed in between) stores +// nothing this run. An unchanged page since the last run costs one GET (a +// 304 with the HTTP cache) and no snapshot. +func (p Plugin) Run(ctx context.Context, env plugin.Env) (plugin.Result, error) { + pg := p.Page + api, url := pg.Slug(), pg.PageURL() + live, archived, err := p.fetch(ctx, env, url) + if err != nil { + return plugin.Result{}, fmt.Errorf("fetching %s: %w", url, err) + } + hash := plugin.SHA256(live) + last, same, err := kit.Unchanged(env, api, live) + if err != nil { + return plugin.Result{}, err + } + if same { + log.Printf("%s: no change since %s", api, last.SourceURL) + return plugin.Result{}, nil + } + want, err := pg.Find(live) + if err != nil { + return plugin.Result{}, fmt.Errorf("reading %s: %w", url, err) + } + // A provider renaming a column makes its table unreadable, and the run + // would quietly read fewer notices. Past notices stay on the page, so a + // real drop is rare: fail loudly instead of storing a partial list. + if g, ok := pg.(shapeGuarded); ok && g.ShapeGuard() && last != nil { + if before, err := pg.Find(last.Content); err == nil && want.Count()*10 < before.Count()*9 { + return plugin.Result{}, fmt.Errorf("%s now lists %d notices, %d at %s: the page's shape may have changed", url, want.Count(), before.Count(), last.SourceURL) + } + } + + snapURL, snap, got := archived, live, want + if snapURL == "" { + if snapURL, snap, got, err = kit.Cite(ctx, p.Archiver, url, pg.Find, want); err != nil { + return plugin.Result{}, err + } + } + + now := env.Now().UTC() + v1, v2, rejected := pg.Events(got, snapURL, now) + converted, invalid := migrate.Fresh(v1) + // The hash of the live page, so the next run compares like with like. + baseline := plugin.Baseline(api, now.Format("2006-01-02"), snapURL, snapURL, snap, false, now) + baseline.SHA256 = hash + return plugin.Result{Label: snapURL, Events: append(converted, v2...), Rejected: append(rejected, invalid...), Baselines: []plugin.Spec{baseline}}, nil +} + +// fetch reads the live page. When the page's reader asks for it +// (ArchiveWhenBlocked) and the provider's own site blocks a plain fetch with +// 401 or 403 (Salesforce's docs site, every time, checked 2026-11-20; +// confirmed the same day that a real Wayback Machine save-page-now capture +// of that page parses to the same findings as the live page would), it +// falls back to a fresh Wayback Machine snapshot, taken right now by the +// archive's own crawler rather than patch-it's, and returns that content +// with its own permanent URL in archivedURL: it needs no further citation +// step, having come from the archive already. +// +// Only 401 and 403 fall back. A 404 or 410 means the page moved, not that +// it's blocked: asking the archive to snapshot a page that's gone would +// waste the call and hide the real cause behind the archive's own error. +// A 429 or a 5xx is returned as is: retrying it against the archive would +// hide a transient failure as a real page, not fix one. +func (p Plugin) fetch(ctx context.Context, env plugin.Env, pageURL string) (body []byte, archivedURL string, err error) { + body, err = env.Get(ctx, pageURL) + if err == nil { + return body, "", nil + } + b, ok := p.Page.(archivedWhenBlocked) + var se *fetch.StatusError + if !ok || !b.ArchiveWhenBlocked() || !errors.As(err, &se) || (se.StatusCode != 401 && se.StatusCode != 403) { + return nil, "", err + } + archivedURL, body, archErr := p.Archiver.Snapshot(ctx, pageURL) + if archErr != nil { + return nil, "", fmt.Errorf("fetching it directly failed (%w), and so did asking the Wayback Machine to: %w", err, archErr) + } + return body, archivedURL, nil +} diff --git a/plugins/notices/retire/notices.go b/plugins/notices/retire/notices.go new file mode 100644 index 0000000..3fb2ced --- /dev/null +++ b/plugins/notices/retire/notices.go @@ -0,0 +1,41 @@ +package retire + +import ( + "time" + + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/kit" +) + +// What the notices kind (plugins/notices) asks of a deprecations page. + +// Retirements are what one read of a page found. +type Retirements []Retirement + +// Count is how many retirements the page lists. +func (rs Retirements) Count() int { return len(rs) } + +// Slug is the events' api: "openai-models". +func (p Page) Slug() string { return p.API } + +// PageURL is the page, as markdown. +func (p Page) PageURL() string { return p.URL } + +// Find reads every retirement on the page. +func (p Page) Find(page []byte) (kit.Notices, error) { + rs, err := Parse(page, p.Keep) + return Retirements(rs), err +} + +// Events are a v1 event per retired model, citing citeURL (the kind +// converts them to v2: core/migrate reads this package, so it can't be +// called from here). +func (p Page) Events(found kit.Notices, citeURL string, now time.Time) ([]event.ChangeEvent, []event.EventV2, []error) { + v1, errs := Events(p, found.(Retirements), citeURL, now) + return v1, nil, errs +} + +// ShapeGuard is on: past retirements stay on the page, so a read with far +// fewer than the last one means the table changed shape, not that models +// came back. +func (Page) ShapeGuard() bool { return true } diff --git a/plugins/retirements/retire/providers.go b/plugins/notices/retire/providers.go similarity index 100% rename from plugins/retirements/retire/providers.go rename to plugins/notices/retire/providers.go diff --git a/plugins/notices/retire/retire.go b/plugins/notices/retire/retire.go new file mode 100644 index 0000000..1c3d673 --- /dev/null +++ b/plugins/notices/retire/retire.go @@ -0,0 +1,245 @@ +// Package retire reads a model provider's deprecations page and turns every +// retired model into change events: a second kind of source next to the +// OpenAPI differ. There is no spec to diff, only the provider's own table of +// shutdown date, model and named replacement, so this reads the table. +// +// Both providers serve the page as markdown at its URL plus ".md" (checked +// 2026-10-13), and both write each announcement as a table whose first column +// is the date the model stops working. The event cites a Wayback Machine +// snapshot of that markdown (kit/), never the live page: the contract +// requires a source that can't change under the event. +package retire + +import ( + "fmt" + "regexp" + "strings" + "time" + + "github.com/patch-it-dev/patch-it-plugins/core/event" +) + +// Page is one provider's deprecations page and what its models are sent to. +type Page struct { + API string // the api slug the events carry, e.g. "openai-models" + Vendor string // for sentences: "OpenAI" + URL string // the page as markdown + Operation string // the provider's main call that takes a model name + // Keep says whether a model name belongs to this source: the operations + // above take text models, not image, audio or embedding ones. + Keep func(name string) bool +} + +// Retirement is one model name the provider stops serving on Date, with the +// replacement it names. An alias gets its own Retirement, with the row it +// came from. +type Retirement struct { + Model string + Date string // YYYY-MM-DD + Replacement string // the replacement cell, as written ("`gpt-5.6-sol` (`reasoning.mode: pro`)") + Via []string + Excerpt string // the section heading, the table header and the row +} + +var ( + dateHeader = regexp.MustCompile(`(?i)^(shutdown|retirement) date$`) + ticked = regexp.MustCompile("`([^`]+)`") +) + +var dateLayouts = []string{"January 2, 2006", "Jan 2, 2006", "2006-01-02"} + +// Parse reads every retirement table on the page. A model listed more than +// once keeps its first row: both pages list the most recent announcement +// first, and a later one supersedes an earlier date, including a later row +// that withdraws the date ("To be announced"). A replacement that is +// itself retired is followed to the model that replaces it, so a hint never +// points at a model that no longer works. +func Parse(page []byte, keep func(string) bool) ([]Retirement, error) { + lines := strings.Split(strings.ReplaceAll(string(page), "\r\n", "\n"), "\n") + var out []Retirement + seen := map[string]bool{} + heading := "" + for i := 0; i < len(lines); i++ { + line := strings.TrimSpace(lines[i]) + if strings.HasPrefix(line, "#") { + heading = line + continue + } + header := cells(line) + if len(header) < 3 || !dateHeader.MatchString(header[0]) { + continue + } + model, repl := column(header, "model"), column(header, "replacement", "substitute") + if model < 0 || repl < 0 { + continue // an endpoint ("System") or a training-price table: no model to replace + } + i++ // the |---| row + for i+1 < len(lines) && strings.HasPrefix(strings.TrimSpace(lines[i+1]), "|") { + i++ + row := strings.TrimSpace(lines[i]) + c := cells(row) + if len(c) <= model || len(c) <= repl { + return nil, fmt.Errorf("a short row under %q: %s", heading, row) + } + names := ticked.FindAllStringSubmatch(c[model], -1) + date, err := parseDate(c[0]) + if err != nil { + // "To be announced": not a retirement yet, and the newer word on + // these names, so an older row's date for them doesn't count. + for _, m := range names { + seen[m[1]] = true + } + continue + } + excerpt := strings.Join([]string{heading, strings.TrimSpace(lines[headerLine(lines, i)]), row}, "\n") + for _, m := range names { + name := m[1] + if seen[name] || !keep(name) { + continue + } + seen[name] = true + out = append(out, Retirement{Model: name, Date: date, Replacement: c[repl], Excerpt: excerpt}) + } + } + } + if len(out) == 0 { + return nil, fmt.Errorf("no retirement tables found: the page's shape may have changed") + } + follow(out) + return out, nil +} + +// headerLine walks back from a row to its table's header. +func headerLine(lines []string, i int) int { + for i > 0 && strings.HasPrefix(strings.TrimSpace(lines[i-1]), "|") { + i-- + } + return i +} + +// follow replaces a replacement that is itself retired with its own +// replacement, recording the hops: gpt-3.5-turbo-0613's named replacement is +// gpt-3.5-turbo, which shuts down on 2026-10-23 for gpt-5.6-terra. +func follow(rs []Retirement) { + by := map[string]Retirement{} + for _, r := range rs { + by[r.Model] = r + } + for i := range rs { + for hops := 0; hops < 10; hops++ { + next, ok := by[First(rs[i].Replacement)] + if !ok || next.Model == rs[i].Model { + break + } + rs[i].Via = append(rs[i].Via, next.Model) + rs[i].Replacement = next.Replacement + } + } +} + +// First is the first model name a replacement cell gives, "" when it names +// none ("The most capable cyber model available to you."). +func First(replacement string) string { + if m := ticked.FindStringSubmatch(replacement); m != nil { + return m[1] + } + return "" +} + +// cells splits a markdown table row on its unescaped pipes. A cell can hold +// an escaped one: "`gpt-4-0613` \| `gpt-4`". +func cells(row string) []string { + if !strings.HasPrefix(row, "|") { + return nil + } + row = strings.Trim(row, "|") + var out []string + var cur strings.Builder + for i := 0; i < len(row); i++ { + if row[i] == '\\' && i+1 < len(row) && row[i+1] == '|' { + cur.WriteString(`\|`) + i++ + continue + } + if row[i] == '|' { + out = append(out, strings.TrimSpace(cur.String())) + cur.Reset() + continue + } + cur.WriteByte(row[i]) + } + return append(out, strings.TrimSpace(cur.String())) +} + +func column(header []string, words ...string) int { + for i, h := range header { + for _, w := range words { + if strings.Contains(strings.ToLower(h), w) { + return i + } + } + } + return -1 +} + +func parseDate(s string) (string, error) { + for _, layout := range dateLayouts { + if t, err := time.Parse(layout, strings.TrimSpace(s)); err == nil { + return t.Format("2006-01-02"), nil + } + } + return "", fmt.Errorf("not a date: %q", s) +} + +// Events turns retirements into change events, one per model name: the +// `model` parameter can no longer take that name, in any of the provider's +// calls. affected.operation is the provider's main one; the patch-it client +// looks for the name wherever it reaches the provider's SDK, so one event per +// name gives one fix per repo, not one per operation for the same line. +// version is the shutdown date, so a provider moving the date is a new event. +// sourceURL is the snapshot the retirements were read from. +func Events(p Page, rs []Retirement, sourceURL string, now time.Time) ([]event.ChangeEvent, []error) { + var events []event.ChangeEvent + var errs []error + for _, r := range rs { + affected := event.Affected{ + Kind: event.AffectedKindRequestParameter, + Side: event.SideRequest, + Operation: p.Operation, + Property: "model", + Value: r.Model, + } + e := event.ChangeEvent{ + Fingerprint: event.Fingerprint(p.API, r.Date, event.ChangeTypeBreaking, affected, r.Model), + API: p.API, + Version: r.Date, + ChangeType: event.ChangeTypeBreaking, + Breaking: true, + Affected: affected, + Description: fmt.Sprintf("Model %q is shut down on %s: %s requests naming it fail from that date.", r.Model, r.Date, p.Vendor), + MigrationHint: hint(p.Vendor, r), + SourceURL: sourceURL, + SourceExcerpt: r.Excerpt, + Confidence: 1.0, + DetectedAt: now, + } + if err := e.Validate(); err != nil { + errs = append(errs, fmt.Errorf("%s %s: %w", p.API, r.Model, err)) + continue + } + events = append(events, e) + } + return events, errs +} + +func hint(vendor string, r Retirement) string { + repl := strings.TrimSpace(r.Replacement) + if First(repl) == "" { + return fmt.Sprintf("%s names no replacement model: %s", vendor, repl) + } + h := fmt.Sprintf("Use %s instead: %s's recommended replacement.", repl, vendor) + if len(r.Via) > 0 { + h += fmt.Sprintf(" (%s first named %s, which is itself retired.)", vendor, strings.Join(r.Via, ", then ")) + } + return h +} diff --git a/plugins/retirements/retire/retire_test.go b/plugins/notices/retire/retire_test.go similarity index 100% rename from plugins/retirements/retire/retire_test.go rename to plugins/notices/retire/retire_test.go diff --git a/plugins/retirements/retire/testdata/README.md b/plugins/notices/retire/testdata/README.md similarity index 94% rename from plugins/retirements/retire/testdata/README.md rename to plugins/notices/retire/testdata/README.md index e71abfb..b4c3b47 100644 --- a/plugins/retirements/retire/testdata/README.md +++ b/plugins/notices/retire/testdata/README.md @@ -1,6 +1,6 @@ # Saved model deprecations pages -The two providers' deprecations pages, as markdown (each page's URL plus `.md`). `retire`'s tests and the `openai-models` / `anthropic-models` golden tests (`plugins/retirements`) read them. +The two providers' deprecations pages, as markdown (each page's URL plus `.md`). `retire`'s tests and the `openai-models` / `anthropic-models` golden tests (`plugins/notices`) read them. **License:** excerpts for testing; © OpenAI and © Anthropic respectively. Not covered by this repo's license. diff --git a/plugins/retirements/retire/testdata/anthropic-deprecations.md b/plugins/notices/retire/testdata/anthropic-deprecations.md similarity index 100% rename from plugins/retirements/retire/testdata/anthropic-deprecations.md rename to plugins/notices/retire/testdata/anthropic-deprecations.md diff --git a/plugins/retirements/retire/testdata/openai-deprecations.md b/plugins/notices/retire/testdata/openai-deprecations.md similarity index 100% rename from plugins/retirements/retire/testdata/openai-deprecations.md rename to plugins/notices/retire/testdata/openai-deprecations.md diff --git a/plugins/retirements/golden_test.go b/plugins/notices/retirements_golden_test.go similarity index 87% rename from plugins/retirements/golden_test.go rename to plugins/notices/retirements_golden_test.go index b4095c9..e3b356d 100644 --- a/plugins/retirements/golden_test.go +++ b/plugins/notices/retirements_golden_test.go @@ -1,16 +1,16 @@ -package retirements +package notices import ( "testing" "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" - "github.com/patch-it-dev/patch-it-plugins/plugins/retirements/retire" + "github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire" ) // Both providers' saved pages (2026-10-13) in, every event out. The archive // serves the same copy as the snapshot, so the events cite it; a second run // over the unchanged page asks for no snapshot. -func TestGolden(t *testing.T) { +func TestRetirementsGolden(t *testing.T) { for file, page := range map[string]retire.Page{ "openai-deprecations.md": retire.OpenAI, "anthropic-deprecations.md": retire.Anthropic, diff --git a/plugins/retirements/registered_test.go b/plugins/notices/retirements_registered_test.go similarity index 59% rename from plugins/retirements/registered_test.go rename to plugins/notices/retirements_registered_test.go index c5be64c..42cee34 100644 --- a/plugins/retirements/registered_test.go +++ b/plugins/notices/retirements_registered_test.go @@ -1,13 +1,13 @@ -package retirements +package notices import ( "testing" "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" - "github.com/patch-it-dev/patch-it-plugins/plugins/retirements/retire" + "github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire" ) -func TestRegistersItself(t *testing.T) { +func TestRetirementsRegisterThemselves(t *testing.T) { for _, p := range []retire.Page{retire.OpenAI, retire.Anthropic} { kittest.Registered(t, Plugin{Page: p}) } diff --git a/plugins/notices/retirements_retirements_test.go b/plugins/notices/retirements_retirements_test.go new file mode 100644 index 0000000..5af6e91 --- /dev/null +++ b/plugins/notices/retirements_retirements_test.go @@ -0,0 +1,133 @@ +package notices + +import ( + "context" + "fmt" + "strings" + "testing" + "time" + + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" + "github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire" +) + +const deprecations = `### 2026-04-22: Legacy GPT model snapshots + +| Shutdown date | Model snapshot | Substitute model | +| ---------------- | -------------------------- | ---------------- | +| October 23, 2026 | ` + "`gpt-4-0613` \\| `gpt-4`" + ` | ` + "`gpt-5.6-sol`" + ` | +` + +// fakeArchive is the Wayback Machine without the network: it serves what it +// was given and counts the snapshots it was asked for. +type fakeArchive struct { + content string + err error + calls *int +} + +func (f fakeArchive) Snapshot(_ context.Context, page string) (string, []byte, error) { + *f.calls++ + if f.err != nil { + return "", nil, f.err + } + return "https://web.archive.org/web/20261013115538/" + page, []byte(f.content), nil +} + +// page is what the provider's page says now, and what the archive holds. +type page struct { + live string + archive fakeArchive +} + +var current page + +func withPage(t *testing.T, live string, archive fakeArchive) { + t.Helper() + current = page{live, archive} +} + +func openStore(*testing.T) *kittest.Mem { return kittest.NewMem() } + +// retirements runs OpenAI's plugin over the current page through the same core +// the command uses. +func retirements(ctx context.Context, s *kittest.Mem, p retire.Page) (bool, error) { + env := plugin.Env{ + Baselines: s, + Get: func(context.Context, string) ([]byte, error) { return []byte(current.live), nil }, + Now: time.Now, + } + return kittest.Run(ctx, env, s, Plugin{Page: p, Archiver: current.archive}) +} + +func TestRetirementsStoreOneEventPerModel(t *testing.T) { + ctx, s, calls := context.Background(), openStore(t), 0 + withPage(t, deprecations, fakeArchive{content: deprecations, calls: &calls}) + + if rejected, err := retirements(ctx, s, retire.OpenAI); err != nil || rejected { + t.Fatalf("rejected=%v err=%v", rejected, err) + } + events, err := s.All() + if err != nil { + t.Fatal(err) + } + got := map[string]bool{} + for _, e := range events { + got[e.Subject.Provider+" "+e.Version+" "+e.Subject.Name] = true + if !strings.HasPrefix(e.SourceURL, "https://web.archive.org/web/20261013115538/") { + t.Errorf("cites %s, want the snapshot", e.SourceURL) + } + } + if len(events) != 2 || !got["openai 2026-10-23 gpt-4-0613"] || !got["openai 2026-10-23 gpt-4"] { + t.Errorf("want one event per model name, got %v", got) + } + + // Same page again: no snapshot, nothing new. + if _, err := retirements(ctx, s, retire.OpenAI); err != nil { + t.Fatal(err) + } + if calls != 1 { + t.Errorf("%d snapshots for an unchanged page, want 1", calls) + } + if again, _ := s.All(); len(again) != 2 { + t.Errorf("%d events after a rerun, want 2", len(again)) + } +} + +func TestRetirementsStoreNothingWithoutASnapshotThatHoldsThem(t *testing.T) { + for name, archive := range map[string]fakeArchive{ + "the archive refused": {err: fmt.Errorf("429 too many requests")}, + "the page moved since": {content: strings.Replace(deprecations, "October 23", "November 23", 1)}, + } { + ctx, s, calls := context.Background(), openStore(t), 0 + archive.calls = &calls + withPage(t, deprecations, archive) + if _, err := retirements(ctx, s, retire.OpenAI); err == nil { + t.Errorf("%s: want an error", name) + } + if events, _ := s.All(); len(events) != 0 { + t.Errorf("%s: stored %d events with nothing to cite", name, len(events)) + } + if last, _ := s.LastSpec(retire.OpenAI.API); last != nil { + t.Errorf("%s: the page was saved, so the next run would skip it", name) + } + } +} + +// A renamed column hides a table: the run must fail, not store a shorter list. +func TestRetirementsRefuseAPageThatLostMostOfItsTables(t *testing.T) { + ctx, s, calls := context.Background(), openStore(t), 0 + withPage(t, deprecations, fakeArchive{content: deprecations, calls: &calls}) + if _, err := retirements(ctx, s, retire.OpenAI); err != nil { + t.Fatal(err) + } + renamed := strings.Replace(deprecations, "Substitute model", "Successor", 1) + strings.Replace(strings.Replace(deprecations, "gpt-4-0613` \\| `gpt-4", "gpt-4o-old", 1), "Substitute model", "Recommended replacement", 1) + withPage(t, renamed, fakeArchive{content: renamed, calls: &calls}) + if _, err := retirements(ctx, s, retire.OpenAI); err == nil || !strings.Contains(err.Error(), "shape may have changed") { + t.Fatalf("want the shape error, got %v", err) + } + if events, _ := s.All(); len(events) != 2 { + t.Errorf("%d events, want only the first run's 2", len(events)) + } +} diff --git a/plugins/notices/testdata/README.md b/plugins/notices/testdata/README.md new file mode 100644 index 0000000..9e9ae85 --- /dev/null +++ b/plugins/notices/testdata/README.md @@ -0,0 +1,7 @@ +# Golden events + +`golden/openai-models.json` and `golden/anthropic-models.json` are what the `openai-models` and `anthropic-models` plugins store from the saved deprecations pages. The pages themselves are shared with the `retire` package: see [`retire/testdata/README.md`](../retire/testdata/README.md) for their URLs, dates and licenses. + +`golden/github-actions.json`, `golden/vertex-ai-models.json` and `golden/cloudflare.json` come from the saved feeds in [`feed/testdata/`](../feed/testdata/README.md); `golden/salesforce.json` from the saved page in [`eol/testdata/`](../eol/testdata/README.md). + +Rewrite them after an intended change with `go test ./plugins/notices -update`, and say in the PR why the new output is right. diff --git a/plugins/retirements/testdata/golden/anthropic-models.json b/plugins/notices/testdata/golden/anthropic-models.json similarity index 100% rename from plugins/retirements/testdata/golden/anthropic-models.json rename to plugins/notices/testdata/golden/anthropic-models.json diff --git a/plugins/feed/testdata/golden/cloudflare.json b/plugins/notices/testdata/golden/cloudflare.json similarity index 100% rename from plugins/feed/testdata/golden/cloudflare.json rename to plugins/notices/testdata/golden/cloudflare.json diff --git a/plugins/feed/testdata/golden/github-actions.json b/plugins/notices/testdata/golden/github-actions.json similarity index 100% rename from plugins/feed/testdata/golden/github-actions.json rename to plugins/notices/testdata/golden/github-actions.json diff --git a/plugins/retirements/testdata/golden/openai-models.json b/plugins/notices/testdata/golden/openai-models.json similarity index 100% rename from plugins/retirements/testdata/golden/openai-models.json rename to plugins/notices/testdata/golden/openai-models.json diff --git a/plugins/eol/testdata/golden/salesforce.json b/plugins/notices/testdata/golden/salesforce.json similarity index 100% rename from plugins/eol/testdata/golden/salesforce.json rename to plugins/notices/testdata/golden/salesforce.json diff --git a/plugins/feed/testdata/golden/vertex-ai-models.json b/plugins/notices/testdata/golden/vertex-ai-models.json similarity index 100% rename from plugins/feed/testdata/golden/vertex-ai-models.json rename to plugins/notices/testdata/golden/vertex-ai-models.json diff --git a/plugins/retirements/retire/retire.go b/plugins/retirements/retire/retire.go index 1c3d673..200af4c 100644 --- a/plugins/retirements/retire/retire.go +++ b/plugins/retirements/retire/retire.go @@ -1,245 +1,24 @@ -// Package retire reads a model provider's deprecations page and turns every -// retired model into change events: a second kind of source next to the -// OpenAPI differ. There is no spec to diff, only the provider's own table of -// shutdown date, model and named replacement, so this reads the table. +// Package retire is the old import path of github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire, +// the notices kind's deprecations-page reader. // -// Both providers serve the page as markdown at its URL plus ".md" (checked -// 2026-10-13), and both write each announcement as a table whose first column -// is the date the model stops working. The event cites a Wayback Machine -// snapshot of that markdown (kit/), never the live page: the contract -// requires a source that can't change under the event. +// Deprecated: import github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire +// instead. This package only forwards to it, so code written against the old +// path keeps building; it goes once nothing imports it. package retire -import ( - "fmt" - "regexp" - "strings" - "time" +import moved "github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire" - "github.com/patch-it-dev/patch-it-plugins/core/event" +// Deprecated: the types live in github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire. +type ( + Page = moved.Page + Retirement = moved.Retirement ) -// Page is one provider's deprecations page and what its models are sent to. -type Page struct { - API string // the api slug the events carry, e.g. "openai-models" - Vendor string // for sentences: "OpenAI" - URL string // the page as markdown - Operation string // the provider's main call that takes a model name - // Keep says whether a model name belongs to this source: the operations - // above take text models, not image, audio or embedding ones. - Keep func(name string) bool -} - -// Retirement is one model name the provider stops serving on Date, with the -// replacement it names. An alias gets its own Retirement, with the row it -// came from. -type Retirement struct { - Model string - Date string // YYYY-MM-DD - Replacement string // the replacement cell, as written ("`gpt-5.6-sol` (`reasoning.mode: pro`)") - Via []string - Excerpt string // the section heading, the table header and the row -} - +// Deprecated: the functions and values live in github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire. var ( - dateHeader = regexp.MustCompile(`(?i)^(shutdown|retirement) date$`) - ticked = regexp.MustCompile("`([^`]+)`") + Events = moved.Events + First = moved.First + Parse = moved.Parse + Anthropic = moved.Anthropic + OpenAI = moved.OpenAI ) - -var dateLayouts = []string{"January 2, 2006", "Jan 2, 2006", "2006-01-02"} - -// Parse reads every retirement table on the page. A model listed more than -// once keeps its first row: both pages list the most recent announcement -// first, and a later one supersedes an earlier date, including a later row -// that withdraws the date ("To be announced"). A replacement that is -// itself retired is followed to the model that replaces it, so a hint never -// points at a model that no longer works. -func Parse(page []byte, keep func(string) bool) ([]Retirement, error) { - lines := strings.Split(strings.ReplaceAll(string(page), "\r\n", "\n"), "\n") - var out []Retirement - seen := map[string]bool{} - heading := "" - for i := 0; i < len(lines); i++ { - line := strings.TrimSpace(lines[i]) - if strings.HasPrefix(line, "#") { - heading = line - continue - } - header := cells(line) - if len(header) < 3 || !dateHeader.MatchString(header[0]) { - continue - } - model, repl := column(header, "model"), column(header, "replacement", "substitute") - if model < 0 || repl < 0 { - continue // an endpoint ("System") or a training-price table: no model to replace - } - i++ // the |---| row - for i+1 < len(lines) && strings.HasPrefix(strings.TrimSpace(lines[i+1]), "|") { - i++ - row := strings.TrimSpace(lines[i]) - c := cells(row) - if len(c) <= model || len(c) <= repl { - return nil, fmt.Errorf("a short row under %q: %s", heading, row) - } - names := ticked.FindAllStringSubmatch(c[model], -1) - date, err := parseDate(c[0]) - if err != nil { - // "To be announced": not a retirement yet, and the newer word on - // these names, so an older row's date for them doesn't count. - for _, m := range names { - seen[m[1]] = true - } - continue - } - excerpt := strings.Join([]string{heading, strings.TrimSpace(lines[headerLine(lines, i)]), row}, "\n") - for _, m := range names { - name := m[1] - if seen[name] || !keep(name) { - continue - } - seen[name] = true - out = append(out, Retirement{Model: name, Date: date, Replacement: c[repl], Excerpt: excerpt}) - } - } - } - if len(out) == 0 { - return nil, fmt.Errorf("no retirement tables found: the page's shape may have changed") - } - follow(out) - return out, nil -} - -// headerLine walks back from a row to its table's header. -func headerLine(lines []string, i int) int { - for i > 0 && strings.HasPrefix(strings.TrimSpace(lines[i-1]), "|") { - i-- - } - return i -} - -// follow replaces a replacement that is itself retired with its own -// replacement, recording the hops: gpt-3.5-turbo-0613's named replacement is -// gpt-3.5-turbo, which shuts down on 2026-10-23 for gpt-5.6-terra. -func follow(rs []Retirement) { - by := map[string]Retirement{} - for _, r := range rs { - by[r.Model] = r - } - for i := range rs { - for hops := 0; hops < 10; hops++ { - next, ok := by[First(rs[i].Replacement)] - if !ok || next.Model == rs[i].Model { - break - } - rs[i].Via = append(rs[i].Via, next.Model) - rs[i].Replacement = next.Replacement - } - } -} - -// First is the first model name a replacement cell gives, "" when it names -// none ("The most capable cyber model available to you."). -func First(replacement string) string { - if m := ticked.FindStringSubmatch(replacement); m != nil { - return m[1] - } - return "" -} - -// cells splits a markdown table row on its unescaped pipes. A cell can hold -// an escaped one: "`gpt-4-0613` \| `gpt-4`". -func cells(row string) []string { - if !strings.HasPrefix(row, "|") { - return nil - } - row = strings.Trim(row, "|") - var out []string - var cur strings.Builder - for i := 0; i < len(row); i++ { - if row[i] == '\\' && i+1 < len(row) && row[i+1] == '|' { - cur.WriteString(`\|`) - i++ - continue - } - if row[i] == '|' { - out = append(out, strings.TrimSpace(cur.String())) - cur.Reset() - continue - } - cur.WriteByte(row[i]) - } - return append(out, strings.TrimSpace(cur.String())) -} - -func column(header []string, words ...string) int { - for i, h := range header { - for _, w := range words { - if strings.Contains(strings.ToLower(h), w) { - return i - } - } - } - return -1 -} - -func parseDate(s string) (string, error) { - for _, layout := range dateLayouts { - if t, err := time.Parse(layout, strings.TrimSpace(s)); err == nil { - return t.Format("2006-01-02"), nil - } - } - return "", fmt.Errorf("not a date: %q", s) -} - -// Events turns retirements into change events, one per model name: the -// `model` parameter can no longer take that name, in any of the provider's -// calls. affected.operation is the provider's main one; the patch-it client -// looks for the name wherever it reaches the provider's SDK, so one event per -// name gives one fix per repo, not one per operation for the same line. -// version is the shutdown date, so a provider moving the date is a new event. -// sourceURL is the snapshot the retirements were read from. -func Events(p Page, rs []Retirement, sourceURL string, now time.Time) ([]event.ChangeEvent, []error) { - var events []event.ChangeEvent - var errs []error - for _, r := range rs { - affected := event.Affected{ - Kind: event.AffectedKindRequestParameter, - Side: event.SideRequest, - Operation: p.Operation, - Property: "model", - Value: r.Model, - } - e := event.ChangeEvent{ - Fingerprint: event.Fingerprint(p.API, r.Date, event.ChangeTypeBreaking, affected, r.Model), - API: p.API, - Version: r.Date, - ChangeType: event.ChangeTypeBreaking, - Breaking: true, - Affected: affected, - Description: fmt.Sprintf("Model %q is shut down on %s: %s requests naming it fail from that date.", r.Model, r.Date, p.Vendor), - MigrationHint: hint(p.Vendor, r), - SourceURL: sourceURL, - SourceExcerpt: r.Excerpt, - Confidence: 1.0, - DetectedAt: now, - } - if err := e.Validate(); err != nil { - errs = append(errs, fmt.Errorf("%s %s: %w", p.API, r.Model, err)) - continue - } - events = append(events, e) - } - return events, errs -} - -func hint(vendor string, r Retirement) string { - repl := strings.TrimSpace(r.Replacement) - if First(repl) == "" { - return fmt.Sprintf("%s names no replacement model: %s", vendor, repl) - } - h := fmt.Sprintf("Use %s instead: %s's recommended replacement.", repl, vendor) - if len(r.Via) > 0 { - h += fmt.Sprintf(" (%s first named %s, which is itself retired.)", vendor, strings.Join(r.Via, ", then ")) - } - return h -} diff --git a/plugins/retirements/retirements.go b/plugins/retirements/retirements.go index d4d200a..6e4ff50 100644 --- a/plugins/retirements/retirements.go +++ b/plugins/retirements/retirements.go @@ -1,92 +1,13 @@ -// Package retirements is the source plugin for a model provider's deprecations -// page (OpenAI, Anthropic): every retired model becomes an event. There is no -// spec to diff: the page is read as it is now, and the events cite a Wayback -// Machine snapshot of it, never the live page (kit/). +// Package retirements is the old import path of the notices kind for a +// model provider's deprecations page, kept so code that imports it still +// builds. +// +// Deprecated: use plugins/notices: notices.Plugin{Page: retire.OpenAI}. This +// package only forwards there and registers nothing; it goes once nothing +// imports it. package retirements -import ( - "context" - "fmt" - "log" +import "github.com/patch-it-dev/patch-it-plugins/plugins/notices" - "github.com/patch-it-dev/patch-it-plugins/core/kit" - "github.com/patch-it-dev/patch-it-plugins/core/migrate" - "github.com/patch-it-dev/patch-it-plugins/core/plugin" - "github.com/patch-it-dev/patch-it-plugins/plugins/retirements/retire" -) - -func init() { - plugin.RegisterProvider(plugin.Provider{ - ID: "openai", Name: "OpenAI", Category: plugin.CategoryAI, Homepage: "https://openai.com", - Sources: []plugin.Source{{ - ID: "models", Layer: plugin.LayerAIModels, Page: "providers/openai-models.md", - Watches: "Model deprecations and shutdown dates (Chat Completions and Responses text models)", - URLs: []string{"https://developers.openai.com/api/docs/deprecations"}, - Plugin: Plugin{Page: retire.OpenAI, Archiver: kit.Wayback{}}, - }}, - }) - plugin.RegisterProvider(plugin.Provider{ - ID: "anthropic", Name: "Anthropic", Category: plugin.CategoryAI, Homepage: "https://www.anthropic.com", - Sources: []plugin.Source{{ - ID: "models", Layer: plugin.LayerAIModels, Page: "providers/anthropic-models.md", - Watches: "Model deprecations and retirement dates (Messages API models)", - URLs: []string{"https://platform.claude.com/docs/en/about-claude/model-deprecations"}, - Plugin: Plugin{Page: retire.Anthropic, Archiver: kit.Wayback{}}, - }}, - }) -} - -// Plugin reads one provider's page. -type Plugin struct { - Page retire.Page - Archiver kit.Archiver -} - -func (p Plugin) Name() string { return p.Page.API } - -// Run stores an event for every retired model on the page. The events are read -// from the snapshot itself, so every excerpt is on the page it cites; a -// snapshot that doesn't hold what the live page says (the page changed in -// between) stores nothing this run. An unchanged page since the last run costs -// one GET and no snapshot. -func (p Plugin) Run(ctx context.Context, env plugin.Env) (plugin.Result, error) { - live, err := env.Get(ctx, p.Page.URL) - if err != nil { - return plugin.Result{}, fmt.Errorf("fetching %s: %w", p.Page.URL, err) - } - hash := plugin.SHA256(live) - last, same, err := kit.Unchanged(env, p.Page.API, live) - if err != nil { - return plugin.Result{}, err - } - if same { - log.Printf("%s: no change since %s", p.Page.API, last.SourceURL) - return plugin.Result{}, nil - } - want, err := retire.Parse(live, p.Page.Keep) - if err != nil { - return plugin.Result{}, fmt.Errorf("reading %s: %w", p.Page.URL, err) - } - // A provider renaming a column makes its table unreadable, and the run would - // quietly read fewer retirements. Past retirements stay on both pages, so a - // real drop is rare: fail loudly instead of storing a partial list. - if last != nil { - if before, err := retire.Parse(last.Content, p.Page.Keep); err == nil && len(want)*10 < len(before)*9 { - return plugin.Result{}, fmt.Errorf("%s now lists %d retirements, %d at %s: the page's shape may have changed", p.Page.URL, len(want), len(before), last.SourceURL) - } - } - - read := func(b []byte) ([]retire.Retirement, error) { return retire.Parse(b, p.Page.Keep) } - snapURL, snap, got, err := kit.Cite(ctx, p.Archiver, p.Page.URL, read, want) - if err != nil { - return plugin.Result{}, err - } - - now := env.Now().UTC() - events, errs := retire.Events(p.Page, got, snapURL, now) - // The hash of the live page, so the next run compares like with like. - baseline := plugin.Baseline(p.Page.API, now.Format("2006-01-02"), snapURL, snapURL, snap, false, now) - baseline.SHA256 = hash - converted, invalid := migrate.Fresh(events) - return plugin.Result{Label: snapURL, Events: converted, Rejected: append(errs, invalid...), Baselines: []plugin.Spec{baseline}}, nil -} +// Plugin is notices.Plugin: set Page and Archiver, as before. +type Plugin = notices.Plugin diff --git a/plugins/retirements/retirements_test.go b/plugins/retirements/retirements_test.go index fe89d4d..80e9b99 100644 --- a/plugins/retirements/retirements_test.go +++ b/plugins/retirements/retirements_test.go @@ -1,133 +1,17 @@ package retirements import ( - "context" - "fmt" - "strings" "testing" - "time" "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" - "github.com/patch-it-dev/patch-it-plugins/core/plugin" "github.com/patch-it-dev/patch-it-plugins/plugins/retirements/retire" ) -const deprecations = `### 2026-04-22: Legacy GPT model snapshots - -| Shutdown date | Model snapshot | Substitute model | -| ---------------- | -------------------------- | ---------------- | -| October 23, 2026 | ` + "`gpt-4-0613` \\| `gpt-4`" + ` | ` + "`gpt-5.6-sol`" + ` | -` - -// fakeArchive is the Wayback Machine without the network: it serves what it -// was given and counts the snapshots it was asked for. -type fakeArchive struct { - content string - err error - calls *int -} - -func (f fakeArchive) Snapshot(_ context.Context, page string) (string, []byte, error) { - *f.calls++ - if f.err != nil { - return "", nil, f.err - } - return "https://web.archive.org/web/20261013115538/" + page, []byte(f.content), nil -} - -// page is what the provider's page says now, and what the archive holds. -type page struct { - live string - archive fakeArchive -} - -var current page - -func withPage(t *testing.T, live string, archive fakeArchive) { - t.Helper() - current = page{live, archive} -} - -func openStore(*testing.T) *kittest.Mem { return kittest.NewMem() } - -// retirements runs OpenAI's plugin over the current page through the same core -// the command uses. -func retirements(ctx context.Context, s *kittest.Mem, p retire.Page) (bool, error) { - env := plugin.Env{ - Baselines: s, - Get: func(context.Context, string) ([]byte, error) { return []byte(current.live), nil }, - Now: time.Now, - } - return kittest.Run(ctx, env, s, Plugin{Page: p, Archiver: current.archive}) -} - -func TestRetirementsStoreOneEventPerModel(t *testing.T) { - ctx, s, calls := context.Background(), openStore(t), 0 - withPage(t, deprecations, fakeArchive{content: deprecations, calls: &calls}) - - if rejected, err := retirements(ctx, s, retire.OpenAI); err != nil || rejected { - t.Fatalf("rejected=%v err=%v", rejected, err) - } - events, err := s.All() - if err != nil { - t.Fatal(err) - } - got := map[string]bool{} - for _, e := range events { - got[e.Subject.Provider+" "+e.Version+" "+e.Subject.Name] = true - if !strings.HasPrefix(e.SourceURL, "https://web.archive.org/web/20261013115538/") { - t.Errorf("cites %s, want the snapshot", e.SourceURL) - } - } - if len(events) != 2 || !got["openai 2026-10-23 gpt-4-0613"] || !got["openai 2026-10-23 gpt-4"] { - t.Errorf("want one event per model name, got %v", got) - } - - // Same page again: no snapshot, nothing new. - if _, err := retirements(ctx, s, retire.OpenAI); err != nil { - t.Fatal(err) - } - if calls != 1 { - t.Errorf("%d snapshots for an unchanged page, want 1", calls) - } - if again, _ := s.All(); len(again) != 2 { - t.Errorf("%d events after a rerun, want 2", len(again)) - } -} - -func TestRetirementsStoreNothingWithoutASnapshotThatHoldsThem(t *testing.T) { - for name, archive := range map[string]fakeArchive{ - "the archive refused": {err: fmt.Errorf("429 too many requests")}, - "the page moved since": {content: strings.Replace(deprecations, "October 23", "November 23", 1)}, - } { - ctx, s, calls := context.Background(), openStore(t), 0 - archive.calls = &calls - withPage(t, deprecations, archive) - if _, err := retirements(ctx, s, retire.OpenAI); err == nil { - t.Errorf("%s: want an error", name) - } - if events, _ := s.All(); len(events) != 0 { - t.Errorf("%s: stored %d events with nothing to cite", name, len(events)) - } - if last, _ := s.LastSpec(retire.OpenAI.API); last != nil { - t.Errorf("%s: the page was saved, so the next run would skip it", name) - } - } -} - -// A renamed column hides a table: the run must fail, not store a shorter list. -func TestRetirementsRefuseAPageThatLostMostOfItsTables(t *testing.T) { - ctx, s, calls := context.Background(), openStore(t), 0 - withPage(t, deprecations, fakeArchive{content: deprecations, calls: &calls}) - if _, err := retirements(ctx, s, retire.OpenAI); err != nil { - t.Fatal(err) - } - renamed := strings.Replace(deprecations, "Substitute model", "Successor", 1) + strings.Replace(strings.Replace(deprecations, "gpt-4-0613` \\| `gpt-4", "gpt-4o-old", 1), "Substitute model", "Recommended replacement", 1) - withPage(t, renamed, fakeArchive{content: renamed, calls: &calls}) - if _, err := retirements(ctx, s, retire.OpenAI); err == nil || !strings.Contains(err.Error(), "shape may have changed") { - t.Fatalf("want the shape error, got %v", err) - } - if events, _ := s.All(); len(events) != 2 { - t.Errorf("%d events, want only the first run's 2", len(events)) +// Code written against the old paths still builds and runs the same source. +func TestTheOldPathStillWorks(t *testing.T) { + p := Plugin{Page: retire.OpenAI} + kittest.Registered(t, p) + if p.Name() != "openai-models" { + t.Errorf("Plugin{Page: retire.OpenAI} is %q", p.Name()) } } diff --git a/plugins/retirements/testdata/README.md b/plugins/retirements/testdata/README.md deleted file mode 100644 index 5d272e2..0000000 --- a/plugins/retirements/testdata/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# Golden events - -`golden/openai-models.json` and `golden/anthropic-models.json` are what the `openai-models` and `anthropic-models` plugins store from the saved deprecations pages. The pages themselves are shared with the `retire` package: see [`retire/testdata/README.md`](../../../retire/testdata/README.md) for their URLs, dates and licenses. - -Rewrite them after an intended change with `go test ./plugins/retirements -update`, and say in the PR why the new output is right. diff --git a/providers/anthropic-models.md b/providers/anthropic-models.md index 77b50db..d13782e 100644 --- a/providers/anthropic-models.md +++ b/providers/anthropic-models.md @@ -4,7 +4,7 @@ Claude models that are retired or have a retirement date on the Claude API, with the replacement Anthropic recommends. One breaking event per model name. -Format plugin: `retirements` (`plugins/retirements`), reading with `plugins/retirements/retire/`. +Kind: `notices` (`plugins/notices`), reading with the deprecations-page reader, `plugins/notices/retire/`. ## Why this source diff --git a/providers/cloudflare.md b/providers/cloudflare.md index e70607f..9a91803 100644 --- a/providers/cloudflare.md +++ b/providers/cloudflare.md @@ -4,7 +4,7 @@ Cloudflare's REST API (`api.cloudflare.com/client/v4`): every operation Cloudflare names as deprecated on its API deprecations page. It's a `breaking` event, dated by the end of life, when the item says the endpoints stop on a full end-of-life date. Otherwise it's a `deprecation`. -Format plugin: `feed` (`plugins/feed`), with the `CloudflareAPI` reader. +Kind: `notices` (`plugins/notices`), with the feed reader (`plugins/notices/feed`) and its `CloudflareAPI` feed. ## Why this source diff --git a/providers/github-actions.md b/providers/github-actions.md index 3fa321f..c9adb20 100644 --- a/providers/github-actions.md +++ b/providers/github-actions.md @@ -4,7 +4,7 @@ GitHub-hosted runner images that GitHub retires: one `ci_runtime` event per `runs-on` label the retirement removes (`macos-14`, `macos-14-large`, …), dated by the removal date. -Format plugin: `feed` (`plugins/feed`), with the `GitHubActions` reader. +Kind: `notices` (`plugins/notices`), with the feed reader (`plugins/notices/feed`) and its `GitHubActions` feed. ## Why this source diff --git a/providers/openai-models.md b/providers/openai-models.md index ae73355..9ddceb7 100644 --- a/providers/openai-models.md +++ b/providers/openai-models.md @@ -4,7 +4,7 @@ OpenAI models that are being shut down: every text model name code sends to the Chat Completions or Responses API, with its shutdown date and the replacement OpenAI recommends. One breaking event per model name. -Format plugin: `retirements` (`plugins/retirements`), reading with `plugins/retirements/retire/`. +Kind: `notices` (`plugins/notices`), reading with the deprecations-page reader, `plugins/notices/retire/`. ## Why this source diff --git a/providers/salesforce.md b/providers/salesforce.md index 1396a1b..0d27ada 100644 --- a/providers/salesforce.md +++ b/providers/salesforce.md @@ -4,7 +4,7 @@ Salesforce's REST API version policy: whole numbered API version ranges (`/services/data/vNN.N/`) that Salesforce's own end-of-life page says are already retired (every resource under that version returns `410:GONE`) or scheduled to be. -Format plugin: `eol` (`plugins/eol`), with the `Salesforce` page. +Kind: `notices` (`plugins/notices`), with the end-of-life reader (`plugins/notices/eol`) and its `Salesforce` page. ## Why this source diff --git a/providers/vertex-ai-models.md b/providers/vertex-ai-models.md index d167ad0..eb00d3c 100644 --- a/providers/vertex-ai-models.md +++ b/providers/vertex-ai-models.md @@ -4,7 +4,7 @@ Generative AI model endpoints on Google Cloud's Vertex AI that Google deprecates: one `model` event per model id in a "Discontinued endpoints" table, with the replacement when the row names exactly one. -Format plugin: `feed` (`plugins/feed`), with the `VertexAIModels` reader. +Kind: `notices` (`plugins/notices`), with the feed reader (`plugins/notices/feed`) and its `VertexAIModels` feed. ## Why this source diff --git a/retire/retire.go b/retire/retire.go index e519a3e..ff9477b 100644 --- a/retire/retire.go +++ b/retire/retire.go @@ -1,19 +1,19 @@ -// Package retire is the old import path of github.com/patch-it-dev/patch-it-plugins/plugins/retirements/retire. +// Package retire is the old import path of github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire. // -// Deprecated: import github.com/patch-it-dev/patch-it-plugins/plugins/retirements/retire +// Deprecated: import github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire // instead. This package only forwards to it, so code written against the old // path keeps building; it will be removed in a later release. package retire -import moved "github.com/patch-it-dev/patch-it-plugins/plugins/retirements/retire" +import moved "github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire" -// Deprecated: the types live in github.com/patch-it-dev/patch-it-plugins/plugins/retirements/retire. +// Deprecated: the types live in github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire. type ( Page = moved.Page Retirement = moved.Retirement ) -// Deprecated: the functions and values live in github.com/patch-it-dev/patch-it-plugins/plugins/retirements/retire. +// Deprecated: the functions and values live in github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire. var ( Events = moved.Events First = moved.First