Skip to content

docs: typecheck every example and drop hand-written version prose - #13

Merged
Upd4ting merged 1 commit into
campaign/integrationfrom
docs/a2-docs-checks
Oct 31, 2026
Merged

Upd4ting merged 1 commit into
campaign/integrationfrom
docs/a2-docs-checks

Conversation

@Upd4ting

@Upd4ting Upd4ting commented Oct 31, 2026 •

Copy link
Copy Markdown
Member

Why

Goal (Antony): the docs rewrite on campaign/integration, every repo's docs check green against the re-pinned docs action (.github tag v1-campaign, docs action tooling-configs v0.2.17, pin 46816ff). This PR switches this repo's ci-node caller to @v1-campaign and fixes every failure that action reports, so the integration branch stays green.

What changed

  • .github/workflows/ci.yml: the ci-node caller @v1 -> @v1-campaign. Other callers stay on @v1.
  • docs/tsconfig.json (existing docs project): added module: esnext and moduleResolution: bundler. The root config is CommonJS, which raised TS1378 on top-level await in the examples. The docs project already maps @antelopejs/interface-subscriptions to src/index.ts, and include is unchanged. The plan names nodenext; esnext/bundler is what the merged mongodb and dms docs projects use.
  • README.md: the quick-start event handler now imports type Subscription and declares grantOrRevokeAccess(subscription: Subscription): Promise<void>, the application policy the prose already says it stands for (the prose now adds that the declare line only gives it a type). The Compatibility paragraph drops "1.16.0" from "@antelopejs/core 1.16.0 is a development test runner, not a runtime peer." (the one version failure). What stays is true: @antelopejs/core is a devDependency only, and peerDependencies holds only interface-core and interface-payment. The generated block carries those ranges.
  • docs/2.subscriptions.md: three loose statements are now complete, checked functions with imports from the public packages: subscribe(accountId, customer, method: PaymentMethod) around CreateSubscription, switchMethod(subscription: Subscription, newMethodId, idempotencyKey) around UpdateSubscriptionPaymentMethod, and cancel(id) around the two CancelSubscription calls. The calls and arguments are unchanged; only the free variables became parameters.
  • docs/3.events.md: the event handler imports type SubscriptionEvent and declares alreadyHandled(eventId: string): Promise<boolean> and applyToAccount(event: SubscriptionEvent): Promise<void> (the page already treats them as the application's). The payment-webhook snippet is wrapped in handlePaymentWebhook(request: WebhookRequest) with imports of VerifyWebhook and WebhookRequest from @antelopejs/interface-payment and SUBSCRIPTION_METADATA_KEY; its body is unchanged. Its return was outside any function.
  • docs/4.implementing.md:68: 1 fence marked fragment (the 7 remaining-names diagnostics). It is the construct() of an implementing module, whose CreateSubscription, GetSubscription, ListSubscriptions, CancelSubscription, UpdateSubscriptionPaymentMethod, register and unregister are the implementer's own functions defined elsewhere. Proof it is a true excerpt: the block unchanged, with those seven names declared with the interface's own parameter and return types, typechecks against docs/tsconfig.json with ImplementInterface(subscriptions, ...) and no error.
  • Fragment markers added: 1. No example deleted. Checked examples go from 9 to 8, which is the one fragment (counts from the Docs: lines of the raw before and of the CI log below).

Proofs

Lever: campaign/tools/docs-measure.sh interface-subscriptions --action 46816ff3bd104560514386e30e73b89478d7989e, copied from its output.

Before (origin/campaign/integration db88bde):

interface-subscriptions campaign/integration@db88bde total=35 ts=34 version=1 fences=7
raw: /home/antony/.cache/campaign2/docs/interface-subscriptions-db88bde.raw

After (committed head bceb643, --dir .): no output, exit 0.

$ docs-measure.sh interface-subscriptions --dir . --action 46816ff3bd104560514386e30e73b89478d7989e
$ echo $?
0

pnpm exec antelopejs-sync --check: Guardrails are in sync.
pnpm run checks on head bceb643: Checks: 9 passed, 0 failed.

Attention

  • Only docs, README, docs tsconfig and the ci-node ref changed. No code, package version, ratchet or suppression change.

CI docs step

Run https://github.com/AntelopeJS/interface-subscriptions/actions/runs/41170399547 on head bceb643, step "Check documentation" (copied from the log):

Docs: 6 files, 17 local links, 1 compatibility tables, 8 checked examples, 0 API pages; 0 failures.
Run AntelopeJS/tooling-configs/actions/docs@46816ff3bd104560514386e30e73b89478d7989e

@Upd4ting
Upd4ting marked this pull request as ready for review October 31, 2026 04:55
@Upd4ting

Copy link
Copy Markdown
Member Author

interface-subscriptions#13 head bceb643: PASS+NOTES

Head verified: bceb643b5f5113496d71d6784577a0f93bd6a5fa (base campaign/integration db88bde, merge-base equal). Verifier verify-docs-c, own clone /home/antony/.cache/campaign/h8/verify/interface-subscriptions-13. I did not write this PR.

Checks

Check Result
Files changed .github/workflows/ci.yml README.md docs/2.subscriptions.md docs/3.events.md docs/4.implementing.md docs/tsconfig.json. No package, lockfile, src, ratchet or suppressions file.
Caller ref ci.yml ci-node @v1 -> @v1-campaign. Every other reusable workflow stays @v1. Tag v1-campaign = .github 98c0f46, whose ci-node.yml:110 pins actions/docs@46816ff3bd104560514386e30e73b89478d7989e # v0.2.17. docs-guard.sh exit 0.
Docs check in CI on this head Run 41170399547: headSha=bceb643b5f5113496d71d6784577a0f93bd6a5fa conclusion=success event=pull_request created=2026-10-31T04:53:52Z. Log: ci-node.yml@refs/tags/v1-campaign (98c0f46b694adf0413ce11d42df70ba9d255f23f), actions/docs@46816ff3bd104560514386e30e73b89478d7989e, Docs: 6 files, 17 local links, 1 compatibility tables, 8 checked examples, 0 API pages; 0 failures. CI pnpm run checks (which includes sync:check) green.
Lever before (rerun by me, --action 46816ff) interface-subscriptions db88bdec99225ed4449c0d1727cf9d661d1aba78@db88bde total=35 ts=34 version=1 fences=7 exit 1 Docs: 6 files, 17 local links, 1 compatibility tables, 9 checked examples, 0 API pages; 35 failures.
Lever after (rerun by me, pin resolved from the caller ref) exit 0 Docs: 6 files, 17 local links, 1 compatibility tables, 8 checked examples, 0 API pages; 0 failures.
No example dropped Fence lines in *.md (base head): 32 32. Fragment markers at head: docs/4.implementing.md:64.
Sync My pnpm exec antelopejs-sync --check on the head: "Guardrails are in sync."
Docs tsconfig The existing docs/tsconfig.json gains module: esnext and moduleResolution: bundler. Nothing else changes.
Deleted version prose "@antelopejs/core 1.16.0 is a development test runner" lost its version. devDependencies has @antelopejs/core 1.16.0, and the block carries both peer ranges. The kept sentence "Development uses the same payment-interface semver range" is true, since devDependencies and peerDependencies both say >=0.0.2 <1.0.0.
Edited fences Each one makes the same calls with the same arguments inside an exported function, with free variables turned into typed parameters, and imports from @antelopejs/interface-subscriptions and @antelopejs/interface-payment. All are checked by CI. grantOrRevokeAccess, alreadyHandled and applyToAccount get declare lines.
Fragment (1 of 1 read) docs/4.implementing.md:64, construct() of an implementing module, passes the module's own functions to ImplementInterface. The classifier's public-import pass would import the contract's own proxies for those names, which would be wrong code, so this is a true excerpt. Stub check: with each name declared as typeof the matching contract export (and register/unregister as typeof SubscriptionEvents.register/.unregister), the fence typechecks verbatim with 0 errors, and a seeded error is caught.
Examples Checked examples 9 -> 8, which is the one marker. No fence deleted.
Title, commits, attribution Conventional title, one commit, no attribution. Body counts match my rerun.

Blocking

None.

Notes

  • The body places the fragment at docs/4.implementing.md:68. The marker is on line 64. Cosmetic.

Artifacts: /home/antony/.cache/campaign/h8/verify/docs-c-r1/interface-subscriptions-13/ (state.txt, diff, ci.log, base.raw), levers in /home/antony/.cache/campaign/h8/verify/docs-c-r1/bin/ (collect.sh, fences.mjs, exports.mjs, classify.py, fragcheck.mjs, sample.py, sample-small.py, verdict.sh), outputs in /home/antony/.cache/campaign/h8/verify/docs-c-r1/frag/.

@Upd4ting
Upd4ting merged commit 9eebc70 into campaign/integration Oct 31, 2026
6 checks passed
@Upd4ting
Upd4ting deleted the docs/a2-docs-checks branch October 31, 2026 05:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant