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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 22 additions & 5 deletions plugins/catalog/catalog.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,8 @@
// name (and, for a list of upcoming changes, its date and what to use
// instead). Each reader is a plugin of its own in this package, read
// version by version (plugin.Versioned): Redis's commands at each release
// tag (redis.go).
// tag (redis.go), GitHub's GraphQL upcoming changes at each commit
// (graphql.go).
//
// Precision over recall: a name that moves (a genuine rename) reads as one
// removal and one addition, same as any other. A reader never guesses a
Expand All @@ -28,13 +29,29 @@ func init() {
Plugin: Redis,
}},
})
plugin.RegisterProvider(plugin.Provider{
ID: "github", Name: "GitHub", Category: plugin.CategoryDevTools, Homepage: "https://github.com",
Sources: []plugin.Source{{
ID: "graphql", Layer: plugin.LayerAPI, Page: "providers/github-graphql.md",
Watches: "GraphQL API fields, arguments, input fields and enum values GitHub announces it will remove, with the date, from the file its breaking-changes page is built from",
URLs: []string{"https://docs.github.com/en/graphql/overview/breaking-changes", "https://github.com/github/docs/blob/main/src/graphql/data/fpt/upcoming-changes.json"},
Packages: []string{"npm:@octokit/graphql"},
Plugin: GitHubGraphQL,
}},
})
}

// finish fingerprints and validates the events a reader made, keeping the
// valid ones and the reasons the others failed.
func finish(api string, made []event.Event) (events []event.Event, rejected []error) {
for _, e := range made {
e.Fingerprint = event.Fingerprint(e.API, e.Version, e.ChangeType, e.Subject, "")
// valid ones and the reasons the others failed. details, when given, are
// the fingerprints' detail, one per event: what separates two changes at
// one location.
func finish(api string, made []event.Event, details []string) (events []event.Event, rejected []error) {
for i, e := range made {
detail := ""
if details != nil {
detail = details[i]
}
e.Fingerprint = event.Fingerprint(e.API, e.Version, e.ChangeType, e.Subject, detail)
if err := e.Validate(); err != nil {
rejected = append(rejected, fmt.Errorf("%s %s: %w", api, e.Description, err))
continue
Expand Down
199 changes: 199 additions & 0 deletions plugins/catalog/graphql.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,199 @@
package catalog

import (
"context"
"encoding/json"
"fmt"
"html"
"regexp"
"sort"
"strings"

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

// UpcomingChanges is a GraphQL API's file of announced removals, kept in a
// repo and read at each commit that changed it: GitHub's
// src/graphql/data/fpt/upcoming-changes.json in github/docs, which
// docs.github.com's "Breaking changes" page is built from. The file is an
// object keyed by removal date, each a list of {location, description,
// reason, date, criticality}: location is "Type.field" (or
// "Type.field.argument"), date the day it goes.
//
// A version is a commit (its date, its SHA). An entry in to's file that
// from's didn't have is a newly announced removal: a deprecation event on
// that location whose version is the removal date (GitHub's GraphQL API has
// no versions of its own, so the day it breaks is the one to gate on, as a
// model's shutdown date is), with previous_version the commit before. An
// entry a commit drops and a later one restores, with the same date, is then
// the same event again, which the store dedupes by fingerprint. An entry dated before the commit that
// adds it isn't an announcement (a revert putting back a removal already
// made: the file lost and regained 17 such entries on 2026-01-05 and 06), and
// an entry that leaves the file isn't read: it shipped, or was withdrawn,
// and the file doesn't say which.
type UpcomingChanges struct {
API string // the source id the events carry: "github/graphql"
Vendor string // for sentences: "GitHub"
Repo string // owner/name on GitHub
Path string // the file's path in the repo
// Endpoint is the GraphQL endpoint as an operation: every query and
// mutation is a POST to it ("POST /graphql").
Endpoint string
}

// GitHubGraphQL is GitHub's GraphQL API's upcoming changes (checked
// 2026-11-21: 1,291 entries, every one "criticality": "breaking", 29
// commits since 2023-05-01).
var GitHubGraphQL = UpcomingChanges{
API: "github/graphql", Vendor: "GitHub",
Repo: "github/docs", Path: "src/graphql/data/fpt/upcoming-changes.json",
Endpoint: "POST /graphql",
}

func (u UpcomingChanges) Name() string { return u.API }

// FileURL is the file at a commit: its own provenance.
func (u UpcomingChanges) FileURL(sha string) string {
return fmt.Sprintf("%s/%s/%s/%s", github.Raw, u.Repo, sha, u.Path)
}

// ListVersions is every commit that changed the file, oldest first.
func (u UpcomingChanges) ListVersions(ctx context.Context, env plugin.Env) ([]plugin.Version, error) {
return versions.GitHubCommits(ctx, env.Get, u.Repo, u.Path)
}

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

// upcoming is one entry of the file: the fields read, in the file's order,
// which is also how an event quotes it (the entry's "owner", a GitHub team
// or handle, is left out).
type upcoming struct {
Location string `json:"location"`
Description string `json:"description"`
Reason string `json:"reason"`
Date string `json:"date"`
Criticality string `json:"criticality"`
}

func (e upcoming) key() string { return e.Location + "@" + e.Date }

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking (precision): because the key includes Date, an entry GitHub postpones (same location, new future date) reads as a fresh announcement. And an entry that's removed by mistake and put back while its date is still in the future gets announced a second time. In both cases the event gets a new version, so it also gets a new fingerprint, and downstream sees a second deprecation for a location it was already told about. The page lists the postponement under Known gaps, which is fine. If you want it tighter, you could skip a location that any earlier commit in the pair's from already had (keyed on Location alone), and add a line to the page about the "removed and put back while still in the future" case.


// entries reads the file: every entry, in the file's order of dates.
func entries(body []byte) ([]upcoming, error) {
var byDate map[string][]json.RawMessage
if err := json.Unmarshal(body, &byDate); err != nil {
return nil, err
}
dates := make([]string, 0, len(byDate))
for d := range byDate {
dates = append(dates, d)
}
sort.Strings(dates)
var out []upcoming
for _, d := range dates {
for _, r := range byDate[d] {
var e upcoming
if err := json.Unmarshal(r, &e); err != nil {
return nil, err
}
out = append(out, e)
}
}
return out, nil
}

var gqlTag = regexp.MustCompile(`<[^>]+>`)

// gqlText is an entry's HTML as one plain sentence.
func gqlText(s string) string {
return strings.Join(strings.Fields(html.UnescapeString(gqlTag.ReplaceAllString(s, ""))), " ")
}

// Extract is a deprecation event per entry in to's file that from's didn't
// have, dated before to's commit or not at all excluded (see
// UpcomingChanges), with previous_version from's commit. A zero from has
// nothing to compare.
func (u UpcomingChanges) Extract(_ context.Context, env plugin.Env, from, to plugin.Snapshot) (plugin.Result, error) {
if from.IsZero() {
return plugin.Result{}, nil
}
before, err := entries(from.Content)
if err != nil {
return plugin.Result{}, fmt.Errorf("reading %s: %w", from.SourceURL, err)
}
after, err := entries(to.Content)
if err != nil {
return plugin.Result{}, fmt.Errorf("reading %s: %w", to.SourceURL, err)
}
had := map[string]bool{}
for _, e := range before {
had[e.key()] = true
}
var made []event.Event
var details []string
for _, e := range after {
if had[e.key()] || e.Date < to.Version.ID || e.Criticality != "breaking" {
continue
}
subject, ok := u.subject(e.Location)
if !ok {
continue
}
var quote strings.Builder
enc := json.NewEncoder(&quote)
enc.SetEscapeHTML(false)
if err := enc.Encode(e); err != nil {
return plugin.Result{}, err
}
hint := gqlText(e.Description)
if r := gqlText(e.Reason); r != "" && r != hint {
hint += " " + r
}
made = append(made, event.Event{
API: u.API, Version: e.Date, PreviousVersion: from.Version.ID,
ChangeType: event.ChangeTypeDeprecation,
Subject: subject,
Description: fmt.Sprintf("%s's GraphQL API removes %s on %s: code that queries or sends it fails from that date.",
u.Vendor, e.Location, e.Date),
MigrationHint: hint,
SourceURL: to.SourceURL,
SourceExcerpt: excerpt(strings.TrimSpace(quote.String())),
Confidence: 1.0,
DetectedAt: env.Now().UTC(),
})
details = append(details, "")
}
events, rejected := finish(u.API, made, details)
return plugin.Result{Events: events, Rejected: rejected}, nil
}

// subject places a location in the contract's api_operation: an input
// object's field, or an argument of a root field (Query.field.argument), is
// a request parameter of the endpoint; any other location (a field, a root
// field itself, a field's argument, an enum's value) is a property of its
// type, as a schema.
func (u UpcomingChanges) subject(location string) (event.Subject, bool) {
typ, rest, ok := strings.Cut(location, ".")
if !ok || typ == "" || rest == "" {
return event.Subject{}, false
}
root := typ == "Query" || typ == "Mutation" || typ == "Subscription"
if strings.HasSuffix(typ, "Input") || (root && strings.Contains(rest, ".")) {
return event.Subject{Type: event.SubjectAPIOperation, Kind: event.KindRequestParameter, Side: event.SideRequest,
Operation: u.Endpoint, Property: location}, true
}
return event.Subject{Type: event.SubjectAPIOperation, Kind: event.KindSchemaProperty, Side: event.SideResponse,
Schema: typ, Property: rest}, true
}

var _ plugin.Versioned = UpcomingChanges{}
145 changes: 145 additions & 0 deletions plugins/catalog/graphql_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,145 @@
package catalog

import (
"context"
"fmt"
"strings"
"testing"

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

// The commits of github/docs the saved files are at (testdata/README.md),
// oldest first, as GitHub's commit list names them.
var graphqlCommits = []plugin.Version{
{ID: "2026-01-05", Ref: "fc26275f90e62249fabc0f287255b3e5e60cb6e8"},
{ID: "2026-01-06", Ref: "54c26c43342f7818c4001af7eaf6a3295e3f822d"},
{ID: "2026-01-08", Ref: "2706f417a6afec24c57482d62f70035ee35c10fb"},
{ID: "2026-02-13", Ref: "fc7cedfe9c6b2c0a40fd213cd18c0afc774b67fc"},
{ID: "2026-03-03", Ref: "3a14e541873e834edf32b43b71911fe80d109a70"},
{ID: "2026-05-22", Ref: "a934f06d211bef668253e3826c118a4e559dc1ba"},
{ID: "2026-06-23", Ref: "c5738e5815fff90d38f0166f7c9949bfb664e003"},
}

func graphqlPages() kittest.Pages {
pages := kittest.Pages{}
for _, v := range graphqlCommits {
pages[GitHubGraphQL.FileURL(v.Ref)] = "testdata/github-graphql-upcoming-changes-" + v.Ref[:8] + ".json"
}
return pages
}

func graphqlPair(t *testing.T, from, to plugin.Version) []event.Event {
t.Helper()
return kittest.Versions(t, kittest.Env(t, graphqlPages()), GitHubGraphQL, from, to)
}

// The golden test: four consecutive commits, three pairs. 2026-03-03 adds
// CheckAnnotation.databaseId and Artifact.databaseId (removed on
// 2027-01-01, in the file's order), 2026-05-22 User.viewerRelevantRepositories
// and 2026-06-23 CopilotAgentTask.type (both 2026-10-01). Every entry the
// commits share is no event.
func TestGraphQLGolden(t *testing.T) {
var got []event.Event
var names []string
for _, pair := range versions.Pairs(graphqlCommits[3:]) {
for _, e := range graphqlPair(t, pair[0], pair[1]) {
got = append(got, e)
names = append(names, fmt.Sprintf("%s->%s %s.%s", e.PreviousVersion, pair[1].ID, e.Subject.Schema, e.Subject.Property))
}
}
want := "2026-02-13->2026-03-03 CheckAnnotation.databaseId | 2026-02-13->2026-03-03 Artifact.databaseId | 2026-03-03->2026-05-22 User.viewerRelevantRepositories | 2026-05-22->2026-06-23 CopilotAgentTask.type"
if strings.Join(names, " | ") != want {
t.Errorf("got %s\nwant %s", strings.Join(names, " | "), want)
}
for _, e := range got {
if e.ChangeType != event.ChangeTypeDeprecation || e.Subject.Kind != event.KindSchemaProperty || !strings.Contains(e.SourceExcerpt, `"criticality":"breaking"`) || strings.Contains(e.SourceExcerpt, "owner") {
t.Errorf("%+v", e)
}
}
for i := range got {
got[i].ID = 0
}
kittest.Golden(t, "testdata/golden/github-graphql.json", got)
}

// The pinned drop test: on 2026-01-05 the file lost 17 entries (removals
// dated 2024-07-01 to 2026-01-01, already made), got them back the next day
// and lost them again on 2026-01-08. Putting back a removal already past
// isn't an announcement, and an entry leaving the file says nothing: no
// event in either pair, though the second pair adds 17 entries.
func TestGraphQLRevertsAreNoAnnouncement(t *testing.T) {
for _, pair := range versions.Pairs(graphqlCommits[:3]) {
if got := graphqlPair(t, pair[0], pair[1]); len(got) != 0 {
t.Errorf("%s -> %s: %d events, want 0", pair[0].ID, pair[1].ID, len(got))
}
}
// The second pair does add entries: what the date check drops.
from, _ := GitHubGraphQL.ReadAt(context.Background(), kittest.Env(t, graphqlPages()), graphqlCommits[0])
to, _ := GitHubGraphQL.ReadAt(context.Background(), kittest.Env(t, graphqlPages()), graphqlCommits[1])
a, _ := entries(from.Content)
b, _ := entries(to.Content)
if len(b)-len(a) != 17 {
t.Errorf("the re-added entries: %d, want 17", len(b)-len(a))
}
}

// An input object's field and a root field's argument are request
// parameters of POST /graphql; any other location is a property of its type.
func TestGraphQLLocations(t *testing.T) {
for loc, want := range map[string]string{
"AddPullRequestReviewInput.comments": "request_parameter POST /graphql AddPullRequestReviewInput.comments",
"Query.sponsorables.dependencyEcosystem": "request_parameter POST /graphql Query.sponsorables.dependencyEcosystem",
"RepositoryPermission.TRIAGE_PLUS": "schema_property RepositoryPermission TRIAGE_PLUS",
"Issue.stateReason.enableDuplicate": "schema_property Issue stateReason.enableDuplicate",
} {
s, ok := GitHubGraphQL.subject(loc)
got := strings.Join(strings.Fields(fmt.Sprintf("%s %s %s %s", s.Kind, s.Operation, s.Schema, s.Property)), " ")
if !ok || got != want {
t.Errorf("%s: %q, want %q", loc, got, want)
}
}
if _, ok := GitHubGraphQL.subject("NoDot"); ok {
t.Error("a location without a field isn't read")
}
}

func TestGraphQLVersionsAreTheFilesCommits(t *testing.T) {
env := kittest.Env(t, kittest.Pages{
"https://api.github.com/repos/github/docs/commits?path=src%2Fgraphql%2Fdata%2Ffpt%2Fupcoming-changes.json&per_page=100&page=1": "testdata/github-commits-upcoming-changes-excerpt.json",
})
vs, err := GitHubGraphQL.ListVersions(context.Background(), env)
if err != nil || len(vs) != 3 || vs[0].Ref != graphqlCommits[3].Ref || vs[2].ID != "2026-05-22" {
t.Errorf("%v %v", vs, err)
}
}

// An entry a commit drops while still upcoming and a later commit restores
// is the same event: its version is the removal date, not the commit's, so
// the fingerprint matches and the store keeps one.
func TestGraphQLARestoredEntryIsTheSameEvent(t *testing.T) {
first := graphqlPair(t, graphqlCommits[3], graphqlCommits[4])
// 2026-03-03's file without its two additions, then the file again.
from, err := GitHubGraphQL.ReadAt(context.Background(), kittest.Env(t, graphqlPages()), graphqlCommits[3])
if err != nil {
t.Fatal(err)
}
to, err := GitHubGraphQL.ReadAt(context.Background(), kittest.Env(t, graphqlPages()), graphqlCommits[4])
if err != nil {
t.Fatal(err)
}
from.Version = plugin.Version{ID: "2026-04-01", Ref: "dropped"}
to.Version = plugin.Version{ID: "2026-04-02", Ref: "restored"}
again, err := GitHubGraphQL.Extract(context.Background(), kittest.Env(t, nil), from, to)
if err != nil || len(again.Events) != len(first) {
t.Fatalf("%v, %d events", err, len(again.Events))
}
for i, e := range again.Events {
if e.Version != "2027-01-01" || e.Fingerprint != first[i].Fingerprint {
t.Errorf("%s: version %s, same fingerprint %v", e.Subject.Property, e.Version, e.Fingerprint == first[i].Fingerprint)
}
}
}
2 changes: 1 addition & 1 deletion plugins/catalog/redis.go
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,7 @@ func (c Commands) Extract(ctx context.Context, env plugin.Env, from, to plugin.S
DetectedAt: env.Now().UTC(),
})
}
events, rejected := finish(c.API, made)
events, rejected := finish(c.API, made, nil)
return plugin.Result{Events: events, Rejected: rejected}, nil
}

Expand Down
Loading
Loading