V4 release (#137)

* Update node api docs * Update cli docs * Add v4 migration guide * Bump deps for module and website * Add v4 docs
tclindner · Oct 6, 2019 · 7bd437c · 7bd437c
1 parent eaac08b
commit 7bd437c
Show file tree

Hide file tree

Showing 16 changed files with 1,057 additions and 563 deletions.
diff --git a/docs/api.md b/docs/api.md
@@ -3,137 +3,71 @@ id: api
 title: Node.js API
 ---
 
-npm-package-json-lint exports two main objects: `CLIEngine` and `NpmPackageJsonLint`.
+npm-package-json-lint exports one object, `NpmPackageJsonLint`.
 
-## NpmPackageJsonLint()
+## NpmPackageJsonLint(options)
 
 Creates an instance of NpmPackageJsonLint
 
-`NpmPackageJsonLint` has one public method, `lint`. `lint` takes a package.json object in object form and a config object as parameters.
+`NpmPackageJsonLint` has one public method, `lint`. `lint` takes a `NpmPackageJsonLintOptions` object.
 
-### .lint(packageJsonData, configObj)
-
-Runs configured rules against the provided package.json object.
-
-#### packageJsonData
+#### options
 
 Type: `Object`
 
-A package.json file in object form.
+A `NpmPackageJsonLint` options object.
 
-#### configObj
-
-Type: `Object`
-
-A valid configuration object.
+| Option | Type | Description | Default |
+| --- | --- | --- | --- |
+| `cwd` | {string} | The current working diretory for all file operations. | `process.cwd()` |
+| `packageJsonObject` | {Object} | A package.json object. This must be provided or a `patterns` should be provided. | -- |
+| `packageJsonFilePath` | {string} | If providing a package.json object, this option allows a file path to be assigned to it. | -- |
+| `config` | {object} | Allows for a config object to be passed as an object via code instead of a file. | -- |
+| `configFile` | {string} | Relative path to a configuration file. If provided, the config in the file will be used and npm-package-json-lint will not traverse the file system to find other config files. | -- |
+| `patterns` | {string[]} | An array of glob patterns used to find package.json files. This must be provided or a `packageJsonObject` should be provided. | -- |
+| `quiet` | {boolean} | A flag indicating whether to suppress warnings. | `false` |
+| `ignorePath` | {string} | File path to an ignore file. | `` |
 
 #### Example
 
-The following example demostrates how to use `lint`.
+The following example demostrates how to instantiate `NpmPackageJsonLint`.
 
 ```js
 const {NpmPackageJsonLint} = require('npm-package-json-lint');
 
-const npmPackageJsonLint = new NpmPackageJsonLint();
-const results = npmPackageJsonLint.lint(packageJsonDataAsObject, configObject);
+const npmPackageJsonLint = new NpmPackageJsonLint({
+  cwd,
+  packageJsonObject,
+  packageJsonFilePath,
+  config,
+  configFile,
+  configBaseDirectory,
+  patterns,
+  quiet,
+  ignorePath
+});
 ```
 
-#### Return
-
-`lint` returns an object with an array of `LintIssue`s. Please see `LintIssue` section for more detail.
+### .lint()
 
-```js
-{
-  issues: [
-    {
-      lintId: 'require-name',
-      severity: 'error',
-      node: 'name',
-      lintMessage: 'name is required'
-    }
-  ]
-}
-```
-
-### .version
-
-Calling `.version` on an instance of `NpmPackageJsonLint` will return the version number of npm-package-json-lint that the linter is associated with.
+Runs configured rules against the provided package.json object(s).
 
 #### Example
 
-```js
-const {NpmPackageJsonLint} = require('npm-package-json-lint');
-
-const npmPackageJsonLint = new NpmPackageJsonLint();
-
-npmPackageJsonLint.version;
-// => '3.0.0'
-```
-
-## CLIEngine(options)
-
-Creates an instance of CLIEngine
-
-### options
-
-Type: `Object`
-
-CLIEngine configuration object
-
-* `configFile`      {String}  Name of module/file to use.
-* `cwd`             {String}  The current working diretory for all file operations.
-* `useConfigFiles`  {Boolean} False disables use of .npmpackagejsonlintrc.json files and npmpackagejsonlint.config.js files.
-* `rules`            {Object} An object of rules to use.
-
-### Example
-
-The following example demostrates how to initialize a `CLIEngine`.
+The following example demostrates how to use `lint`.
 
 ```js
-const {CLIEngine} = require('npm-package-json-lint');
-
-const cliEngineOptions = {
-  configFile: '',
-  cwd: process.cwd(),
-  useConfigFiles: true,
-  rules: {}
-};
-
-const cliEngine = new CLIEngine(cliEngineOptions);
-```
-
-### .executeOnPackageJsonFiles(patterns)
-
-Runs npm-package-json-lint against the array a patterns.
-
-#### patterns
-
-Type: `Array`
-
-An array of glob patterns
-
-#### Example
-
-The following example demostrates how to use `executeOnPackageJsonFiles`.
+const {NpmPackageJsonLint} = require('npm-package-json-lint');
 
-```js
-const {CLIEngine} = require('npm-package-json-lint');
-
-const cliEngineOptions = {
-  configFile: '',
-  cwd: process.cwd(),
-  useConfigFiles: true,
-  rules: {}
-};
-const patterns = ['.'];
-
-const cliEngine = new CLIEngine(cliEngineOptions);
-const results = cliEngine.executeOnPackageJsonFiles(patterns);
+const npmPackageJsonLint = new NpmPackageJsonLint({
+  ...
+});
+const results = npmPackageJsonLint.lint();
 ```
 
 #### Return
 
-`executeOnPackageJsonFiles` returns an object with an array of results.
+Returns an object with an array of results.
 
 ```js
 {
@@ -149,36 +83,16 @@ const results = cliEngine.executeOnPackageJsonFiles(patterns);
         }
       ],
       errorCount: 1,
+      ignoreCount: 0,
       warningCount: 0
     }
   ],
   errorCount: 1,
+  ignoreCount: 0,
   warningCount: 0
 }
 ```
 
-### .version
-
-Calling `.version` on an instance of `CLIEngine` will return the version number of npm-package-json-lint that the CLIEngine is associated with.
-
-#### Example
-
-```js
-const {CLIEngine} = require('npm-package-json-lint');
-
-const cliEngineOptions = {
-  configFile: '',
-  cwd: process.cwd(),
-  useConfigFiles: true,
-  rules: {}
-};
-
-const cliEngine = new CLIEngine(cliEngineOptions);
-
-cliEngine.version;
-// => '3.0.0'
-```
-
 > **WARNING**
 
 Only the functions documented above are supported. All other functions that are exposed may change with any release. Please refrain from using them.
diff --git a/docs/cli.md b/docs/cli.md
@@ -80,3 +80,7 @@ $ npmPkgJsonLint . --ignorePath .gitignore
 ```
 
 > Looks for all `package.json` files in the project and exclude ignored paths. The CLI engine automatically looks for relevant config files for each package.json file that is found.
+
+## `--maxWarnings` (alias `-mw`)
+
+Max number of warnings that are allowed before an error is thrown. By default, npm-package-json-lint allows `10000000`.
diff --git a/docs/rules.md b/docs/rules.md
@@ -5,6 +5,10 @@ title: Rules
 
 Rules allow npm-package-json-lint to be fully customizable. npm-package-json-lint will only run the rules supplied. As of v2.7.0, there are multiple ways to supply [configuration](configuration.md). One of the easiest way is via a [.npmpackagejsonlintrc.json](rcfile-example.md) file. The default configuration supplied in v1 is no longer provided in v2. Please see the new default config module, [npm-package-json-lint-config-default](https://github.com/tclindner/npm-package-json-lint-config-default) instead.
 
+> Migrating from v3.x.x to 4.x.x?
+
+Please see [migrating-from-v3-to-v4](v3-to-v4.md)
+
 > Migrating from v2.x.x to 3.x.x?
 
 Please see [migrating-from-v2-to-v3](v2-to-v3.md)

diff --git a/docs/v3-to-v4.md b/docs/v3-to-v4.md
@@ -0,0 +1,14 @@
+---
+id: v3-to-v4
+title: v3 to v4 Migration Guide
+---
+
+v4.0.0 Migration Guide
+
+> FYI: v4 drops support for Node 6 and 7. If you need support for versions of Node that have reached EOL, please use v3.
+
+## Node.js API
+
+There is a new [Node.js API](api.md) available. Please see the docs.
+
+Please see the [release notes](https://github.com/tclindner/npm-package-json-lint/releases/tag/v4.0.0) for additional changes introduced in v4.0.0.
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "npm-package-json-lint",
-  "version": "4.0.0-beta.3",
+  "version": "4.0.0",
   "description": "Configurable linter for package.json files.",
   "keywords": [
     "lint",
@@ -50,7 +50,7 @@
     "strip-json-comments": "^3.0.1"
   },
   "devDependencies": {
-    "eslint": "^6.4.0",
+    "eslint": "^6.5.1",
     "eslint-config-tc": "^8.0.1",
     "eslint-formatter-pretty": "^2.1.1",
     "eslint-plugin-import": "^2.18.2",

diff --git a/website/i18n/en.json b/website/i18n/en.json
@@ -311,6 +311,9 @@
       "v2-to-v3": {
         "title": "v2 to v3 Migration Guide"
       },
+      "v3-to-v4": {
+        "title": "v3 to v4 Migration Guide"
+      },
       "why": {
         "title": "Why npm-package-json-lint?"
       },
@@ -616,9 +619,6 @@
       },
       "version-3.7.0/version-3.7.0-v2-to-v3": {
         "title": "v2 to v3 Migration Guide"
-      },
-      "version-3.7.0/version-3.7.0-why": {
-        "title": "Why npm-package-json-lint?"
       }
     },
     "links": {