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
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ core/event/ core/migrate/ the change-event types from patch-it's contract (
core/diff/ core/normalize/ core/hint/ the OpenAPI diff engine and its helpers
plugins/<kind>/ one package per kind, with its providers: openapi (+ adapter/, one spec adapter
per provider), notices (+ retire/, feed/, eol/), migrationguide (+ sdkguide/,
members/), changelog (Markdown, RST or JSON), catalog;
members/), changelog (Markdown, RST or JSON), catalog, apisurface (+ pysurface/);
plugins/all imports every one
plugins/removedmembers/ apichangelog/ retirements/ feed/ eol/ deprecated: merged into
migrationguide, changelog and notices, they only forward there
Expand Down
2 changes: 1 addition & 1 deletion docs/how-it-works.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ There's no list in this repo: `make plugins` prints every provider and source fr
|---|---|
| [`core/plugin/`](../core/plugin/) | The `Plugin` interface (`Run`; `ListVersions`, `ReadAt`, `Extract`), the registry of providers and sources (`RegisterProvider`, `Lookup`, `LookupSource`, `Providers`), `Env`, `Result` |
| [`core/versions/`](../core/versions/) | Every version of a source: GitHub releases, tags and commits, PyPI, npm, a page's Web Archive captures (all, or the one at a date) |
| [`plugins/`](../plugins/) | One package per kind, with its providers; `plugins/all` imports every one |
| [`plugins/`](../plugins/) | One package per kind, with its providers (openapi, changelog, notices, migrationguide, catalog, apisurface); `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/), [`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 |
Expand Down
2 changes: 1 addition & 1 deletion docs/plugins.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@
"first_name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9.-]*$", "description": "The source's first name, its old slug: what fingerprints keep hashing after the contract switches to source ids." },
"aliases": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9.-]*$" }, "description": "Every other name the source answers to." },
"packages": { "type": "array", "items": { "type": "string", "pattern": "^(pypi|npm|go|maven|nuget|rubygems|cargo|packagist):[^\\s]+$" }, "description": "The published packages this source covers, as ecosystem:name, so a lockfile entry finds its sources." },
"kind": { "type": "string", "enum": ["openapi", "changelog", "notices", "migrationguide", "catalog"] },
"kind": { "type": "string", "enum": ["openapi", "changelog", "notices", "migrationguide", "catalog", "apisurface"] },
"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://" } },
Expand Down
7 changes: 7 additions & 0 deletions docs/writing-a-plugin.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,7 @@ Write the numbers on the provider page, as `providers/vercel.md` does for its sp
| `plugins/migrationguide` | A guide that lists what a release removed, at the release's tag: an SDK's migration guide per new major (removed request parameters), or a package's table of removed members (an RST simple table or a Markdown pipe table) | A `sdkguide.Guide` in `plugins/migrationguide/sdkguide/`, or a `members.Guide` in `plugins/migrationguide/members/` |
| `plugins/changelog` | A changelog: a `CHANGELOG.md` / `CHANGES.rst` / `HISTORY.rst`, each release's section at its tag (releases from PyPI or npm), or a vendor's machine-readable API changelog in JSON (per day, endpoint and API version, oasdiff change codes), commit by commit | A `changelog.File` with its `TagPrefix`, or a `changelog.Log` |
| `plugins/catalog` | A flat JSON catalog, one entry per name, with no release tags to pin — a commit SHA stands in | A `catalog.Catalog`, diffed between two snapshots for names that disappeared entirely |
| `plugins/apisurface` | A published package's public API, compared between two releases: the classes, functions, methods and parameters in each release's files (Python first: the wheel or sdist from PyPI) | A `apisurface.Package` (registry name, ecosystem, top-level module) and its `plugin.RegisterProvider` block |

## 4. The interface

Expand Down Expand Up @@ -124,6 +125,12 @@ Extract(ctx, env, from, to Snapshot) (Result, error) // the changes fro

A living page with no versions of its own (a deprecations page, a feed: a `notices` source) is read as it is now by `Run`, and each change to it is a dated version. Its history comes from the Web Archive: the `notices` kind lists every distinct capture (`WaybackCaptures`), reads each, and extracts what each one added, citing that capture, so a year of it can be backfilled by date with no stored copies.

### The `apisurface` kind: reading a package's API without running it

`plugins/apisurface` downloads a release's wheel (or sdist) through `env.Get`, opens it in memory (`archive/zip`, `archive/tar`: nothing is written to disk) and hands the `.py` and `.pyi` files to `plugins/apisurface/pysurface`, which reads them as text: logical lines, indentation, and the headers of `def`, `class`, `__all__` and `from … import`. Nothing in the package is imported, compiled or run. That's the safest way to read code someone else publishes, and it needs no dependency: a Python interpreter (the `ast` module) would mean running a second runtime next to the plugins, and the pure-Go Python parsers available follow old grammars and pull in a large module for what is a few hundred lines here. The cost is that only signatures are read, never what a body does, and anything the reader can't be sure of is left out (see `providers/openai-python-sdk.md`). Archive and file sizes are capped (`MaxFileBytes`, `MaxSourceBytes`), so a crafted release can't exhaust the runner.

An event cites the newer release's file, and its excerpt quotes the definition's path and line in both releases. npm packages (`.d.ts` files) are next.

### Register the provider and its source

In the kind's package `init`, with the metadata ([AGENTS.md](../AGENTS.md) rule 1):
Expand Down
1 change: 1 addition & 0 deletions plugins/all/all.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
package all

import (
_ "github.com/patch-it-dev/patch-it-plugins/plugins/apisurface"
_ "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/migrationguide"
Expand Down
Loading
Loading