ci(docs): type-check TS code blocks in docs/content/docs#87
Merged
Conversation
Add scripts/docs-typecheck.mjs — extracts ```ts / ```typescript fenced blocks from all docs/**/*.md files, writes each to a temp .ts file in .docs-typecheck/tmp/, and runs tsc --noEmit against them. Errors are mapped back to the original MD file:line:col and emitted as GitHub Actions annotations in CI. New files: - scripts/docs-typecheck.mjs — main extractor + tsc runner - .docs-typecheck/globals.d.ts — ambient declarations: $b24 (B24Frame), $logger, initializeB24Frame, hookUrl, ImportMeta.dev/.env - .docs-typecheck/tsconfig.json — relaxed settings (noImplicitAny=false, skipLibCheck=true, moduleResolution=bundler, moduleDetection=force) Wired into root typecheck script (package.json) and .github/workflows/ci.yml so the check runs in the ci job after dev:prepare. Doc fixes to reach 0 errors (77 blocks checked): - Replace non-existent B24OAuth.fromConfig() static method with correct constructor call in 5 installation docs + 0.index.md (real API bug) - Fix Logger.error() missing required context argument (66.logger.md) - Add missing imports (SdkError, SelectedUser, Processor, Logger, etc.) - Change interface/type-only blocks from ```ts to ```ts-type in 0.index.md and 77.limiters.md - Add // @check-ignore to illustrative blocks with top-level return, undeclared batch variables, or AbstractHandler (not re-exported) - Apply !!() cast for devMode from import.meta.env (string|boolean|undefined) - Fix logger.log() → console.log() for undeclared $logger in placement example https://claude.ai/code/session_01HRoQoDveLCnCQpUUFJp9Vz
Captures repo layout, dev workflow, scripts reference, and docs CI gates (frontmatter, links, TS block type-checker). https://claude.ai/code/session_01HRoQoDveLCnCQpUUFJp9Vz
…agent audit
Following a multi-perspective review (docs, dev, QA, security, CTO):
scripts/__tests__/docs-typecheck.test.mjs (new):
- 13 unit tests for extractTsBlocks: basic extraction, ```ts-type skipping,
@check-ignore with/without reason, empty-line tolerance, non-nearest-line
non-skip, line-number mapping formula, unclosed fence, empty block, CRLF
- escapeAnnotation unit test: verifies % / \r / \n encoding
- 3 integration tests: real docs tree exits 0, block count in output, no
false ::error annotations in GITHUB_ACTIONS=true mode
(27 total — mirrors the pattern of docs-lint.test.mjs)
scripts/docs-typecheck.mjs:
- Security (MEDIUM): escape % \r \n in GitHub Actions ::error annotations
to prevent workflow command injection via tsc error messages
- CRLF: normalise \r\n before split so Windows-committed MD files map
line numbers correctly
- Multiline tsc messages: collect indented continuation lines so the full
diagnostic text is reported (not just the first line)
- @check-ignore: startsWith('// @check-ignore') so "// @check-ignore: reason"
is also recognised as an opt-out marker
.docs-typecheck/globals.d.ts:
- Keep `declare let $b24` (not const): `declare const` would TS2588 all frame
snippets that do `$b24 = await initializeB24Frame()`. Updated comment explains why.
scripts/docs-lint.mjs:
- Add @check-ignore marker counter with a warning threshold (50) to prevent
silent accumulation of opt-outs over time
docs (38 files):
- Add reason to every // @check-ignore marker (convention: "// @check-ignore: reason")
so future readers understand why each block is skipped
CLAUDE.md:
- List all ambient globals (hookUrl, initializeB24Frame were missing)
- Document "// @check-ignore: reason" convention and globals.d.ts drift warning
https://claude.ai/code/session_01HRoQoDveLCnCQpUUFJp9Vz
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.
Summary
Closes #50. Part of milestone v1.1.3-docs.
Adds a CI step that type-checks every
```ts/```typescriptfenced block indocs/content/docs/**/*.mdagainst the real@bitrix24/b24jssdkpackage types.scripts/docs-typecheck.mjs— walks the docs tree, extracts TS blocks, writes each to a temp.tsfile, runstsc --noEmit, and maps error locations back to the originalMD file:line:col. Emits::errorannotations in GitHub Actions CI..docs-typecheck/globals.d.ts— ambient declarations for$b24(B24Frame),$logger,initializeB24Frame,hookUrl, andImportMeta.dev/.envso short snippets compile without importing everything..docs-typecheck/tsconfig.json— relaxed settings (noImplicitAny=false,skipLibCheck=true,moduleResolution=bundler,moduleDetection=force).package.json—docs:typecheck-blocksscript + appended totypecheck..github/workflows/ci.yml—pnpm run docs:typecheck-blocksadded to thecijob afterdev:prepare.Markers
```ts-typefences (type-signature fragments) — always skipped.// @check-ignoreon the line immediately before a fence — skips that block.Doc fixes (77 blocks → 0 errors)
B24OAuth.fromConfig()does not exist — replaced withnew B24OAuth(authOptions, oAuthSecret)constructor in 5 installation docs +0.index.mdLogger.error()context argument is not optional — added{}where omitted (66.logger.md)SdkError,SelectedUser,Processor,Logger,ConsoleHandler,LogLevel,MemoryHandler,B24Hookwhere blocks relied on ambient globals```tsto```ts-typein0.index.mdand77.limiters.mdreturn// @check-ignoreto illustrative error-handling blocks that usereturnat module scopedevModetype!!()cast —import.meta.env?.DEVisstring|boolean|undefined, notbooleanAbstractHandler// @check-ignoreto the custom-handler exampleloggerlogger.log()→console.log()in31.frame-placement.md(logger was never declared)Test plan
node scripts/docs-typecheck.mjs→77 block(s) checked, 0 error(s)file:line:coloutputpnpm run typecheckpasses end-to-end (includes docs:typecheck-blocks)pnpm run lintclean (ESLint auto-fixed during dev; verified before commit)pnpm run docs:lint-pages --strict→ 0 errorspnpm run docs:lint-links→ 0 broken linkspnpm run docs:lint:test→ 11 pass, 0 failhttps://claude.ai/code/session_01HRoQoDveLCnCQpUUFJp9Vz
Generated by Claude Code