docs/: code-quality issues in the code-example subsystem and server utils

[IgorShevchik]

Found during a multi-angle code review of the docs site (while maintaining the Russian mirror bitrix-tools/b24jssdk, which syncs docs/ from here 1:1). None are crashes today, but several are latent/fragile. Reporting upstream so the mirror can stay byte-identical. Line numbers are approximate (current main).

Medium

1. Server util imports a browser composable — docs/server/utils/transformMDC.ts does import { useB24 } from '../../app/composables/useB24' and calls only prepareCode, but useB24.ts touches sessionStorage / window.name / useNuxtApp / nextTick. It works today only because those code paths aren't hit during SSR/prerender, but any change to useB24 init can break /raw and llms-full.txt generation. Suggestion: extract prepareCode / transformCodeForDocumentationSafe into a browser-free module (e.g. utils/codeTransform.ts).

2. Brace counting ignores strings/comments — useB24.ts transformCodeForDocumentationSafe increments/decrements braceDepth per literal {/} char without accounting for string literals or comments, so e.g. const s = 'a{b}' or // { result } skews the count and can truncate the example early/late. The region:start / endregion:start markers already present could be used instead.

3. fetchCodeExample swallows errors — docs/app/composables/fetchCodeExample.ts: on failure the .catch stores a stub object into state.value[name] and throws; the trailing await state.value[name] (now a non-promise object) silently resolves and returns the stub, so callers can't distinguish success from failure. Suggestion: keep the in-flight promise in a separate variable, set the result/stub only in finally.

Low

4. Always-true condition — docs/server/utils/normalizeComponentName.ts: normalizedName[1] === normalizedName[1]?.toUpperCase() compares a char with itself (always true). The JSDoc says "followed by an uppercase letter"; it should check the char after the B24 prefix (index 3). Note: this file also appears to be unused (no imports).

5. Dead code (no imports anywhere) — docs/app/composables/cachedParseMarkdown.ts, docs/server/utils/extractSections.ts, docs/server/utils/normalizeComponentName.ts. Consider removing or marking @deprecated.

6. Dead branch — docs/server/utils/transformMDC.ts processLinks has a node[0] === 'tip' branch, but callouts (tip, …) are already converted to blockquote earlier in the same function, so the branch never runs.

7. Possible key collision — docs/modules/code-example.ts keys examples by parse(relativePath).name only; scanDirectory is recursive, so two files with the same basename in different subdirs would overwrite each other. Use the relative path as the key.

8. Unnecessary await — docs/app/components/content/CodeExample.vue await useCodeExample() — useCodeExample is synchronous; the await adds a needless Suspense barrier.

9. any types — docs/modules/code-example.ts let _configResolved: any (use ResolvedConfig from vite); fetchCodeExample.ts Record<string, CodeExample | any> collapses to any.

10. Hardcoded dedent — useB24.ts uses .slice(2) to strip exactly 2 spaces of indentation from example lines; brittle if example indentation style changes (4 spaces/tabs). A min-indent dedent would be safer.

Minor

11. Unneeded CORS — docs/server/api/code-examples.get.ts sets Access-Control-Allow-Origin: * on a same-origin, read-only endpoint; can be dropped/narrowed.

Happy to send PRs for any of these if useful.

[IgorShevchik]

Second review pass surfaced a few more (still in docs/ mirrored 1:1 from here, reporting upstream):

Medium/High

• fetchCodeExample.ts returns undefined on the dedup path — state.value[name] = $fetch(...).then((data) => { state.value[name] = data }) stores the promise's resolution (undefined) for a tick, and the trailing return state.value[name] after await can hand back undefined (or the still-pending promise on a concurrent 2nd call). Keep the in-flight Promise in a separate map; store data only in finally; return await promise.
• docs/app/workers/prettier.js has no error handling — processMessage/handleFormatMessage aren't wrapped in try/catch; if prettier.format throws, the worker never posts back, so the handlers[uid] promise leaks and never settles. Wrap and self.postMessage({ uid, error }).
• useB24.ts const b24Config = {} — empty untyped object passed to B24Hook.fromWebhookUrl / $initializeB24Frame; a signature change would fail silently. Type it or drop it.
• transformMDC.ts prepareHref empty-path edge case — href = '#anchor' → split('#') → path === '' → produces …/raw/.md#anchor. Add if (!path) return href.

Low (dead code / types)

• More unused exports/files beyond the earlier list: docs/app/utils/index.ts upperName, useB24.ts HOOK_PLACEHOLDER, docs/app/composables/useDocs.ts (trivial wrapper).
• transformMDC.ts processLinks(nodes: Node[]) uses the global DOM Node type for MDC nodes (should be any[]/local type).
• useNavigation.ts 'restApiVersion' in category branch is always false (field absent on that type) — dead.
• docs/app/workers/prettier.js pins prettier 3.7.4 from CDN while the package.json copy may differ → inconsistent SSR vs client formatting.

(Mirror keeps these byte-identical to upstream, so not patching downstream.)

---

Generated by Claude Code