AK-21/Graphite-Industrial-Intelligence

1# vfile-message2 3[![Build][badge-build-image]][badge-build-url]4[![Coverage][badge-coverage-image]][badge-coverage-url]5[![Downloads][badge-downloads-image]][badge-downloads-url]6[![Size][badge-size-image]][badge-size-url]7 8Create [vfile][github-vfile] messages.9 10## Contents11 12* [What is this?](#what-is-this)13* [When should I use this?](#when-should-i-use-this)14* [Install](#install)15* [Use](#use)16* [API](#api)17  * [`VFileMessage(reason[, options])`](#vfilemessagereason-options)18  * [`Options`](#options)19  * [Well-known](#well-known)20* [Compatibility](#compatibility)21* [Contribute](#contribute)22* [License](#license)23 24## What is this?25 26This package provides a (lint) message format.27 28## When should I use this?29 30In most cases,31you can use `file.message` from `VFile` itself,32but in some cases you might not have a file,33and still want to emit warnings or errors,34in which case this can be used directly.35 36## Install37 38This package is [ESM only][github-gist-esm].39In Node.js (version 16+),40install with [npm][npmjs-install]:41 42```sh43npm install vfile-message44```45 46In Deno with [`esm.sh`][esmsh]:47 48```js49import {VFileMessage} from 'https://esm.sh/vfile-message@4'50```51 52In browsers with [`esm.sh`][esmsh]:53 54```html55<script type="module">56  import {VFileMessage} from 'https://esm.sh/vfile-message@4?bundle'57</script>58```59 60## Use61 62```js63import {VFileMessage} from 'vfile-message'64 65const message = new VFileMessage(66  'Unexpected unknown word `braavo`, did you mean `bravo`?',67  {place: {column: 8, line: 1}, ruleId: 'typo', source: 'spell'}68)69 70console.log(message)71```72 73Yields:74 75```text76[1:8: Unexpected unknown word `braavo`, did you mean `bravo`?] {77  reason: 'Unexpected unknown word `braavo`, did you mean `bravo`?',78  line: 1,79  column: 8,80  ancestors: undefined,81  cause: undefined,82  fatal: undefined,83  place: {line: 1, column: 8},84  ruleId: 'typo',85  source: 'spell'86}87```88 89## API90 91This package exports the identifier [`VFileMessage`][api-vfile-message].92There is no default export.93It exports the additional [TypeScript][] type [`Options`][api-options].94 95### `VFileMessage(reason[, options])`96 97Create a message for `reason`.98 99> 🪦 **Note**: also has obsolete signatures.100 101###### Parameters102 103* `reason` (`string`)104  — reason for message (should use markdown)105* `options` ([`Options`][api-options], optional)106  — configuration.107 108###### Extends109 110[`Error`][developer-mozilla-error].111 112###### Returns113 114Instance of `VFileMessage`.115 116###### Fields117 118* `ancestors` ([`Array<Node>`][github-unist-node] or `undefined`)119  — stack of (inclusive) ancestor nodes surrounding the message120* `cause` ([`Error`][developer-mozilla-error] or `undefined`)121  — original error cause of the message122* `column` (`number` or `undefined`)123  — starting column of message124* `fatal` (`boolean` or `undefined`)125  — state of problem; `true`: error, file not usable; `false`: warning,126  change may be needed; `undefined`: info, change likely not needed127* `line` (`number` or `undefined`)128  — starting line of message129* `place` ([`Point`][github-unist-point], [`Position`][github-unist-position]130  or `undefined`)131  — place of message132* `reason` (`string`)133  — reason for message (should use markdown)134* `ruleId` (`string` or `undefined`, example: `'my-rule'`)135  — category of message136* `source` (`string` or `undefined`, example: `'my-package'`)137  — namespace of message138 139### `Options`140 141Configuration (TypeScript type).142 143###### Fields144 145* `ancestors` ([`Array<Node>`][github-unist-node], optional)146  — stack of (inclusive) ancestor nodes surrounding the message147* `cause` ([`Error`][developer-mozilla-error], optional)148  — original error cause of the message149* `place` ([`Point`][github-unist-point] or [`Position`][github-unist-position],150  optional)151  — place of message152* `ruleId` (`string`, optional, example: `'my-rule'`)153  — category of message154* `source` (`string`, optional, , example: `'my-package'`)155  — namespace of who sent the message156 157### Well-known158 159It’s OK to store custom data directly on the `VFileMessage`, some of those are160handled by [utilities][github-vfile-util].161The following fields are documented and typed here.162 163###### Fields164 165* `actual` (`string`, optional)166  — specify the source value that’s being reported, which is deemed incorrect167* `expected` (`Array<string>`, optional)168  — suggest acceptable values that can be used instead of `actual`169* `url` (`string`, optional)170  — link to docs for the message (this must be an absolute URL that can be171  passed as `x` to `new URL(x)`)172* `note` (`string`, optional)173  — long form description of the message (you should use markdown)174 175## Compatibility176 177Projects maintained by the unified collective are compatible with maintained178versions of Node.js.179 180When we cut a new major release, we drop support for unmaintained versions of181Node.182This means we try to keep the current release line, `vfile-message@^4`,183compatible with Node.js 16.184 185## Contribute186 187See [`contributing.md`][health-contributing] in [`vfile/.github`][health]188for ways to get started.189See [`support.md`][health-support] for ways to get help.190 191This project has a [code of conduct][health-coc].192By interacting with this repository,193organization,194or community you agree to abide by its terms.195 196## License197 198[MIT][file-license] © [Titus Wormer][wooorm]199 200<!-- Definitions -->201 202[api-options]: #options203 204[api-vfile-message]: #vfilemessagereason-options205 206[badge-build-image]: https://github.com/vfile/vfile-message/workflows/main/badge.svg207 208[badge-build-url]: https://github.com/vfile/vfile-message/actions209 210[badge-coverage-image]: https://img.shields.io/codecov/c/github/vfile/vfile-message.svg211 212[badge-coverage-url]: https://codecov.io/github/vfile/vfile-message213 214[badge-downloads-image]: https://img.shields.io/npm/dm/vfile-message.svg215 216[badge-downloads-url]: https://www.npmjs.com/package/vfile-message217 218[badge-size-image]: https://img.shields.io/bundlejs/size/vfile-message219 220[badge-size-url]: https://bundlejs.com/?q=vfile-message221 222[developer-mozilla-error]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error223 224[esmsh]: https://esm.sh225 226[file-license]: license227 228[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c229 230[github-unist-node]: https://github.com/syntax-tree/unist#node231 232[github-unist-point]: https://github.com/syntax-tree/unist#point233 234[github-unist-position]: https://github.com/syntax-tree/unist#position235 236[github-vfile]: https://github.com/vfile/vfile237 238[github-vfile-util]: https://github.com/vfile/vfile#utilities239 240[health]: https://github.com/vfile/.github241 242[health-coc]: https://github.com/vfile/.github/blob/main/code-of-conduct.md243 244[health-contributing]: https://github.com/vfile/.github/blob/main/contributing.md245 246[health-support]: https://github.com/vfile/.github/blob/main/support.md247 248[npmjs-install]: https://docs.npmjs.com/cli/install249 250[typescript]: https://www.typescriptlang.org251 252[wooorm]: https://wooorm.com253