Release 5.0

.circleci/config.yml

@@ -1,5 +1,8 @@
 version: 2.1
 
+orbs:
+  stoplight: stoplight/[email protected]
+
 commands:
   cached-dependencies:
     steps:
@@ -64,12 +67,6 @@ jobs:
     steps:
       - install-and-test
 
-  test-node-8:
-    docker:
-      - image: circleci/node:8-browsers
-    steps:
-      - install-and-test
-
   release:
     docker:
       - image: circleci/node:10
@@ -88,11 +85,12 @@ jobs:
           else
             npm publish
           fi
-      - run: yarn build.binary
+      - run: npx pkg . --targets linux,macos --out-path ./binaries
       - persist_to_workspace:
           root: ./
           paths:
             - binaries
+
   upload_artifacts:
     docker:
       - image: circleci/golang:1-stretch
@@ -109,10 +107,9 @@ jobs:
 workflows:
   commit:
     jobs:
-      - test-node-latest
+      # - test-node-latest TODO bring it back when circle supports node-13
       - test-node-12
       - test-node-10
-      - test-node-8
   release:
     jobs:
       - release:
@@ -129,3 +126,11 @@ workflows:
               only: /^v.*/
           requires:
             - release
+      - stoplight/analyze:
+          filters:
+            branches:
+              ignore: /.*/
+            tags:
+              only: /^v.*/
+          requires:
+            - release

.dependabot/config.yml

@@ -0,0 +1,35 @@
+version: 1
+update_configs:
+  - package_manager: "javascript"
+    directory: "/"
+    update_schedule: "live"
+    version_requirement_updates: increase_versions
+
+    commit_message:
+      prefix: "fix"
+      include_scope: true
+
+    allowed_updates:
+      - match:
+          dependency_name: "@stoplight/*" # match all Stoplight deps, regardless of type
+          update_type: "all"
+      - match:
+          dependency_type: "production"
+          update_type: "all"
+      - match:
+          dependency_type: "development"
+          update_type: "security"
+
+  - package_manager: "javascript"
+    directory: "/"
+    update_schedule: "weekly" # we do not need to check for devDependencies updates on a daily basis
+    version_requirement_updates: increase_versions
+
+    commit_message:
+      prefix: "chore"
+      include_scope: true
+
+    allowed_updates:
+      - match:
+          dependency_type: "development"
+          update_type: "all"

.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+
+[*.{ts,js,yaml,scenario,md}]
+indent_style = space
+indent_size = 2
+
+[*.{ts,js}]
+trim_trailing_whitespace = true
+insert_final_newline = true

.github/workflows/automerge.yml

@@ -19,6 +19,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: automerge
+        if: github.actor != 'dependabot-preview[bot]' && github.actor != 'dependabot[bot]'
         uses: "pascalgn/[email protected]"
         env:
           GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"

.github/workflows/markdown-links.yml

@@ -0,0 +1,16 @@
+name: Check Markdown Links
+
+on:
+  pull_request:
+    branches:
+      - master
+      - develop
+
+jobs:
+  markdown-link-check:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@master
+      with:
+        fetch-depth: 1
+    - uses: gaurav-nelson/github-action-markdown-link-check@master

.gitignore

@@ -7,7 +7,7 @@
 
 /binaries
 /rulesets
-/src/__tests__/__fixtures__/oas-functions.json
+/__karma__/__fixtures__/
 /test-harness/tmp/
 
 # testing

.nvmrc

@@ -0,0 +1 @@
+10.15.3

CHANGELOG.md

