Skip to content

plugins part 2: six kinds, every version, apisurface, new-plugin by kind (I19) - #221

Merged
adssib merged 20 commits into
mainfrom
pl2-all
Nov 21, 2026
Merged

adssib merged 20 commits into
mainfrom
pl2-all

Conversation

@adssib

@adssib adssib commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

The one PR to merge for plugins part 2 (I19): branch pl2-all is the top of the stack (#213 → #214 → #215 → #216 → #217 → #218 → #219 → #220). The stacked PRs are there to review one step at a time; merging this one lands them all (close them after).

Closes #175 · Closes #176 · Closes #177 · Closes #178 · Closes #181 · Closes #182 · Part of #179 and #171

What it contains

PR Ticket What
#213 I19.4 removedmembers → a migrationguide reader (members); one Plugin, one Extract
#214 I19.5 apichangelog → the changelog kind's JSON parser, now versioned by commit
#215 I19.6 retirements + feed + eol → one notices kind (shared steps once; ShapeGuard, ArchiveWhenBlocked); RSS/HTML helpers → core/extract
#216 I19.8, I19.11 Every version for GitHub, GitLab, Elasticsearch, Sentry, Algolia, Appwrite (recorded responses); versions.WaybackCaptures; notices backfilled by date from captures
#217 prep for patch-it#58 Source.Packages (ecosystem:name), plugin.ForPackage
#218 I19.10 apisurface kind (Python, static, no new dependency), openai/python-sdk, golden over two trimmed real wheels; npm → #212
#219 I19.7 new-plugin by provider/source/kind/reader with prompts, every kind incl. apisurface; make new-plugin; docs/which-kind.md
#220 I19 No forwarders, no legacy: the top-level and merged-kind forwarding packages and CanonicalKind deleted; one event type (v1 and core/migrate deleted); sources named only by their provider/source id, which events carry in api (old slugs, aliases, first_name deleted); Replay/Replayer deleted, catalog read version by version; new-plugin's --format/--api deleted. Plus the fixes from the first review of apisurface (#218)

Six kinds after this: openapi, changelog, notices, migrationguide, catalog, apisurface. Top level: core/ plugins/ cmd/ internal/ docs/ providers/ contract/ scripts/ .github (internal/pluginlist builds the list for cmd/list-plugins).

Golden proof

Up to #219 every existing golden is a byte-identical rename. In #220, every golden is regenerated on purpose, in one commit (one event type, sources named by their id, …): api is now the source id (stripe → stripe/api, openai-models → openai/models, …), and the fingerprint hashes api, so every fingerprint changes with it. A script compared each old golden with its new one with api and fingerprint set aside: all 23 are otherwise identical (the three core/normalize goldens also move from v1's affected to subject, same fields). Two notices goldens are renamed to their id: cloudflare-api.json, google-vertex-ai-models.json.

make check passes (go1.27.1, incl. gofmt), and scripts/check_contract.py against patch-it main's fixtures/ passes (the copy is unchanged; it's resynced after patch-it#58 merges).

What the next bump changes for the hosted ingestion service

Forwarders deleted; ingest must switch imports on its v0.4.0 bump. Ingest pins v0.3.0, where every old path still exists, so nothing breaks until it bumps. Old → new:

v0.3.0 now
plugins/retirements (retirements.Plugin) plugins/notices (notices.Plugin{Page: retire.OpenAI})
plugins/retirements/retire plugins/notices/retire
plugins/feed plugins/notices + plugins/notices/feed
plugins/eol plugins/notices + plugins/notices/eol
plugins/removedmembers plugins/migrationguide + plugins/migrationguide/members
plugins/apichangelog plugins/changelog (changelog.Plugin{Log: …})
core/migrate (migrate.ToV2, Fresh) gone: there are no v1 events
event.EventV2, DecodeV2, FingerprintV2 event.Event, Decode, Fingerprint
event.ChangeEvent, event.Affected, event.AffectedKind* gone; event.Kind* for an api_operation subject's kind
plugin.Register, lookup by old slug gone: RegisterProvider only; Lookup/LookupSource/Names take and return provider/source ids
SourceInfo.Alias(), Aliases(); alias, first_name, aliases in plugins.json gone
plugin.Replayer, Spec.Replay, plugin.Baseline(…, replay, now), kittest.Replay gone; plugin.Baseline(…, now); kittest.Pair reads and extracts a version pair
testdata under the old kind directories under plugins/notices/…, plugins/migrationguide/…, plugins/changelog/…; goldens plugins/notices/testdata/golden/<provider>-<source>.json

Events' api is the provider/source id after the bump, so every fingerprint differs from what v0.3.0 stored: with no data to keep, the database is reset, not migrated. The every-golden check gains plugins/apisurface/testdata/golden/openai-1.1.2.json (a version pair: ReadAt both, Extract).

What still uses Run / Env.Baselines / plugin.Spec, and why it isn't deleted here: every kind now implements ListVersions / ReadAt / Extract, but notices' living-page read (fetch the page now, compare with the last baseline's hash, cite a fresh Wayback snapshot) exists only as Run, and the ingest worker's living-page path calls it. Deleting Run means giving that read its own method and changing ingest's worker in the same step, and converting the 17 test files whose goldens run through kittest.Ingest (Run twice) to version pairs. That's its own change (worker + plugins together), not a cleanup; on the versioned kinds Run is otherwise only used by those tests.

Releasing

The Release workflow's scheduled run skips when a new plugins/<kind>/ directory appears (notices, apisurface): the first release after this merges is a minor, run by hand (agents never release).

Calls I made (please check)

  • feed merged into notices (as asked for this rewrite; I19.6 · One notices kind #177 said feed stays separate).
  • No forwarders and no compatibility shims (Adib): ingest pins v0.3.0, so deleting the old paths can't break it; it switches imports on its bump (table above).
  • Events' api is the provider/source id now, ahead of patch-it#58 merging: no one consumes these events yet, and the contract change says ids only.
  • Python's API is read by a small Go text reader (no interpreter, no parser dependency); what it can't be sure of it leaves out. New required parameters are logged, not events (no contract subject).
  • Packages per source: only names I could check (see registry: packages, first name and aliases per source #217).
  • new-plugin adds one source per run; its files are named <provider>-<source> (no --api, no --format).
  • apisurface review fixes (on add the apisurface kind: a Python package's public API between releases (I19.10) #218): a rename needs a matching parameter besides self/cls; a symbol in a file the newer release couldn't read (over MaxFileBytes) is a logged note, not a removal; a removed method whose class still exists is a note when the class's bases changed, a base class in the package (private ones included) now defines it, or the class now defines the name as an attribute. To follow bases, each release's snapshot keeps the package's base classes and the names their bodies define (pysurface.ReadClasses).
  • I19.8 is not closed: three migration guides still name their release, and Go proxy / Maven version sources aren't written. I19.9 (backfill helpers) isn't in this stack.

Related PRs

🤖 Generated with Claude Code

adssib and others added 8 commits November 20, 2026 17:48
One kind for a guide that lists what a release removed: the SDK guide and
the removed-members readers implement migrationguide.Guide, and one
Plugin lists, reads and extracts for both. plugins/removedmembers only
forwards now; old kind names resolve through plugin.CanonicalKind.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: adssib <[email protected]>
changelog.Plugin reads a Markdown/RST changelog (File) or a JSON one (Log).
The JSON one now lists its versions (the commits that changed the file),
reads each, and extracts what a commit added. plugins/apichangelog only
forwards.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: adssib <[email protected]>
One Plugin reads every live page of dated notices: fetch, unchanged
check, shape guard and blocked-page fallback as reader options, Wayback
cite, events, baseline. The deprecations-page, feed and end-of-life
readers live under plugins/notices; the RSS/Atom and HTML helpers move to
core/extract. The old packages only forward.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: adssib <[email protected]>
GitHub, GitLab, Elasticsearch, Sentry, Algolia and Appwrite list every
version of their spec, tested on recorded responses. versions.WaybackCaptures
lists a living page's distinct Web Archive captures (CDX), and the notices
kind reads and extracts them pair by pair, so a page's history can be
backfilled by date.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: adssib <[email protected]>
Each source lists the packages it covers (ecosystem:name) and
plugin.ForPackage finds a package's sources; the list prints them with
each source's first name and aliases, for the contract switch to source
ids.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: adssib <[email protected]>
Python first: every release on PyPI, its wheel (or sdist) read in memory
as text by pysurface (no import, no execution, no new dependency), and
consecutive surfaces compared into removed and renamed symbols, removed
parameters and parameters that lost their default. Registers
openai/python-sdk, with a golden over two trimmed real wheels.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: adssib <[email protected]>
--provider/--name/--category/--homepage, --source/--kind/--reader/--layer,
--url and --package (repeatable), asked for in a terminal when missing;
every kind and reader scaffolds (apisurface included, an OpenAPI adapter
gets its Versions stub), plugins/all gets a new kind's import, and the
old --format flags keep working for one release. make new-plugin ARGS=.
docs/which-kind.md asks which kind a source is; a test checks every
registered source's kind is one of its answers.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: adssib <[email protected]>
plugin/, event/, fetch/, migrate/, kit/ (and kit/kittest/), retire/ and
sdkguide/ only forwarded to core/ and plugins/. Code importing them moves
to core/plugin, core/event, core/fetch, core/migrate, core/kit,
plugins/notices/retire and plugins/migrationguide/sdkguide.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: adssib <[email protected]>
@claude

claude Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

Claude finished @adssib's task in 1m 49s —— View job


⚠️ Merge after fixes. The restructure is clean: the goldens are pure renames, the registry metadata is complete, and build, vet, gofmt, the race tests and the leak guard all pass. But the new apisurface kind has three ways to emit a breaking event for something that isn't a real break, and each of those becomes a wrong PR in someone's repo.

Rules

Rule Status Evidence
Metadata in the registration (Rule 1) ✅ Every source is registered with RegisterProvider (plugins/notices/notices.go, plugins/apisurface/apisurface.go:36). openai/python-sdk has its id, layer, watches, URLs, page and Packages. The new Packages field is checked against plugin.Ecosystems(). The repo has no docs/plugins.md or plugins.json. I read the words of the new and changed sources and they match what the code reads.
Provider page ✅ providers/openai-python-sdk.md has Why this source: the PyPI link, checked 2026-11-20, why the wheel is the best source, the alternatives (CHANGELOG.md, release notes, the OpenAPI spec) and a quote.
Golden test + dated quote ✅ plugins/apisurface/testdata/golden/openai-1.1.2.json comes from two trimmed real wheels. testdata/README.md gives the URL, date, license (Apache-2.0, LICENSE kept), how they were trimmed, and a quote. Every other golden is a byte-identical rename (-M100%).
Drop test ✅ TestAnAddedNameIsNoEvent: 1.1.2's added AssistantDeleted produces no event.
Fetch only via env ✅ All fetches go through env.Get / versions.*. Archives are read in memory, nothing touches disk, there are size caps, and tar links are never followed. apisurface has no net/http; it only uses net/url.
Source URL + quote on every event ✅ Each event cites the wheel URL and quotes the definition's file and line in both releases.
Nothing private (Rule 2) ✅ The leak guard is clean (8 hashed terms). I found no internal names, links or session links in the code, docs, the 8 commit messages or the PR body.
DCO / commits ✅ All 8 commits are signed off, with lowercase imperative subjects and the co-author trailer.

Bugs (blocking, all precision in apisurface, with inline comments)

  1. A rename can be inferred from self alone (apisurface.go:290). len(old.Params) > 0 counts self. So if a class drops close(self) and adds an unrelated aclose(self) in the same release, the event is renamed_symbol with the hint "Use aclose, with the same parameters". Fix: require at least one matching parameter besides self/cls.
  2. A file that crosses MaxFileBytes makes every symbol in it look removed (apisurface.go:168). A module read at the older release but skipped at the newer one (b.Skipped) loses all its symbols from the surface, so each one becomes a removed_symbol breaking event. Fix: drop (and log) changes whose Before.File is in Skipped, or refuse the pair when the skipped lists differ.
  3. A method moved up to a base class is reported as removed (apisurface.go:300). The provider page calls this a known gap, but the code emits a false removed_symbol instead of missing a change. Fix: for a removed method whose class still exists, log a note instead of an event when the class's bases name a class in the package, or when they changed between the two releases.

None of the three is hit by the openai 1.1.1 → 1.1.2 golden, so a fix shouldn't touch it. Each one is worth its own TestCompare case.

Verified

  • go build ./...: ok
  • go vet ./...: ok
  • gofmt -l .: printed nothing
  • go test -race ./...: passed (exit 0)
  • python3 scripts/leak_guard.py --all: "no banned terms (8 hashed terms checked)"
  • I did not run make contract (no patch-it checkout here), so the PR's claim that it passes is not something I checked.

Non-blocking

  • One removed class gives two events, one for the definition path (types.beta.asssitant_deleted.AsssitantDeleted) and one for the re-export (types.beta.AsssitantDeleted), with different fingerprints. That's correct, since both import paths break, but they could be grouped into one event with two Symbols.
  • versions.WaybackCaptures collapses same-day captures by keeping the later one. If a page changes and then changes back within a day, the result is a pair of identical consecutive versions. That's harmless because Extract gives no events for it, but a comment saying so would help.
  • changelog.runLog still emits every finding on each changed run and relies on fingerprints downstream to drop repeats. That's the same behavior as before, but now that extractLog takes a from, passing the baseline in would make Run and backfill agree.
  • The doc and provider page are honest that a parameter going from positional-or-keyword to positional-only isn't an event. That's fine under precision over recall.

Comment thread plugins/apisurface/apisurface.go Outdated
for _, g := range byParent {
if len(g[0]) == 1 && len(g[1]) == 1 {
old, now := a[g[0][0]], b[g[1][0]]
if old.Params != nil && !old.Overloaded && !now.Overloaded && slices.Equal(old.Params, now.Params) && len(old.Params) > 0 {

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Precision: a rename can be inferred from self alone. len(old.Params) > 0 counts self, so for methods the only "same parameters" evidence can be [self]. Example: a class drops close(self) and, in the same release, adds an unrelated aclose(self) (or to_dict(self) → model_dump(self), which isn't a drop-in). That becomes a renamed_symbol with the hint "Use aclose, with the same parameters", which is a confident and wrong fix in someone's PR.

Suggestion: only count it as a rename when at least one parameter besides a leading self/cls matches. Otherwise fall back to removed_symbol, which is still true.

real := func(ps []pysurface.Param) int {
	if len(ps) > 0 && (ps[0].Name == "self" || ps[0].Name == "cls") {
		return len(ps) - 1
	}
	return len(ps)
}
if old.Params != nil && !old.Overloaded && !now.Overloaded && slices.Equal(old.Params, now.Params) && real(old.Params) > 0 {

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Fixed in 00cf574 (on #218's branch, merged up): a rename now needs at least one matching parameter besides a leading self/cls (callerParams); close(self) → aclose(self) is a removed_symbol. Test: TestSelfAloneIsNoRename.

Comment thread plugins/apisurface/apisurface.go Outdated
now := env.Now().UTC()
var events []event.EventV2
var rejected []error
for _, c := range Compare(a.Surface, b.Surface) {

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Precision: a file that crosses MaxFileBytes makes every symbol in it look removed. If a module was read at the older release but skipped at the newer one because it grew past 4 MiB (b.Skipped), every class, function and method defined in it, plus every re-export of them, is missing from b.Surface. Each one then becomes a removed_symbol breaking event, even though nothing was removed. The doc comment in artifact.go says a skipped file is "a gap in the surface, never guessed at", but here the gap is read as a removal.

Suggestion: before building events, drop (and log) any change whose Before.File is in b.Skipped or a.Skipped. Or refuse the pair outright when the two skipped lists differ.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Fixed in 00cf574: a removal whose definition's file is in the newer release's Skipped list is a logged note ("… was too big to read"), never an event; that covers its re-exports too, since a re-export carries its definition's file. Test: TestASkippedFileRemovesNothing.

continue // its class is reported
}
before := a[k]
c := Change{Change: event.PackageRemovedSymbol, Kind: before.Kind, Symbol: k, Before: &before}

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Precision: a method moved up to a base class is reported as removed. The provider page lists "Inherited methods aren't followed to the base class" as a known gap, but what it actually does is produce a false event, not miss one. If openai.X.create moves to a shared base class in the package (common in generated SDKs that get refactored), X.create drops out of the surface and this line emits removed_symbol, even though X().create(...) still works. The same thing happens when a def becomes a class attribute (create = _create) or a @property becomes a plain attribute.

A cheap guard: for a removed method whose class still exists, look at the class's base list (it's already in Signature). If it names a class the package defines, or it changed between the two releases, downgrade the change to a Note (logged, no event).

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Fixed in 00cf574, a bit more precisely than the suggestion: each release's snapshot now keeps the package's classes that are named as a base (private modules and names included) with their bases and every name their bodies define (pysurface.ReadClasses). A removed method whose class is still there is a note when (a) the class's bases changed, (b) the class itself now defines the name (create = _create, a property made a plain attribute), or (c) a base, followed through the package's own classes, defines it. A base outside the package with unchanged bases still reads as removed (documented as a known gap on the provider page). Test: TestAMethodMovedUpIsNotRemoved, plus TestReadClasses. The golden is unchanged.

adssib and others added 6 commits November 20, 2026 18:26
…r a method moved up

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: adssib <[email protected]>
- core/event: the v1 ChangeEvent, its fingerprint and core/migrate are gone;
  every reader builds event.Event (was EventV2) directly. api_operation's
  kind type is event.Kind.
- A source's plugin is named by its id, provider/source, and its events
  carry that id in api. The old slugs, Alias/Aliases/first_name, Register
  by slug and Lookup by slug are gone; RegisterProvider refuses a plugin
  whose Name isn't its source's id. plugins.json drops alias, first_name
  and aliases.
- Replay, Replayer and Spec.Replay are gone: a version pair is ReadAt
  twice and Extract (kittest.Pair in tests). catalog gains ListVersions,
  ReadAt and Extract, so every kind is read version by version.
- new-plugin: --format, --api and the old meanings of --provider and
  --source are gone; files are named <provider>-<source>.

Goldens regenerated on purpose: api is now the source id, and since the
fingerprint hashes api, every fingerprint changed with it. Checked with a
script: old and new goldens are identical once api and fingerprint are
set aside (three normalize goldens also move from v1's affected to
subject). Two notices goldens are renamed to their id
(cloudflare-api.json, google-vertex-ai-models.json).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: adssib <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: adssib <[email protected]>
@adssib

adssib commented Nov 21, 2026

Copy link
Copy Markdown
Contributor Author

@claude review

This round (details in the updated PR body):

  1. The three apisurface blockers (fixed on add the apisurface kind: a Python package's public API between releases (I19.10) #218's branch, merged up; replies inline): no rename on self/cls alone; a symbol in a file the newer release couldn't read is a note, not a removal; a removed method whose class still exists is a note when its bases changed, a base class in the package now defines it, or the class defines the name as an attribute. Four new tests; the golden is unchanged.
  2. No legacy, no compatibility (Adib's call): deleted the merged kinds' forwarding packages (plugins/retirements, retirements/retire, feed, eol, removedmembers, apichangelog) and plugin.CanonicalKind; v1 events and core/migrate (every reader builds event.Event directly); old slugs, aliases and first_name (a plugin is named by its provider/source id, which events carry in api); Replay/Replayer/Spec.Replay (catalog now lists, reads and extracts versions); new-plugin's --format/--api; dead linkText. New test: no package under plugins/ only forwards, and every top-level one registers sources.
  3. Goldens regenerated deliberately in one commit: api is the id, so every fingerprint changed; a script confirmed old and new are identical apart from api and fingerprint.
  4. Left on purpose: Run / Env.Baselines / plugin.Spec, because the notices living-page read exists only as Run and ingest's worker calls it (see the body).

Local: make check with go1.27.1 (gofmt included); contract fixtures vs patch-it main: match. Handbook: patch-it-dev/developer-handbook#41.

@claude

claude Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

Claude finished @adssib's task in 1m 5s —— View job


⚠️ Merge after fixes. One small blocker is left. Two of the three apisurface fixes work as described, and the "class now defines the name as an attribute" case from the third works in the test but not on real wheels. Everything else in this round is clean: the legacy removal, the id-only naming and the golden regeneration.

  • Re-check the three apisurface fixes
  • Review the legacy removal (forwarders, v1, aliases, Replay)
  • Check the regenerated goldens
  • Check the AGENTS.md rules
  • Post the verdict

Rules

Rule Status Evidence
Metadata in the registration ✅ RegisterProvider is the only way in: Register and lookup by slug are gone. check() now refuses a plugin whose Name() isn't provider/source (core/plugin/provider.go), so the api an event carries can't drift from the id. Packages is checked against plugin.Ecosystems(). No hand-kept list came back. I read the words of openai/python-sdk and they match what the code reads.
Provider page ✅ providers/openai-python-sdk.md still has Why this source. It now lists "a base class outside the package" as a known gap, which is accurate.
Golden + dated quote, golden edits explained ✅ I diffed every golden in a36eb22. The only lines that changed besides api and fingerprint are the three core/normalize goldens' affected → subject (+ "type": "api_operation"), as the commit message and the PR body say. openai-1.1.2.json keeps its 1.1.1 → 1.1.2 events, now with api: "openai/python-sdk".
Drop test ✅ TestAnAddedNameIsNoEvent, plus the new negative cases: TestSelfAloneIsNoRename, TestASkippedFileRemovesNothing and TestAMethodMovedUpIsNotRemoved.
Fetch only via env / no fs outside testdata ✅ Nothing new fetches. ReadClasses works on the in-memory files ReadAt already holds.
Source URL + quote on every event ✅ Unchanged: the wheel URL, plus the definition's file and line in both releases.
Precision over recall ⚠️ See blocker 1.
Nothing private ✅ I found no internal names, private links or session links in the new commits, docs or PR body.
Tests — I can't run them here; CI_go covers build, vet, gofmt, the import and net/http guards, go test -race and make todos.

Blocking

  1. The "class now defines the name" check only works for classes that another class extends (plugins/apisurface/apisurface.go:383). notGone looks up the method's own class in b.Classes[className(cls.Signature)]. But ReadClasses only keeps classes that some other class names as a base (pysurface.go, the named[n] filter). For a leaf class like resources.Completions, the most common case, the lookup always misses. So create = _create, or a @property made a plain attribute, on a leaf class still emits a removed_symbol breaking event.
    TestAMethodMovedUpIsNotRemoved passes only because it builds Classes by hand with "Completions" in it, which ReadClasses would never produce for that input.
    Two possible fixes:

    • Have ReadClasses also keep the classes that own a public method, or simply every module-level class. The snapshot gets a bit bigger, but only names are stored.
    • Or keep each class's own Members on its Surface symbol.

    Then add a case to TestReadClasses with a leaf class, so the test goes through the real reader.

Checked and fine

  • Rename on self/cls alone: callerParams drops a leading self/cls before the "> 0" test. A 1:1 pair with a real parameter in common is still a rename (tested).
  • Skipped file: slices.Contains(b.Skipped, before.File) runs before any event. A re-export carries its definition's file, so it's covered too (tested).
  • Method moved to a base: following bases through b.Classes with a seen set is cycle-safe. Any change in the bases downgrades the removal to a note. Merging same-name classes from different modules (openai has two Completions) can only hide a removal, never invent one, so it's on the safe side.
  • No forwarders: plugins/all has the new test that no package only forwards. There are no imports left of migrate, retire/, sdkguide/ or the top-level plugin/ event/ fetch/ kit/.
  • Baseline(…, now) without replay: every caller is updated, and apisurface stores and reads its baseline under Package.ID, the same key it uses for api.

Non-blocking

  • Replay is still mentioned after the API was deleted. Test names and comments in plugins/openapi/{github,gitlab,datadog,vercel,openapi}_test.go, plugins/catalog/catalog_test.go:41 and plugins/changelog/json_test.go:152 still say "the plugin's Replay", and so do about ten provider pages (providers/datadog.md:27, elasticsearch.md:45, neon.md, vercel.md, …). They now describe a method that doesn't exist; "a version pair (ReadAt both, Extract)" would be accurate. openapi_test.go:148 also still talks about --from/--to.
  • core/plugin/plugin.go:69: the comment // valid v2 events, to store should drop "v2" now that there's only one event type.
  • apisurface.Package.ID repeats the registration's provider/source. check() catches a mismatch, so it's safe, but another apisurface source has to write the id twice. Optional: derive it, or add a sentence about it to docs/writing-a-plugin.md.
  • Still open from the last round: one removed class still gives two events (the definition path and the re-export).

@adssib

adssib commented Nov 21, 2026

Copy link
Copy Markdown
Contributor Author

@claude review

Fixes for the last review:

  • Blocker, fixed (f901430 on add the apisurface kind: a Python package's public API between releases (I19.10) #218's branch, merged up): ReadClasses keeps every module-level class, not only the ones named as a base, so a leaf class's own attribute (create = _create, a property made a plain attribute) is found. TestAMethodMovedUpIsNotRemoved now reads both releases through the real reader (pysurface.Read + ReadClasses) with a leaf Completions; TestReadClasses includes the leaf class.
  • Non-blocking, done (d33aac1): no "Replay" left: test names, helpers and messages in plugins/openapi, catalog, changelog say version pair (pairWith, TestGitHubPairRecreates…, TestAPairStoresEventsAndNoBaseline, the --from/--to comment gone); the provider pages say "a version pair, A → B"; plugin.go and kittest no longer say "v2"; the openapi package comment describes listing and pairs.
  • Not acted on: deriving apisurface.Package.ID from the registration (check() already refuses a mismatch), and grouping a removed class's definition and re-export into one event (both import paths do break; left as is).

Local: make check with go1.27.1; contract fixtures vs patch-it main: match.

@claude

claude Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

Claude finished @adssib's task in 27s —— View job


✅ Ready to merge. The last blocker is fixed, and it's tested through the real reader. Only two small wording leftovers remain, and neither blocks.

  • Re-check the ReadClasses / leaf-class fix (f901430)
  • Check the "Replay" wording cleanup (d33aac1)
  • Re-check the AGENTS.md rules
  • Post the verdict

Rules

Rule Status Evidence
Metadata in the registration ✅ Unchanged since the last round. RegisterProvider is the only way in, and check() refuses a Name() that isn't provider/source. No hand-kept list.
Provider page + Why this source ✅ providers/openai-python-sdk.md is unchanged. The edits in d33aac1 to the other pages only change the wording ("a version pair, A → B").
Golden + dated quote, golden edits explained ✅ Neither commit touches a golden. The regeneration in the last round was already explained and checked.
Drop test ✅ TestAnAddedNameIsNoEvent, plus the negative cases in TestAMethodMovedUpIsNotRemoved, which now runs on real-reader input.
Fetch only via env, no fs outside testdata ✅ Nothing new fetches.
Source URL + quote on every event ✅ Unchanged.
Precision over recall ✅ See below.
Nothing private ✅ I found nothing in the two new commits or the comment. Both commits are signed off (18/18 on the branch).
Tests — I can't run them here; CI_go covers build, vet, gofmt, the import and net/http guards, go test -race and make todos.

The blocker, re-checked

  • ReadClasses (plugins/apisurface/pysurface/pysurface.go:111) now keeps every module-level class, so b.Classes[className(cls.Signature)] in notGone (apisurface.go:383) finds a leaf class's own members. create = _create or a property made a plain attribute on Completions becomes a note, not a removed_symbol.
  • TestAMethodMovedUpIsNotRemoved now builds both releases with pysurface.Read + ReadClasses from source text. A leaf Completions gets models = _models, create/list move up to SyncAPIResource/_Base, Files gains a base, and gone really is removed. The expected output still has exactly one removed_symbol (gone), so the test covers both directions: it isn't suppressing everything.
  • TestReadClasses now expects the leaf Completions with its models member.
  • The trade-off is that the snapshot also stores leaf classes, but only their names. Merging same-name classes across modules can still only hide a removal, never invent one, so it stays on the safe side.

Non-blocking

  • One "Replay" is left: plugins/catalog/catalog_test.go:41 still says "This is the pair the plugin's Replay from oldRef to newRef recreates." It could say "the version pair oldRef → newRef that ReadAt + Extract recreate". The other "replay" hits (algolia_test.go:59, convex_test.go:80, adapter/sentry.go:34, adapter/gitlab.go:104, openapi/testdata/README.md, providers/gitlab.md:27) use it as an ordinary verb, not the deleted API, so they're fine to leave. Swapping adapter/gitlab.go:104's "(a branch, for a replay)" to "(a branch, read as a version)" would make the cleanup complete.
  • You chose not to group a removed class's definition and re-export into one event, and not to derive Package.ID from the registration. Both are reasonable: both import paths do break, and check() already guards the id.

Thanks for working through three rounds so carefully. The apisurface precision guards are solid now.

adssib and others added 2 commits November 20, 2026 19:14
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: adssib <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: adssib <[email protected]>
@adssib
adssib merged commit 8cfe96f into main Nov 21, 2026
8 checks passed
@adssib
adssib deleted the pl2-all branch November 21, 2026 00:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant