JS plugin API: expose comments (leading/trailing trivia) to rules, and allow diagnostics on tokens/ranges

[nemchik]

Problem

Biome JS plugin rules cannot read comments. That rules out a whole class of checks that ESLint handles routinely:

• File-header pragmas / docblocks: @jest-environment, @jsx, @flow, license or copyright headers (eslint-plugin-header), required file docblocks.
• Declaration JSDoc: "exported function has a /** */ block", tag validation (eslint-plugin-jsdoc).

Related earlier requests, both closed without a linked change: #10474 (JSDoc presence in GritQL) and #10928 (listed "no JSDoc / leading-trivia API" among the gaps that force a separate CLI).

What I observed (Biome 2.6.5, also 2.6.4)

@biomejs/runtime has JsAstToken.kind values COMMENT / MULTILINE_COMMENT, but its docs say comments "remain token trivia", and nothing exposes them. RuleContext has only filePath and sourceType. Repro:

// rule.js
import { ast, defineRule, registerDiagnostic } from "@biomejs/runtime/plugin";
export const probe = defineRule({
  query: ast("JS_MODULE"),
  run(node) {
    registerDiagnostic(node, "information",
      `hasTag=${node.text.includes("@NApiVersion")} start=${JSON.stringify(node.text.slice(0, 25))}`);
  },
});

// a.js
/**
 * @NApiVersion 2.0
 */
define([], function () {
  /** doc */
  function f() {}
  return { beforeLoad: f };
});

Output: hasTag=false start="define([], function () {\n". The header comment is not in node.text, and no other API reaches it.

Request

1. Read-only trivia access in the JS plugin API. Preferred shape: JsAstToken.leadingTrivia() / trailingTrivia() returning pieces with kind, text and range. A file header is the leading trivia of the first token and a JSDoc is the leading trivia of a declaration's first token, so one primitive covers both. Acceptable alternatives: context.sourceText, or a per-file context.comments list. I'm happy with whichever fits Biome's design.
2. Also needed, and separable: diagnostics on a token, trivia piece or range. registerDiagnostic(node, ...) only accepts a node, so a rule cannot highlight the offending comment (for example @NApiVersion 2.0) or point at the file start when a required header is missing.

Why a plugin API and not a sibling tool

Every project that needs this today ships a separate script or CLI (see the example in #10474 and the reasoning in #10928). Such tools run in CI and pre-commit but never in the editor, because the Biome LSP only runs rules it knows about. Comment access would let those checks live next to the rest of the lint rules and show up as real-time editor diagnostics.

Real-world example

biome-plugin-suitescript is a set of JS-plugin rules where nearly everything works through the plugin API. The one exception is checking two header tags against what the module returns, which needs both the comment and the AST. It therefore ships a small CLI that parses with oxc-parser only to read comments (findTag, rationale in ADR 0001). The ADR says to retire the CLI once plugins can read comments.

I can't contribute the Rust side, but I'm glad to test a prototype or give feedback on the API shape.

[ematipico]

I was hoping for a comment in #11420 but I suppose that's fine.

Yeah I suppose the diagnostic API, as it is, is a bit limited. Maybe we should create an overload API and let it accept a node, a token or a range

[nemchik]

Sorry for the separate discussion. Feel free to close this and I can re-post in #11420 is that would be easier to track.

TY for the quick response and consideration!