[POC] feat/script-api-docs-autocomplete - #9462

Document the JSDoc rules the script API reference and editor
autocomplete are generated from, and fix the Bru constructor's
options being tagged @Property instead of @PARAM.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Give every member scripts can reach a summary, typed tags, a category
and examples, and hide host-facing state behind @internal/@Protected.
Members assigned outside the class body (runRequest, test result
getters, grpc) are declared in the constructor so they can carry docs.

types/globals.d.ts declares the script globals and the contexts each
is available in. List classes now name their item shapes, and
read-only views (response headers, gRPC response metadata) are
modelled as typedefs without the write methods.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

scripts/generate-script-api.js walks the script API from
packages/bruno-js/types/globals.d.ts with the TypeScript compiler API
and writes two committed outputs from the same walk:

- packages/bruno-js/types/script-api.d.ts: one flattened interface per
  public type, the input of the API reference
- bruno-app/.../generated/script-api-manifest.json: one entry per
  member path, with signature, docs, contexts and runtimes

tsc's own JS declaration emit is not used: it drops subclass overrides
whose type matches the base, leaks private methods and keeps internal
base classes in the hierarchy.

The run fails on undocumented or uncategorized members, unresolved
JSDoc types, generic or duplicate public types and types from outside
bruno-js, and checks the emitted .d.ts compiles on its own. CI runs it
with --check so stale outputs fail the lint job.

Root TypeScript moves to 5.x, and @types/chai is pinned to chai 4's
major for the expect/assert globals.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

npm run docs:script-api renders packages/bruno-js/types/script-api.d.ts
into docs-dist/script-api/. Navigation is grouped by global (bru, req,
res, tests & assertions, bru.grpc): each global names a @category and
the generator files every type it reaches under it, and members are
grouped by their own @category.

A small TypeDoc plugin registers the custom @context and @runtime tags
and renders them as sentences ("Available in pre-request scripts",
"Developer Mode only: not available in Safe Mode").

CI builds the site on PRs with warnings as errors, so broken docs fail
early. Hosting is out of scope; only the build output is produced.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Run a probe script in every context (pre-request, post-response, tests
and the four gRPC hooks) under node-vm and QuickJS, and compare what it
can reach with the generated manifest:

- every member documented for the context is present
- Safe Mode exposes exactly the members without @runtime nodevm
- nothing reachable is undocumented, apart from the listed internal
  state and the write methods of read-only lists, which throw

The QuickJS shim's bru.visualize and bru.getSecretVar are listed as
known exceptions: Bru implements neither, so calling them throws.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Script editor hints now come from the generated script API manifest
instead of hand-written lists (STATIC_API_HINTS, grpcAutocompleteHints).
An editor's showHintsFor groups select its script contexts, so each
editor only offers what its scripts can call (req.onFail in pre-request,
bru.getAssertionResults in tests, per-hook bru.grpc members).

- API hint rows show the member's summary
- the highlighted hint's signature, docs, example and Safe Mode note
  show in a panel beside the list
- hovering a documented member in a script editor shows the same docs
  (brunoApiInfo CodeMirror option)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

The TypeDoc site now follows Bruno's Mintlify docs: the orange primary
and warm gray scale, Inter, a blurred top bar with the Bruno logo, search
and links to the docs, GitHub and Discord, a sidebar with group headers
and a highlighted current page, and an "On this page" rail.

Signatures and examples render as rounded code cards with GitHub
highlighting, parameters and returns as field lists, and @context,
@runtime and @deprecated as callouts. The overview lists each global's
types as cards. Light and dark follow TypeDoc's theme switch.

The theme is plain CSS over TypeDoc's default theme (customCss), so it
needs no plugin and survives TypeDoc upgrades that keep its markup.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

TypeScript keeps the `- ` of `@property {T} name - text` in the
property's comment, and the generator copied it through. The API
reference rendered those 80 descriptions as one-item bullet lists, and
editor hovers and hint summaries started with "- ". The @PARAM and
@returns text was already stripped the same way.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…ailing

A member or global without a JSDoc summary no longer stops
generate-script-api: it is left out of script-api.d.ts and the editor
manifest, and the run lists what it skipped in a warning. A global also
needs @context to be included, as nothing else says which scripts have
it.

A missing @category is no longer an error either: the member stays in,
in its type's default section on the site and under its global in the
manifest. A type without a summary is kept, as the members that use it
need its declaration.

Misspelled @context or @runtime values, documented `_` members not
marked @internal or @Protected, unresolved types and types from outside
bruno-js still fail the run.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…ing it

The editor manifest (bruno-app/src/utils/codemirror/generated/) is no
longer committed. The CI setup step and `npm run setup` generate it
before bruno-app is built, and `generate-script-api --check` now only
compares the committed script-api.d.ts.

bruno-app imports it as `script-api-manifest`, which rsbuild resolves to
the generated file when it exists and to an empty list otherwise. A
build without it still succeeds: script editors then offer no API hints
or docs. Jest maps it to the generated file, as the autocomplete specs
check against the real API.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

The editor manifest is no longer committed, so the parity test no
longer reads it from bruno-app. generate-script-api.js exports
generateScriptApi(), which runs the walk without writing anything, and
the test checks the runtimes against the manifest it returns. The test
now needs no generated file and always checks the current JSDoc.

The script still runs as a CLI when executed directly.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

The reference site is not published yet, so its build output is unused.
Building it belongs in the workflow that publishes it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>