vfile-reporter
!Buildbuild-badgebuild
!Coveragecoverage-badgecoverage
!Downloadsdownloads-badgedownloads
!Sizesize-badgesize
!Sponsorssponsors-badgecollective
!Backersbackers-badgecollective
!Chatchat-badgechatvfile utility to create a report.
!Example screenshot of vfile-reporterscreenshot
Contents
* [`reporter(files[, options])`](#reporterfiles-options)
* [`Options`](#options)
What is this?
This package create a textual report from files 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 when you want to display a report about what occurred while processing to a human.There are other reportersreporters that display information differently listed in vfile.
Install
This package is ESM onlyesm. In Node.js (version 16+), install with npm:npm install vfile-reporter
In Deno with
esm.sh
esmsh:import {reporter} from 'https://esm.sh/vfile-reporter@8'
In browsers with
esm.sh
esmsh:<script type="module">
import {reporter} from 'https://esm.sh/vfile-reporter@8?bundle'
</script>
Use
Say our moduleexample.js
looks as follows:import {VFile} from 'vfile'
import {reporter} from 'vfile-reporter'
const one = new VFile({path: 'test/fixture/1.js'})
const two = new VFile({path: 'test/fixture/2.js'})
one.message('Warning!', {line: 2, column: 4})
console.error(reporter([one, two]))
…now running
node example.js
yields:test/fixture/1.js
2:4 warning Warning!
test/fixture/2.js: no issues found
⚠ 1 warning
API
This package exports the identifierreporter
api-reporter.
That value is also the default
export.reporter(files[, options])
Create a report from one or more files.Parameters
files
(Array<VFile>
vfile orVFile
)
— files to report
options
(Options
api-options, optional)
— configuration
Returns
Report (string
).Options
Configuration (TypeScript type).Fields
color
(boolean
, default:true
when in Node.js and
[color is supported][supports-color], or `false`)
— use ANSI colors in report
defaultName
(string
, default:'<stdin>'
)
— Label to use for files without file path; if one file and no `defaultName`
is given, no name will show up in the report
verbose
(boolean
, default:false
)
— show message notes, URLs, and ancestor stack trace if available
quiet
(boolean
, default:false
)
— do not show files without messages
silent
(boolean
, default:false
)
— show errors only; this hides info and warning messages, and sets
`quiet: true`
traceLimit
(number
, default:10
)
— max number of nodes to show in ancestors trace); ancestors can be shown
when `verbose: true`
Example
Here’s a small example that looks through a markdown AST for emphasis and strong nodes, and checks whether they use*
.
The message has detailed information which will be shown in verbose mode.example.js
:import {fromMarkdown} from 'mdast-util-from-markdown'
import {visitParents} from 'unist-util-visit-parents'
import {VFile} from 'vfile'
import {reporter} from 'vfile-reporter'
const file = new VFile({
path: new URL('example.md', import.meta.url),
value: '# *hi*, _world_!'
})
const value = String(file)
const tree = fromMarkdown(value)
visitParents(tree, (node, parents) => {
if (node.type === 'emphasis' || node.type === 'strong') {
const start = node.position?.start.offset
if (start !== undefined && value.charAt(start) === '_') {
const m = file.message('Expected `*` (asterisk), not `_` (underscore)', {
ancestors: [...parents, node],
place: node.position,
ruleId: 'attention-marker',
source: 'some-lint-example'
})
m.note = `It is recommended to use asterisks for emphasis/strong attention when
writing markdown.
There are some small differences in whether sequences can open and/or close…`
m.url = 'https://example.com/whatever'
}
}
})
console.error(reporter([file], {verbose: false}))
…running
node example.js
yields:/Users/tilde/Projects/oss/vfile-reporter/example.md
1:9-1:16 warning Expected `*` (asterisk), not `_` (underscore) attention-marker some-lint-example
⚠ 1 warning
To show the info, pass
verbose: true
to reporter
, and run again:
and see:/Users/tilde/Projects/oss/vfile-reporter/example.md
1:9-1:16 warning Expected `*` (asterisk), not `_` (underscore) attention-marker some-lint-example
[url]:
https://example.com/whatever
[note]:
It is recommended to use asterisks for emphasis/strong attention when
writing markdown.
There are some small differences in whether sequences can open and/or close…
[trace]:
at emphasis (1:9-1:16)
at heading (1:1-1:17)
at root (1:1-1:17)
⚠ 1 warning
Types
This package is fully typed with TypeScript. It exports the additional typeOptions
api-options.Compatibility
Projects maintained by the unified collective are compatible with maintained versions of Node.js.When we cut a new major release, we drop support for unmaintained versions of Node. This means we try to keep the current release line,
vfile-reporter@^8
,
compatible with Node.js 16.Security
Use ofvfile-reporter
is safe.Related
— create a JSON report
— create a pretty report
— create a jUnit report
— create a report with content excerpts
Contribute
Seecontributing.md
contributing in vfile/.github
health for ways to
get started.
See support.md
support for ways to get help.This project has a code of conductcoc. By interacting with this repository, organisation, or community you agree to abide by its terms.