test(conformance): guard against Bot API method drift

Add a conformance test that parses the published Bot API surface via the
internal/botdoc extractor and asserts every method is implemented on
*Bot, covered by other means (getMe -> Self), or explicitly categorized
as deferred or not-applicable (getUpdates/webhooks, logOut/close). Fails
on any uncategorized method (drift when Telegram ships a new one) and on
stale allowlist entries that are no longer published.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: ernado

conformance_test.go

@@ -0,0 +1,135 @@
+package botapi
+
+import (
+	"os"
+	"path/filepath"
+	"reflect"
+	"testing"
+
+	"github.com/PuerkitoBio/goquery"
+
+	"github.com/gotd/botapi/internal/botdoc"
+)
+
+// coveredByOtherMeans lists published methods the library satisfies through a
+// different API shape than a same-named method, mapped to where.
+var coveredByOtherMeans = map[string]string{
+	"getMe": "Bot.Self()",
+}
+
+// deferredMethods lists published methods that are planned but not yet
+// implemented. Each is an acknowledged gap tracked in docs/roadmap.md; the
+// conformance test allows them so it can still catch *unacknowledged* drift.
+var deferredMethods = map[string]string{
+	"editMessageMedia":                "Phase 3 deferred",
+	"answerPreCheckoutQuery":          "payments — deferred until payment updates land",
+	"answerShippingQuery":             "payments — deferred until payment updates land",
+	"sendInvoice":                     "payments — deferred",
+	"setPassportDataErrors":           "Telegram Passport — deferred",
+	"sendGame":                        "games — deferred",
+	"setGameScore":                    "games — deferred",
+	"getGameHighScores":               "games — deferred",
+	"getStickerSet":                   "stickers — deferred (needs Sticker[] conversion)",
+	"setStickerSetThumb":              "stickers — deferred",
+	"getChat":                         "chat info — deferred",
+	"getUserProfilePhotos":            "deferred",
+	"setChatStickerSet":               "chat sticker set — deferred",
+	"deleteChatStickerSet":            "chat sticker set — deferred",
+	"setChatAdministratorCustomTitle": "member management — deferred",
+	"stopPoll":                        "deferred",
+}
+
+// notApplicableMethods lists published methods that do not apply to the
+// MTProto-native model and are intentionally not implemented.
+var notApplicableMethods = map[string]string{
+	"getUpdates":     "MTProto-native: updates arrive on the persistent connection (Decision #2)",
+	"setWebhook":     "no webhook surface (Decision #2)",
+	"deleteWebhook":  "no webhook surface (Decision #2)",
+	"getWebhookInfo": "no webhook surface (Decision #2)",
+	"logOut":         "HTTP Bot API server lifecycle method; not applicable over MTProto",
+	"close":          "HTTP Bot API server lifecycle method; not applicable over MTProto",
+}
+
+// TestMethodConformance asserts that every method published in the Bot API docs
+// is either implemented on *Bot, covered by other means, or explicitly
+// acknowledged as deferred / not-applicable. It is a drift guard: when Telegram
+// ships a new method, this test fails until the method is implemented or
+// categorized. It also fails if an allowlist entry stops being a published
+// method (so the lists cannot rot).
+func TestMethodConformance(t *testing.T) {
+	api := loadAPI(t)
+
+	implemented := botMethodSet()
+	published := map[string]struct{}{}
+
+	var uncategorized []string
+	for _, def := range api.Methods {
+		name := def.Name
+		published[name] = struct{}{}
+
+		switch {
+		case implemented[goName(name)]:
+		case coveredByOtherMeans[name] != "":
+		case deferredMethods[name] != "":
+		case notApplicableMethods[name] != "":
+		default:
+			uncategorized = append(uncategorized, name)
+		}
+	}
+
+	if len(uncategorized) > 0 {
+		t.Errorf("API drift: %d published method(s) are neither implemented nor categorized: %v\n"+
+			"Implement them, or add to deferredMethods/notApplicableMethods in conformance_test.go.",
+			len(uncategorized), uncategorized)
+	}
+
+	// Guard against stale allowlists: every acknowledged name must still be a
+	// published method.
+	for _, lists := range []map[string]string{coveredByOtherMeans, deferredMethods, notApplicableMethods} {
+		for name := range lists {
+			if _, ok := published[name]; !ok {
+				t.Errorf("stale allowlist entry %q is no longer a published method; remove it", name)
+			}
+		}
+	}
+}
+
+// loadAPI extracts the Bot API surface from the committed documentation
+// snapshot.
+func loadAPI(t *testing.T) botdoc.API {
+	t.Helper()
+	path := filepath.Join("internal", "botdoc", "_testdata", "api.html")
+	f, err := os.Open(path)
+	if err != nil {
+		t.Fatalf("open api docs: %v", err)
+	}
+	defer func() { _ = f.Close() }()
+	doc, err := goquery.NewDocumentFromReader(f)
+	if err != nil {
+		t.Fatalf("parse api docs: %v", err)
+	}
+	return botdoc.Extract(doc)
+}
+
+// botMethodSet returns the set of exported method names on *Bot.
+func botMethodSet() map[string]bool {
+	t := reflect.TypeFor[*Bot]()
+	set := make(map[string]bool, t.NumMethod())
+	for i := 0; i < t.NumMethod(); i++ {
+		set[t.Method(i).Name] = true
+	}
+	return set
+}
+
+// goName maps a Bot API method name (lowerCamelCase) to the Go method name that
+// would implement it (UpperCamelCase): only the first letter changes.
+func goName(apiName string) string {
+	if apiName == "" {
+		return ""
+	}
+	b := []byte(apiName)
+	if b[0] >= 'a' && b[0] <= 'z' {
+		b[0] -= 'a' - 'A'
+	}
+	return string(b)
+}

docs/roadmap.md

@@ -175,7 +175,10 @@ Deferred within Phase 5: payment answers
   `examples/media` (send by URL, echo incoming media by file_id, `GetFile`).
 - ☑ Allocation tests on hot paths (`bench_test.go`): entity/markup/user
   conversion and `file_unique_id`, with `-benchmem`.
-- ☐ Conformance test against kept `botdoc` extractor (API-version drift guard)
+- ☑ Conformance test against the `botdoc` extractor (`conformance_test.go`):
+  every published method must be implemented on `*Bot`, covered by other means,
+  or categorized as deferred/not-applicable — failing on uncategorized (drift)
+  methods or stale allowlist entries.
 - ◐ Docs: package docs (`doc.go`) and README done; reference/migration guide
   still to write.