vfile-reporter: Report Generator

Common errors

• ERR_REQUIRE_ESM: require() of ES Module .../node_modules/vfile-reporter/index.js from ... not supported.

  cause `vfile-reporter` is an ES Module and cannot be loaded with CommonJS `require()`.
  fix Use `import { reporter } from 'vfile-reporter'` in an ES Module context. Ensure your `package.json` has `"type": "module"` or your file ends with `.mjs`.

• TypeError: Cannot read properties of undefined (reading 'message') or similar when `files` is not a `VFile` instance.

  cause The `reporter` function expects an array of `VFile` instances or a single `VFile` instance.
  fix Always pass valid `VFile` objects. Ensure `vfile` is correctly imported and instantiated: `import { VFile } from 'vfile'; new VFile(...)`.

• Error: Cannot find module 'vfile' or similar dependency error.

  cause `vfile`, a core dependency of `vfile-reporter`, is not installed or resolved correctly.
  fix Ensure `vfile` is installed as a dependency: `npm install vfile`.

• SyntaxError: Named export 'reporter' not found. The requested module 'vfile-reporter' does not provide an export named 'reporter'

  cause This error might occur if you are trying to use a named import (e.g., `{ reporter }`) on an older version that only supported default exports, or if your bundler configuration is incorrect.
  fix Ensure you are using `vfile-reporter` v7.0.1 or later for named exports. Try `import reporter from 'vfile-reporter'` if you suspect it's a default-only export issue or check your build configuration.

Warnings

• breaking Version 8.0.0 of `vfile-reporter` dropped support for Node.js versions older than 16. Running on earlier Node.js versions will result in runtime errors.
  Fix: Upgrade your Node.js environment to version 16 or higher. `nvm install 16 && nvm use 16`.
• breaking Since version 7.0.0, `vfile-reporter` is an ESM-only package. Attempting to `require()` it in a CommonJS module will throw an `ERR_REQUIRE_ESM` error.
  Fix: Convert your module to ES Modules (using `import` statements and setting `type: 'module'` in `package.json`) or use dynamic `import()` within CommonJS.
• breaking Version 8.0.0 removed direct support for 'errors' and 'nullish files'. Previously, the reporter might have handled these implicitly. Users are now expected to handle such conditions explicitly before passing files to the reporter.
  Fix: Implement explicit error handling and ensure that only valid `VFile` instances are passed to the `reporter` function. Filter out nullish or errored files beforehand.
• breaking Version 8.0.0 changed to use an `export` map, which means private internal APIs (e.g., direct deep imports) are no longer accessible and will break. The package intends for only its public API to be used.
  Fix: Ensure you are only importing and using the publicly documented API, such as the `reporter` function from the top-level package export. Avoid relying on internal module paths.
• breaking Version 7.0.0 updated its dependency on `vfile` to `v5.0.0`. If your project also uses `vfile` directly, ensure compatibility with `vfile@5.0.0` as it may contain its own breaking changes.
  Fix: Review `vfile@5.0.0` changelog for breaking changes and update your `vfile` usage accordingly in your codebase.

Install

• npm install vfile-reporter npm
• yarn add vfile-reporter yarn
• pnpm add vfile-reporter pnpm

Imports

• reporter
  wrong:

  const { reporter } = require('vfile-reporter')

  correct:

  import { reporter } from 'vfile-reporter'

  Since v7.0.0, `vfile-reporter` is an ESM-only package. CommonJS `require` is not supported. The `reporter` function is a named export.
• reporter

  import reporter from 'vfile-reporter'

  The `reporter` function is also provided as the default export for convenience.
• Options

  import type { Options } from 'vfile-reporter'

  For TypeScript users, the `Options` interface can be imported as a type for configuring the reporter's behavior.

Quickstart

Demonstrates creating multiple VFiles, adding messages to them, and then generating a formatted, human-readable report using `vfile-reporter` with verbose options.

import { VFile } from 'vfile';
import { reporter } from 'vfile-reporter';

// Create some VFile instances
const fileOne = new VFile({
  path: 'src/module-a.js',
  value: 'console.log(\"Hello\")'
});
const fileTwo = new VFile({
  path: 'src/module-b.js',
  value: 'const x = 1;'
});

// Add messages to fileOne
fileOne.message('This is a warning!', { line: 1, column: 9 }, 'linter:warning-id');
fileOne.message('Another issue at line 2.', 2);

// Use the reporter to generate a report for both files
// console.error is often used for reports to stderr
const report = reporter([fileOne, fileTwo], { verbose: true });
console.error(report);

/* Expected output (may vary slightly based on environment):
src/module-a.js
  1:9  warning  This is a warning!  linter:warning-id
  2:1  warning  Another issue at line 2.

src/module-b.js: no issues found

⚠ 2 warnings
*/