@stoplight/spectral - npm Package Compare versions

Comparing version 0.1.2-beta.6 to 1.0.0

package.json

 {
   "name": "@stoplight/spectral",
-  "version": "0.1.2-beta.6",
-  "description": "An object linting framework",
-  "author": "Stoplight, Inc. ([e-mail])",
-  "license": "MIT",
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
+  "version": "1.0.0",
+  "description": "A flexible object linter with out of the box support for OpenAPI v2 and v3.",
+  "keywords": [
+    "json linter",
+    "linter",
+    "json validator",
+    "validator",
+    "OpenAPI",
+    "Swagger",
+    "schema",
+    "API"
+  ],
+  "main": "index.js",
+  "sideEffects": false,
   "files": [
-    "lib"
+    "**/*"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "format": "prettier --write \"src/**/*.{ts}\"",
-    "lint": "tslint src/**/*.{ts}",
-    "prepublishOnly": "yarn build",
-    "test": "jest",
-    "test.cover": "jest --coverage",
-    "test.prod": "yarn lint && yarn test --coverage --no-cache --maxWorkers 2",
-    "test.watch": "jest --watch"
+  "author": "Stoplight <[e-mail]>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stoplightio/spectral"
   },
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=8.3.0"
+  },
   "dependencies": {
-    "ajv": "6.5.x",
+    "@stoplight/types": "3.x.x",
+    "ajv": "6.x.x",
     "jsonpath": "git://github.com/stoplightio/jsonpath.git#fe90d42",
-    "lodash": "^4.17.11",
-    "should": "13.2.x"
+    "lodash": ">=4.17.5"
   },
-  "devDependencies": {
-    "@types/jest": "23.3.x",
-    "@types/jsonpath": "0.2.x",
-    "@types/lodash": "^4.14.118",
-    "@types/node": "10.12.x",
-    "jest": "23.6.x",
-    "prettier": "1.14.x",
-    "ts-jest": "23.10.x",
-    "tslib": "1.9.x",
-    "tslint": "5.11.x",
-    "tslint-config-prettier": "1.15.x",
-    "tslint-plugin-prettier": "2.0.x",
-    "typescript": "3.1.3"
-  },
-  "jest": {
-    "transform": {
-      "^.+\\.tsx?$": "ts-jest"
-    },
-    "testRegex": "(/__tests__/.*|(\\.|/)(test|spec))\\.(jsx?|tsx?)$",
-    "modulePathIgnorePatterns": [
-      "lib"
-    ],
-    "moduleFileExtensions": [
-      "ts",
-      "tsx",
-      "js",
-      "jsx",
-      "json",
-      "node"
-    ],
-    "testEnvironment": "node"
-  }
+  "typings": "index.d.ts"
 }

README.md

@@ -1,90 +0,233 @@
-# spectral
+# Spectral
 
