docs(typedoc): add API reference + PR-time JSDoc gate (Sprint C)#18
Merged
Conversation
Track 2 Sprint C — TypeDoc-driven API reference, auto-published on
every push to main. Track 3 (release flow) is now the only remaining
gate before tagging v0.1.
What's added:
- typedoc (devDep) + typedoc.json: entry point src/index.ts, output
docs/api/, includeVersion, navigationLinks to GitHub + npm,
excludePrivate/Internal/Externals, treatWarningsAsErrors: true so
broken {@link} or missing entry points fail CI.
- pnpm docs / pnpm docs:watch scripts in package.json.
- .github/workflows/docs.yml: runs pnpm docs on every push to main,
uploads the dist via actions/upload-pages-artifact, deploys via
actions/deploy-pages (no gh-pages branch). Permissions: pages:write
+ id-token:write. Concurrency group 'pages' so overlapping pushes
don't fight over the deployment.
- .gitignore + eslint.config.mjs ignores for docs/api/** (generated).
- README: new Docs badge (links to https://bitrix24.github.io/b24rabbitmq/)
+ npm downloads badge. Documentation section now leads with the API
reference link.
- README cleanup: three relative directory links under "Runnable
examples" converted to absolute GitHub URLs — fixes display on
npmjs.com (which breaks relative links) and silences TypeDoc's
"relative path is not a file" warnings on the copied README.
Behavioural changes: none in src/. Public exports unchanged.
Gates: lint, typecheck, test (66/66), coverage 100/100/100/100,
build, docs all green. Generated bundle still 17 kB ESM.
PROJECT-BRIEF Sprint C ticked; critical path now lists Track 3 as
the only remaining v0.1 gate. AGENTS.md gains pnpm docs / docs:watch
in the commands table.
… pnpm builtin
Five parallel review angles (docs / senior-dev / QA / security / CTO)
— two Approve clean, three Approve-with-nits, zero blockers. In-scope
nits folded.
Docs:
- typedoc.json `excludeProtected: false` -> `true`. Drops four
subclass-plumbing methods (setupExchanges / setupQueues /
registerExchange / registerQueue) from the public API landing page;
Base.connect stays (public, throws by design).
- typedoc.json `readme: "README.md"` -> `"none"`. README has many
repo-relative anchors (PROJECT-BRIEF.md, docs/ARCHITECTURE.md, etc.)
that would 404 on the Pages site. Auto-generated module index makes
a cleaner API-reference landing.
Senior-dev:
- .github/workflows/docs.yml: pin pnpm/action-setup@v4 to version 10
(matches packageManager in package.json).
- Add `if-no-files-found: error` to actions/upload-pages-artifact so
an empty docs/api/ from a config regression fails fast instead of
deploying a blank site.
- Add `timeout-minutes: 10` to both jobs so a stuck deploy doesn't
block the `pages` concurrency group indefinitely (relevant because
cancel-in-progress: false).
QA:
- .github/workflows/ci.yml: new `docs` job (PR-time TypeDoc dry-run,
build-only, no Pages deploy). Broken {@link} or missing entry
point now fails the PR BEFORE merge instead of flipping the Docs
badge red on `main`.
- AGENTS.md commands table + the pre-PR "gates must pass" line now
list `pnpm docs:build` as a fifth gate.
- CONTRIBUTING.md gains a "One-time GitHub Pages setup" section
under Maintainer notes documenting the Settings -> Pages ->
Source = "GitHub Actions" toggle.
Script-name collision (caught while validating gates locally):
- `pnpm docs` is a pnpm BUILT-IN command that opens the package's
homepage URL. Our `docs` script was being silently shadowed —
`pnpm docs` printed the homepage instead of running TypeDoc, and
produced no error. Renamed the script `docs` -> `docs:build`
(paired with the existing `docs:watch`) so `pnpm docs:build`
unambiguously runs the script. Updated all references:
package.json, docs.yml, ci.yml, AGENTS.md, CONTRIBUTING.md,
CHANGELOG.md.
Gates: lint, typecheck, test (66/66), coverage 100/100/100/100,
build, docs:build all green.
After discussion, dropped the public Pages hosting from Sprint C.
Reasoning: for a 3-class typed library with full JSDoc, IDE hover
(via the .d.mts that ships in dist/) is the primary user surface.
A public Pages site added admin-toggle friction (Settings -> Pages
-> Source = GitHub Actions, requires repo admin) and an external
URL to maintain without proportional value at pre-v0.1. Can land
later as a follow-up PR if a real user asks.
What stays:
- typedoc devDep + typedoc.json
- pnpm docs:build / pnpm docs:watch scripts
- PR-time `docs` job in .github/workflows/ci.yml — runs pnpm
docs:build on every PR with treatWarningsAsErrors: true so
broken {@link}, missing entry points, or other TypeDoc warnings
fail BEFORE merge
- .gitignore + eslint.config.mjs ignores for docs/api/**
- npm downloads badge in README
What's removed:
- .github/workflows/docs.yml (the Pages deploy workflow)
- Docs badge in README (pointed at a URL that wouldn't exist)
- README "API reference" link replaced with a Documentation note
pointing users at IDE hover + the `pnpm docs:build` local-HTML
path
- CONTRIBUTING.md "One-time GitHub Pages setup" section (no
Pages = no setup)
PROJECT-BRIEF Sprint C entries updated to reflect the new shape
(no public hosting, JSDoc-via-IDE-hover is the primary surface)
and to record the reasoning so future agents don't re-derive it.
CHANGELOG Unreleased / Added entry rewritten to match.
Gates: lint, typecheck, test (66/66), coverage 100/100/100/100,
build, docs:build all green. PR-time docs gate validated locally.
IgorShevchik
changed the title
IgorShevchik
pushed a commit
that referenced
this pull request
May 29, 2026
Manual reconciliation between release-please's auto-generated [0.1.0] block (short subject lines from commits, plus 4 stale uuidv7/type-msg leftovers from pre-0.0.4 history) and the hand-written Unreleased block we maintained through PRs #10-#21 (rich per-entry descriptions with behavioural-change callouts). This is the one-shot reconciliation flagged in CONTRIBUTING.md "Release flow -> CHANGELOG reconciliation on the first auto- release" — subsequent releases will land cleanly because the hand-written approach ends with v0.1. Kept from release-please: - [0.1.0] heading with compare link and 2026-05-28 date. Replaced with hand-written content: - Added (3): release-please+OIDC #19/#21, TypeDoc #18, Logger DI #15. - Changed (3): types any->unknown #16, consumer reconnect #14, producer prefetch #13. - Removed (1): RabbitRPC dropped #12. - Bug Fixes (2): ack/nack idempotency #17, base/registerQueue merge #10. Dropped: - 4 stale `fix(uuidv7): improve` entries from pre-0.0.4 history (already covered in [0.0.3] / [0.0.2] sections below). - 1 stale `fix(type/Message): improve` (already in [0.0.4]). - 7 noise `docs: improve` / `docs(en): fix nav` entries from pre-reanimation that release-please surfaced without bootstrap-sha. Also captures PR #16 (chore(types)) + PR #19 / #21 (chore(release)) which release-please hides under the chore: hidden setting. The hand-written entries describe what actually shipped. Gates: lint, typecheck, test (66/66), build, docs:build all green. Note: this commit is pushed to the release-please branch (not main) — it amends release-please PR #20 in-place. The push from a non-GITHUB_TOKEN identity also triggers PR-time CI, which the original release-please-bot push could not because of GitHub's loop-prevention rule.
IgorShevchik
pushed a commit
that referenced
this pull request
May 29, 2026
First trustworthy release of @bitrix24/b24rabbitmq after the full reanimation cycle. All three roadmap tracks closed: - Track 1 (Correctness): every Phase 1 defect fixed test-first with characterisation locks (PRs #10, #12, #13, #14, #15, #16, #17). - Track 2 (Onboarding & positioning): runnable examples, README integrator section, TypeDoc API reference + PR-time JSDoc gate (PRs #5, #18). - Track 3 (Process & infrastructure): release-please-driven release flow, tag-triggered npm publish with OIDC trusted publishing + provenance, ci aggregator job for branch protection (PRs #19, #21, #22). See the reconciled `[0.1.0]` block in CHANGELOG.md for the rich per-PR descriptions and behavioural-change callouts. Merging this PR creates the v0.1.0 git tag + GitHub Release, which triggers .github/workflows/npm-publish.yml to publish @bitrix24/b24rabbitmq@0.1.0 to npm via OIDC trusted publishing with --provenance attestation. Gates: lint, typecheck, unit tests (node 20 + 22), build, docs:build, commit messages, ci aggregator — all green on PR #20.
IgorShevchik
added a commit
that referenced
this pull request
May 29, 2026
…ager wins (#25) The first workflow_dispatch run of npm-publish.yml on v0.1.0 (https://github.com/bitrix24/b24rabbitmq/actions/runs/26621673812) failed at Install pnpm: Error: Multiple versions of pnpm specified: - version 10 in the GitHub Action config with the key "version" - version pnpm@10.10.0 in the package.json with the key "packageManager" Remove one of these versions to avoid version mismatch errors like ERR_PNPM_BAD_PM_VERSION The explicit `version: 10` on pnpm/action-setup@v4 was added in PR #18 on a senior-dev review nit. On the action version current at runtime, two sources of truth is no longer accepted. Drop the workflow version: input. Let pnpm/action-setup@v4 read packageManager: pnpm@10.10.0 from package.json directly. Same pattern already used in ci.yml. Bonus: the same failed run also logs: "Node.js 20 is deprecated. The following actions target Node.js 20 but are being forced to run on Node.js 24: actions/checkout@v4, pnpm/action-setup@v4." That's exactly the intended behaviour of the FORCE_JAVASCRIPT_ACTIONS_TO_NODE24=true flag added in PR #23 — informational, not an error. Post-merge: re-trigger npm-publish.yml via workflow_dispatch on main. Gates: lint, typecheck, test (66/66), build, docs:build, ci aggregator — all 8 green on PR #25. No src/ changes.
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
2 participants
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.
Track 2 Sprint C — TypeDoc API reference generation + PR-time JSDoc gate. No public hosting — TypeScript users get the docs through IDE hover (the JSDoc ships in
dist/esm/index.d.mtsvia unbuild); a public Pages deploy can land later if a real user asks. After this lands, Track 3 (release flow) is the only remaining gate before tagging v0.1.Why no Pages
Original plan was to publish to
https://bitrix24.github.io/b24rabbitmq/viaactions/deploy-pages. Dropped after re-evaluation:.d.mtsdeclarations shipped to npm.GitHub Actions) — friction without proportional value at pre-v0.1.What's in
TypeDoc setup (kept)
typedocdevDep (no plugins, default HTML theme).typedoc.json— entry pointsrc/index.ts, outputdocs/api/,includeVersion,excludePrivate/excludeProtected/excludeInternal/excludeExternals,readme: "none"(clean API-only landing),treatWarningsAsErrors: true+validation.invalidLink/notExported: trueso a broken{@link}or missing entry point fails CI.pnpm docs:build+pnpm docs:watchscripts. Renamed fromdocsto avoid silent shadowing by pnpm's built-indocscommand (which opens the package's homepage URL).PR-time JSDoc gate (kept) — the highest-value piece
docsjob in.github/workflows/ci.yml— runspnpm docs:buildon every PR as a build-only dry-run.{@link}, missing entry point, or any TypeDoc warning fails the PR BEFORE merge. JSDoc rot becomes a CI signal, not silent drift.Lint / build hygiene (kept)
.gitignoreaddsdocs/api(generated output, not version-controlled).eslint.config.mjsaddsignores: ['docs/api/**']so the generated HTML/JS doesn't get linted (which would otherwise produce 144 errors).README polish (kept partial)
pnpm docs:buildHTML path.What was removed (compared to earlier revision of this PR)
.github/workflows/docs.yml— the Pages deploy workflow.Acceptance (from
PROJECT-BRIEF.mdSprint C, revised)docs/api/, with every public class / type generated. Local + PR-time rather than public Pages.Files
typedoc.json.github/workflows/ci.ymldocsjob (PR-time dry-run)package.jsonpnpm docs:build/docs:watchscripts, +typedocdevDeppnpm-lock.yaml.gitignoredocs/apieslint.config.mjsignores: ['docs/api/**']README.mdPROJECT-BRIEF.mdCHANGELOG.mdAGENTS.mdpnpm docs:build/docs:watchin commands table; pre-PR gates updated to 5CONTRIBUTING.mdpnpm docs:buildin commands tableGates
pnpm lintpnpm typecheckpnpm testpnpm test:coveragepnpm buildpnpm docs:buildBehavioural change
None in
src/. Public exports unchanged. Bundle size unchanged.Downstream consumer check
No public API change.
bitrix24/app-template-automation-rulesis unaffected.Reviews
Pre-Pages-drop revision was reviewed by 5 parallel agents (docs / senior-dev / QA / security / CTO) — two Approve clean, three Approve-with-nits, zero blockers. All in-scope nits folded; the Pages drop addresses the remaining "admin-toggle friction" concern raised by CTO.
What's next
Track 3 — release flow: adopt changesets/release-please, tag-triggered
npm publishwith--provenance, branch protection onmain. Then tag v0.1.