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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,9 +49,10 @@ One target at a time: `make tidy`, `make build`, `make fmt`, `make vet`, `make i
Go module `github.com/patch-it-dev/patch-it-plugins`; the only dependency is `gopkg.in/yaml.v3`.

```
core/plugin/ the Plugin interface, the registry of providers and their sources (metadata), Env, Result, Spec
core/plugin/ the Plugin interface (Run; ListVersions, ReadAt, Extract), the registry of providers and sources, Env, Result
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/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
Expand Down
16 changes: 10 additions & 6 deletions cmd/new-plugin/formats.go
Original file line number Diff line number Diff line change
Expand Up @@ -298,15 +298,19 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 {
defDir: "plugins/changelog",
def: `package changelog

// {{.Ident}} is {{.Provider}}'s changelog at one release.
// {{.Ident}} is {{.Provider}}'s changelog, read release by release (its
// releases listed from the ecosystem's registry, each at TagPrefix+version).
//
// ` + todo + `: the ecosystem, the import name, the repo, the release's tag,
// the release as the changelog heads it, and the changelog's path. Say what
// you checked, with the date, as changelog.go does for Textual and urllib3.
// ` + todo + `: the ecosystem, the import name, the repo, the tag prefix and
// the changelog's path. Say what you checked, with the date, as changelog.go
// does for Textual and urllib3.
var {{.Ident}} = File{
Package: "{{.ID}}", Ecosystem: "pypi", Module: "{{.ID}}",
Repo: "TODO-owner/TODO-repo", Tag: "v1.0.0", Release: "1.0.0", Path: "CHANGELOG.md",
Repo: "TODO-owner/TODO-repo", TagPrefix: "v", Path: "CHANGELOG.md",
}

// {{.Ident}}Golden is the release the golden test pins.
var {{.Ident}}Golden = {{.Ident}}.At("1.0.0")
`,
register: `plugin.Register(Plugin{File: {{.Ident}}})`,
pluginOf: `Plugin{File: {{.Ident}}}`,
Expand All @@ -324,7 +328,7 @@ var {{.Ident}} = File{
ingest: `// {{.Lower}}Ingest runs the plugin over a saved copy of the changelog.
func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 {
t.Helper()
return kittest.Ingest(t, Plugin{File: {{.Ident}}}, kittest.Pages{ {{.Ident}}.URL(): file})
return kittest.Ingest(t, Plugin{File: {{.Ident}}Golden}, kittest.Pages{ {{.Ident}}Golden.URL(): file})
}
`,
imports: []string{"github.com/patch-it-dev/patch-it-plugins/core/event"},
Expand Down
70 changes: 70 additions & 0 deletions core/plugin/versions.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
package plugin

import (
"context"
"time"
)

// A source that has versions (a spec repo's tags, a package's releases on
// PyPI or npm, a guide per major) is read in three parts, so whoever runs it
// can cover every version, not only the newest:
//
// versions, _ := s.ListVersions(ctx, env) // oldest first
// a, _ := s.ReadAt(ctx, env, versions[i])
// b, _ := s.ReadAt(ctx, env, versions[i+1])
// result, _ := s.Extract(ctx, env, a, b) // what changed from a to b
//
// Every consecutive pair is one Extract; a released version never changes, so
// a pair is done once. Run keeps working: it reads the newest version and
// extracts against the last baseline, as before.
//
// A source with no versions of its own (a deprecations page, a feed) has only
// Run: patch-it's hosted ingestion service reads it as a living page.

// Version is one version of a source.
type Version struct {
// ID is the version as events name it: "2.0.0", "2026-11-19", "2025-03-31.basil".
ID string
// Released is when it came out; zero when the source doesn't say.
Released time.Time
// Ref is what to read it at: a tag, a commit SHA, a branch, a date.
Ref string
// URL is where a person sees this version (a release page, a commit).
URL string
}

// Snapshot is a source as it was at one version: what ReadAt read.
type Snapshot struct {
Version Version
Content []byte
SourceURL string // the exact document read, pinned to the version
}

// IsZero is true for the snapshot before the first version: nothing.
func (s Snapshot) IsZero() bool { return s.Version.ID == "" && s.Content == nil }

// VersionLister lists every version a source has, oldest first.
type VersionLister interface {
ListVersions(ctx context.Context, env Env) ([]Version, error)
}

// Reader reads a source at one version.
type Reader interface {
ReadAt(ctx context.Context, env Env, v Version) (Snapshot, error)
}

// Extractor turns two snapshots into the changes between them. from may be
// zero (no earlier version read). The events carry to's version and, when from
// isn't zero, previous_version set to from's. It stores nothing: Result has no
// Baselines (Run adds its own).
type Extractor interface {
Extract(ctx context.Context, env Env, from, to Snapshot) (Result, error)
}

// Versioned is a plugin read version by version.
type Versioned interface {
Plugin
VersionLister
Reader
Extractor
}
Loading
Loading