editorconfig 0.15.3 → 1.0.0

package/README.md

@@ -1,12 +1,11 @@
 # EditorConfig JavaScript Core
 
-[![Build Status](https://travis-ci.org/editorconfig/editorconfig-core-js.svg?branch=master)](https://travis-ci.org/editorconfig/editorconfig-core-js)
-[![dependencies Status](https://david-dm.org/editorconfig/editorconfig-core-js/status.svg)](https://david-dm.org/editorconfig/editorconfig-core-js)
+[![Tests](https://github.com/editorconfig/editorconfig-core-js/actions/workflows/node.js.yml/badge.svg)](https://github.com/editorconfig/editorconfig-core-js/actions/workflows/node.js.yml)
+[![Coverage Status](https://coveralls.io/repos/github/editorconfig/editorconfig-core-js/badge.svg?branch=master)](https://coveralls.io/github/editorconfig/editorconfig-core-js?branch=master)
 
 The EditorConfig JavaScript core will provide the same functionality as the
 [EditorConfig C Core][] and [EditorConfig Python Core][].
 
-
 ## Installation
 
 You need [node][] to use this package.
@@ -25,33 +24,74 @@ $ npm install -g editorconfig
 
 ## Usage
 
-### in Node.js:
-
-#### parse(filePath[, options])
+### Options
 
-options is an object with the following defaults:
+Most of the API takes an `options` object, which has the following defaults:
 
 ```js
 {
   config: '.editorconfig',
   version: pkg.version,
-  root: '/'
+  root: '/',
+  files: undefined,
+  cache: undefined,
 };
 ```
 
-Search for `.editorconfig` starting from the current directory to the root directory.
+<dl>
+  <dt>config</dt>
+  <dd>The name of the config file to look for in the current and every parent
+      directory.</dd>
+
+  <dt>version</dt>
+  <dd>Which editorconfig spec version to use.  Earlier versions had different
+      defaults.</dd>
+
+  <dt>root</dt>
+  <dd>What directory to stop processing in, even if we haven't found a file
+      containing root=true.  Defaults to the root of the filesystem containing
+      `process.cwd()`.</dd>
+
+  <dt>files</dt>
+  <dd>Pass in an empty array, which will be filled with one object for each
+      config file processed.  The objects will have the shape
+      `{filename: "[DIRECTORY]/.editorconfig", glob: "*"}`</dd>
+
+  <dt>cache</dt>
+  <dd>If you are going to process more than one file in the same project, pass
+      in a cache object.  It must have `get(string): object|undefined` and
+      `set(string, object)` methods, like a JavaScript Map.  A long-running
+      process might want to consider that this cache might grow over time,
+      and that the config files might change over time.  However, we leave any
+      complexity of that nature to the caller, since there are so many different
+      approaches that might be taken based on latency, memory, and CPU trade-offs.
+      Note that some of the objects in the cache will be for files that did not
+      exist.  Those objects will have a `notfound: true` property.  All of the
+      objects will have a `name: string` property that contains the
+      fully-qualified file name of the config file and a `root: boolean` property
+      that describes if the config file had a `root=true` at the top.  Any other
+      properties in the objects should be treated as opaque.</dd>
+</dl>
+
+### in Node.js:
+
+#### parse(filePath[, options])
+
+Search for `.editorconfig` files starting from the current directory to the
+root directory.  Combine all of the sections whose section names match
+filePath into a single object.
 
 Example:
 
 ```js
-var editorconfig = require('editorconfig');
-var path = require('path');
-var filePath = path.join(__dirname, '/sample.js');
-var promise = editorconfig.parse(filePath);
-promise.then(function onFulfilled(result) {
-  console.log(result);
-});
+const editorconfig = require('editorconfig');
+const path = require('path');
 
+const filePath = path.join(__dirname, 'sample.js');
+
+(async () => {
+  console.log(await editorconfig.parse(filePath, {files: []}));
+})();
 /*
   {
     indent_style: 'space',
@@ -62,6 +102,10 @@ promise.then(function onFulfilled(result) {
     insert_final_newline: true,
     tab_width: 2
   };
+  assert.deepEqual(files, [
+    { fileName: '[DIRECTORY]/.editorconfig', glob: '*' },
+    { fileName: '[DIRECTORY]/.editorconfig', glob: '*.js' }
+  ])
 */
 ```
 
@@ -69,44 +113,42 @@ promise.then(function onFulfilled(result) {
 
 Synchronous version of `editorconfig.parse()`.
 
-#### parseString(fileContent)
+#### parseBuffer(fileContent)
 
-The `parse()` function above uses `parseString()` under the hood. If you have your file contents
-just pass it to `parseString()` and it'll return the same results as `parse()`.
+The `parse()` function above uses `parseBuffer()` under the hood. If you have
+the contents of a config file, and want to see what is being processed for
+just that file rather than the full directory hierarchy, this might be useful.
 
-#### parseFromFiles(filePath, configs[, options])
+#### parseString(fileContent)
 
-options is an object with the following defaults:
+This is a thin wrapper around `parseBuffer()` for backward-compatibility.
+Prefer `parseBuffer()` to avoid an unnecessary UTF8-to-UTF16-to-UTF8
+conversion.  Deprecated.
 
-```js
-{
-  config: '.editorconfig',
-  version: pkg.version,
-  root: '/'
-};
-```
+#### parseFromFiles(filePath, configs[, options])
 
-Specify the `.editorconfig`.
+Low-level interface, which exists only for backward-compatibility.  Deprecated.
 
 Example:
 
 ```js
-var editorconfig = require('editorconfig');
-var fs = require('fs');
-var path = require('path');
-var configPath = path.join(__dirname, '/.editorconfig');
-var configs = [
+const editorconfig = require('editorconfig');
+const fs = require('fs');
+const path = require('path');
+
+const configPath = path.join(__dirname, '.editorconfig');
+const configs = [
   {
     name: configPath,
     contents: fs.readFileSync(configPath, 'utf8')
   }
 ];
-var filePath = path.join(__dirname, '/sample.js');
-var promise = editorconfig.parseFromFiles(filePath, configs);
-promise.then(function onFulfilled(result) {
-  console.log(result)
-});
 
+const filePath = path.join(__dirname, '/sample.js');
+
+(async () => {
+  console.log(await editorconfig.parseFromFiles(filePath, Promise.resolve(configs)))
+})();
 /*
   {
     indent_style: 'space',
@@ -122,25 +164,26 @@ promise.then(function onFulfilled(result) {
 
 #### parseFromFilesSync(filePath, configs[, options])
 
-Synchronous version of `editorconfig.parseFromFiles()`.
+Synchronous version of `editorconfig.parseFromFiles()`.  Deprecated.
 
 ### in Command Line
 
 ```bash
 $ ./bin/editorconfig
 
-    Usage: editorconfig [OPTIONS] FILEPATH1 [FILEPATH2 FILEPATH3 ...]
-
-    EditorConfig Node.js Core Version 0.11.4-development
-
-    FILEPATH can be a hyphen (-) if you want path(s) to be read from stdin.
+Usage: editorconfig [options] <FILEPATH...>
 
-    Options:
+Arguments:
+  FILEPATH       Files to find configuration for.  Can be a hyphen (-) if you
+                 want path(s) to be read from stdin.
 
-        -h, --help     output usage information
-        -V, --version  output the version number
-        -f <path>      Specify conf filename other than ".editorconfig"
-        -b <version>   Specify version (used by devs to test compatibility)
+Options:
+  -v, --version  Display version information from the package
+  -f <path>      Specify conf filename other than '.editorconfig'
+  -b <version>   Specify version (used by devs to test compatibility)
+  --files        Output file names that contributed to the configuration,
+                 rather than the configuation itself
+  -h, --help     display help for command
 ```
 
 Example:
@@ -154,6 +197,13 @@ tab_width=8
 trim_trailing_whitespace=sometimes
 ```
 
+```bash
+$ ./bin/editorconfig --files /home/zoidberg/humans/anatomy.md
+/home/zoidberg/.editorconfig [*]
+/home/zoidberg/.editorconfig [*.md]
+/home/zoidberg/humans/.editorconfig [*]
+```
+
 ## Development
 
 To install dependencies for this package run this in the package directory:
@@ -166,8 +216,7 @@ Next, run the following commands:
 
 ```bash
 $ npm run build
-$ npm run copy
-$ npm link ./dist
+$ npm link
 ```
 
 The global editorconfig will now point to the files in your development
@@ -197,7 +246,7 @@ $ npm test
 To run the tests with increased verbosity (for debugging test failures):
 
 ```bash
-$ npm run-script test-verbose
+$ npm run ci
 ```
 
 [EditorConfig C Core]: https://github.com/editorconfig/editorconfig-core

package/bin/editorconfig

@@ -1,3 +1,6 @@
 #!/usr/bin/env node
-var cli = require('../src/cli')
-cli.default(process.argv)
+var cli = require('../lib/cli')
+cli.default(process.argv).catch(e => {
+  console.error(e)
+  process.exit(1)
+})

package/lib/cli.d.ts

@@ -0,0 +1,14 @@
+import { type OutputConfiguration } from 'commander';
+import * as editorconfig from './';
+/**
+ * Command line interface for editorconfig.  Pulled out into a separate module
+ * to make it easier to test.
+ *
+ * @param args Usually process.argv.  Note that the first two parameters are
+ * usually 'node' and 'editorconfig'
+ * @param testing If testing, you may pass in a Commander OutputConfiguration
+ * so that you can capture stdout and stderror.  If `testing` is provided,
+ * this routine will throw an error instead of calling `process.exit`.
+ * @returns An array of combined properties, one for each file argument.
+ */
+export default function cli(args: string[], testing?: OutputConfiguration): Promise<editorconfig.Props[]>;

package/lib/cli.js

@@ -0,0 +1,109 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const editorconfig = __importStar(require("./"));
+const package_json_1 = __importDefault(require("../package.json"));
+/**
+ * Default output routine, goes to stdout.
+ *
+ * @param s String to output
+ */
+function writeStdOut(s) {
+    process.stdout.write(s);
+}
+/**
+ * Command line interface for editorconfig.  Pulled out into a separate module
+ * to make it easier to test.
+ *
+ * @param args Usually process.argv.  Note that the first two parameters are
+ * usually 'node' and 'editorconfig'
+ * @param testing If testing, you may pass in a Commander OutputConfiguration
+ * so that you can capture stdout and stderror.  If `testing` is provided,
+ * this routine will throw an error instead of calling `process.exit`.
+ * @returns An array of combined properties, one for each file argument.
+ */
+async function cli(args, testing) {
+    const program = new commander_1.Command();
+    let writeOut = writeStdOut;
+    if (testing) {
+        if (testing.writeOut) {
+            // eslint-disable-next-line @typescript-eslint/unbound-method
+            writeOut = testing.writeOut;
+        }
+        program.configureOutput(testing);
+        program.exitOverride();
+    }
+    program.version('EditorConfig Node.js Core Version ' + package_json_1.default.version, '-v, --version', 'Display version information')
+        .showHelpAfterError()
+        .argument('<FILEPATH...>', 'Files to find configuration for.  Can be a hyphen (-) if you want path(s) to be read from stdin.')
+        .option('-f <path>', 'Specify conf filename other than \'.editorconfig\'')
+        .option('-b <version>', 'Specify version (used by devs to test compatibility)')
+        .option('--files', 'Output file names that contributed to the configuration, rather than the configuation itself')
+        .parse(args);
+    const files = program.args;
+    const opts = program.opts();
+    const cache = new Map();
+    const visited = opts.files ?
+        files.map(() => []) :
+        undefined;
+    // Process sequentially so caching works
+    async function processAll() {
+        const p = [];
+        let i = 0;
+        for (const filePath of files) {
+            p.push(await editorconfig.parse(filePath, {
+                config: opts.f,
+                version: opts.b,
+                files: visited ? visited[i++] : undefined,
+                cache,
+            }));
+        }
+        return p;
+    }
+    return await processAll().then((parsed) => {
+        const header = parsed.length > 1;
+        parsed.forEach((props, i) => {
+            if (header) {
+                writeOut(`[${files[i]}]\n`);
+            }
+            if (visited) {
+                for (const v of visited[i]) {
+                    writeOut(`${v.fileName} [${v.glob}]\n`);
+                }
+            }
+            else {
+                for (const [key, value] of Object.entries(props)) {
+                    writeOut(`${key}=${String(value)}\n`);
+                }
+            }
+        });
+        return parsed;
+    });
+}
+exports.default = cli;

package/lib/index.d.ts

@@ -0,0 +1,105 @@
+/// <reference types="node" />
+import minimatch from 'minimatch';
+export interface KnownProps {
+    end_of_line?: 'lf' | 'crlf' | 'unset';
+    indent_style?: 'tab' | 'space' | 'unset';
+    indent_size?: number | 'tab' | 'unset';
+    insert_final_newline?: true | false | 'unset';
+    tab_width?: number | 'unset';
+    trim_trailing_whitespace?: true | false | 'unset';
+    charset?: string | 'unset';
+}
+interface UnknownMap {
+    [index: string]: unknown;
+}
+export declare type Props = KnownProps & UnknownMap;
+export interface ECFile {
+    name: string;
+    contents?: Buffer;
+}
+declare type SectionGlob = minimatch.Minimatch | null;
+declare type GlobbedProps = [SectionName, Props, SectionGlob][];
+export interface ProcessedFileConfig {
+    root: boolean;
+    name: string;
+    config: GlobbedProps;
+    notfound?: true;
+}
+export interface Visited {
+    fileName: string;
+    glob: string;
+}
+export interface Cache {
+    get(path: string): ProcessedFileConfig | undefined;
+    set(path: string, config: ProcessedFileConfig): this;
+}
+export interface ParseOptions {
+    config?: string;
+    version?: string;
+    root?: string;
+    files?: Visited[];
+    cache?: Cache;
+}
+export declare type SectionName = string | null;
+export interface SectionBody {
+    [key: string]: string;
+}
+export declare type ParseStringResult = [SectionName, SectionBody][];
+/**
+ * Parse a buffer using the faster one-ini WASM approach into something
+ * relatively easy to deal with in JS.
+ *
+ * @param data UTF8-encoded bytes.
+ * @returns Parsed contents.  Will be truncated if there was a parse error.
+ */
+export declare function parseBuffer(data: Buffer): ParseStringResult;
+/**
+ * Parses a string.  If possible, you should always use ParseBuffer instead,
+ * since this function does a UTF16-to-UTF8 conversion first.
+ *
+ * @param data String to parse.
+ * @returns Parsed contents.  Will be truncated if there was a parse error.
+ * @deprecated Use {@link ParseBuffer} instead.
+ */
+export declare function parseString(data: string): ParseStringResult;
+/**
+ * Low-level interface, which exists only for backward-compatibility.
+ * Deprecated.
+ *
+ * @param filepath The name of the target file, relative to process.cwd().
+ * @param files A promise for a list of objects describing the files.
+ * @param options All options
+ * @returns The properties found for filepath
+ * @deprecated
+ */
+export declare function parseFromFiles(filepath: string, files: Promise<ECFile[]>, options?: ParseOptions): Promise<Props>;
+/**
+ * Low-level interface, which exists only for backward-compatibility.
+ * Deprecated.
+ *
+ * @param filepath The name of the target file, relative to process.cwd().
+ * @param files A list of objects describing the files.
+ * @param options All options
+ * @returns The properties found for filepath
+ * @deprecated
+ */
+export declare function parseFromFilesSync(filepath: string, files: ECFile[], options?: ParseOptions): Props;
+/**
+ * Find all of the properties from matching sections in config files in the
+ * same directory or toward the root of the filesystem.
+ *
+ * @param filepath The target file name, relative to process.cwd().
+ * @param options All options
+ * @returns Combined properties for the target file
+ */
+export declare function parse(filepath: string, options?: ParseOptions): Promise<Props>;
+/**
+ * Find all of the properties from matching sections in config files in the
+ * same directory or toward the root of the filesystem.  Synchronous.
+ *
+ * @param filepath The target file name, relative to process.cwd().
+ * @param options All options
+ * @returns Combined properties for the target file
+ */
+export declare function parseSync(filepath: string, options?: ParseOptions): Props;
+export {};