jsDocProcessor check examples buggy with typescript-eslint

[tunnckoCore]

The projectService option in typescript eslint is weird enough but..

@example error: Fatal: Parsing error: /home/charlike/code/mid-april-2025/workspaces-filter/src/foo.ts/1_/home/charlike/code/mid-april-2025/workspaces-filter/src/foo.md/*.js was not found by the project service. Consider either including it in the tsconfig.json or including it in allowDefaultProject.eslint

Whatever i try to include these dummy md/js/example files it fails.

Any hints on integrating eslint-plugin-jsdoc with typescript?

I have a root tsconfig in which i have include that includes both ts and js files. I tried with projectService: true, i tried with { projectService: { allowDefaultProject: ["*.js"] } }, i tried adding *md/*.js ..

It's most likely because of how you build the dummy filename which in turn cannot be detected properly by typescript-eslint (or eslint, or settings or whatever) for some reason. Maaybe just make a random name or hash of the source of the example.

[brettz9]

This has not been tested with typescript-eslint. I had forgotten that we have one test for it.

Fenced blocks of TypeScript also are not currently supported.

In any case, the dummy files are simply ESLint's way of providing a way for the config files to target languages-within-a-language (like we do with JavaScript within JavaScript (@example tag) comment blocks) and should not be included. Hopefully, any solution we may provide in the future can avoid triggering errors as you have seen.

[lishaduck]

Not ideal, because this disables type-checked rules, but I worked around this by adding the following to my config:

{
  name: "jsdoc/examples/rules",
  files: ["**/*.md/*.js"],

  languageOptions: {
    parserOptions: {
      projectService: false,
    },
  },

  rules: {
    // "always" newline rule at end unlikely in sample code
    "eol-last": 0,
    // Wouldn't generally expect example paths to resolve relative to JS file
    "import/no-unresolved": 0,
    // Snippets likely too short to always include import/export info
    "import/unambiguous": 0,
    "jsdoc/require-file-overview": 0,
    // The end of a multiline comment would end the comment the example is in.
    "jsdoc/require-jsdoc": 0,
    // Unlikely to have inadvertent debugging within examples
    "no-console": 0,
    // Often wish to start `@example` code after newline; also may use
    //   empty lines for spacing
    "no-multiple-empty-lines": 0,
    // Many variables in examples will be `undefined`
    "no-undef": 0,
    // Common to define variables for clarity without always using them
    "no-unused-vars": 0,
    // See import/no-unresolved
    "node/no-missing-import": 0,
    "node/no-missing-require": 0,

    // Can generally look nicer to pad a little even if code imposes more stringency
    "padded-blocks": 0,

    ...ts.configs.disableTypeChecked.rules,
  },
},

[lishaduck]

Fenced blocks of TypeScript also are not currently supported.

This is a blocker for me though, I'm going to have to turn off the processor for now.
All of my examples are in fenced code blocks, which gets parsed as template literals 😂

[brettz9]

Fenced blocks of TypeScript also are not currently supported.

This is a blocker for me though, I'm going to have to turn off the processor for now. All of my examples are in fenced code blocks, which gets parsed as template literals 😂

The exampleCodeRegex and rejectExampleCodeRegex options should help identify code between fenced code blocks, but won't currently detect that TypeScript is desired and that the @typescript-eslint parser should be included, for example.

[brettz9]

Now that I've had a chance to take a closer look...

I apologize that I had been mistaken in stating we had not tested with @typescript-eslint. Per one of our tests, it does work to process TypeScript within @example tags (in a JavaScript file).

And I see it works with the following eslint.config.js (thus finding TS examples within a JS file; to find within a TS file, supply getJsdocProcessorPlugin({parser: typescriptEslintParser})):

/**
 * @example
 * const list: number[] = [
 *   1,
 *   2,
 *   3,
 * ];
 * quux(list);;;
 */

export default [
  {
    files: [
      '**/*.md/*.js',
    ],
    languageOptions: {
      parser: typescriptEslintParser,
    },
    rules: {
      'no-extra-semi': [
        'error',
      ],
    },
  },
  {
    files: [
      'eslint.config.js',
    ],
    plugins: {
      examples: getJsdocProcessorPlugin(),
    },
    processor: 'examples/examples',
  },
];

However, indeed, the type-checked rules are indeed problematic, as you discovered. It seems TS expects the files to be on the filesystem, which ESLint does not do here since it is creating them as strings. It seems this is at least confirmed by Google AI (in a related question).

So to allow type-aware rules, I believe we'll either need TS, typescript-eslint, or eslint to change.

It appears I was thankfully also mistaken about fenced code blocks because we can just define it ourselves as follows:

{
    files: [
      '**/*.js',
    ],
    plugins: {
      examples: getJsdocProcessorPlugin({
        exampleCodeRegex: '^```(?:ts|js|typescript|javascript)([\\s\\S]*)```\s*$'
      }),
    },
    processor: 'examples/examples',
  },

This only evaluates code between the fenced block start and end markers.

So, in short, you can get TS-checking, but just not with type-aware rules.

[brettz9]

Btw, I've submitted #1392 to add a new option to make it more convenient to have ignored fenced blocks. Previously one would need to specify which blocks were allowed or ignored.

Now, by default, languages which are not "js", "javascript", "ts", or "typescript" will be ignored by the processor. If you do want such blocks to be checked (e.g., to avoid language name errors), submit allowedLanguagesToProcess: false as an option (as with the old behavior) or add the specific languages within allowedLanguagesToProcess: [language1, language2, etc.].

[lishaduck]

Btw, I've submitted #1392 to add a new option to make it more convenient to have ignored fenced blocks. Previously one would need to specify which blocks were allowed or ignored.

So to enable fenced code blocks, you need exampleCodeRegex: "^```([\\s\\S]*)```\\s*$"?

[brettz9]

Btw, I've submitted #1392 to add a new option to make it more convenient to have ignored fenced blocks. Previously one would need to specify which blocks were allowed or ignored.

So to enable fenced code blocks, you need exampleCodeRegex: "^```([\\s\\S]*)```\\s*$"?

Right (or equivalent). Otherwise, the whole @example tag contents are treated as JavaScript.