chore: package readmes

CONTRIBUTING.md

@@ -12,6 +12,18 @@ The Stoplight Community is dedicated to providing a safe, inclusive, welcoming,
 
 Our Code of Conduct exists because of that dedication, and we do not tolerate harassment in any form. See our reporting guidelines [here](https://github.com/stoplightio/code-of-conduct/blob/master/incident-reporting.md). Our full Code of Conduct can be found at this [link](https://github.com/stoplightio/code-of-conduct/blob/master/long-form-code-of-conduct.md#long-form-code-of-conduct).
 
+## Repository Structure
+The Spectral repo is managed as a monorepo that is composed of multiple packages:
+
+- [core](./packages/core) - contains classes, functions and types used in other packages.
+- [cli](./packages/cli) - package for spectral command-line interface
+- [rulesets](./packages/rulesets) - container for rules and functions
+- [functions](./packages/functions) - built-in functions which can be used in rulesets
+- [formats](./packages/formats)
+- [parsers](./packages/parsers)
+- [ref-resolver](./packages/ref-resolver)
+- [runtime](./packages/runtime)
+
 ## Development
 
 Yarn is a package manager for your code, similar to npm. While you can use npm to use Spectral in your own project, we use yarn for development of Spectral.
@@ -21,7 +33,7 @@ Yarn is a package manager for your code, similar to npm. While you can use npm t
 3. In your terminal, navigate to the directory you cloned Spectral into (check that you are on the `develop` branch).
 4. Install the dependencies: `yarn`
 5. Build Spectral: `yarn build`
-6. Run Spectral from your local installation: `yarn cli lint [openapi_spec_file]`
+6. Run Spectral from your local installation: `yarn cli cli 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` and `yarn test.harness`
 9. Update the documentation if appropriate. For example, if you added a new rule to an OpenAPI ruleset,

README.md

@@ -22,11 +22,11 @@
 **Install**
 
 ```bash
-npm install -g @stoplight/spectral
+npm install -g @stoplight/spectral-cli
 
 # OR
 
-yarn global add @stoplight/spectral
+yarn global add @stoplight/spectral-cli
 ```
 
 Find more [installation methods](https://meta.stoplight.io/docs/spectral/docs/getting-started/2-installation.md) in our documentation.

docs/getting-started/1-concepts.md

@@ -18,6 +18,6 @@ Rules can be comprised of one of more functions, to facilitate any style guide.
 - Tags must be plural
 - Tags must be singular
 
-Spectral comes bundled with a [bunch of functions](../reference/functions.md) and default style guides for [OpenAPI v2 and v3](./4-openapi.md) and [AsyncAPI v2](./5-asyncapi.md), which you can extend, cherry-pick, or disable entirely.
+Spectral comes bundled with a [bunch of functions](../../packages/functions/docs/core-functions.md) and default style guides for [OpenAPI v2 and v3](./4-openapi.md) and [AsyncAPI v2](./5-asyncapi.md), which you can extend, cherry-pick, or disable entirely.
 
-[Learn more about rulesets](./3-rulesets.md).
+[Learn more about rulesets](../../packages/rulesets/docs/rulesets.md).

docs/getting-started/2-installation.md

@@ -3,13 +3,13 @@
 For many, the easiest way to install Spectral is as a node module.
 
 ```bash
-npm install -g @stoplight/spectral
+npm install -g @stoplight/spectral-cli
 ```
 
 If you are a Yarn user:
 
 ```bash
-yarn global add @stoplight/spectral
+yarn global add @stoplight/spectral-cli
 ```
 
 ## Executable Binaries

docs/guides/1-workflows.md

@@ -2,7 +2,7 @@
 
 When and where should you use Spectral? It depends a lot how you are creating and managing your API description documents, but probably wherever they are being made.
 
-- Run [Spectral CLI](2-cli.md) against design docs and get feedback very early on.
+- Run [Spectral CLI](../../packages/cli/README.md) against design docs and get feedback very early on.
 - Run Spectral in [Stoplight Studio](https://stoplight.io/studio/) or [VS Code](https://github.com/stoplightio/vscode-spectral) automatically as you work, without switching to the CLI.
 
 ## Linting Design-First Workflows
@@ -42,7 +42,7 @@ Folks will forget to run Spectral, and that means they can commit broken or (low
 }
 ```
 
-See our [CLI documentation](./2-cli.md) to see what other arguments and options can be used.
+See our [CLI documentation](../../packages/cli/README.md) to see what other arguments and options can be used.
 
 ## Continuous Integration
 

docs/guides/3-javascript.md

@@ -79,7 +79,7 @@ spectral.registerFormat("json-schema-draft7", isJSONSchemaDraft7);
 spectral.registerFormat("json-schema-2019-09", isJSONSchemaDraft2019_09);
 ```
 
-Learn more about predefined formats in the [ruleset documentation](../getting-started/3-rulesets.md#formats).
+Learn more about predefined formats in the [ruleset documentation](../../packages/formats/README.md).
 
 ## Loading Rules
 

docs/migration-guides/4.0.md

@@ -78,7 +78,7 @@ In the above example, all recommended rules from built-in OAS2 ruleset would be
 
 This change shouldn't hurt you much, as the CLI supports _all_ flags that the config file did, so no functionality will be missing.
 
-Ruleset files are quite flexible in Spectral v4, see [docs](../getting-started/3-rulesets.md) for more info.
+Ruleset files are quite flexible in Spectral v4, see [docs](../../packages/rulesets/docs/rulesets.md) for more info.
 
 2. `--max-results` flag is removed
 

docs/reference/openapi-rules.md

@@ -2,7 +2,7 @@
 
 Spectral has a built-in "oas" ruleset, with OAS being shorthand for the [OpenAPI Specification](https://openapis.org/specification).
 
-In your ruleset file you can add `extends: "spectral:oas"` and you'll get all of the following rules applied, depending on the appropriate OpenAPI version used (detected through [formats](../getting-started/3-rulesets.md#formats)).
+In your ruleset file you can add `extends: "spectral:oas"` and you'll get all of the following rules applied, depending on the appropriate OpenAPI version used (detected through [formats](../../packages/formats/README.md)).
 
 ## OpenAPI v2 & v3
 

package.json

@@ -24,6 +24,7 @@
   },
   "scripts": {
     "clean": "rimraf packages/*/{dist,.cache}",
+    "cli": "yarn workspace @stoplight/spectral-cli",
     "build": "tsc --build ./tsconfig.build.json",
     "postbuild": "lerna run postbuild",
     "lint": "yarn lint.prettier && yarn lint.eslint && yarn lint.changelog",

docs/guides/2-cli.md → packages/cli/README.md

@@ -1,6 +1,6 @@
 # Spectral CLI
 
-[Once installed](../getting-started/2-installation.md), Spectral can be run via the command-line:
+Once installed, Spectral can be run via the command-line:
 
 ```bash
 spectral lint petstore.yaml
@@ -46,7 +46,7 @@ The Spectral CLI supports loading documents as YAML or JSON, and validation of O
 
 If you don't specify a ruleset file with the `--ruleset` parameter, the Spectral CLI will look for a ruleset file called `.spectral.yml`, `.spectral.yaml`, or `.spectral.json` in the current working directory. If no ruleset is specified and no default ruleset file is found, the built-in rulesets will be used.
 
-Here you can build a [custom ruleset](../getting-started/3-rulesets.md), or extend and modify our core rulesets:
+Here you can build a [custom ruleset](../../packages/rulesets/docs/rulesets.md), or extend and modify our core rulesets:
 
 - [OpenAPI ruleset](../reference/openapi-rules.md)
 - [AsyncAPI ruleset](../reference/asyncapi-rules.md)
@@ -83,4 +83,4 @@ module.exports = new Resolver({
 });
 ```
 
-You can learn more about `$ref` resolving in the [JS section](./3-javascript.md#using-custom-resolver).
+You can learn more about `$ref` resolving in the [JS section](../../docs/guides/3-javascript.md#using-custom-resolver).

docs/getting-started/3-rulesets.md → packages/formats/README.md

@@ -1,54 +1,4 @@
-# Rulesets
-
-Rulesets are collections of rules written in JSON or YAML, which can be used to power powerful linting of other JSON or YAML files. Meta, we know! 😎
-
-These rules are taking parameters, and calling functions on certain parts of another YAML or JSON object being linted.
-
-## Anatomy of a Ruleset
-
-A ruleset is a JSON or YAML file ([often the file will be called `.spectral.yaml`](../guides/2-cli.md#using-a-ruleset-file)), and there are two main parts.
-
-### Rules
-
-Rules might look a bit like this:
-
-```yaml
-rules:
-  my-rule-name:
-    description: Tags must have a description.
-    given: $.tags[*]
-    severity: error
-    then:
-      field: description
-      function: truthy
-```
-
-Spectral has [built-in functions](../reference/functions.md) such as `truthy` or `pattern`, which can be used to power rules.
-
-Rules then target certain chunks of the JSON/YAML with the `given` keyword, which is a [JSONPath](http://jsonpath.com/) (actually, we use [JSONPath Plus](https://www.npmjs.com/package/jsonpath-plus)).
-
-The example above adds a single rule that looks at the root level `tags` object's children to make sure they all have a `description` property.
-
-### Extending Rulesets
-
-Rulesets can extend other rulesets using the `extends` property, allowing you to pull in other rulesets.
-
-```yaml
-extends: spectral:oas
-```
-
-Extends can reference any [distributed ruleset](../guides/7-sharing-rulesets.md). It can be a single string, or an array of strings, and can contain either local file paths, URLs, or even NPM modules.
-
-```yaml
-extends:
-  - ./config/spectral.json
-  - https://example.org/api/style.yaml
-  - some-npm-module
-```
-
-The `extends` keyword can be combined with extra rules in order to extend and override rulesets. Learn more about that in [custom rulesets](../guides/4-custom-rulesets.md).
-
-### Formats
+# Formats
 
 Formats are an optional way to specify which API description formats a rule, or ruleset, is applicable to. Currently Spectral supports these formats:
 
@@ -118,13 +68,4 @@ rules:
       # ...
 ```
 
-Custom formats can be registered via the [JS API](../guides/3-javascript.md), but the [CLI](../guides/2-cli.md) is limited to using the predefined formats.
-
-## Core Rulesets
-
-Spectral comes with two rulesets included:
-
-- `spectral:oas` - [OpenAPI v2/v3 rules](./4-openapi.md)
-- `spectral:asyncapi` - [AsyncAPI v2 rules](./5-asyncapi.md)
-
-You can also make your own: read more about [Custom Rulesets](../guides/4-custom-rulesets.md).
+Custom formats can be registered via the [JS API](../../docs/guides/3-javascript.md), but the [CLI](../cli/README.md) is limited to using the predefined formats.

docs/reference/functions.md → packages/functions/docs/core-functions.md

@@ -1,6 +1,6 @@
 # Core Functions
 
-Rules use "functions" and those can be custom defined. To save everyone the effort of writing functions for common tasks, Spectral comes with a few bundled out of the box. If you find these don't do what you need, you can [also write custom functions](../guides/5-custom-functions.md).
+Rules use "functions" and those can be custom defined. To save everyone the effort of writing functions for common tasks, Spectral comes with a few bundled out of the box.
 
 ## alphabetical
 

docs/guides/5-custom-functions.md → packages/functions/docs/custom-functions.md

@@ -1,6 +1,6 @@
 # Custom Functions
 
-If the core functions are not enough for your [custom ruleset](../getting-started/3-rulesets.md), Spectral allows you to write and use your own custom functions.
+If the core functions are not enough for your [custom ruleset](../rulests/README.md), Spectral allows you to write and use your own custom functions.
 
 Create a directory to contain your new functions. By default `functions/` is assumed.
 
@@ -18,7 +18,7 @@ module.exports = targetVal => {
 };
 ```
 
-The function is exported anonymously but it has the name `abc` from the file. This name is then loaded in your [ruleset](./4-custom-rulesets.md), via `functions: [abc]`.
+The function is exported anonymously but it has the name `abc` from the file. This name is then loaded in your [ruleset](../rulests/custom-rulesets.md), via `functions: [abc]`.
 
 **my-ruleset.yaml**
 

docs/guides/4-custom-rulesets.md → packages/rulesets/docs/custom-rulesets.md

@@ -21,7 +21,7 @@ rules:
       function: truthy
 ```
 
-Spectral has [built-in functions](../reference/functions.md) such as `truthy` or `pattern`, which can be used to power rules.
+Spectral has [built-in functions](../../functions/docs/core-functions.md) such as `truthy` or `pattern`, which can be used to power rules.
 
 ### Given
 
@@ -80,7 +80,7 @@ rules:
 
 ### Then
 
-The `then` part of the rule explains which function to apply to the `given` JSONPath. The function you apply [may be one of the core functions](../reference/functions.md) or it may be [a custom function](./5-custom-functions.md).
+The `then` part of the rule explains which function to apply to the `given` JSONPath. The function you apply [may be one of the core functions](../../functions/docs/core-functions.md) or it may be [a custom function](../../functions/docs/custom-functions.md).
 
 `then` has two required keywords:
 
@@ -101,7 +101,7 @@ then:
     match: "^[0-9]+$"
 ```
 
-The above [`pattern` based rule](../reference/functions.md#pattern) would error on `456avbas` as it is not numeric.
+The above [`pattern` based rule](../../functions/docs/core-functions.md#pattern) would error on `456avbas` as it is not numeric.
 
 ```yaml
 responses:
@@ -260,8 +260,8 @@ rules:
 
 ## Core Functions
 
-Several functions [are provided by default](../reference/functions.md) for your rules.
+Several functions [are provided by default](../../functions/docs/core-functions.md) for your rules.
 
 ## Custom Functions
 
-If none of the [core functions](../reference/functions.md) do what you want, you can [write your own custom functions](./5-custom-functions.md).
+If none of the [core functions](../../functions/docs/core-functions.md) do what you want, you can [write your own custom functions](../../functions/docs/custom-functions.md).

packages/rulesets/docs/rulesets.md

@@ -0,0 +1,64 @@
+# Rulesets
+
+Rulesets are collections of rules written in JSON or YAML, which can be used to power powerful linting of other JSON or YAML files. Meta, we know! 😎
+
+These rules are taking parameters, and calling functions on certain parts of another YAML or JSON object being linted.
+
+## Anatomy of a Ruleset
+
+A ruleset is a JSON or YAML file ([often the file will be called `.spectral.yaml`](../../cli/README.md#using-a-ruleset-file)), and there are two main parts.
+
+### Rules
+
+Rules might look a bit like this:
+
+```yaml
+rules:
+  my-rule-name:
+    description: Tags must have a description.
+    given: $.tags[*]
+    severity: error
+    then:
+      field: description
+      function: truthy
+```
+
+Spectral has [built-in functions](../../functions/docs/core-functions.md) such as `truthy` or `pattern`, which can be used to power rules.
+
+Rules then target certain chunks of the JSON/YAML with the `given` keyword, which is a [JSONPath](http://jsonpath.com/) (actually, we use [JSONPath Plus](https://www.npmjs.com/package/jsonpath-plus)).
+
+The example above adds a single rule that looks at the root level `tags` object's children to make sure they all have a `description` property.
+
+### Extending Rulesets
+
+Rulesets can extend other rulesets using the `extends` property, allowing you to pull in other rulesets.
+
+```yaml
+extends: spectral:oas
+```
+
+Extends can reference any [distributed ruleset](./sharing-rulesets.md). It can be a single string, or an array of strings, and can contain either local file paths, URLs, or even NPM modules.
+
+```yaml
+extends:
+  - ./config/spectral.json
+  - https://example.org/api/style.yaml
+  - some-npm-module
+```
+
+The `extends` keyword can be combined with extra rules in order to extend and override rulesets. Learn more about that in [custom rulesets](./custom-rulesets.md).
+
+### Formats
+
+Formats are an optional way to specify which API description formats a rule, or ruleset, is applicable to.
+
+You can read more about that in [formats package](../formats/README.md).
+
+## Core Rulesets
+
+Spectral comes with two rulesets included:
+
+- `spectral:oas` - [OpenAPI v2/v3 rules](./4-openapi.md)
+- `spectral:asyncapi` - [AsyncAPI v2 rules](./5-asyncapi.md)
+
+You can also make your own: read more about [Custom Rulesets](../rulesets/README.md).

docs/guides/7-sharing-rulesets.md → packages/rulesets/docs/sharing-rulesets.md

@@ -1,6 +1,6 @@
 # Sharing & Distributing Rulesets
 
-A [ruleset](../getting-started/3-rulesets.md) becomes infinitely more useful when other developers are using it. By itself, it's just a way of enforcing some rules on a single project, but when distributed a ruleset can become a "style guide" for enforcing consistency across a whole bunch of projects!
+A [ruleset](./rulesets.md) becomes infinitely more useful when other developers are using it. By itself, it's just a way of enforcing some rules on a single project, but when distributed a ruleset can become a "style guide" for enforcing consistency across a whole bunch of projects!
 
 To help you out distribute your rulesets among the others, Spectral provides a few ways to load rulesets from a variety of resources:
 
@@ -38,7 +38,7 @@ extends:
   - https://raw.githubusercontent.com/openapi-contrib/style-guides/master/apisyouwonthate.yml
 ```
 
-As with any ruleset, you can pass these directly to the [Spectral CLI](./2-cli.md):
+As with any ruleset, you can pass these directly to the [Spectral CLI](../../cli/README.md):
 
 ```shell
 spectral lint -r https://example.com/some-ruleset.yml