AK-21/Graphite-Industrial-Intelligence

1<h1>2  <img src="https://raw.githubusercontent.com/vfile/vfile/fc8164b/logo.svg?sanitize=true" alt="vfile" />3</h1>4 5[![Build][build-badge]][build]6[![Coverage][coverage-badge]][coverage]7[![Downloads][downloads-badge]][downloads]8[![Size][size-badge]][size]9[![Sponsors][sponsors-badge]][collective]10[![Backers][backers-badge]][collective]11[![Chat][chat-badge]][chat]12 13**vfile** is a small and browser friendly virtual file format that tracks14metadata about files (such as its `path` and `value`) and lint15[messages][api-vfile-messages].16 17## Contents18 19* [unified](#unified)20* [What is this?](#what-is-this)21* [When should I use this?](#when-should-i-use-this)22* [Install](#install)23* [Use](#use)24* [API](#api)25  * [`VFile(options?)`](#vfileoptions)26  * [`file.cwd`](#filecwd)27  * [`file.data`](#filedata)28  * [`file.history`](#filehistory)29  * [`file.messages`](#filemessages)30  * [`file.value`](#filevalue)31  * [`file.basename`](#filebasename)32  * [`file.dirname`](#filedirname)33  * [`file.extname`](#fileextname)34  * [`file.path`](#filepath)35  * [`file.stem`](#filestem)36  * [`VFile#fail(reason[, options])`](#vfilefailreason-options)37  * [`VFile#info(reason[, options])`](#vfileinforeason-options)38  * [`VFile#message(reason[, options])`](#vfilemessagereason-options)39  * [`VFile#toString(encoding?)`](#vfiletostringencoding)40  * [`Compatible`](#compatible)41  * [`Data`](#data)42  * [`DataMap`](#datamap)43  * [`Map`](#map)44  * [`MessageOptions`](#messageoptions)45  * [`Options`](#options)46  * [`Reporter`](#reporter)47  * [`ReporterSettings`](#reportersettings)48  * [`Value`](#value)49  * [Well-known](#well-known)50* [List of utilities](#list-of-utilities)51* [Reporters](#reporters)52* [Types](#types)53* [Compatibility](#compatibility)54* [Contribute](#contribute)55* [Sponsor](#sponsor)56* [Acknowledgments](#acknowledgments)57* [License](#license)58 59## unified60 61**vfile** is part of the unified collective.62 63* for more about us, see [`unifiedjs.com`][site]64* for how the collective is governed, see [`unifiedjs/collective`][governance]65* for updates, see [@unifiedjs][twitter] on Twitter66 67## What is this?68 69This package provides a virtual file format.70It exposes an API to access the file value, path, metadata about the file, and71specifically supports attaching lint messages and errors to certain places in72these files.73 74## When should I use this?75 76The virtual file format is useful when dealing with the concept of files in77places where you might not be able to access the file system.78The message API is particularly useful when making things that check files (as79in, linting).80 81vfile is made for [unified][], which amongst other things checks files.82However, vfile can be used in other projects that deal with parsing,83transforming, and serializing data, to build linters, compilers, static site84generators, and other build tools.85 86This is different from the excellent [`vinyl`][vinyl] in that vfile has a87smaller API, a smaller size, and focuses on messages.88 89## Install90 91This package is [ESM only][esm].92In Node.js (version 16+), install with [npm][]:93 94```sh95npm install vfile96```97 98In Deno with [`esm.sh`][esmsh]:99 100```js101import {VFile} from 'https://esm.sh/vfile@6'102```103 104In browsers with [`esm.sh`][esmsh]:105 106```html107<script type="module">108  import {VFile} from 'https://esm.sh/vfile@6?bundle'109</script>110```111 112## Use113 114```js115import {VFile} from 'vfile'116 117const file = new VFile({118  path: '~/example.txt',119  value: 'Alpha *braavo* charlie.'120})121 122console.log(file.path) // => '~/example.txt'123console.log(file.dirname) // => '~'124 125file.extname = '.md'126 127console.log(file.basename) // => 'example.md'128 129file.basename = 'index.text'130 131console.log(file.history) // => ['~/example.txt', '~/example.md', '~/index.text']132 133file.message('Unexpected unknown word `braavo`, did you mean `bravo`?', {134  place: {line: 1, column: 8},135  source: 'spell',136  ruleId: 'typo'137})138 139console.log(file.messages)140```141 142Yields:143 144```txt145[146  [~/index.text:1:8: Unexpected unknown word `braavo`, did you mean `bravo`?] {147    ancestors: undefined,148    cause: undefined,149    column: 8,150    fatal: false,151    line: 1,152    place: { line: 1, column: 8 },153    reason: 'Unexpected unknown word `braavo`, did you mean `bravo`?',154    ruleId: 'typo',155    source: 'spell',156    file: '~/index.text'157  }158]159```160 161## API162 163This package exports the identifier [`VFile`][api-vfile].164There is no default export.165 166### `VFile(options?)`167 168Create a new virtual file.169 170`options` is treated as:171 172* `string` or [`Uint8Array`][mdn-uint8-array] — `{value: options}`173* `URL` — `{path: options}`174* `VFile` — shallow copies its data over to the new file175* `object` — all fields are shallow copied over to the new file176 177Path related fields are set in the following order (least specific to178most specific): `history`, `path`, `basename`, `stem`, `extname`,179`dirname`.180 181You cannot set `dirname` or `extname` without setting either `history`,182`path`, `basename`, or `stem` too.183 184###### Parameters185 186* `options` ([`Compatible`][api-compatible], optional)187  — file value188 189###### Returns190 191New instance (`VFile`).192 193###### Example194 195```js196new VFile()197new VFile('console.log("alpha");')198new VFile(new Uint8Array([0x65, 0x78, 0x69, 0x74, 0x20, 0x31]))199new VFile({path: path.join('path', 'to', 'readme.md')})200new VFile({stem: 'readme', extname: '.md', dirname: path.join('path', 'to')})201new VFile({other: 'properties', are: 'copied', ov: {e: 'r'}})202```203 204### `file.cwd`205 206Base of `path` (`string`, default: `process.cwd()` or `'/'` in browsers).207 208### `file.data`209 210Place to store custom info (`Record<string, unknown>`, default: `{}`).211 212It’s OK to store custom data directly on the file but moving it to `data` is213recommended.214 215### `file.history`216 217List of file paths the file moved between (`Array<string>`).218 219The first is the original path and the last is the current path.220 221### `file.messages`222 223List of messages associated with the file224([`Array<VFileMessage>`][api-vfile-message]).225 226### `file.value`227 228Raw value ([`Uint8Array`][mdn-uint8-array], `string`, `undefined`).229 230### `file.basename`231 232Get or set the basename (including extname) (`string?`, example: `'index.min.js'`).233 234Cannot contain path separators (`'/'` on unix, macOS, and browsers, `'\'` on235windows).236Cannot be nullified (use `file.path = file.dirname` instead).237 238### `file.dirname`239 240Get or set the parent path (`string?`, example: `'~'`).241 242Cannot be set if there’s no `path` yet.243 244### `file.extname`245 246Get or set the extname (including dot) (`string?`, example: `'.js'`).247 248Cannot contain path separators (`'/'` on unix, macOS, and browsers, `'\'` on249windows).250Cannot be set if there’s no `path` yet.251 252### `file.path`253 254Get or set the full path (`string?`, example: `'~/index.min.js'`).255 256Cannot be nullified.257You can set a file URL (a `URL` object with a `file:` protocol) which will be258turned into a path with [`url.fileURLToPath`][file-url-to-path].259 260### `file.stem`261 262Get or set the stem (basename w/o extname) (`string?`, example: `'index.min'`).263 264Cannot contain path separators (`'/'` on unix, macOS, and browsers, `'\'` on265windows).266Cannot be nullified.267 268### `VFile#fail(reason[, options])`269 270Create a fatal message for `reason` associated with the file.271 272The `fatal` field of the message is set to `true` (error; file not usable) and273the `file` field is set to the current file path.274The message is added to the `messages` field on `file`.275 276> 🪦 **Note**: also has obsolete signatures.277 278###### Parameters279 280* `reason` (`string`)281  — reason for message, should use markdown282* `options` ([`MessageOptions`][api-message-options], optional)283  — configuration284 285###### Returns286 287Nothing (`never`).288 289###### Throws290 291Message ([`VFileMessage`][vmessage]).292 293### `VFile#info(reason[, options])`294 295Create an info message for `reason` associated with the file.296 297The `fatal` field of the message is set to `undefined` (info; change likely not298needed) and the `file` field is set to the current file path.299The message is added to the `messages` field on `file`.300 301> 🪦 **Note**: also has obsolete signatures.302 303###### Parameters304 305* `reason` (`string`)306  — reason for message, should use markdown307* `options` ([`MessageOptions`][api-message-options], optional)308  — configuration309 310###### Returns311 312Message ([`VFileMessage`][vmessage]).313 314### `VFile#message(reason[, options])`315 316Create a message for `reason` associated with the file.317 318The `fatal` field of the message is set to `false` (warning; change may be319needed) and the `file` field is set to the current file path.320The message is added to the `messages` field on `file`.321 322> 🪦 **Note**: also has obsolete signatures.323 324###### Parameters325 326* `reason` (`string`)327  — reason for message, should use markdown328* `options` ([`MessageOptions`][api-message-options], optional)329  — configuration330 331###### Returns332 333Message ([`VFileMessage`][vmessage]).334 335### `VFile#toString(encoding?)`336 337Serialize the file.338 339> **Note**: which encodings are supported depends on the engine.340> For info on Node.js, see:341> <https://nodejs.org/api/util.html#whatwg-supported-encodings>.342 343###### Parameters344 345* `encoding` (`string`, default: `'utf8'`)346  — character encoding to understand `value` as when it’s a347  [`Uint8Array`][mdn-uint8-array]348 349###### Returns350 351Serialized file (`string`).352 353### `Compatible`354 355Things that can be passed to the constructor (TypeScript type).356 357###### Type358 359```ts360type Compatible = Options | URL | VFile | Value361```362 363### `Data`364 365Custom info (TypeScript type).366 367Known attributes can be added to [`DataMap`][api-data-map].368 369###### Type370 371```ts372type Data = Record<string, unknown> & Partial<DataMap>373```374 375### `DataMap`376 377This map registers the type of the `data` key of a `VFile` (TypeScript type).378 379This type can be augmented to register custom `data` types.380 381###### Type382 383```ts384interface DataMap {}385```386 387###### Example388 389```ts390declare module 'vfile' {391  interface DataMap {392    // `file.data.name` is typed as `string`393    name: string394  }395}396```397 398### `Map`399 400Raw source map (TypeScript type).401 402See [`source-map`][source-map].403 404###### Fields405 406* `version` (`number`)407  — which version of the source map spec this map is following408* `sources` (`Array<string>`)409  — an array of URLs to the original source files410* `names` (`Array<string>`)411  — an array of identifiers which can be referenced by individual mappings412* `sourceRoot` (`string`, optional)413  — the URL root from which all sources are relative414* `sourcesContent` (`Array<string>`, optional)415  — an array of contents of the original source files416* `mappings` (`string`)417  — a string of base64 VLQs which contain the actual mappings418* `file` (`string`)419  — the generated file this source map is associated with420 421### `MessageOptions`422 423Options to create messages (TypeScript type).424 425See [`Options` in `vfile-message`][vfile-message-options].426 427### `Options`428 429An object with arbitrary fields and the following known fields (TypeScript430type).431 432###### Fields433 434* `basename` (`string`, optional)435  — set `basename` (name)436* `cwd` (`string`, optional)437  — set `cwd` (working directory)438* `data` ([`Data`][api-data], optional)439  — set `data` (associated info)440* `dirname` (`string`, optional)441  — set `dirname` (path w/o basename)442* `extname` (`string`, optional)443  — set `extname` (extension with dot)444* `history` (`Array<string>`, optional)445  — set `history` (paths the file moved between)446* `path` (`URL | string`, optional)447  — set `path` (current path)448* `stem` (`string`, optional)449  — set `stem` (name without extension)450* `value` ([`Value`][api-value], optional)451  — set `value` (the contents of the file)452 453### `Reporter`454 455Type for a reporter (TypeScript type).456 457###### Type458 459```ts460type Reporter<Settings = ReporterSettings> = (461  files: Array<VFile>,462  options: Settings463) => string464```465 466### `ReporterSettings`467 468Configuration for reporters (TypeScript type).469 470###### Type471 472```ts473type ReporterSettings = Record<string, unknown>474```475 476### `Value`477 478Contents of the file (TypeScript type).479 480Can either be text or a [`Uint8Array`][mdn-uint8-array] structure.481 482###### Type483 484```ts485type Value = Uint8Array | string486```487 488### Well-known489 490The following fields are considered “non-standard”, but they are allowed, and491some utilities use them:492 493* `map` ([`Map`][api-map])494  — source map; this type is equivalent to the `RawSourceMap` type from the495  `source-map` module496* `result` (`unknown`)497  — custom, non-string, compiled, representation; this is used by unified to498  store non-string results; one example is when turning markdown into React499  nodes500* `stored` (`boolean`)501  — whether a file was saved to disk; this is used by vfile reporters502 503There are also well-known fields on messages, see504[them in a similar section of505`vfile-message`](https://github.com/vfile/vfile-message#well-known).506 507<a name="utilities"></a>508 509## List of utilities510 511* [`convert-vinyl-to-vfile`](https://github.com/dustinspecker/convert-vinyl-to-vfile)512  — transform from [Vinyl][]513* [`to-vfile`](https://github.com/vfile/to-vfile)514  — create a file from a file path and read and write to the file system515* [`vfile-find-down`](https://github.com/vfile/vfile-find-down)516  — find files by searching the file system downwards517* [`vfile-find-up`](https://github.com/vfile/vfile-find-up)518  — find files by searching the file system upwards519* [`vfile-glob`](https://github.com/shinnn/vfile-glob)520  — find files by glob patterns521* [`vfile-is`](https://github.com/vfile/vfile-is)522  — check if a file passes a test523* [`vfile-location`](https://github.com/vfile/vfile-location)524  — convert between positional and offset locations525* [`vfile-matter`](https://github.com/vfile/vfile-matter)526  — parse the YAML front matter527* [`vfile-message`](https://github.com/vfile/vfile-message)528  — create a file message529* [`vfile-messages-to-vscode-diagnostics`](https://github.com/shinnn/vfile-messages-to-vscode-diagnostics)530  — transform file messages to VS Code diagnostics531* [`vfile-mkdirp`](https://github.com/vfile/vfile-mkdirp)532  — make sure the directory of a file exists on the file system533* [`vfile-rename`](https://github.com/vfile/vfile-rename)534  — rename the path parts of a file535* [`vfile-sort`](https://github.com/vfile/vfile-sort)536  — sort messages by line/column537* [`vfile-statistics`](https://github.com/vfile/vfile-statistics)538  — count messages per category: failures, warnings, etc539* [`vfile-to-eslint`](https://github.com/vfile/vfile-to-eslint)540  — convert to ESLint formatter compatible output541 542> 👉 **Note**: see [unist][] for projects that work with nodes.543 544## Reporters545 546* [`vfile-reporter`][reporter]547  — create a report548* [`vfile-reporter-json`](https://github.com/vfile/vfile-reporter-json)549  — create a JSON report550* [`vfile-reporter-folder-json`](https://github.com/vfile/vfile-reporter-folder-json)551  — create a JSON representation of vfiles552* [`vfile-reporter-pretty`](https://github.com/vfile/vfile-reporter-pretty)553  — create a pretty report554* [`vfile-reporter-junit`](https://github.com/kellyselden/vfile-reporter-junit)555  — create a jUnit report556* [`vfile-reporter-position`](https://github.com/Hocdoc/vfile-reporter-position)557  — create a report with content excerpts558 559> 👉 **Note**: want to make your own reporter?560> Reporters *must* accept `Array<VFile>` as their first argument, and return561> `string`.562> Reporters *may* accept other values too, in which case it’s suggested to stick563> to `vfile-reporter`s interface.564 565## Types566 567This package is fully typed with [TypeScript][].568It exports the additional types569[`Compatible`][api-compatible],570[`Data`][api-data],571[`DataMap`][api-data-map],572[`Map`][api-map],573[`MessageOptions`][api-message-options],574[`Options`][api-options],575[`Reporter`][api-reporter],576[`ReporterSettings`][api-reporter-settings], and577[`Value`][api-value].578 579## Compatibility580 581Projects maintained by the unified collective are compatible with maintained582versions of Node.js.583 584When we cut a new major release, we drop support for unmaintained versions of585Node.586This means we try to keep the current release line, `vfile@^6`,587compatible with Node.js 16.588 589## Contribute590 591See [`contributing.md`][contributing] in [`vfile/.github`][health] for ways to592get started.593See [`support.md`][support] for ways to get help.594 595This project has a [code of conduct][coc].596By interacting with this repository, organization, or community you agree to597abide by its terms.598 599## Sponsor600 601Support this effort and give back by sponsoring on [OpenCollective][collective]!602 603<table>604<tr valign="middle">605<td width="20%" align="center" rowspan="2" colspan="2">606  <a href="https://vercel.com">Vercel</a><br><br>607  <a href="https://vercel.com"><img src="https://avatars1.githubusercontent.com/u/14985020?s=256&v=4" width="128"></a>608</td>609<td width="20%" align="center" rowspan="2" colspan="2">610  <a href="https://motif.land">Motif</a><br><br>611  <a href="https://motif.land"><img src="https://avatars1.githubusercontent.com/u/74457950?s=256&v=4" width="128"></a>612</td>613<td width="20%" align="center" rowspan="2" colspan="2">614  <a href="https://www.hashicorp.com">HashiCorp</a><br><br>615  <a href="https://www.hashicorp.com"><img src="https://avatars1.githubusercontent.com/u/761456?s=256&v=4" width="128"></a>616</td>617<td width="20%" align="center" rowspan="2" colspan="2">618  <a href="https://www.gitbook.com">GitBook</a><br><br>619  <a href="https://www.gitbook.com"><img src="https://avatars1.githubusercontent.com/u/7111340?s=256&v=4" width="128"></a>620</td>621<td width="20%" align="center" rowspan="2" colspan="2">622  <a href="https://www.gatsbyjs.org">Gatsby</a><br><br>623  <a href="https://www.gatsbyjs.org"><img src="https://avatars1.githubusercontent.com/u/12551863?s=256&v=4" width="128"></a>624</td>625</tr>626<tr valign="middle">627</tr>628<tr valign="middle">629<td width="20%" align="center" rowspan="2" colspan="2">630  <a href="https://www.netlify.com">Netlify</a><br><br>631  <!--OC has a sharper image-->632  <a href="https://www.netlify.com"><img src="https://images.opencollective.com/netlify/4087de2/logo/256.png" width="128"></a>633</td>634<td width="10%" align="center">635  <a href="https://www.coinbase.com">Coinbase</a><br><br>636  <a href="https://www.coinbase.com"><img src="https://avatars1.githubusercontent.com/u/1885080?s=256&v=4" width="64"></a>637</td>638<td width="10%" align="center">639  <a href="https://themeisle.com">ThemeIsle</a><br><br>640  <a href="https://themeisle.com"><img src="https://avatars1.githubusercontent.com/u/58979018?s=128&v=4" width="64"></a>641</td>642<td width="10%" align="center">643  <a href="https://expo.io">Expo</a><br><br>644  <a href="https://expo.io"><img src="https://avatars1.githubusercontent.com/u/12504344?s=128&v=4" width="64"></a>645</td>646<td width="10%" align="center">647  <a href="https://boostnote.io">Boost Note</a><br><br>648  <a href="https://boostnote.io"><img src="https://images.opencollective.com/boosthub/6318083/logo/128.png" width="64"></a>649</td>650<td width="10%" align="center">651  <a href="https://markdown.space">Markdown Space</a><br><br>652  <a href="https://markdown.space"><img src="https://images.opencollective.com/markdown-space/e1038ed/logo/128.png" width="64"></a>653</td>654<td width="10%" align="center">655  <a href="https://www.holloway.com">Holloway</a><br><br>656  <a href="https://www.holloway.com"><img src="https://avatars1.githubusercontent.com/u/35904294?s=128&v=4" width="64"></a>657</td>658<td width="10%"></td>659<td width="10%"></td>660</tr>661<tr valign="middle">662<td width="100%" align="center" colspan="8">663  <br>664  <a href="https://opencollective.com/unified"><strong>You?</strong></a>665  <br><br>666</td>667</tr>668</table>669 670## Acknowledgments671 672The initial release of this project was authored by673[**@wooorm**](https://github.com/wooorm).674 675Thanks to [**@contra**](https://github.com/contra),676[**@phated**](https://github.com/phated), and others for their work on677[Vinyl][], which was a huge inspiration.678 679Thanks to680[**@brendo**](https://github.com/brendo),681[**@shinnn**](https://github.com/shinnn),682[**@KyleAMathews**](https://github.com/KyleAMathews),683[**@sindresorhus**](https://github.com/sindresorhus), and684[**@denysdovhan**](https://github.com/denysdovhan)685for contributing commits since!686 687## License688 689[MIT][license] © [Titus Wormer][author]690 691<!-- Definitions -->692 693[build-badge]: https://github.com/vfile/vfile/workflows/main/badge.svg694 695[build]: https://github.com/vfile/vfile/actions696 697[coverage-badge]: https://img.shields.io/codecov/c/github/vfile/vfile.svg698 699[coverage]: https://codecov.io/github/vfile/vfile700 701[downloads-badge]: https://img.shields.io/npm/dm/vfile.svg702 703[downloads]: https://www.npmjs.com/package/vfile704 705[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=vfile706 707[size]: https://bundlejs.com/?q=vfile708 709[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg710 711[backers-badge]: https://opencollective.com/unified/backers/badge.svg712 713[collective]: https://opencollective.com/unified714 715[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg716 717[chat]: https://github.com/vfile/vfile/discussions718 719[npm]: https://docs.npmjs.com/cli/install720 721[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c722 723[esmsh]: https://esm.sh724 725[typescript]: https://www.typescriptlang.org726 727[health]: https://github.com/vfile/.github728 729[contributing]: https://github.com/vfile/.github/blob/main/contributing.md730 731[support]: https://github.com/vfile/.github/blob/main/support.md732 733[coc]: https://github.com/vfile/.github/blob/main/code-of-conduct.md734 735[license]: license736 737[author]: https://wooorm.com738 739[unified]: https://github.com/unifiedjs/unified740 741[vinyl]: https://github.com/gulpjs/vinyl742 743[site]: https://unifiedjs.com744 745[twitter]: https://twitter.com/unifiedjs746 747[unist]: https://github.com/syntax-tree/unist#list-of-utilities748 749[reporter]: https://github.com/vfile/vfile-reporter750 751[vmessage]: https://github.com/vfile/vfile-message752 753[vfile-message-options]: https://github.com/vfile/vfile-message#options754 755[mdn-uint8-array]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array756 757[source-map]: https://github.com/mozilla/source-map/blob/58819f0/source-map.d.ts#L15-L23758 759[file-url-to-path]: https://nodejs.org/api/url.html#url_url_fileurltopath_url760 761[governance]: https://github.com/unifiedjs/collective762 763[api-vfile-messages]: #filemessages764 765[api-vfile-message]: #vfilemessagereason-options766 767[api-vfile]: #vfileoptions768 769[api-compatible]: #compatible770 771[api-data]: #data772 773[api-data-map]: #datamap774 775[api-map]: #map776 777[api-message-options]: #messageoptions778 779[api-options]: #options780 781[api-reporter]: #reporter782 783[api-reporter-settings]: #reportersettings784 785[api-value]: #value786