@@ -5,6 +5,44 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.0.0] - 2019-12-24
+
+### Features
+- Alphabetical rule function now supports numeric keys [#730](https://github.com/stoplightio/spectral/issues/730)
+- Non-JSON-ish YAML mapping keys are reported [#726](https://github.com/stoplightio/spectral/issues/726)
+- CLI: new formatter - text [#822](https://github.com/stoplightio/spectral/issues/822)
+- CLI: new formatter - teamcity [#823](https://github.com/stoplightio/spectral/issues/823)
+- CLI: new formatter - HTML [#389](https://github.com/stoplightio/spectral/issues/389)
+- CLI: custom resolver can be provided leveraging --resolver flag [#717](https://github.com/stoplightio/spectral/issues/717)
+- CLI: input can be provided via STDIN [#757](https://github.com/stoplightio/spectral/issues/757)
+- Implement ignoreUnsupportedFormats to make it easier to detect unrecognized formats [#678](https://github.com/stoplightio/spectral/issues/678)
+- Rule's Given can be an array now [#799](https://github.com/stoplightio/spectral/pull/799)
+- Casing built-in function is added [#564](https://github.com/stoplightio/spectral/issues/564)
+- New oas rule - `operation-tag-defined` [#704](https://github.com/stoplightio/spectral/pull/704)
+
+### Changed
+- BREAKING: The oas2 and oas3 rulesets have been merged into a single oas ruleset [#773](https://github.com/stoplightio/spectral/pull/773)
+- BREAKING: Deprecated Spectral#addRules and Spectral#addFunctions have been removed [#561](https://github.com/stoplightio/spectral/issues/561)
+- BREAKING: Some oas rules, such as `example-value-or-externalValue` and `openapi-tags`, are now included in the recommended rulset [#725](https://github.com/stoplightio/spectral/issues/725) [#706](https://github.com/stoplightio/spectral/pull/706)
+- BREAKING: The `model-description` and `operation-summary-formatted` rules have been removed [#725](https://github.com/stoplightio/spectral/issues/725)
+- BREAKING: The `when` rule property has been removed [#585](https://github.com/stoplightio/spectral/issues/585)
+- BREAKING: Rules are set to recommended by default [#719](https://github.com/stoplightio/spectral/pull/719)
+- Improved error source detection [#685](https://github.com/stoplightio/spectral/pull/685)
+- Error paths point at unresolved document [#839](https://github.com/stoplightio/spectral/pull/839)
+- Validation messages contain more consistent error paths [#867](https://github.com/stoplightio/spectral/pull/867)
+- CLI: Default `--fail-severity` is now `error`, so getting a  `warn`, `info` or a `hint` will not return a exit status code [#706](https://github.com/stoplightio/spectral/pull/706)
+- Rulesets no longer require a `rules` property [#652](https://github.com/stoplightio/spectral/pull/652)
+
+### Fixed
+- Circular remote references with JSON pointers are resolved correctly [json-ref-resolver#141](https://github.com/stoplightio/json-ref-resolver/pull/141)
+- Local root JSON pointers are resolved correctly [json-ref-resolver#146](https://github.com/stoplightio/json-ref-resolver/pull/146) 
+- Invalid JSON pointers are reported as errors now [json-ref-resolver#140](https://github.com/stoplightio/json-ref-resolver/pull/140) and [json-ref-resolver#147](https://github.com/stoplightio/json-ref-resolver/pull/147)
+- Unixify glob patterns under Windows [#679](https://github.com/stoplightio/spectral/issues/679)
+- Improved duplicate keys detection [#751](https://github.com/stoplightio/spectral/issues/751)
+- Spectral should be usable in browsers with no crypto module available [#846](https://github.com/stoplightio/spectral/pull/846)
+- Falsy values are printed in validation messages [#824](https://github.com/stoplightio/spectral/pull/824)
+- Validation results are no longer duplicate [#680](https://github.com/stoplightio/spectral/issues/680), [#737](https://github.com/stoplightio/spectral/pull/737) and [#856](https://github.com/stoplightio/spectral/pull/856)
+
 ## [4.2.0] - 2019-10-08
 
 ### Features

CONTRIBUTING.md

@@ -23,7 +23,9 @@ Yarn is a package manager for your code, similar to npm. While you can use npm t
 5. Build Spectral: `yarn build`
 6. Run Spectral from your local installation: `node dist/cli/index.js lint [openapi_spec_file]`
 7. Create a new branch for your work: `git checkout -b [name_of_your_new_branch]`
-8. Make changes, add tests, and then run the tests: `yarn test.prod`
+8. Make changes, add tests, and then run the tests: `yarn test.prod` and `yarn test.harness`
+9. Update the documentation if appropriate. For example, if you added a new rule to an OpenAPI ruleset,
+add a description of the rule in `docs/reference/openapi-rules.md`.
 
 Now, you are ready to commit & push your changes, and make a pull request to the Spectral repo! 😃
 
@@ -33,7 +35,7 @@ If this is your first Pull Request on GitHub, here's some [help](https://egghead
 
 ## To run tests
 
-We run tests in the two envirnoments that Spectral supports - the browser, and node.js. Browser tests are run in a headless Chrome browser via the Karma test runner, while node.js tests are run via the Jest test runner.
+We run tests in the two environments that Spectral supports - the browser, and node.js. Browser tests are run in a headless Chrome browser via the Karma test runner, while node.js tests are run via the Jest test runner.
 
 Tests should usually be written for both environments, but there are valid cases when you need to write separate tests for each test runner. To do so, just create a file with `*.karma.test.ts` suffix or `*.jest.test.ts`. A good example of Jest only tests are the tests covering Spectral's CLI functionality - something that obviously is not relevant to the browser context.
 
@@ -61,6 +63,12 @@ Running a specific test:
 yarn test src/cli/commands/__tests__/lint.test.ts
 ```
 
+Running the harness tests (these must pass or the PR merge will be blocked):
+
+```bash
+yarn test.harness
+```
+
 ## Creating an issue
 
 We want to keep issues in this repo focused on bug reports and feature requests. 

README.md

@@ -1,8 +1,6 @@
 ![Spectral logo](img/spectral-banner.png)
 
-[![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)
-[![Build Status](https://dev.azure.com/vncz/vncz/_apis/build/status/stoplightio.spectral?branchName=develop)](https://dev.azure.com/vncz/vncz/_build/latest?definitionId=4&branchName=develop)
+[![Buy us a tree](https://img.shields.io/badge/Buy%20us%20a%20tree-%F0%9F%8C%B3-lightgreen)](https://offset.earth/stoplightinc)
 [![CircleCI](https://circleci.com/gh/stoplightio/spectral.svg?style=svg)](https://circleci.com/gh/stoplightio/spectral)
 
 A flexible JSON linter with out of the box support for OpenAPI v2 and v3.
@@ -79,6 +77,7 @@ If you are using Spectral in your project and want to be listed in the examples
 - [Mike Ralphson](https://github.com/MikeRalphson) for kicking off the Spectral CLI and his work on Speccy
 - [Jamund Ferguson](https://github.com/xjamundx) for JUnit formatter
 - [Sindre Sorhus](https://github.com/sindresorhus) for Stylish formatter
+- Julian Laval for HTML formatter
 
 ## Support
 

docs/getting-started/rulesets.md

@@ -18,7 +18,9 @@ rules:
       function: truthy
 ```
 
+Spectral has a built-in set of functions such as `truthy` or `pattern`, which you can reference in your rules.
 The example above adds a single rule that checks that tags objects have a description property defined.
+Since v5.0, each rule is recommended by default. Prior to that the default was to be not recommended. It is best to be explicit and set `recommended: true` or `recommended: false` if a ruleset is likely to be used across multiple versions.
 
 Running `spectral lint` on the following object with the ruleset above will result in an error being reported, since the tag does not have a description:
 
@@ -76,9 +78,8 @@ Specifying the format is optional, so you can completely ignore this if all the
 
 ```yaml
 rules:
-  api-servers:
+  oas3-api-servers:
     description: "OpenAPI `servers` must be present and non-empty array."
-    recommended: true
     formats: ["oas3"]
     given: "$"
     then:
@@ -99,7 +100,7 @@ Alternatively, formats can be specified at the ruleset level:
 ```yaml
 formats: ["oas3"]
 rules:
-  api-servers:
+  oas3-api-servers:
     description: "OpenAPI `servers` must be present and non-empty array."
     recommended: true
     given: "$"
@@ -118,9 +119,15 @@ Now all the rules in this ruleset will only be applied if the specified format i
 
 Custom formats can be registered via the [JS API](../guides/javascript.md), but the CLI is limited to using the predefined ones.
 
+## Given
+
+The `given` keyword is, besides `then`, the only required property on each rule definition. 
+It can be any valid JSONPath expression or an array of JSONPath expressions.
+[JSONPath Online Evaluator](http://jsonpath.com/) is a helpful tool to determine what `given` path you want.
+
 ## Severity
 
-The `severity` keyword is optional and can be `error`, `warn`, `info`, or `hint`.
+The `severity` keyword is optional and can be `error`, `warn`, `info`, or `hint`. The default value is `warn`.
 
 ## Then
 
@@ -155,12 +162,10 @@ responses:
 
 ## Extending rules
 
-Rulesets can extend other rulesets. For example, Spectral comes with two built in rulesets - one for OpenAPI v2 (`spectral:oas2`), and one for OpenAPI v3 (`spectral:oas3`). 
-
-Use the `extends` property in your ruleset file to build upon or customize other rulesets.
+Rulesets can extend other rulesets using the `extends` property. This can be used to build upon or customize other rulesets.
 
 ```yaml
-extends: spectral:oas2
+extends: spectral:oas
 rules:
   my-rule-name:
     description: Tags must have a description.
@@ -185,45 +190,62 @@ extends:
 Sometimes you might want to apply specific rules from another ruleset. Use the `extends` property, and pass `off` as the second argument in order to add the rules from another ruleset, but disable them all by default. This allows you to pick and choose which rules you would like to enable.
 
 ```yaml
-extends: [[spectral:oas2, off]]
+extends: [[spectral:oas, off]]
 rules:
-  # This rule is defined in the spectral:oas2 ruleset. We're passing `true` to turn it on and inherit the severity defined in the spectral:oas2 ruleset.
+  # This rule is defined in the spectral:oas ruleset. We're passing `true` to turn it on and inherit the severity defined in the spectral:oas ruleset.
   operation-operationId-unique: true
 ```
 
-The example above will run the single rule that we enabled, since we passed `off` to disable all rules by default when extending the `spectral:oas2` ruleset.
+The example above will run the single rule that we enabled, since we passed `off` to disable all rules by default when extending the `spectral:oas` ruleset.
 
 ## Disabling rules
 
 This example shows the opposite of the "Enabling Specific rules" example. Sometimes you might want to enable all rules by default, and disable a few.
 
 ```yaml
-extends: [[spectral:oas2, all]]
+extends: [[spectral:oas, all]]
 rules:
   operation-operationId-unique: false
 ```
 
-The example above will run all of the rules defined in the `spectral:oas2` ruleset (rather than the default behavior that runs only the recommended ones), with one exceptions - we turned `operation-operationId-unique` off.
+The example above will run all of the rules defined in the `spectral:oas` ruleset (rather than the default behavior that runs only the recommended ones), with one exceptions - we turned `operation-operationId-unique` off.
 
-The current recommended rules are marked with the property `recommended: true` in their respective rulesets:
+- [Rules relevant to OpenAPI v2 and v3](../reference/openapi-rules.md)
 
-- [Rules relevant to both OpenAPI v2 and v3](https://github.com/stoplightio/spectral/tree/master/src/rulesets/oas/index.json)
-- [Rules specific to only OpenAPI v2](https://github.com/stoplightio/spectral/tree/master/src/rulesets/oas2/index.json)
-- [Rules specific to only OpenAPI v3](https://github.com/stoplightio/spectral/tree/master/src/rulesets/oas3/index.json)
 
 ## Changing rule severity
 
 ```yaml
-extends: spectral:oas2
+extends: spectral:oas
 rules:
   operation-2xx-response: warn
 ```
 
-The example above will run the recommended rules from the `spectral:oas2` ruleset, but report `operation-2xx-response` as a warning rather than as an error (as is the default behavior in the `spectral:oas2` ruleset).
+The example above will run the recommended rules from the `spectral:oas` ruleset, but report `operation-2xx-response` as a warning rather than as an error (as is the default behavior in the `spectral:oas` ruleset).
 
 Available severity levels are `error`, `warn`, `info`, `hint`, and `off`.
 
+## Enriching rule messages
+
+To help you create meaningful error messages, Spectral comes with a couple of placeholders that are evaluated at runtime.
+
+- {{error}} - the error returned by function
+- {{description}} - the description set on the rule
+- {{path}} - the whole error path
+- {{property}} - the last segment of error path
+- {{value}} - the linted value
 
+### Examples
+
+```yaml
+message: "{{error}}" # will output the message generated by then.function 
+
+message: "The value of '{{property}}' property must equal 'foo'"
+
+message: "{{value}} is greater than 0"
+
+message: "{{path}} cannot point at remote reference"
+```
 ## Creating custom functions
 
 Learn more about [custom functions](../guides/custom-functions.md).