Repository navigation
one interface per shape: versioned or living, no Run - #225
Merged
Merged
Conversation
A plugin is plugin.Versioned (ListVersions, ReadAt) or plugin.Living (Read), never both, and every change is what Extract finds between two snapshots. notices is the one living kind: Read fetches the page, keeps the snapshot when it hashes the same, and cites a Wayback snapshot otherwise. Run, Env.Baselines, plugin.Spec, plugin.Baseline, kit.Unchanged, Result.Label and the Wayback version helpers are gone. plugin.ErrNothingToRead marks a release or page with no part a reader can use. core/event applies the contract's rules 13 and 14 and drops supersedes; contract/fixtures resynced from patch-it main. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: adssib <[email protected]>
|
Claude finished @adssib's task in 1m 30s —— View job ✅ Ready to merge. The interface split is clean, every kind has exactly one shape and Rules
BugsNone found. Points I checked:
Verified
Non-blocking (optional)
Your four "calls I made" look reasonable to me, especially passing |
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]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Important
Needs a minor release (v0.4.0) after merge. The plugin interface changes (
Run,Env.Baselines,plugin.Specare gone), so the next tag is a minor, run by hand. Agents never release. patch-it's hosted ingestion service switches to it in its own PR, pinned to this branch until the tag exists.What this changes
No source-specific change: the plugin interface, so living pages work like versioned pairs and
Runcan go.1. One interface per shape,
Extractshared (core/plugin)RegisterProviderrefuses a plugin that is both or neither.openapi,changelog,migrationguide,catalog,apisurfaceare versioned;noticesis living.SnapshotgainsCompareHash: the hash of the live page as fetched, which a living page's nextReadcompares with (the content kept is the Wayback snapshot's bytes).notices.Read(ctx, env, last): fetch the page; when it hashes aslastdid, returnlast(one GET, no Wayback call); otherwise read it, apply the shape guard againstlast, cite it withkit.Cite(or the archive fallback when the site answers 401/403), and return a snapshot dated now (Version.ID= RFC 3339).notices.Extract(last, cur)is the noticescurhas thatlastdidn't, citingcur. The runner does:cur := Read(last); ifcur.CompareHash != last.CompareHash→Extract(last, cur), store events, keepcur.lastintoRead(the suggestion wasRead(ctx, env)): without it, every read would need a Wayback snapshot just to be compared, and the shape guard has nothing to compare with.2. Deleted (no shims):
Plugin.Runon all six kinds,Env.Baselines,BaselineReader,plugin.Spec,plugin.Baseline,Result.LabelandResult.Baselines,kit.Unchanged,migrationguide.Guide.Current(+ both readers'),changelog'srunLogandLog.CommitsURL, notices'ListVersions/ReadAt(Web Archive captures as versions),versions.WaybackCapturesandversions.WaybackAt(no caller left), theVersionLister/Reader/Extractorsub-interfaces; in the test kitkittest.Ingest,IngestWith,Run,Sink.SaveSpec/LastSpecand Mem's baselines; two unused fixtures (commits-c0f99ca9.json,commits-day.json).3. Test kit, both shapes (
core/kit/kittest):Versions(t, env, p, from, to)(ReadAt both, Extract),Extracted(t, env, p, from, to)(snapshots the test built),Page(t, env, p)(a living page's first read; a second read must return the kept snapshot and store nothing). Each extracts twice and fails on anything new. Non-failing steps for error tests:Pair,Extract,ReadPage.4.
plugin.ErrNothingToRead: a wrap-able sentinel for a release or page with no part a reader can use. Returned (wrapped) by the changelog (no heading for the release), both migration-guide readers (not this major's guide, no section, no table, an empty table), and the notices readers (no table). A table that isn't the expected one stays a plain error. Tests useerrors.Is.5. Contract (patch-it#58):
contract/fixtures/resynced from patch-itmain(change-events-v2-ids.json,change-events-v2-from-to.jsonadded,change-events-invalid.jsondeleted, the rest rewritten to ids).core/event: rule 13 (previous_versionrequired onapi_operation/package_release:event.PairType), rule 14 (apimatches the contract'sprovider/sourcepattern),supersedesgone. Every fixture file is now validated (not only two), and every invalid case is refused.make check PATCH_IT=<patch-it main>passes.6. Docs and scaffolding:
docs/writing-a-plugin.md§4 (both shapes,ErrNothingToRead) and §6 (the kit),docs/which-kind.md(which kinds are which shape),docs/how-it-works.md,AGENTS.mdlayout;cmd/new-plugintemplates usekittest.Versions/Extracted/Page(the scaffold test builds, vets and tests a source of every kind and reader).Golden proof
Every golden compared before/after with a script (
api, fingerprint and every other field included):core/normalizefiles, all 11openapi,notices/{openai,anthropic}-models,github-actions,google-vertex-ai-models(27 of 37)idchangedapisurface/openai-1.1.2(0→1,2): its test returnedExtract's events directly; it now goes throughkittest.Versionsand the store like every other golden, so ingest's conformance test can replay it byte for byteprevious_versionadded, nothing else differschangelog/textual-0.86.0(0.85.2),urllib3-2.0.0(1.26.15),mongodb-atlas(2026-11-09);migrationguide/anthropic-1.0.0(0.75.0),numpy-2.0.0(1.26.4),newrelic-11.0.0(10.17.0),posthog-8.0.0(7.91.4);notices/cloudflare-api,salesforce(2026-11-14T12:00:00Z)Why the 9 gain
previous_version: they areapi_operation/package_releaseevents, which rule 13 now refuses withoutprevious_version. They used to come fromRunextracting the pinned release against nothing; now each is a real pair from the release before (from PyPI, or the commit before inmongodb/openapi). Fingerprints don't hashprevious_version, so every fingerprint is unchanged.Checklist
testdata/README.md: the two deleted fixtures' row removedproviders/*.md:cloudflare.md,salesforce.md(whatprevious_versionis for a notice),convex.md,supabase.md(no "daily ingest")env.Get/core/kit/make check PATCH_IT=<patch-it main>passes (go1.27.1, incl. its gofmt;go test -race)Calls I made (please check)
previous_versionon datedapi_operationnotices (Cloudflare, Salesforce). The merged contract requires it on everyapi_operation, but these are dated notices read from a page with no releases. I set it to the dated read the page was compared with (the read before; on a first read, the read itself), so the events are valid and nothing is dropped. The client's gate treats both as dated APIs and doesn't read the field. If you'd rather the contract said "a change found by comparing two versions" instead of listing types, that's a patch-it change; the code here would follow it.kittest.Extracted): thoseExtracts read only the newer release's own section. The MongoDB JSON changelog's golden names the real commit before (f49749a6, 2026-11-09) without reading it, so every change in the saved file is extracted; for that, itsExtractsubtracts the older side's findings only when it has content.ListVersionsover captures): a kind is exactly one shape. A living page's past is no longer backfilled from captures; it starts at its first read.versions.WaybackCaptures/WaybackAtare deleted with it (I19.9 can bring a Wayback-at-date helper back with a caller).ErrNothingToReadon the notices readers too ("page has no table"): for a living page the runner still treats any error as a failure; the sentinel says why.Related PRs
Read/Extract,errors.Is(err, plugin.ErrNothingToRead), every golden replayed through Postgres; pinned to this PR's head until v0.4.0)Part of #179.
🤖 Generated with Claude Code