From cdec69434d94496f1182da97a7e18abab35688ea Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Fri, 25 Mar 2022 17:05:38 +0100 Subject: [PATCH] Add improved docs --- lib/index.js | 2 +- readme.md | 135 ++++++++++++++++++++++++++++++++++++--------------- 2 files changed, 96 insertions(+), 41 deletions(-) diff --git a/lib/index.js b/lib/index.js index 12c86e9..795450e 100644 --- a/lib/index.js +++ b/lib/index.js @@ -22,7 +22,7 @@ * @property {VFile} file * @property {Statistics} stats * - * @typedef {{[x: string]: number}} Sizes + * @typedef {Record} Sizes * * @typedef Info * @property {Array} rows diff --git a/readme.md b/readme.md index f42bc6e..3d98248 100644 --- a/readme.md +++ b/readme.md @@ -7,28 +7,60 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -Create a report for a **[vfile][]**. +[vfile][] utility to create a report from a file. ![Example screenshot of vfile-reporter][screenshot] -## Features +## Contents -* [x] Ranges (`3:2` and `3:2-3:6`) -* [x] Stack-traces to show where awful stuff occurs -* [x] Successful files (configurable) -* [x] All of [**VFile**][vfile]’s awesomeness +* [What is this?](#what-is-this) +* [When should I use this?](#when-should-i-use-this) +* [Install](#install) +* [Use](#use) +* [API](#api) + * [`reporter(files[, options])`](#reporterfiles-options) +* [Types](#types) +* [Compatibility](#compatibility) +* [Security](#security) +* [Related](#related) +* [Contribute](#contribute) +* [License](#license) -## Install +## What is this? + +This package create a textual report from a file showing the warnings that +occurred while processing. +Many CLIs of tools that process files, whether linters (such as ESLint) or +bundlers (such as esbuild), have similar functionality. + +## When should I use this? + +You can use this package whenever you want to display a report about what +occurred while processing to a human. -This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c): -Node 12+ is needed to use it and it must be `import`ed instead of `require`d. +## Install -[npm][]: +This package is [ESM only][esm]. +In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]: ```sh npm install vfile-reporter ``` +In Deno with [`esm.sh`][esmsh]: + +```js +import {reporter} from 'https://esm.sh/vfile-reporter@7' +``` + +In browsers with [`esm.sh`][esmsh]: + +```html + +``` + ## Use Say `example.js` contains: @@ -58,55 +90,72 @@ test/fixture/2.js: no issues found ## API -This package exports the following identifiers: `reporter`. -That identifier is also the default export. +This package exports the identifier `reporter`. +That value is also the default export. ### `reporter(files[, options])` -Generate a stylish report from the given [`vfile`][vfile], `Array`, -or `Error`. +Create a report from an error, on file, or multiple files. ##### `options` +Configuration (optional). + +###### `options.color` + +Use ANSI colors in report (`boolean`, default: depends). +The default behavior is the check if [color is supported][supports-color]. + ###### `options.verbose` -Output long form descriptions of messages, if applicable (`boolean`, default: -`false`). +Show message [`note`][message-note]s (`boolean`, default: `false`). +Notes are optional, additional, long descriptions. ###### `options.quiet` -Do not output anything for a file which has no warnings or errors (`boolean`, -default: `false`). -The default behavior is to show a success message. +Do not show files without messages (`boolean`, default: `false`). ###### `options.silent` -Do not output messages without `fatal` set to true (`boolean`, default: -`false`). +Show errors only (`boolean`, default: `false`). +This does not show info and warning messages. Also sets `quiet` to `true`. -###### `options.color` - -Whether to use color (`boolean`, default: depends). -The default behavior is the check if [color is supported][supports-color]. - ###### `options.defaultName` -Label to use for files without file-path (`string`, default: `''`). +Label to use for files without file path (`string`, default: `''`). If one file and no `defaultName` is given, no name will show up in the report. +##### Returns + +`string`. + +## Types + +This package is fully typed with [TypeScript][]. +It exports the additional type `Options`. + +## Compatibility + +Projects maintained by the unified collective are compatible with all maintained +versions of Node.js. +As of now, that is Node.js 12.20+, 14.14+, and 16.0+. +Our projects sometimes work with older versions, but this is not guaranteed. + +## Security + +Use of `vfile-reporter` is safe. + ## Related * [`vfile-reporter-json`](https://github.com/vfile/vfile-reporter-json) - — JSON reporter + — create a JSON report * [`vfile-reporter-pretty`](https://github.com/vfile/vfile-reporter-pretty) - — Pretty reporter -* [`convert-vinyl-to-vfile`](https://github.com/dustinspecker/convert-vinyl-to-vfile) - — Convert from [Vinyl][] -* [`vfile-statistics`](https://github.com/vfile/vfile-statistics) - — Count messages per category -* [`vfile-sort`](https://github.com/vfile/vfile-sort) - — Sort messages by line/column + — create a pretty report +* [`vfile-reporter-junit`](https://github.com/kellyselden/vfile-reporter-junit) + — create a jUnit report +* [`vfile-reporter-position`](https://github.com/Hocdoc/vfile-reporter-position) + — create a report with content excerpts ## Contribute @@ -115,7 +164,7 @@ get started. See [`support.md`][support] for ways to get help. This project has a [code of conduct][coc]. -By interacting with this repository, organization, or community you agree to +By interacting with this repository, organisation, or community you agree to abide by its terms. ## License @@ -152,13 +201,19 @@ Nicholas C. Zakas, and licensed under MIT. [npm]: https://docs.npmjs.com/cli/install -[contributing]: https://github.com/vfile/.github/blob/HEAD/contributing.md +[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c + +[esmsh]: https://esm.sh + +[typescript]: https://www.typescriptlang.org + +[contributing]: https://github.com/vfile/.github/blob/main/contributing.md -[support]: https://github.com/vfile/.github/blob/HEAD/support.md +[support]: https://github.com/vfile/.github/blob/main/support.md [health]: https://github.com/vfile/.github -[coc]: https://github.com/vfile/.github/blob/HEAD/code-of-conduct.md +[coc]: https://github.com/vfile/.github/blob/main/code-of-conduct.md [license]: license @@ -172,4 +227,4 @@ Nicholas C. Zakas, and licensed under MIT. [supports-color]: https://github.com/chalk/supports-color -[vinyl]: https://github.com/gulpjs/vinyl +[message-note]: https://github.com/vfile/vfile-message#note