-> **Warning** This is still a prototype and not ready for general use.
+[![Test Coverage](https://api.codeclimate.com/v1/badges/1aa53502913a428f40ac/test_coverage)](https://codeclimate.com/github/stoplightio/spectral/test_coverage)
+[![Maintainability](https://api.codeclimate.com/v1/badges/1aa53502913a428f40ac/maintainability)](https://codeclimate.com/github/stoplightio/spectral/maintainability)
 
-This is an enhanced version of the [speccy](https://github.com/wework/speccy)
-project. Differences between this project and speccy include:
+## Features
 
-- Lint rules can be applied to _any_ JSON object, not just OAS3 specifications.
+- Create custom rules to lint _any JSON object_.
+- Use JSON paths to apply rules / functions to specific parts of your JSON objects.
+- Built-in set of functions to help build custom rules. Functions include pattern checks, parameter checks, alphabetical ordering, a specified number of characters, provided keys are present in an object, etc.
+- Create custom functions for advanced use cases.
+- Optional ready to use rules and functions to validate and lint OpenAPI v2 _and_ v3 documents.
+- Validate JSON with [Ajv](https://github.com/epoberezkin/ajv).
 
-- All dependencies on the [oas-kit](https://github.com/Mermade/oas-kit/)
-  repository have been removed, since rules are no longer OAS-specific.
+## Installation
 
-- The rule structure has been modified slightly to use
-  [JSONPath](http://goessner.net/articles/JsonPath/) `path` parameters instead
-  of the `object` parameters (which were OAS-specific).
+```shell
+npm install @stoplight/spectral
+```
 
-- Rules are more clearly defined (thanks to TypeScript typings) and now require
-  specifying a `type` parameter.
+Supports Node v8.3+ and modern browsers.
 
-- Some rule types have been enhanced to be a little more flexible. An example of
-  this includes the ability to specify the object to be linted in the `path`
-  parameter itself, instead of relying on rule-specific options to be applied.
+## Usage
 
-- Ported to TypeScript.
+There are two key concepts in Spectral: **Rules** and **Functions**.
 
-Things that speccy has, but spectral does not (though they would be easy to add):
+- **Rules** filter your object down to a set of target values, and specify the function that should evaluate those values.
+- **Functions** accept a value and return issue(s) if the value is incorrect.
 
-- A 'server' and CLI mode
+Think of a set of **rules** and **functions** as a flexible and customizable style guide for your JSON objects.
 
-- The ability to add rules from file
+### Creating a custom rule:
 
-- The ability for rule files to specify a dependency on other rule files
+Spectral has a built-in set of functions which you can reference in your rules. This example uses the `RuleFunction.PATTERN` to create a rule that checks that all property values are in snake case.
 
-## Usage
+```javascript
+const { RuleFunction, Spectral } = require("@stoplight/spectral");
 
-```typescript
-import { Spectral } from '@stoplight/spectral';
-import { defaultRuleset } from '@stoplight/spectral/rulesets';
+const spectral = new Spectral();
 
-// an OASv2 specification
+spectral.addRules({
+  snake_case: {
+    summary: "Checks for snake case pattern",
+
+    // evaluate every property
+    given: "$..*",
+
+    then: {
+      function: RuleFunction.PATTERN,
+      functionOptions: {
+        match: "^[a-z]+[a-z0-9_]*[a-z0-9]+$"
+      }
+    }
+  }
+});
+
+const results = spectral.run({
+  name: "helloWorld"
+});
+
+console.log(JSON.stringify(results, null, 4));
+
+// => outputs a single result since `helloWorld` is not snake_case
+// {
+//   "results": [
+//     {
+//       "name": "snake_case",
+//       "message": "must match the pattern '^[a-z]+[a-z0-9_]*[a-z0-9]+$'",
+//       "severity": 50,
+//       "severityLabel": "error",
+//       "path": [
+//         "name"
+//       ]
+//     }
+//   ]
+// }
+```
+
+### Creating a custom function:
+
+Sometimes the built-in functions don't cover your use case. This example creates a custom function, `customNotThatFunction`, and then uses it within a rule, `openapi_not_swagger`. The custom function checks that you are not using a specific string (e.g., "Swagger") and suggests what to use instead (e.g., "OpenAPI").
+
+```javascript
+const { Spectral } = require("@stoplight/spectral");
+
+// custom function
+const customNotThatFunction = (targetValue, options) => {
+  const { match, suggestion } = options;
+
+  if (targetValue && targetValue.match(new RegExp(match))) {
+    // return the single error
+    return [
+      {
+        message: `Use ${suggestion} instead of ${match}!`
+      }
+    ];
+  }
+};
+
+const spectral = new Spectral();
+
+spectral.addFunctions({
+  notThat: customNotThatFunction
+});
+
+spectral.addRules({
+  openapi_not_swagger: {
+    summary: "Checks for use of Swagger, and suggests OpenAPI.",
+
+    // check every property
+    given: "$..*",
+
+    then: {
+      // reference the function we added!
+      function: "notThat",
+
+      // pass it the options it needs
+      functionOptions: {
+        match: "Swagger",
+        suggestion: "OpenAPI"
+      }
+    }
+  }
+});
+
+const results = spectral.run({
+  description: "Swagger is pretty cool!"
+});
+
+console.log(JSON.stringify(results, null, 4));
+
+// => outputs a single result since we are using the term `Swagger` in our object
+// {
+//   "results": [
+//     {
+//       "name": "openapi_not_swagger",
+//       "message": "Use OpenAPI instead of Swagger!",
+//       "severity": 50,
+//       "severityLabel": "error",
+//       "path": [
+//         "description"
+//       ]
+//     }
+//   ]
+// }
+```
+
+### Linting an OAS 2 document:
+
+Spectral also includes a number of ready made rules and functions for OpenAPI 2 and 3 documents. This example uses the OpenAPI 2 rules to lint an OpenAPI 2 document.
+
+You can also add to these rules to create a customized linting style guide for your OAS documents.
+
+```javascript
+const { Spectral } = require("@stoplight/spectral");
+const {
+  oas2Functions,
+  oas2Rules
+} = require("@stoplight/spectral/rulesets/oas2");
+
+// an OASv2 document
 var myOAS = {
-  [...]
+  // ... properties in your document
   responses: {
-    '401asdf': {
-      description: '',
+    "200": {
+      description: "",
       schema: {
-        $ref: '#/definitions/error-response',
-      },
-    },
-  },
-  [...]
+        $ref: "#/definitions/error-response"
+      }
+    }
+  }
+  // ... properties in your document
 };
 
 // create a new instance of spectral with all of the baked in rulesets
-const spectral = new Spectral({ rulesets: [defaultRuleset()] });
+const spectral = new Spectral();
 
+spectral.addFunctions(oas2Functions());
+spectral.addRules(oas2Rules());
+
+spectral.addRules({
+  // .. extend with your own custom rules
+});
+
 // run!
-console.log(spectral.run({ spec: 'oas2', target: myOAS }));
+const results = spectral.run(myOAS);
 
-//  [ {
-//   path: '$.responses',
-//   rule:
-//     { type: 'pattern',
-//       name: 'all-responses-must-be-numeric',
-//       path: '$..responses',
-//       enabled: true,
-//       description: 'reference components should all match regex ^[0-9]+',
-//       pattern: { property: '*', value: '^[0-9]+$' } },
-//     error:
-//       Error {
-//         operator: 'to be',
-//         expected: true,
-//         message: 'reference components should all match regex ^[0-9]+',
-//         showDiff: true,
-//         actual: false,
-//         stackStartFunction: [Function: assert],
-//         negate: false,
-//         assertion:
-//         Assertion {
-//           obj: false,
-//           anyOne: false,
-//           negate: false,
-//           params: [Object],
-//           onlyThis: undefined,
-//           light: false } } } ]
+console.log(JSON.stringify(results, null, 4));
 ```
 
+Note: The existing OAS rules are opinionated. There might be some rules that you prefer to change. We encourage you to create your rules to fit your use case. We welcome additions to the existing rulesets as well!
+
+### Example Implementations
+
+- [Spectral Bot](https://github.com/tbarn/spectral-bot), a GitHub pull request bot that lints your repo's OAS document that uses the [Probot](https://probot.github.io) framework, built by [Taylor Barnett](https://github.com/tbarn)
+
+## FAQs
+
+**How is this different than [Ajv](https://github.com/epoberezkin/ajv)?**
+
+Ajv is a JSON Schema validator, not a linter. Spectral does expose a `schema` function that you can use in your rules to validate all or part of the target object with JSON Schema (Ajv is used under the hood). However, Spectral also provides a number of other functions and utilities that you can use to build up a linting ruleset to validates things that JSON Schema is not well suited for.
+
+**I want to lint my OpenAPI Specification documents but don't want to implement Spectral right now.**
+
+No problem! A hosted version of Spectral comes **free** with the Stoplight platform. Sign up for a free account [here](https://stoplight.io/?utm_source=github&utm_campaign=spectral).
+
+**What is the difference between Spectral and [Speccy](https://github.com/wework/speccy)?**
+
+With Spectral, lint rules can be applied to _any_ JSON object, not just OAS 3 documents. The rule structure is different between the two. Spectral uses [JSONPath](http://goessner.net/articles/JsonPath/) `path` parameters instead of the `object` parameters (which are OAS-specific). Rules are also more clearly defined (thanks to TypeScript typings) and now require specifying a `type` parameter. Some rule types have been enhanced to be a little more flexible along with being able to create your own rules based on the built-in and custom functions.
+
+## Contributing
+
+If you are interested in contributing to Spectral itself, check out our [contributing docs](CONTRIBUTING.md) to get started.
+
+If you are using Spectral in your open source project and want to be listed in the examples section, we encourage you to open an [issue](https://github.com/stoplightio/spectral/issues).
+
 ## Helpful Links
 
-- [JSONPath Tester](https://jsonpath.curiousconcept.com/)
+- [JSONPath Online Evaluator](http://jsonpath.com/), a helpful tool to determine what `path` you want
+- [stoplightio/json](https://github.com/stoplightio/json), a library of useful functions for when working with JSON
+- [stoplightio/yaml](https://github.com/stoplightio/yaml), a library of useful functions for when working with YAML, including parsing YAML into JSON with a source map that includes JSONPath pointers for every property in the result
+
+## Thanks :)
+
+- [Phil Sturgeon](https://github.com/philsturgeon) for collaboration and creating Speccy
+
+## Support
+
+If you have a bug or feature request, please open an issue [here](https://github.com/stoplightio/spectral/issues).
+
+If you need help using Spectral or have a support question, please use the [Stoplight Community forum](https://community.stoplight.io). We've created an open source category for these questions. It's also a great place to share your implementations.
+
+If you want to discuss something in private, you can reach out to Stoplight support at [[e-mail]](mailto:[e-mail]).

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

No repository

Supply chain risk

Package does not have a linked source code repository. Without this field, a package will have no reference to the location of the source code use to generate the package.

Found 1 instance in 1 package

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Improved metrics

Dev dependency count

0

decreased by-100%

Number of low quality alerts

1

decreased by-50%

Number of lines in readme file

234

increased by157.14%

Number of low supply chain risk alerts

0

decreased by-100%

Worsened metrics

Total package byte prevSize

227433

decreased by-15.04%

Number of package files

83

decreased by-15.31%

Lines of code

5071

decreased by-16.5%

Number of medium supply chain risk alerts

1

increased byInfinity%

Dependency changes

• + Added@stoplight/types@3.x.x

• + Added@stoplight/types@3.1.0(transitive)

• + Addedajv@6.12.6(transitive)

• + Addedfast-deep-equal@3.1.3(transitive)

• - Removedshould@13.2.x

• - Removedajv@6.5.5(transitive)

• - Removedfast-deep-equal@2.0.1(transitive)

• - Removedshould@13.2.3(transitive)

• - Removedshould-equal@2.0.0(transitive)

• - Removedshould-format@3.0.3(transitive)

• - Removedshould-type@1.4.0(transitive)

• - Removedshould-type-adaptors@1.1.0(transitive)

• - Removedshould-util@1.0.1(transitive)

• Updatedajv@6.x.x

• Updatedlodash@>=4.17.5