Skip to content

@W-22653715 adding docs browser in vs extension#487

Open
charithaT07 wants to merge 8 commits into
developfrom
W-22653715-Docs-browser
Open

@W-22653715 adding docs browser in vs extension#487
charithaT07 wants to merge 8 commits into
developfrom
W-22653715-Docs-browser

Conversation

@charithaT07

@charithaT07 charithaT07 commented Jun 9, 2026

Copy link
Copy Markdown
Collaborator

Summary

Brief description of what this PR does.

What this PR does

Adds a new Docs Browser to the B2C DX VS Code extension. It's an
offline-first, in-editor reference for the SFCC Script API (dw.*) — every
class, interface, enum, method, property, and constant on the Script API
surface, available without leaving your editor.

Right-click any dw.* symbol in a JavaScript or TypeScript cartridge file
View B2C Docs → reader panel opens beside your code with the
signature, parameters, return type, throws, examples, and full description.
Class pages list all members inline so you can navigate without going back
to the sidebar.

Why

B2C developers lose 15–30 minutes a day context-switching between VS Code
and the official documentation site to look up Script API methods. The Docs
Browser eliminates that switch and removes the network dependency: 7,366
entries ship inside the VSIX and work fully offline.

This is also a Prophet-parity feature — Prophet's Script API browser is one
of the most-used parts of that extension, and we needed a first-party
equivalent.

Where the data comes from

JSDoc comments inside @salesforce/b2c-script-types .d.ts files vendored
into this repo at version 26.7.0. The same data already powers the
extension's IntelliSense — the Docs Browser is its rich reader complement.

Features

  • Sidebar tree under B2C-DX → Docs. Browse all dw.* packages and classes.
  • Reader panel beside the editor. Reused across opens, theme-aware.
  • Class pages show inline tables of constants, properties, and methods
    with full signatures. Every row is clickable.
  • Search — sidebar quick-pick or panel search box. Treats dot/slash forms
    as equivalent (dw.order.BasketMgr and dw/order/BasketMgr match the same entry).
  • Right-click → View B2C Docs in .js/.ts cartridge files. Resolves
    via Go-to-Definition for accuracy (no scraping).
  • Keyboard shortcuts:
    • Alt+D → search docs
    • Alt+Shift+D → view docs at cursor (cartridge files only)
  • Recently viewed — last 10 entries persist across restart.
  • Friendly "no match" toast with a one-click "Search Docs" recovery button.
  • Feature flag b2c-dx.features.docsBrowser to disable everything.

Architecture

  • Build pipeline (scripts/build-docs-index/) parses .d.ts files with
    ts-morph into a normalized DocEntry[] schema. Output is byte-deterministic
    and gated by CI to prevent stale committed JSON.
  • Runtime (src/docs-browser/) lazy-loads three tiers:
    1. Manifest on first call.
    2. Lightweight search dictionary on first sidebar/panel open.
    3. Full source file only when an entry is actually opened.
      Class member tables read straight from the search dictionary, so opening a
      class page never blocks the UI thread on the multi-megabyte full source.
  • Webview uses strict CSP with per-load nonces, no unsafe-eval, and
    HTML built entirely host-side from a tiny allowlist Markdown renderer.

Test plan

  • pnpm --filter b2c-vs-extension run typecheck:agent — clean
  • pnpm --filter b2c-vs-extension run lint:agent — clean
  • pnpm --filter b2c-vs-extension run test — 264 unit + 4 integration
    tests passing, 0 failing
  • pnpm --filter b2c-vs-extension run build:docs-index deterministic
    across rebuilds (CI gate fails on drift)

What changed

  • New module src/docs-browser/ (loader, search, tree, webview, recents,
    symbol resolver, entry renderer, Markdown renderer).
  • Build pipeline scripts/build-docs-index/ plus generated index in
    resources/docs/.
  • Two new keybindings (Alt+D, Alt+Shift+D) and four new commands.
  • New CI step verifies the committed docs index is up to date.
  • New Vitepress page docs/vscode-extension/docs-browser.md.
  • New devDependency ts-morph (build-time only, not bundled).

Testing

How was this tested?

Dependencies

  • No net-new third-party dependencies were added
  • If net-new third-party dependencies were added, rationale/discussion is included and 3pl-approved is set by a maintainer

  • Tests pass (pnpm test)
  • Code is formatted (pnpm run format)

@github-actions github-actions Bot added the needs-3pl-review PR introduces net-new third-party dependencies and needs discussion label Jun 9, 2026
@charithaT07 charithaT07 marked this pull request as ready for review June 10, 2026 16:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

needs-3pl-review PR introduces net-new third-party dependencies and needs discussion

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant