From 1057287a54a1421468450be5206b53c78547337a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A8ve=20Sfartz?= Date: Mon, 29 Aug 2022 23:08:11 +0200 Subject: [PATCH 01/13] docs(repo): update for the documentation URL example (#2258) --- docs/guides/4-custom-rulesets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/4-custom-rulesets.md b/docs/guides/4-custom-rulesets.md index 9d1a1e5c2c..4cef09bf47 100644 --- a/docs/guides/4-custom-rulesets.md +++ b/docs/guides/4-custom-rulesets.md @@ -265,7 +265,7 @@ rules: notMatch: basic ``` -In this example, violations of the `tag-description` rule would indicate `https://www.example.com/docs/api-ruleset.md#tag-description` as the location for finding out more about the rule. +In this example, violations of the `no-http-basic` rule would indicate `https://www.example.com/docs/api-style-guide.md#no-http-basic` as the location for finding out more about the rule. If no `documentationUrl` is provided, no links will show up, and users will just have to rely on the error messages to figure out how the errors can be fixed. From 9d6884ccce9f5940082c13e02d40d84aec0fc35f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20Ro=C5=BCek?= Date: Tue, 30 Aug 2022 13:25:48 +0200 Subject: [PATCH 02/13] chore(parsers): include LICENSE --- packages/parsers/LICENSE | 190 ++++++++++++++++++++++++++++++++++ packages/parsers/package.json | 2 +- 2 files changed, 191 insertions(+), 1 deletion(-) create mode 100644 packages/parsers/LICENSE diff --git a/packages/parsers/LICENSE b/packages/parsers/LICENSE new file mode 100644 index 0000000000..ba50e461e6 --- /dev/null +++ b/packages/parsers/LICENSE @@ -0,0 +1,190 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + Copyright 2018 Stoplight, Inc. + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/packages/parsers/package.json b/packages/parsers/package.json index 60953af57a..3899a5a8db 100644 --- a/packages/parsers/package.json +++ b/packages/parsers/package.json @@ -5,7 +5,7 @@ "bugs": "https://github.com/stoplightio/spectral/issues", "author": "Stoplight ", "engines": { - "node": ">=12" + "node": "^12.20 || >=14.13" }, "license": "Apache-2.0", "main": "dist/index.js", From 59dacc2ebe41a1c1034002e0c9cb6d445a91df7f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20Ro=C5=BCek?= Date: Tue, 30 Aug 2022 13:44:54 +0200 Subject: [PATCH 03/13] chore(ruleset-migrator): include LICENSE --- packages/ruleset-migrator/LICENSE | 190 ++++++++++++++++++++++++++++++ 1 file changed, 190 insertions(+) create mode 100644 packages/ruleset-migrator/LICENSE diff --git a/packages/ruleset-migrator/LICENSE b/packages/ruleset-migrator/LICENSE new file mode 100644 index 0000000000..ba50e461e6 --- /dev/null +++ b/packages/ruleset-migrator/LICENSE @@ -0,0 +1,190 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + Copyright 2018 Stoplight, Inc. + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. From 7d16080b91f043f9e9d8559ecb1c8e432c986580 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20Ro=C5=BCek?= Date: Tue, 30 Aug 2022 13:52:25 +0200 Subject: [PATCH 04/13] chore(ruleset-migrator): update deps --- packages/ruleset-migrator/package.json | 8 +++--- yarn.lock | 39 +++++++------------------- 2 files changed, 14 insertions(+), 33 deletions(-) diff --git a/packages/ruleset-migrator/package.json b/packages/ruleset-migrator/package.json index eb75a9e769..b66c1a6ea6 100644 --- a/packages/ruleset-migrator/package.json +++ b/packages/ruleset-migrator/package.json @@ -21,13 +21,13 @@ "url": "https://github.com/stoplightio/spectral.git" }, "dependencies": { - "@stoplight/json": "~3.17.0", - "@stoplight/ordered-object-literal": "1.0.2", + "@stoplight/json": "~3.20.1", + "@stoplight/ordered-object-literal": "~1.0.4", "@stoplight/path": "1.3.2", "@stoplight/spectral-functions": "^1.0.0", "@stoplight/spectral-runtime": "^1.1.0", - "@stoplight/types": "^12.3.0", - "@stoplight/yaml": "4.2.2", + "@stoplight/types": "^13.6.0", + "@stoplight/yaml": "~4.2.3", "@types/node": "*", "ajv": "^8.6.0", "ast-types": "0.14.2", diff --git a/yarn.lock b/yarn.lock index 2c2cd3f658..56dfe95e22 100644 --- a/yarn.lock +++ b/yarn.lock @@ -2463,7 +2463,7 @@ __metadata: languageName: node linkType: hard -"@stoplight/json@npm:3.17.0, @stoplight/json@npm:~3.17.0": +"@stoplight/json@npm:3.17.0": version: 3.17.0 resolution: "@stoplight/json@npm:3.17.0" dependencies: @@ -2499,17 +2499,10 @@ __metadata: languageName: node linkType: hard -"@stoplight/ordered-object-literal@npm:1.0.2": - version: 1.0.2 - resolution: "@stoplight/ordered-object-literal@npm:1.0.2" - checksum: 46eba542a594885aa57e786883046217cfbe1b7bb4261899b12b30fb76058139c4e3b5bd4061e388bf0f327bb6e18b9858c4e47ff129fceb2b1afee4bf45cfa5 - languageName: node - linkType: hard - -"@stoplight/ordered-object-literal@npm:^1.0.1, @stoplight/ordered-object-literal@npm:^1.0.2, @stoplight/ordered-object-literal@npm:^1.0.3": - version: 1.0.3 - resolution: "@stoplight/ordered-object-literal@npm:1.0.3" - checksum: 091c0e5569e00f40a8bbd3ec0304d3282dac24dc6fc22dad594e008390c2022b4d32557cfb10528aa81a44fe4067085a2b973716f3e710318b3a08ff32c12d6c +"@stoplight/ordered-object-literal@npm:^1.0.1, @stoplight/ordered-object-literal@npm:^1.0.2, @stoplight/ordered-object-literal@npm:^1.0.3, @stoplight/ordered-object-literal@npm:~1.0.4": + version: 1.0.4 + resolution: "@stoplight/ordered-object-literal@npm:1.0.4" + checksum: 81afa24943880b0a213af3728a9fe0a28bd01d4840b9583d448f7823ced5b6e673628698b59d201cef50afebcbd89256e133714a174968d11b624d943e0c2c2f languageName: node linkType: hard @@ -2683,15 +2676,15 @@ __metadata: version: 0.0.0-use.local resolution: "@stoplight/spectral-ruleset-migrator@workspace:packages/ruleset-migrator" dependencies: - "@stoplight/json": ~3.17.0 - "@stoplight/ordered-object-literal": 1.0.2 + "@stoplight/json": ~3.20.1 + "@stoplight/ordered-object-literal": ~1.0.4 "@stoplight/path": 1.3.2 "@stoplight/spectral-core": ^1.1.0 "@stoplight/spectral-functions": ^1.0.0 "@stoplight/spectral-rulesets": ^1.1.0 "@stoplight/spectral-runtime": ^1.1.0 - "@stoplight/types": ^12.3.0 - "@stoplight/yaml": 4.2.2 + "@stoplight/types": ^13.6.0 + "@stoplight/yaml": ~4.2.3 "@types/node": "*" ajv: ^8.6.0 ast-types: 0.14.2 @@ -2755,7 +2748,7 @@ __metadata: languageName: node linkType: hard -"@stoplight/types@npm:^12.0.0, @stoplight/types@npm:^12.3.0": +"@stoplight/types@npm:^12.3.0": version: 12.5.0 resolution: "@stoplight/types@npm:12.5.0" dependencies: @@ -2782,18 +2775,6 @@ __metadata: languageName: node linkType: hard -"@stoplight/yaml@npm:4.2.2": - version: 4.2.2 - resolution: "@stoplight/yaml@npm:4.2.2" - dependencies: - "@stoplight/ordered-object-literal": ^1.0.1 - "@stoplight/types": ^12.0.0 - "@stoplight/yaml-ast-parser": 0.0.48 - tslib: ^2.2.0 - checksum: 4ca96f28783672aa4e2ecf71ed80c9842997a5d145a77db0af74c717254d1a48e49e883451b90c29521742421745cb45e1434e9af8ed801d5ce02c7a4fe1ce8d - languageName: node - linkType: hard - "@stoplight/yaml@npm:^4.2.2, @stoplight/yaml@npm:~4.2.3": version: 4.2.3 resolution: "@stoplight/yaml@npm:4.2.3" From 573e112c694d1876546faf208c53cd2e66c7f713 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20Ro=C5=BCek?= Date: Tue, 30 Aug 2022 14:06:17 +0200 Subject: [PATCH 05/13] fix(ruleset-migrator): http/https uris not followed correctly (#2247) --- .../src/__tests__/ruleset.test.ts | 55 +++++++++++++++++++ packages/ruleset-migrator/src/tree/index.ts | 10 ++-- 2 files changed, 60 insertions(+), 5 deletions(-) diff --git a/packages/ruleset-migrator/src/__tests__/ruleset.test.ts b/packages/ruleset-migrator/src/__tests__/ruleset.test.ts index 161bd1f3f3..4f41b3d7a7 100644 --- a/packages/ruleset-migrator/src/__tests__/ruleset.test.ts +++ b/packages/ruleset-migrator/src/__tests__/ruleset.test.ts @@ -161,6 +161,61 @@ describe('migrator', () => { }); }); + it('should follow links correctly', async () => { + serveAssets({ + 'http://domain/bitbucket/projects/API/repos/spectral-rules/raw/.spectral.yml?at=refs%2Fheads%2Fmaster': { + extends: ['spectral:oas', 'oas-rules.yml'], + rules: { + 'valid-type': 'error', + }, + }, + 'http://domain/bitbucket/projects/API/repos/spectral-rules/raw/oas-rules.yml': { + rules: { + 'valid-type': { + given: '$', + function: { + then: 'truthy', + }, + }, + }, + }, + }); + + await vol.promises.writeFile( + path.join(cwd, 'ruleset.json'), + JSON.stringify({ + extends: [ + 'http://domain/bitbucket/projects/API/repos/spectral-rules/raw/.spectral.yml?at=refs%2Fheads%2Fmaster', + ], + }), + ); + + expect( + await migrateRuleset(path.join(cwd, 'ruleset.json'), { + format: 'esm', + fs: vol as any, + }), + ).toEqual(`import {oas} from "@stoplight/spectral-rulesets"; +export default { + "extends": [{ + "extends": [oas, { + "rules": { + "valid-type": { + "given": "$", + "function": { + "then": "truthy" + } + } + } + }], + "rules": { + "valid-type": "error" + } + }] +}; +`); + }); + describe('custom npm registry', () => { it('should be supported', async () => { serveAssets({ diff --git a/packages/ruleset-migrator/src/tree/index.ts b/packages/ruleset-migrator/src/tree/index.ts index 42205c9e1b..1acc8d69d3 100644 --- a/packages/ruleset-migrator/src/tree/index.ts +++ b/packages/ruleset-migrator/src/tree/index.ts @@ -128,11 +128,6 @@ export class Tree { if (path.isURL(identifier) || path.isAbsolute(identifier)) { resolved = identifier; this.#resolvedPaths.add(identifier); - } else if (kind === 'ruleset' && isPackageImport(identifier)) { - resolved = - ctx.npmRegistry !== null - ? path.join(ctx.npmRegistry, identifier) - : requireResolve?.(identifier, { paths: [ctx.cwd] }) ?? path.join(ctx.cwd, identifier); } else if ( (ctx.npmRegistry !== null && ctx.filepath.startsWith(ctx.npmRegistry)) || isKnownNpmRegistry(ctx.filepath) @@ -142,6 +137,11 @@ export class Tree { // / // // where asset can be a custom fn, etc. resolved = path.join(ctx.filepath, identifier); + } else if (kind === 'ruleset' && !path.isURL(ctx.filepath) && isPackageImport(identifier)) { + resolved = + ctx.npmRegistry !== null + ? path.join(ctx.npmRegistry, identifier) + : requireResolve?.(identifier, { paths: [ctx.cwd] }) ?? path.join(ctx.cwd, identifier); } else { resolved = path.join(ctx.filepath, '..', identifier); this.#resolvedPaths.add(resolved); From e06fd4239d8db05a5ec7f91518bcaeef51f051e9 Mon Sep 17 00:00:00 2001 From: stoplight-bot Date: Tue, 30 Aug 2022 12:12:31 +0000 Subject: [PATCH 06/13] chore(release): 1.7.4 [skip ci] # [@stoplight/spectral-ruleset-migrator-v1.7.4](https://github.com/stoplightio/spectral/compare/@stoplight/spectral-ruleset-migrator-v1.7.3...@stoplight/spectral-ruleset-migrator-v1.7.4) (2022-08-30) ### Bug Fixes * **ruleset-migrator:** http/https uris not followed correctly ([#2247](https://github.com/stoplightio/spectral/issues/2247)) ([573e112](https://github.com/stoplightio/spectral/commit/573e112c694d1876546faf208c53cd2e66c7f713)) --- packages/ruleset-migrator/CHANGELOG.md | 7 +++++++ packages/ruleset-migrator/package.json | 2 +- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/packages/ruleset-migrator/CHANGELOG.md b/packages/ruleset-migrator/CHANGELOG.md index cacc596d9d..16f8cb095b 100644 --- a/packages/ruleset-migrator/CHANGELOG.md +++ b/packages/ruleset-migrator/CHANGELOG.md @@ -1,3 +1,10 @@ +# [@stoplight/spectral-ruleset-migrator-v1.7.4](https://github.com/stoplightio/spectral/compare/@stoplight/spectral-ruleset-migrator-v1.7.3...@stoplight/spectral-ruleset-migrator-v1.7.4) (2022-08-30) + + +### Bug Fixes + +* **ruleset-migrator:** http/https uris not followed correctly ([#2247](https://github.com/stoplightio/spectral/issues/2247)) ([573e112](https://github.com/stoplightio/spectral/commit/573e112c694d1876546faf208c53cd2e66c7f713)) + # [@stoplight/spectral-ruleset-migrator-v1.7.3](https://github.com/stoplightio/spectral/compare/@stoplight/spectral-ruleset-migrator-v1.7.2...@stoplight/spectral-ruleset-migrator-v1.7.3) (2022-03-10) diff --git a/packages/ruleset-migrator/package.json b/packages/ruleset-migrator/package.json index b66c1a6ea6..60b949f657 100644 --- a/packages/ruleset-migrator/package.json +++ b/packages/ruleset-migrator/package.json @@ -1,6 +1,6 @@ { "name": "@stoplight/spectral-ruleset-migrator", - "version": "1.7.3", + "version": "1.7.4", "homepage": "https://github.com/stoplightio/spectral", "bugs": "https://github.com/stoplightio/spectral/issues", "author": "Stoplight ", From aa6d91557598ea817537f1ef40f1878a19a86f25 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20Ro=C5=BCek?= Date: Tue, 30 Aug 2022 22:13:54 +0200 Subject: [PATCH 07/13] chore(core): include LICENSE --- packages/core/LICENSE | 190 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 190 insertions(+) create mode 100644 packages/core/LICENSE diff --git a/packages/core/LICENSE b/packages/core/LICENSE new file mode 100644 index 0000000000..ba50e461e6 --- /dev/null +++ b/packages/core/LICENSE @@ -0,0 +1,190 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + Copyright 2018 Stoplight, Inc. + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. From aacdcd77f0ff38c880f6292904449d0af5e7eed4 Mon Sep 17 00:00:00 2001 From: Frederic Kayser <61844946+FredericKayser@users.noreply.github.com> Date: Tue, 30 Aug 2022 22:20:17 +0200 Subject: [PATCH 08/13] perf(core): bump jsonpath-plus to 7.1.0 (#2259) --- packages/core/package.json | 2 +- yarn.lock | 35 +++++++++++++++++++++-------------- 2 files changed, 22 insertions(+), 15 deletions(-) diff --git a/packages/core/package.json b/packages/core/package.json index beaede8482..e43497456c 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -52,7 +52,7 @@ "ajv-formats": "~2.1.0", "blueimp-md5": "2.18.0", "es-aggregate-error": "^1.0.7", - "jsonpath-plus": "6.0.1", + "jsonpath-plus": "7.1.0", "lodash": "~4.17.21", "lodash.topath": "^4.5.2", "minimatch": "3.1.2", diff --git a/yarn.lock b/yarn.lock index 56dfe95e22..adf1e99410 100644 --- a/yarn.lock +++ b/yarn.lock @@ -1816,20 +1816,20 @@ __metadata: linkType: hard "@jsep-plugin/regex@npm:^1.0.1": - version: 1.0.1 - resolution: "@jsep-plugin/regex@npm:1.0.1" + version: 1.0.2 + resolution: "@jsep-plugin/regex@npm:1.0.2" peerDependencies: jsep: ^0.4.0||^1.0.0 - checksum: db0f196af5142deb250fca04bdec373dc3d1c3d3a925acddad4dfa0422d89cdfde3fe45c6b0bfe825965c9cbaf7a20c9bb02251c49cf2b84679595b52bc44618 + checksum: b19f1cb160d5b026f93aeaf586cf506288c4ce588dc7e7b794f1da3ea950e969bdd6b2cfc7e31ad4b9b7860d15db116f7bb0a0cee9d0db59109869312f2fbf92 languageName: node linkType: hard "@jsep-plugin/ternary@npm:^1.0.2": - version: 1.0.2 - resolution: "@jsep-plugin/ternary@npm:1.0.2" + version: 1.1.2 + resolution: "@jsep-plugin/ternary@npm:1.1.2" peerDependencies: jsep: ^0.4.0||^1.0.0 - checksum: f2be94dd194f8c0f2367b457e2b20261f4317be49fad2336bd81b3ee97278e721bf4bc17c0a152c5530460f75bee2d60baeb132b7f50e044bf1352abafa6c7a8 + checksum: dcecd91d67c35bbd040a0dafd6c8d313587ffae408278c860fc6b75437eeb0feb6202a09d46e55a26513b36c7fd6f357339a23d7905d1b7f8fbb27400d75b974 languageName: node linkType: hard @@ -2579,7 +2579,7 @@ __metadata: ajv-formats: ~2.1.0 blueimp-md5: 2.18.0 es-aggregate-error: ^1.0.7 - jsonpath-plus: 6.0.1 + jsonpath-plus: 7.1.0 lodash: ~4.17.21 lodash.topath: ^4.5.2 minimatch: 3.1.2 @@ -3851,11 +3851,11 @@ __metadata: linkType: hard "astring@npm:^1.7.5, astring@npm:^1.8.1": - version: 1.8.1 - resolution: "astring@npm:1.8.1" + version: 1.8.3 + resolution: "astring@npm:1.8.3" bin: astring: bin/astring - checksum: 2a86ff8cc0c8f25694865cb8b22cdff784b8a0b115bd970c3def864618f22fe6ea78c3bef3ecdc359b2e5eb254a16d408ab06fa52a44e887b298cbf980a8083c + checksum: 72fc85de7420ca6edeee15157fd65c5253a8cb1ced979ba66ecc439fa569f1c1cc242e4c0a9fc5a6380bf73fb5ec894dc65cf1dc0f3d1cab8c707b31df7daa1c languageName: node linkType: hard @@ -8305,9 +8305,9 @@ __metadata: linkType: hard "jsep@npm:^1.1.2, jsep@npm:^1.2.0": - version: 1.2.0 - resolution: "jsep@npm:1.2.0" - checksum: 7166871e91f6be3409658b7417955a72bba4341b664e9cf062c9e0150e7f465aedc4d8fbb67e7967e3c224cbb41f155a0c16df489614421578cb96f1ba1c5519 + version: 1.3.6 + resolution: "jsep@npm:1.3.6" + checksum: e166a8fa453878e0b64cc82025db13bb6d4835b36de892373722f7cecd9cdaed05dc61db090a0d84426783ff0aab419d1719801b2014796beb873030a3c8b12a languageName: node linkType: hard @@ -8471,7 +8471,14 @@ __metadata: languageName: node linkType: hard -"jsonpath-plus@npm:6.0.1, jsonpath-plus@npm:^6.0.1": +"jsonpath-plus@npm:7.1.0": + version: 7.1.0 + resolution: "jsonpath-plus@npm:7.1.0" + checksum: a4005dc860c6b7e339229842537ceb6eb839d87a3447f989792b9c64f2564bbbd40663515f9481fb5a1b6cb0f988afba5b0b150e0285c463b794a45ed1aaf555 + languageName: node + linkType: hard + +"jsonpath-plus@npm:^6.0.1": version: 6.0.1 resolution: "jsonpath-plus@npm:6.0.1" checksum: bddec34b742249c5b38077dfcd8eb479fab4e077943253017326503ce4f527ef66938288c728712fd923907493d6eaba69a43015dc3dd9fdf48d89028ae7f466 From ffb881dff4efa5ad9fb8ebd80b15db7ed4ce4bdb Mon Sep 17 00:00:00 2001 From: stoplight-bot Date: Tue, 30 Aug 2022 20:27:27 +0000 Subject: [PATCH 09/13] chore(release): 1.14.1 [skip ci] # [@stoplight/spectral-core-v1.14.1](https://github.com/stoplightio/spectral/compare/@stoplight/spectral-core-v1.14.0...@stoplight/spectral-core-v1.14.1) (2022-08-30) ### Performance Improvements * **core:** bump jsonpath-plus to 7.1.0 ([#2259](https://github.com/stoplightio/spectral/issues/2259)) ([aacdcd7](https://github.com/stoplightio/spectral/commit/aacdcd77f0ff38c880f6292904449d0af5e7eed4)) --- packages/core/CHANGELOG.md | 7 +++++++ packages/core/package.json | 2 +- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/packages/core/CHANGELOG.md b/packages/core/CHANGELOG.md index d54f020250..b2d3b4fab4 100644 --- a/packages/core/CHANGELOG.md +++ b/packages/core/CHANGELOG.md @@ -1,3 +1,10 @@ +# [@stoplight/spectral-core-v1.14.1](https://github.com/stoplightio/spectral/compare/@stoplight/spectral-core-v1.14.0...@stoplight/spectral-core-v1.14.1) (2022-08-30) + + +### Performance Improvements + +* **core:** bump jsonpath-plus to 7.1.0 ([#2259](https://github.com/stoplightio/spectral/issues/2259)) ([aacdcd7](https://github.com/stoplightio/spectral/commit/aacdcd77f0ff38c880f6292904449d0af5e7eed4)) + # [@stoplight/spectral-core-v1.14.0](https://github.com/stoplightio/spectral/compare/@stoplight/spectral-core-v1.13.1...@stoplight/spectral-core-v1.14.0) (2022-08-24) diff --git a/packages/core/package.json b/packages/core/package.json index e43497456c..6b1edc6544 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -1,6 +1,6 @@ { "name": "@stoplight/spectral-core", - "version": "1.14.0", + "version": "1.14.1", "sideEffects": false, "homepage": "https://github.com/stoplightio/spectral", "bugs": "https://github.com/stoplightio/spectral/issues", From 776a1fcfe905d65aca6915665ade81c8ea10e0d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20Ro=C5=BCek?= Date: Tue, 6 Sep 2022 18:19:56 +0200 Subject: [PATCH 10/13] chore(ruleset-bundler): include LICENSE --- packages/ruleset-bundler/LICENSE | 190 +++++++++++++++++++++++++++++++ 1 file changed, 190 insertions(+) create mode 100644 packages/ruleset-bundler/LICENSE diff --git a/packages/ruleset-bundler/LICENSE b/packages/ruleset-bundler/LICENSE new file mode 100644 index 0000000000..ba50e461e6 --- /dev/null +++ b/packages/ruleset-bundler/LICENSE @@ -0,0 +1,190 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + Copyright 2018 Stoplight, Inc. + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. From 1e366731f01d95f1dc4ad47cf8fdebcda61ff19d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20Ro=C5=BCek?= Date: Tue, 6 Sep 2022 18:20:16 +0200 Subject: [PATCH 11/13] fix(ruleset-bundler): address Rollup.js warning --- packages/ruleset-bundler/package.json | 8 +++---- packages/ruleset-bundler/src/plugins/url.ts | 5 ++-- yarn.lock | 26 ++++++++++----------- 3 files changed, 20 insertions(+), 19 deletions(-) diff --git a/packages/ruleset-bundler/package.json b/packages/ruleset-bundler/package.json index 67e9fda4c3..459428be71 100644 --- a/packages/ruleset-bundler/package.json +++ b/packages/ruleset-bundler/package.json @@ -38,20 +38,20 @@ "release": "semantic-release -e semantic-release-monorepo" }, "dependencies": { - "@rollup/plugin-commonjs": "~22.0.0", + "@rollup/plugin-commonjs": "~22.0.2", "@stoplight/path": "1.3.2", "@stoplight/spectral-core": ">=1", "@stoplight/spectral-formats": ">=1", "@stoplight/spectral-functions": ">=1", "@stoplight/spectral-parsers": ">=1", "@stoplight/spectral-ref-resolver": ">=1", - "@stoplight/spectral-ruleset-migrator": "^1.5.2", + "@stoplight/spectral-ruleset-migrator": "^1.7.4", "@stoplight/spectral-rulesets": ">=1", "@stoplight/spectral-runtime": "^1.1.0", - "@stoplight/types": "^12.3.0", + "@stoplight/types": "^13.6.0", "@types/node": "*", "pony-cause": "1.1.1", - "rollup": "~2.75.5", + "rollup": "~2.79.0", "tslib": "^2.3.1", "validate-npm-package-name": "3.0.0" }, diff --git a/packages/ruleset-bundler/src/plugins/url.ts b/packages/ruleset-bundler/src/plugins/url.ts index aca0b4a5a1..a96f58e7f9 100644 --- a/packages/ruleset-bundler/src/plugins/url.ts +++ b/packages/ruleset-bundler/src/plugins/url.ts @@ -4,8 +4,9 @@ import type { IO } from '../types'; export const url = ({ fetch }: IO): Plugin => ({ name: '@stoplight-spectral/url', - async resolveId(id, importer) { + async resolveId(id, importer, opts): Promise { const resolved = await this.resolve(id, importer, { + ...opts, skipSelf: true, }); @@ -32,7 +33,7 @@ export const url = ({ fetch }: IO): Plugin => ({ return; }, - async load(id) { + async load(id): Promise { if (!isURL(id)) return; const res = await fetch(id); if (!res.ok) { diff --git a/yarn.lock b/yarn.lock index adf1e99410..250d405113 100644 --- a/yarn.lock +++ b/yarn.lock @@ -2235,9 +2235,9 @@ __metadata: languageName: node linkType: hard -"@rollup/plugin-commonjs@npm:~22.0.0": - version: 22.0.0 - resolution: "@rollup/plugin-commonjs@npm:22.0.0" +"@rollup/plugin-commonjs@npm:~22.0.2": + version: 22.0.2 + resolution: "@rollup/plugin-commonjs@npm:22.0.2" dependencies: "@rollup/pluginutils": ^3.1.0 commondir: ^1.0.1 @@ -2248,7 +2248,7 @@ __metadata: resolve: ^1.17.0 peerDependencies: rollup: ^2.68.0 - checksum: fdcce2bf58875fde0e06f001544c0d9a0509a12929393862f72dcef8fcbf4d5d0ba0d5db6cf10ba4351335caf67a3dbdb95000678c468585e3972994f92e2ce9 + checksum: 70098a4b91afe3f164f5d27cba65edf148c5ed146ee0e07a964b66940681553ac77391083114cdcf9427e7f2706bf0d61eab310b3a2caeab83b7452c0292fcae languageName: node linkType: hard @@ -2649,30 +2649,30 @@ __metadata: version: 0.0.0-use.local resolution: "@stoplight/spectral-ruleset-bundler@workspace:packages/ruleset-bundler" dependencies: - "@rollup/plugin-commonjs": ~22.0.0 + "@rollup/plugin-commonjs": ~22.0.2 "@stoplight/path": 1.3.2 "@stoplight/spectral-core": ">=1" "@stoplight/spectral-formats": ">=1" "@stoplight/spectral-functions": ">=1" "@stoplight/spectral-parsers": ">=1" "@stoplight/spectral-ref-resolver": ">=1" - "@stoplight/spectral-ruleset-migrator": ^1.5.2 + "@stoplight/spectral-ruleset-migrator": ^1.7.4 "@stoplight/spectral-rulesets": ">=1" "@stoplight/spectral-runtime": ^1.1.0 - "@stoplight/types": ^12.3.0 + "@stoplight/types": ^13.6.0 "@types/node": "*" "@types/validate-npm-package-name": ^3.0.3 fetch-mock: ^9.11.0 memfs: ^3.3.0 pony-cause: 1.1.1 prettier: ^2.4.1 - rollup: ~2.75.5 + rollup: ~2.79.0 tslib: ^2.3.1 validate-npm-package-name: 3.0.0 languageName: unknown linkType: soft -"@stoplight/spectral-ruleset-migrator@^1.5.0, @stoplight/spectral-ruleset-migrator@^1.5.2, @stoplight/spectral-ruleset-migrator@workspace:packages/ruleset-migrator": +"@stoplight/spectral-ruleset-migrator@^1.5.0, @stoplight/spectral-ruleset-migrator@^1.7.4, @stoplight/spectral-ruleset-migrator@workspace:packages/ruleset-migrator": version: 0.0.0-use.local resolution: "@stoplight/spectral-ruleset-migrator@workspace:packages/ruleset-migrator" dependencies: @@ -11545,9 +11545,9 @@ __metadata: languageName: node linkType: hard -"rollup@npm:~2.75.5": - version: 2.75.5 - resolution: "rollup@npm:2.75.5" +"rollup@npm:~2.79.0": + version: 2.79.0 + resolution: "rollup@npm:2.79.0" dependencies: fsevents: ~2.3.2 dependenciesMeta: @@ -11555,7 +11555,7 @@ __metadata: optional: true bin: rollup: dist/bin/rollup - checksum: fa3e61959efbc88cda75315dc22f035489be9dda3ae7d45a3a474f19efc3661ef6f9849486c7ca51e1a3e2aedef91f4e3223e8123bbeaf155913533d071994d1 + checksum: 166f1ffea1898e157003920065b3a328e7012ea6808860ee8fe5d1ce94804fcce9985c95a3c0f7fe9c611aff0d09a70f073f1d6f715c8faba28e4e40f71ee3bb languageName: node linkType: hard From 9a8436af447f0e8749e66f0ec813674dd47abde9 Mon Sep 17 00:00:00 2001 From: stoplight-bot Date: Tue, 6 Sep 2022 16:29:39 +0000 Subject: [PATCH 12/13] chore(release): 1.3.2 [skip ci] # [@stoplight/spectral-ruleset-bundler-v1.3.2](https://github.com/stoplightio/spectral/compare/@stoplight/spectral-ruleset-bundler-v1.3.1...@stoplight/spectral-ruleset-bundler-v1.3.2) (2022-09-06) ### Bug Fixes * **ruleset-bundler:** address Rollup.js warning ([1e36673](https://github.com/stoplightio/spectral/commit/1e366731f01d95f1dc4ad47cf8fdebcda61ff19d)) --- packages/ruleset-bundler/CHANGELOG.md | 7 +++++++ packages/ruleset-bundler/package.json | 2 +- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/packages/ruleset-bundler/CHANGELOG.md b/packages/ruleset-bundler/CHANGELOG.md index 477151be11..a4bfe81989 100644 --- a/packages/ruleset-bundler/CHANGELOG.md +++ b/packages/ruleset-bundler/CHANGELOG.md @@ -1,3 +1,10 @@ +# [@stoplight/spectral-ruleset-bundler-v1.3.2](https://github.com/stoplightio/spectral/compare/@stoplight/spectral-ruleset-bundler-v1.3.1...@stoplight/spectral-ruleset-bundler-v1.3.2) (2022-09-06) + + +### Bug Fixes + +* **ruleset-bundler:** address Rollup.js warning ([1e36673](https://github.com/stoplightio/spectral/commit/1e366731f01d95f1dc4ad47cf8fdebcda61ff19d)) + # [@stoplight/spectral-ruleset-bundler-v1.3.1](https://github.com/stoplightio/spectral/compare/@stoplight/spectral-ruleset-bundler-v1.3.0...@stoplight/spectral-ruleset-bundler-v1.3.1) (2022-08-03) diff --git a/packages/ruleset-bundler/package.json b/packages/ruleset-bundler/package.json index 459428be71..2bdd0f9cd8 100644 --- a/packages/ruleset-bundler/package.json +++ b/packages/ruleset-bundler/package.json @@ -1,6 +1,6 @@ { "name": "@stoplight/spectral-ruleset-bundler", - "version": "1.3.1", + "version": "1.3.2", "homepage": "https://github.com/stoplightio/spectral", "bugs": "https://github.com/stoplightio/spectral/issues", "author": "Stoplight ", From 8bbf7bb3e1f6fa8eeee55091d69d4d4175d8a0f8 Mon Sep 17 00:00:00 2001 From: Heitor Tashiro Sergent Date: Thu, 8 Sep 2022 10:10:36 -0500 Subject: [PATCH 13/13] docs(repo): grammar review (#2256) --- docs/getting-started/1-concepts.md | 4 +- docs/getting-started/2-installation.md | 15 ++-- docs/getting-started/3-rulesets.md | 6 +- docs/getting-started/4-openapi.md | 8 +-- docs/getting-started/5-asyncapi.md | 6 +- docs/guides/1-workflows.md | 20 +++--- docs/guides/2-cli.md | 12 ++-- docs/guides/4-custom-rulesets.md | 49 ++++++------- docs/guides/5-custom-functions.md | 91 +++++++++++++------------ docs/guides/7-sharing-rulesets.md | 16 ++--- docs/guides/8-continuous-integration.md | 10 +-- docs/migration-guides/5.0.md | 9 +-- docs/migration-guides/6.0.md | 19 ++---- docs/reference/asyncapi-rules.md | 24 +++---- docs/reference/functions.md | 11 ++- docs/reference/openapi-rules.md | 36 +++++----- 16 files changed, 165 insertions(+), 171 deletions(-) diff --git a/docs/getting-started/1-concepts.md b/docs/getting-started/1-concepts.md index e643c7cdf3..009e3f9966 100644 --- a/docs/getting-started/1-concepts.md +++ b/docs/getting-started/1-concepts.md @@ -10,11 +10,11 @@ To achieve this, Spectral has three key concepts: Spectral comes bundled with a [set of core functions](../reference/functions.md) and rulesets for working with [OpenAPI v2 and v3](./4-openapi.md) and [AsyncAPI v2](./5-asyncapi.md) that you can chose to use or extend, but Spectral is about far more than just checking your OpenAPI/AsyncAPI documents are valid. -By far the most popular use-case of Spectral is automating [API Style Guides](https://stoplight.io/api-style-guides-guidelines-and-best-practices?utm_source=github&utm_medium=spectral&utm_campaign=docs), implementing rules that your Architecture, DevOps, API Governance or "Center of Excellence" teams have decided upon. Companies generally write these style guides as wiki pages, and loads can be found on [API Style Book.com](http://apistylebook.com/), but most of these rules could be automated with Spectral. +By far the most popular use-case of Spectral is automating [API Style Guides](https://stoplight.io/api-style-guides-guidelines-and-best-practices?utm_source=github&utm_medium=spectral&utm_campaign=docs), implementing rules that your Architecture, DevOps, API Governance or "Center of Excellence" teams have decided upon. Companies generally write these style guides as wiki pages, and several can be found on [API Stylebook](http://apistylebook.com/), but most of these rules could be automated with Spectral. - Paths must be `/kebab-case` ([more ideas for URL rules](https://blog.stoplight.io/consistent-api-urls-with-openapi-and-style-guides)) - HTTP Basic is not allowed at this company -- Restrict use of numeric integers in favor of UUID or whatever other ID patter you pick +- Restrict the use of numeric integers in favor of UUID or any other ID pattern you choose - Enforce consistent hypermedia formats, like [JSON:API], or [another format](https://sookocheff.com/post/api/on-choosing-a-hypermedia-format/). To do that, you'll want to learn a bit more about how rulesets work. diff --git a/docs/getting-started/2-installation.md b/docs/getting-started/2-installation.md index 75b496bc96..30f62418ec 100644 --- a/docs/getting-started/2-installation.md +++ b/docs/getting-started/2-installation.md @@ -1,12 +1,12 @@ # Installation -For many, the easiest way to install Spectral is as a node module. +You can install Spectral using [npm](https://www.npmjs.com/): ```bash npm install -g @stoplight/spectral-cli ``` -If you are a Yarn user: +Or if you are a [Yarn](https://yarnpkg.com/) user: ```bash yarn global add @stoplight/spectral-cli @@ -14,25 +14,26 @@ yarn global add @stoplight/spectral-cli ## Executable Binaries -For users without Node and/or NPM/Yarn, we provide standalone packages for [all major platforms](https://github.com/stoplightio/spectral/releases). The quickest way to install the appropriate package for your operating system is via this shell script: +For users without Node.js and/or npm/Yarn, we provide standalone packages for [all major platforms](https://github.com/stoplightio/spectral/releases). The quickest way to install the appropriate package for your operating system is via this shell script: ```bash curl -L https://raw.github.com/stoplightio/spectral/master/scripts/install.sh | sh ``` -Note, the binaries do _not_ auto-update, so you will need to run it again to install new versions. +The binaries do _not_ auto-update, so you will need to run the command again to install new versions. ## Docker -Spectral is also available as a Docker image, which can be handy for all sorts of things, like if you're contributing code to Spectral, want to integrate it into your CI build. -If the file you want to lint is on your computer, you'll need to mount the directory where the file resides as a volume +Spectral is also available as a Docker image, which can be useful if you're contributing code to Spectral, or you want to integrate it into your CI build, among other things. + +If the file you want to lint is on your computer, you'll need to mount the directory where the file resides as a volume: ```bash # make sure to update the value of `--ruleset` according to the actual location of your ruleset docker run --rm -it -v $(pwd):/tmp stoplight/spectral lint --ruleset "/tmp/.spectral.js" "/tmp/file.yaml" ``` -To use the docker image on GitLab you need to set `entrypoint` to `""` like this +To use the docker image on GitLab you need to set `entrypoint` to `""` like this: ```yml stages: diff --git a/docs/getting-started/3-rulesets.md b/docs/getting-started/3-rulesets.md index 5da44065c0..6e229c328c 100644 --- a/docs/getting-started/3-rulesets.md +++ b/docs/getting-started/3-rulesets.md @@ -15,7 +15,7 @@ Rules might look a bit like this: ```yaml rules: paths-kebab-case: - description: Should paths be kebab-case. + description: Paths should be kebab-case. message: "{{property}} should be kebab-case (lower-case and separated with hyphens)" severity: warn given: $.paths[*]~ @@ -62,7 +62,7 @@ Rulesets can extend other rulesets using the `extends` property, allowing you to 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. +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: @@ -95,7 +95,7 @@ Formats are an optional way to specify which API description formats a rule, or - `json-schema-2019-09` (`$schema` says this is JSON Schema 2019-09) - `json-schema-2020-12` (`$schema` says this is JSON Schema 2020-12) -Specifying the format is optional, so you can completely ignore this if all the rules you are writing apply to any document you lint, or if you have specific rulesets for different formats. If you'd like to use one ruleset for multiple formats, the formats key is here to help. +Specifying the format is optional, so you can completely ignore this if all the rules you are writing apply to any document you lint, or if you have specific rulesets for different formats. If you'd like to use one ruleset for multiple formats, the `formats` key is here to help. ```yaml rules: diff --git a/docs/getting-started/4-openapi.md b/docs/getting-started/4-openapi.md index 579e7ab86d..36919ec237 100644 --- a/docs/getting-started/4-openapi.md +++ b/docs/getting-started/4-openapi.md @@ -1,9 +1,7 @@ # OpenAPI Support -Spectral is a generic linter, but you can add an "oas" ruleset, with OAS being shorthand for the [OpenAPI Specification](https://openapis.org/specification). +Spectral has a built-in [OpenAPI Specification](https://openapis.org/specification) ruleset that you can use to validate your OpenAPI files. -Add `extends: "spectral:oas"` to your ruleset file to apply rules for OpenAPI v2 and v3.x, depending on the appropriate OpenAPI version used (detected through [formats](../getting-started/3-rulesets.md#formats). See the [OpenAPI Rules](../reference/openapi-rules.md). +Add `extends: "spectral:oas"` ("oas" being shorthand for OpenAPI Specification) to your ruleset file to apply rules for OpenAPI v2 and v3.x, depending on the appropriate OpenAPI version being used (this is automatically detected through [formats](../getting-started/3-rulesets.md#formats)). - - -> If you would like support for other API description formats like [RAML](https://raml.org/), message formats like [JSON:API](https://jsonapi.org/), etc., we recommend you start building custom but generic rulesets which can be shared with others. We've started putting together some over here on [OpenAPI Contrib](https://github.com/openapi-contrib/style-guides/). +You can see a full list of the rules in this ruleset in [OpenAPI Rules](../reference/openapi-rules.md). diff --git a/docs/getting-started/5-asyncapi.md b/docs/getting-started/5-asyncapi.md index 3ff51ec958..7ab32585be 100644 --- a/docs/getting-started/5-asyncapi.md +++ b/docs/getting-started/5-asyncapi.md @@ -1,5 +1,7 @@ # AsyncAPI Support -Spectral is a generic linter, but you can add an [AsyncAPI v2](https://www.asyncapi.com/docs/specifications/v2.0.0) ruleset. +Spectral has a built-in [AsyncAPI v2](https://www.asyncapi.com/docs/specifications/v2.0.0) ruleset that you can use to validate your AsyncAPI files. -Add `extends: "spectral:asyncapi"` to your ruleset file to apply rules for AsyncAPI v2. See the [AsyncAPI Rules](../reference/asyncapi-rules.md). +Add `extends: "spectral:asyncapi"` to your ruleset file to apply rules for AsyncAPI v2. + +You can see a full list of the rules in this ruleset in [AsyncAPI Rules](../reference/asyncapi-rules.md). diff --git a/docs/guides/1-workflows.md b/docs/guides/1-workflows.md index dfb4f978d3..a77eda97c6 100644 --- a/docs/guides/1-workflows.md +++ b/docs/guides/1-workflows.md @@ -7,11 +7,11 @@ You can: 1. Run [Spectral CLI](2-cli.md) against design docs and get early feedback. 2. Run Spectral in [Stoplight Studio](https://stoplight.io/studio/?utm_source=github&utm_medium=spectral&utm_campaign=docs) or [VS Code](https://github.com/stoplightio/vscode-spectral?utm_source=github&utm_medium=spectral&utm_campaign=docs) as you work to avoid switching to CLI. 3. Run Spectral as a [Git hook](#git-hooks) to enforce linting as part of the commit process. -4. Use [Continuous Integration](#continuous-integration) to reject pull requests that don't match your rulesets and style-guide. +4. Use [Continuous Integration](#continuous-integration) to reject pull requests that don't match your rulesets and style guide. ## Linting Design-First Workflows -If you are using Studio, Spectral automatically runs as you work so you never need to switch to the CLI. +If you are using [Stoplight Studio](https://stoplight.io/studio/?utm_source=github&utm_medium=spectral&utm_campaign=docs), Spectral automatically runs as you work so you never need to switch to the CLI. Seeing these errors and warnings facilitate consistent APIs, quickly and easily, without requiring "OpenAPI Gatekeepers" to manually enforce the rules. @@ -19,21 +19,23 @@ Seeing these errors and warnings facilitate consistent APIs, quickly and easily, Using Spectral gets a little tricky for developers who are following a code-first (a.k.a "design-second") workflow. If the API description documents live in YAML or JSON files, the design-first workflow can be used, with new changes being linted. -If the API description documents live in some other format, such as comments or annotations inside code, consider using a tool with an export option on the CLI. Here's an example using [go-swagger](https://github.com/go-swagger/go-swagger). +If the API description documents live in some other format, such as comments or annotations inside code, consider using a tool with an export option on the CLI. Here's an example using [go-swagger](https://github.com/go-swagger/go-swagger): ```bash swagger generate spec -o ./tmp/openapi.json && spectral lint ./tmp/openapi.json ``` -By the time you've written your code, if Spectral points anything out related to your actual API, and not providing feedback on the API description document itself, figuring out what to do next might be troublesome. +After you've written your code and your API is already in production, if Spectral points anything out with your API description, figuring out what to do next might be troublesome. -For example if the API has a bunch of URLs with underscores, then becoming consistent is either a case of waiting for the next major version and changing things in there, or taking a more evolution-based approach, aliasing `/example_url` to `/example-url`, then look into [deprecating the old URL](https://apisyouwonthate.com/blog/api-evolution-for-rest-http-apis/). +For example, if the API has a bunch of URLs with underscores, then becoming consistent is either a case of waiting for the next major version and changing things in there, or taking a more evolution-based approach, aliasing `/example_url` to `/example-url`, then look into [deprecating the old URL](https://apisyouwonthate.com/blog/api-evolution-for-rest-http-apis/). ## Git-hooks -Git commit hooks prevent developers form committing broken or low quality documents. Here's a simple solution using [Husky](https://github.com/typicode/husky). +[Git hooks](https://git-scm.com/docs/githooks) are programs or commands you can set up and have them run when you commit or push. They can help lint your commit messages, run tests, or even lint your API descriptions with Spectral. -```jsonc +Here's an example of a Spectral Git hook using [Husky](https://github.com/typicode/husky): + +```json // package.json { "husky": { @@ -50,8 +52,8 @@ See our [CLI documentation](./2-cli.md) to see what other arguments and options ## Continuous Integration -Spectral can be used in any CI environment that runs run NodeJS or our Docker image: Jenkins, CircleCI, GitHub Actions, etc. +Spectral can be used in any CI environment that runs Node.js or our Docker image: Jenkins, CircleCI, GitHub Actions, etc. -By enabling the JUnit output format when you lint, most CI servers will show visual results helping people realise what mistakes were made and where. +By enabling the JUnit output format when you lint, most CI servers will show visual results helping people realize which mistakes were made and where. Read our [Continuous Integration guide](8-continuous-integration.md) for more information on setting things up in your CI of choice. diff --git a/docs/guides/2-cli.md b/docs/guides/2-cli.md index 154acbf8c8..846b7aa933 100644 --- a/docs/guides/2-cli.md +++ b/docs/guides/2-cli.md @@ -18,7 +18,7 @@ You can lint multiple files at the same time by passing on multiple arguments: spectral lint petstore.yaml https://example.com/petstore/openapi-v2.json https://example.com/todos/openapi-v3.json ``` -Alternatively you can use [glob syntax](https://github.com/mrmlnc/fast-glob#basic-syntax) to match multiple files at once: +Alternatively, you can use [glob syntax](https://github.com/mrmlnc/fast-glob#basic-syntax) to match multiple files at once: ```bash spectral lint ./reference/**/*.oas*.{json,yml,yaml} @@ -62,21 +62,21 @@ Here you can build a [custom ruleset](../getting-started/3-rulesets.md), or exte ## Error Results -Spectral has a few different error severities: `error`, `warn`, `info` and `hint`, and they are in "order" from highest to lowest. By default, all results will be shown regardless of severity, but since v5.0, only the presence of errors will cause a failure status code of 1. Seeing results and getting a failure code for it are now two different things. +Spectral has a few different error severities: `error`, `warn`, `info`, and `hint`, and they are in "order" from highest to lowest. By default, all results will be shown regardless of severity, but since v5.0, only the presence of errors will cause a failure status code of 1. Seeing results and getting a failure code for it are now two different things. The default behavior can be modified with the `--fail-severity=` option. Setting fail severity to `--fail-severity=info` would return a failure status code of 1 for any info results or higher. Using `--fail-severity=warn` will cause a failure status code for errors or warnings. -Changing the fail severity will not affect output. To change what results Spectral CLI prints to the screen, add the `--display-only-failures` switch (or just `-D` for short). This will strip out any results which are below the specified fail severity. +Changing the fail severity will not affect output. To change the results Spectral CLI prints to the screen, add the `--display-only-failures` switch (or just `-D` for short). This will strip out any results which are below the specified fail severity. ## Proxying -To have requests made from Spectral be proxied through a server, you'd need to specify PROXY environment variable: +To have requests made from Spectral be proxied through a server, you'd need to specify the `PROXY` environment variable: `PROXY=<> spectral lint spec.yaml` ## Custom \$ref Resolving -If you want to customize \$ref resolving, you can leverage `--resolver` flag and pass a path to the JS file exporting a custom instance of json-ref-resolver Resolver. +If you want to customize \$ref resolving, you can leverage the `--resolver` flag and pass a path to the JS file exporting a custom instance of json-ref-resolver Resolver. ### Example @@ -87,7 +87,7 @@ const { Resolver } = require("@stoplight/json-ref-resolver"); module.exports = new Resolver({ resolvers: { - // pass any resolver for protocol you need + // pass any resolver for the protocol you need }, }); ``` diff --git a/docs/guides/4-custom-rulesets.md b/docs/guides/4-custom-rulesets.md index 4cef09bf47..8c7cc5d266 100644 --- a/docs/guides/4-custom-rulesets.md +++ b/docs/guides/4-custom-rulesets.md @@ -1,8 +1,8 @@ # Custom Rulesets -Customising existing rulesets might be all you need at first, but at some point you will want to make a custom ruleset. For example, the OpenAPI and AsyncAPI rulesets help create better quality descriptions of APIs, but you could create a custom ruleset to tell you how to make better APIs. This approach is how huge companies automate [API Style Guides](https://stoplight.io/api-style-guides-guidelines-and-best-practices/?utm_source=github&utm_medium=spectral&utm_campaign=docs), instead of writing up giant Wiki documents that nobody reads. +Customizing existing rulesets might be all you need at first, but at some point, you will want to make a custom ruleset. For example, the OpenAPI and AsyncAPI rulesets help create better quality descriptions of APIs, but you could create a custom ruleset to tell you how to make better APIs. This approach is how huge companies automate [API Style Guides](https://stoplight.io/api-style-guides-guidelines-and-best-practices/?utm_source=github&utm_medium=spectral&utm_campaign=docs), instead of writing up giant Wiki documents that nobody reads. -If you'd like to make sure your APIs are consistent and high quality before they've even built, create a ruleset with rules that define how URLs should work, what security schemes are appropriate, or what error formats should be used. Read our article _[Six Things You Should Include in Your API Style Guide](https://blog.stoplight.io/six-things-you-should-include-in-your-api-style-guide?utm_source=github&utm_medium=spectral&utm_campaign=docs)._ +If you'd like to make sure your APIs are consistent and high quality even before they're built, create a ruleset with rules that define how URLs should work, what security schemes are appropriate, or what error formats should be used. Read our article _[Six Things You Should Include in Your API Style Guide](https://blog.stoplight.io/six-things-you-should-include-in-your-api-style-guide?utm_source=github&utm_medium=spectral&utm_campaign=docs)._ Or you can create a custom ruleset to make sure your Jekyll or Gatsby custom data is valid. Whatever you want to do, to start with you'll need to create some rules. @@ -52,9 +52,7 @@ For example, if you want to enforce conventions on the folder structure used for [splitting up documents](https://blog.stoplight.io/keeping-openapi-dry-and-portable?utm_medium=spectral&utm_source=github&utm_campaign=docs). -If your rule needs to access the raw `$ref` reference values, you can set -`resolved: false` to allow the rule to receive the raw un-resolved version of -the document. Otherwise `resolved: true` is the default. +If your rule needs to access the raw `$ref` reference values, you can set `resolved: false` to allow the rule to receive the raw un-resolved version of the document. Otherwise `resolved: true` is the default. Here's an example of a rule that can access `$ref` values: @@ -94,7 +92,7 @@ then: function: truthy ``` -The `field` keyword is optional, and is for applying the function to a specific property in an object. If omitted the function will be applied to the entire target of the `given` JSONPath. The value can also be `@key` to apply the rule to a keys of an object. +The `field` keyword is optional and is used to apply the function to a specific property in an object. If omitted the function will be applied to the entire target of the `given` JSONPath. The value can also be `@key` to apply the rule to the keys of an object. ```yaml given: "$.responses" @@ -174,7 +172,7 @@ rules: This provides a new description, but anything can be changed. -If you're just looking change the severity of the rule, there is a handy shortcut. +If you're just looking to change the severity of the rule, there is a handy shortcut. ### Changing Rule Severity @@ -190,7 +188,7 @@ Available severity levels are `error`, `warn`, `info`, `hint`, and `off`. ## Recommended or All -Rules by default are considered "recommended" (equivalent to a rule having) `recommended: true` but they can also be marked as not recommended with `recommended: false`. This can help scenarios like rolling out rulesets across API landscapes with a lot of legacy APIs which might have a hard time following every rule immediately. A two-tier system for rules can be helpful here, to avoid requiring several rulesets for this basic use-case. +Rules by default are considered "recommended" (equivalent to a rule having) `recommended: true` but they can also be marked as not recommended with `recommended: false`. This can help scenarios like rolling out rulesets across API landscapes with a lot of legacy APIs which might have a hard time following every rule immediately. A two-tier system for rules can be helpful here, to avoid requiring several rulesets for this basic use case. You can try this out with the core OpenAPI ruleset. If you simply extend the ruleset, by default you will only get the recommended rules. @@ -198,7 +196,7 @@ You can try this out with the core OpenAPI ruleset. If you simply extend the rul extends: [[spectral:oas, recommended]] ``` -Far more rule exist than just the recommended ones, there are various other rules which will help you create high quality OpenAPI descriptions. +Far more rules exist than just the recommended ones, there are various other rules which will help you create high-quality OpenAPI descriptions. ```yaml extends: [[spectral:oas, all]] @@ -216,7 +214,7 @@ rules: 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 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 exception - we turned `operation-operationId-unique` off. ### Enabling Rules @@ -228,11 +226,11 @@ rules: 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:oas` ruleset. +The example above will only run the rule `operation-operationId-unique` that we enabled since we passed `off` to disable all rules by default when extending the `spectral:oas` ruleset. ## Parsing Options -If you do not care about duplicate keys or invalid values (such as non-string mapping keys in YAML), you can tune their severity using `parserOptions` setting. +If you do not care about duplicate keys or invalid values (such as non-string mapping keys in YAML), you can tune their severity using the `parserOptions` setting. ```yaml extends: spectral:oas @@ -247,7 +245,7 @@ parserOptions: Optionally provide a documentation URL to your ruleset in order to help end-users find more information about various warnings. Result messages will sometimes be more than enough to explain what the problem is, but it can also be beneficial to explain _why_ a message exists, and this is a great place to do that. -Whatever you link you provide, the rule name will be appended as an anchor. +The rule name is appended to the link as an anchor. ```yaml # 👇 This line allows people to find more information @@ -339,7 +337,7 @@ This code example adds two rules: `valid-rule` and `only-new-json-schema`, thing For those of you using custom functions, the keywords `functions` & `functionOptions` have been removed, as they were designed to help Spectral find your functions. Now functions are passed as a variable, instead of using a string that contains the name like the JSON/YAML formats. -For now the JSON, YAML, and JS, are all being maintained, and there are no current plans to drop support for any of them. +For now the JSON, YAML, and JS formats are all being maintained, and there are no current plans to drop support for any of them. ## Aliases @@ -365,7 +363,7 @@ aliases: - "$.paths[*]~" ``` -If you deal with a variety of different spec, you may find the above approach insufficient, particularly when the shape of the document is notably different. +If you deal with a variety of different specs, you may find the above approach insufficient, particularly when the shape of the document is notably different. In such a case, you may want to consider using scoped aliases. ```yaml @@ -383,12 +381,10 @@ aliases: - $.components.parameters[*] ``` -Now, if you referenced `SharedParameterObject` alias, the chosen path would be determined based on the document you use. +Now, if you referenced the `SharedParameterObject` alias, the chosen path would be determined based on the document you use. For instance, if a given document matched OpenAPI 2.x, `$.parameters[*]` would be used as the JSONPath expression. -Having a closer look on the example above, one may notice that it'd be still somewhat complicated to target _all_ Parameter Objects -that a specific OpenAPI document may contain. -To make it more feasible and avoid overly complex JSONPath expressions, `given` can be an array. +Having a closer look at the example above, one may notice that it'd be still somewhat complicated to target _all_ Parameter Objects that a specific OpenAPI document may contain. To make it more feasible and avoid overly complex JSONPath expressions, `given` can be an array. ```yaml aliases: @@ -415,8 +411,7 @@ aliases: Rulesets can then reference aliases in the [given](#given) keyword, either in full: `"given": "#Paths"`, or use it as a prefix for further JSONPath syntax, like dot notation: `"given": "#ParameterObject.name"`. -Bear in mind that an alias has to be explicitly defined in either at the top-level or inside an override. -This is to avoid ambiguity. +Keep in mind that an alias has to be explicitly defined either at the root level or inside an override. This is to avoid ambiguity. ```yaml aliases: @@ -451,7 +446,7 @@ overrides: - legacy/**/*.json rules: falsy-value: - given: "#Value" # invalid because undeclared both at the top-level and the override. Note that this could be technically resolvable for some JSON documents, because the previous override block has the alias, but to spare some headaches, we demand an alias to be explicitly defined. + given: "#Value" # invalid because undeclared both at the top-level and the override. Note that this could be technically resolvable for some JSON documents because the previous override block has the alias, but to spare some headaches, we demand an alias to be explicitly defined. severity: error then: function: falsy @@ -461,7 +456,7 @@ overrides: ## Overrides -Previously Spectral supported exceptions, which were limited in their ability to target particular rules on specific files or parts of files, or changing parts of a rule. Overrides is the much more powerful version of exceptions, with the ability to customize ruleset usage for different files and projects without having to duplicate any rules. +Previously Spectral supported exceptions, which were limited in their ability to target particular rules on specific files or parts of files, or change parts of a rule. Overrides is the much more powerful version of exceptions, with the ability to customize ruleset usage for different files and projects without having to duplicate any rules. Overrides can be used to apply rulesets on: @@ -522,7 +517,7 @@ Please bear in mind that overrides are only applied to the _root_ documents. If **Example:** -Given the following 2 YAML documents +Given the following 2 YAML documents: ```yaml # my-document.yaml @@ -545,7 +540,7 @@ required: - id ``` -and the ruleset below +And the ruleset below: ```json { @@ -569,7 +564,7 @@ and the ruleset below } ``` -running `spectral lint my-document.yaml` will result in +Running `spectral lint my-document.yaml` will result in the following output: ``` /project/User.yaml @@ -578,7 +573,7 @@ running `spectral lint my-document.yaml` will result in ✖ 1 problem (0 errors, 1 warning, 0 infos, 0 hints) ``` -while executing `spectral lint User.yaml` will output +While executing `spectral lint User.yaml` will output: ``` No results with a severity of 'error' or higher found! diff --git a/docs/guides/5-custom-functions.md b/docs/guides/5-custom-functions.md index 2d5bce5c97..d55d3db0dc 100644 --- a/docs/guides/5-custom-functions.md +++ b/docs/guides/5-custom-functions.md @@ -1,8 +1,8 @@ # 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](../getting-started/3-rulesets.md), Spectral allows you to write and use custom functions. -Create a directory to contain your new functions. By default `functions/` is assumed. +Start by creating a directory to contain your new functions. By default, Spectral looks for the `functions/` folder. **functions/abc.js** @@ -32,7 +32,7 @@ rules: function: "abc" ``` -The function is looking for a targetVal of `"hello"` for anywhere its applied, and this rule uses a given target of `$.greeting`. +The function is looking for a `targetVal` of `"hello"` for anywhere it's applied, and this rule uses a given target of `$.greeting`. If the object being linted looks like this, everything is going to be ok. @@ -111,11 +111,11 @@ export default createRulesetFunction({ ### input -`input` the value the custom function is provided with and is supposed to lint against. +`input` is the value the custom function is provided with and is supposed to lint against. It's based on `given` [JSON Path][jsonpath] expression defined on the rule and optionally `field` if placed on `then`. -For example, a rule might have `given` with a JSON Path expression of `$`, and the following partial of an OpenAPI document: +For example, a rule might have `given` with a JSON Path expression of `$`, and the following partial OpenAPI document: ```yaml openapi: 3.0.0 @@ -127,47 +127,45 @@ In this example, `targetValue` would be a JavaScript object literal containing ` ### options -Options corresponds to `functionOptions` that's defined in `then` property of each rule. +`options` corresponds to `functionOptions` that's defined in the `then` property of each rule. -Each rule can specify options that each function should receive. This can be done as follows +Each rule can specify options that each function should receive. This can be done as follows: ```yaml operation-id-kebab-case: given: "$..operationId" then: function: pattern - functionOptions: # this object be passed down as options to the custom function + functionOptions: # this object is passed down as options to the custom function match: ^[a-z][a-z0-9\-]*$ ``` ### context -`context.path` contains a resolved property path pointing to the place in the document +`context.path` contains a resolved property path pointing to a place in the document. -`context.document` provides an access to the document that we attempt to lint. -You may find it useful if you'd like to see which formats were applied to it, or in case you'd like to get its unresolved version. +`context.document` provides access to the document that we attempt to lint. You may find it useful if you'd like to see which formats were applied to it, or in case you'd like to get its unresolved version. -`context.documentInventory` provides an access to resolved and unresolved documents as well, $ref resolution graph, as some other advanced properties. -You shouldn't need it for most of the time. +`context.documentInventory` provides access to resolved and unresolved documents, the $ref resolution graph, as well as some other advanced properties. You shouldn't need it most of the time. -`context.rule` an actual rule your function was called for. +`context.rule` is an actual rule your function was called for. -Custom functions take exactly the same arguments as core functions do, so you are more than welcome to take a look at the existing implementation. +Custom functions take the same arguments as core functions do, so you are more than welcome to take a look at the existing implementation. The process of creating a function involves 2 steps: -- create a js file inside of a directory called `functions` that should be placed next to your ruleset file -- create a `functions` array in your ruleset if you haven't done it yet and place a string with the filename without `.js` extension +- Create a `.js` file inside of a directory called `functions` that should be placed next to your ruleset file +- Create a `functions` array in your ruleset and place a string using the function filename without the `.js` extension -## Returning multiple results +## Returning Multiple Results -Many functions will return a single message, but it is possible for a function to return multiple. +Many functions will return a single message, but a function can return multiple messages. For example, if a rule is created to make sure something is unique, it could either: -- return a single error for the entire array which lists offending values in a comma separated list -- return a single error for the array value which contains the first offending non-unique item -- return multiple errors for each duplicate value located +- Return a single error for the entire array which lists offending values in a comma-separated list +- Return a single error for the array value which contains the first offending non-unique item +- Return multiple errors for each duplicate value located How exactly you chose to implement messages depends on the rule at hand and probably personal preference too. @@ -235,14 +233,15 @@ export default createRulesetFunction( ); ``` -It's worth keeping in mind, Spectral will attempt to deduplicate messages when they bear the same `code` and target the same `path`. +It's worth keeping in mind, Spectral will attempt to deduplicate messages when they have the same `code` and target the same `path`. -As such, when your custom function is susceptible to return more than one result, you have to specify a different `path` for each result. +As such, if your custom function might return more than one result, you should specify a different `path` for each result. -## Referencing core functions +## Referencing Core Functions Your custom function may also build on top of existing functions Spectral offers. -Make sure to provide all arguments that was originally passed to your function, otherwise a core function may misbehave. + +Make sure to provide all arguments that were originally passed to your function, otherwise, a core function may misbehave. ### Example @@ -251,7 +250,7 @@ import { truthy } from "@stoplight/spectral-functions"; export default function (input, ...args) { if (input.info["skip-info"] === true) { - // if info has a property with key called "skip-info" and its value is true, let's do nothing + // if info has a property with a key called "skip-info" and its value is true, let's do nothing return; } @@ -266,8 +265,8 @@ As of Spectral 5.4.0, custom functions can also be asynchronous. -> Ideally linting should always be deterministic, which means if its run 10 times it should return the same results 10 times. To ensure this is the case, please refrain from introducing any logic that is prone to non-deterministic behavior. Examples of this might be contacting external service you have no control over, or that might be unstable, or change the way it responds over time. -> While, it may seem tempting to have a function that does so, the primary use case is to support libraries that makes async fs calls or exchanging information, i.e. obtaining a dictionary file, with a locally running server, etc. +> Ideally linting should always be deterministic, which means if it's run 10 times it should return the same results 10 times. To ensure this is the case, please refrain from introducing any logic that is prone to non-deterministic behavior. Examples of this might be contacting an external service you have no control over, or that is unstable, or that changes the way it responds over time. +> While it may seem tempting to have a function that does so, the primary use case is to support libraries that makes async fs calls or exchange information, i.e. obtaining a dictionary file, with a locally running server, etc. **functions/dictionary.js** @@ -309,7 +308,7 @@ rules: ## Changing Directory -Want to place your functions in somewhere other than the `functions/` directory? Use the `functionsDir` keyword in your ruleset. +Want to place your functions somewhere other than the `functions/` directory? Use the `functionsDir` keyword in your ruleset. ```yaml functions: @@ -332,28 +331,32 @@ This indicates that almost any arbitrary code can be executed. Potential risks include: -- data / credentials infiltration, -- data tampering, -- running cpu-intensive tasks, i.e. crypto-mining. +- Data/credentials infiltration +- Data tampering +- Running cpu-intensive tasks, i.e. crypto-mining While the risk is relatively low, you should be careful about including **external rulesets** you are not in charge of, in particular those that leverage custom functions. + You are strongly encouraged to review the custom functions a given ruleset provides. What you should hunt for is: -- obfuscated code, -- calls to an untrusted external library, -- places where remote code is executed. +- Obfuscated code +- Calls to an untrusted external library +- Places where remote code is executed -If you notice any weirdness, consider forking the ruleset and removal of any evil-looking code. +If you notice any weirdness, consider forking the ruleset and removing any evil-looking code. ## Inheritance -Core functions can be overridden with custom rulesets, so if you'd like to make your own truthy go ahead. Custom functions are only available in the ruleset which defines them, so loading a foo in one ruleset will not clobber a foo in another ruleset. +Core functions can be overridden with custom rulesets, so if you'd like to make your own `truthy` function you can do so. + +Custom functions are only available in the ruleset which defines them, so loading a `foo` function in one ruleset will not affect a `foo` function in another ruleset. + +## Performance Tips -## Performance tips +Try to avoid allocating objects if your custom function is very generic, and therefore is expected to be used by plenty of rules. -- try to avoid allocating objects as much as possible if your custom function might is very generic, and therefore is expected to be used by plenty of rules. - If your document is huge enough, and JSON path expression is loose (meaning it matches a lot of properties), your function might be called hundreds of thousands of times. +If your document is big, and the JSON path expression is loose (meaning it matches a lot of properties), your function might be called hundreds of thousands of times. ```js // bad @@ -381,14 +384,14 @@ export default (targetVal, { excludedWords }) => { Spectral is meant to support a variety of environments, so ideally your function should behave similarly in Node.js and browser contexts. Do not rely on globals or functions specific to a particular environment. For example, do not expect the browser `window` global to always be available, since this global is not available in Node.js environments. -If you need to access environment specific APIs, make sure you provide an alternative for other environments. A good example of such a situation is `fetch` - a function available natively in a browser context, but missing in Node.js. +If you need to access environment-specific APIs, make sure you provide an alternative for other environments. A good example of such a situation is `fetch` - a function available natively in a browser context, but missing in Node.js. -To keep your code cross-platform, you'd need to use a cross platform package such as [node-fetch](https://www.npmjs.com/package/node-fetch) or [isomorphic-fetch](https://www.npmjs.com/package/isomorphic-fetch), both of which implement spec-compliant fetch API and work in Node.js. +To keep your code cross-platform, you'd need to use a cross-platform package such as [node-fetch](https://www.npmjs.com/package/node-fetch) or [isomorphic-fetch](https://www.npmjs.com/package/isomorphic-fetch), both of which implement spec-compliant fetch API and work in Node.js. ## Code Transpilation We encourage you to not transpile the code to ES5 if you can help it. Spectral does not support older environments than ES2019, so there is no need to bloat the bundle with useless transformations and polyfills. Ship untransformed async/await, do not include unneeded shims, it's all good. -Prior to 6.x, Spectral hadn't supported ES Modules, yet as of recently using ES Modules is the recommended way to do things. +Before 6.x, Spectral hadn't supported ES Modules, yet as of recently using ES Modules is the recommended way to do things. [jsonpath]: https://jsonpath.com/ diff --git a/docs/guides/7-sharing-rulesets.md b/docs/guides/7-sharing-rulesets.md index 0d4214d90b..a6b3478c76 100644 --- a/docs/guides/7-sharing-rulesets.md +++ b/docs/guides/7-sharing-rulesets.md @@ -4,8 +4,8 @@ A [ruleset](../getting-started/3-rulesets.md) becomes infinitely more useful whe To help you out distribute your rulesets among the others, Spectral provides a few ways to load rulesets from a variety of resources: -- via a HTTP server -- via [NPM](#npm) +- via an HTTP server +- via [npm](#npm) - via the filesystem Or mix and match! @@ -21,7 +21,7 @@ There are various pros and cons to each approach, so see what is right for you. ## HTTP Server -At its most basic level, a Spectral ruleset is just a JSON or YAML file. It can be hosted anywhere you like: on your web hosting, Amazon S3, or anywhere text files are accessible, and then pulled into your own local ruleset in the filesystem: +At its most basic level, a Spectral ruleset is just a JSON or YAML file. It can be hosted anywhere you like: on your web hosting, Amazon S3, or anywhere text files are accessible, and then pulled into your local ruleset in the filesystem: **ruleset.yaml** @@ -44,11 +44,11 @@ As with any ruleset, you can pass these directly to the [Spectral CLI](./2-cli.m spectral lint -r https://example.com/some-ruleset.yml ``` -## NPM +## npm -As Spectral is a [NPM](https://www.npmjs.com/) package, we support loading rulesets from other NPM packages. +As Spectral is an [npm](https://www.npmjs.com/) package, we support loading rulesets from other npm packages. -Not only it lets you serve files without a need for hosting your own server or uploading it somewhere else, but also supports versioning out of the box, and makes it easy to bundle a ruleset with custom rulesets. +Not only does it let you serve files without a need for hosting your own server or uploading it somewhere else, but also supports versioning out of the box, and makes it easy to bundle a ruleset with custom rulesets. This is a very basic example showing how the directory structure as well as package.json may look like. @@ -116,7 +116,7 @@ extends: - example-spectral-ruleset ``` -Pegging a ruleset on given version is possible through a `package.json`: +Locking a ruleset on a given version is possible through `package.json`: ```json { @@ -126,7 +126,7 @@ Pegging a ruleset on given version is possible through a `package.json`: } ``` -If you Spectral in a browser or don't want to install the package, you can also reference that package through the use of CDNs for NPM repository, such as [unpkg.com](https://unpkg.com/): +If you use Spectral in a browser or don't want to install the package, you can also reference that package through the use of CDNs for npm repositories, such as [unpkg.com](https://unpkg.com/): ```yaml extends: diff --git a/docs/guides/8-continuous-integration.md b/docs/guides/8-continuous-integration.md index f432d25f62..4f4d4e9f52 100644 --- a/docs/guides/8-continuous-integration.md +++ b/docs/guides/8-continuous-integration.md @@ -1,6 +1,6 @@ # Continuous Integration -Spectral CLI can be run anywhere that NPM packages can be installed and run via CLI, which these days is pretty much any CI solution going. +Spectral CLI can be run anywhere that npm packages can be installed and run via CLI, which these days is pretty much any CI solution going. Here are some examples of Spectral in various CI solutions to give you an idea. @@ -37,7 +37,9 @@ workflows: - lint ``` -Change the `openapi.yaml` to point to whatever documents you want to lint, and use -f (format) to pick the JUnit output format. This is a standard test format that many CI servers understand, and means you should be able to see the errors in the Test interface. +Make sure to change `openapi.yaml` to point to whatever documents you want to lint. + +The `-f` (format) flag is used in the script to pick the JUnit output format. This is a standard test format that many CI servers understand, and means you should be able to see the errors in the Test interface. ![On the CircleCI build results page there is a tab called Tests, which will show Spectral results so long as the junit format has been enabled](../img/ci-circleci.png) @@ -69,9 +71,9 @@ lint:spectral: junit: $CI_PROJECT_DIR/spectral-report.xml ``` -Note that this CI job exposes Spectral results on the merge request page, along with any other test output you may have. To ensure that GitLab can parse the output of spectral, we use the `-f junit`flag. +Make sure to change `openapi.yaml` to point to whatever documents you want to lint. -You will also need to edit your `openapi.yaml` file to point to the particular documents you want to lint. +The `-f` (format) flag is used in the script to pick the JUnit output format. This is a standard test format that many CI servers understand, and means you should be able to see the Spectral output on the merge request page. ## Jenkins diff --git a/docs/migration-guides/5.0.md b/docs/migration-guides/5.0.md index 16c984f6f4..581efb38e9 100644 --- a/docs/migration-guides/5.0.md +++ b/docs/migration-guides/5.0.md @@ -5,9 +5,9 @@ this migration guide covers the most notable changes. ### I have my own custom rulesets... -1. oas2 and oas3 rulesets have been merged to oas +1. `oas2` and `oas3` rulesets have been merged to `oas` -From now on, you don't need to worry about oas2 or oas3, you simply extend oas ruleset and Spectral will figure out which rules to apply based on given formats. +From now on, you don't need to worry about `oas2` or `oas3`, you simply extend the `oas` ruleset and Spectral will figure out which rules to apply based on given formats. **Spectral v4**: @@ -27,8 +27,9 @@ From now on, you don't need to worry about oas2 or oas3, you simply extend oas r 2. All rules are recommended by default now -Previously it wasn't quite clear that you need to make rule recommended in order to have it enabled by default. -We addressed it and right now you need to explicitly mark rule as unrecommended assuming you do want it to be so. +Previously it wasn't quite clear that you need to make a rule recommended to have it enabled by default. + +We addressed it and right now you need to explicitly mark a rule as unrecommended assuming you do want it to be so. **Spectral v4**: diff --git a/docs/migration-guides/6.0.md b/docs/migration-guides/6.0.md index 12f968f87e..b6d8856f20 100644 --- a/docs/migration-guides/6.0.md +++ b/docs/migration-guides/6.0.md @@ -2,14 +2,8 @@ ## General -1. Spectral has become a monorepo now and CLI <-> Core have been split into separate packages. - If you intend to use a CLI version of Spectral make sure to install `@stoplight/spectral-cli`. - Otherwise, go with `@stoplight/spectral-core` which is the JS API. - -2. No default ruleset is loaded by default as of now, thus if you don't supply a ruleset, Spectral will refuse to lint the document. - If you use CLI, make sure to have a valid ruleset in your project or use a `--ruleset` flag. - JS API has a method called `setRuleset` which can be used to set the relevant ruleset. - +1. Spectral has become a monorepo now and CLI <-> Core have been split into separate packages. If you intend to use a CLI version of Spectral make sure to install `@stoplight/spectral-cli`. Otherwise, go with `@stoplight/spectral-core` which is the JS API. +2. No default ruleset is loaded by default as of now, thus if you don't supply a ruleset, Spectral will refuse to lint the document. If you use CLI, make sure to have a valid ruleset in your project or use a `--ruleset` flag. JS API has a method called `setRuleset` which can be used to set the relevant ruleset. 3. Spectral is stricter overall and certain soft errors that previously were marked as warnings will throw now. ## Core @@ -70,16 +64,13 @@ const spectral = new Spectral({ ## Functions -1. `schema` function uses Ajv v8 in favor of Ajv v6. It is preferred to provide JSON Schema Draft 7 schemas or newer, albeit older drafts are also supported via json-schema-migrate. - `oasVersion` is no longer supported. Use `oasSchema` function from the OAS ruleset if you want to supply OAS Schema Object. - +1. `schema` function uses Ajv v8 in favor of Ajv v6. It is preferred to provide JSON Schema Draft 7 schemas or newer, albeit older drafts are also supported via json-schema-migrate. `oasVersion` is no longer supported. Use the `oasSchema` function from the OAS ruleset if you want to supply an OAS Schema Object. 2. `schemaPath` is no longer available. If you happened to use this function, you can write a custom function that implements the same functionality. ## CLI 1. deprecated `--show-unmatched-globs` flag has been removed. Alternative available: `--fail-on-unmatched-globs` - -2. `--skip-rule` has been removed. Use a custom ruleset instead - set a severity of a particular rule to "off". +2. `--skip-rule` has been removed. Use a custom ruleset instead - set the severity of a particular rule to "off". ## Rulesets @@ -115,7 +106,7 @@ Change: all reusable `components` are now validated. - `operation-default-response` -Workaround: Insert the following rule to your custom ruleset. +Workaround: Insert the following rule in your custom ruleset. ```json "operation-default-response": { diff --git a/docs/reference/asyncapi-rules.md b/docs/reference/asyncapi-rules.md index 26a4a33f2b..9e547a7f73 100644 --- a/docs/reference/asyncapi-rules.md +++ b/docs/reference/asyncapi-rules.md @@ -40,7 +40,7 @@ Channel servers must be defined in the `servers` object. asyncapi: "2.0.0" info: title: Awesome API - description: A very well defined API + description: A very well-defined API version: "1.0" servers: production: @@ -58,7 +58,7 @@ channels: asyncapi: "2.0.0" info: title: Awesome API - description: A very well defined API + description: A very well-defined API version: "1.0" servers: production: @@ -80,7 +80,7 @@ The schema definition of the application headers must be of type “object”. ### asyncapi-info-contact-properties -The [asyncapi-info-contact](#asyncapi-info-contact) rule will ask you to put in a contact object, and this rule will make sure it's full of the most useful properties: `name`, `url` and `email`. +The [asyncapi-info-contact](#asyncapi-info-contact) rule will ask you to put in a contact object, and this rule will make sure it's full of the most useful properties: `name`, `url`, and `email`. Putting in the name of the developer/team/department/company responsible for the API, along with the support email and help-desk/GitHub Issues/whatever URL means people know where to go for help. This can mean more money in the bank, instead of developers just wandering off or complaining online. @@ -92,7 +92,7 @@ Putting in the name of the developer/team/department/company responsible for the asyncapi: "2.0.0" info: title: Awesome API - description: A very well defined API + description: A very well-defined API version: "1.0" contact: name: A-Team @@ -104,7 +104,7 @@ info: Info object should contain `contact` object. -Hopefully your API description document is so good that nobody ever needs to contact you with questions, but that is rarely the case. The contact object has a few different options for contact details. +Hopefully, your API description document is so good that nobody ever needs to contact you with questions, but that is rarely the case. The contact object has a few different options for contact details. **Recommended:** Yes @@ -176,7 +176,7 @@ info: ### asyncapi-message-examples -All `examples` in message object should follow by `payload` and `headers` schemas. +All `examples` in message object should follow `payload` and `headers` schemas. **Bad Example** @@ -261,7 +261,7 @@ Operation objects should have a description. ### asyncapi-operation-operationId-uniqueness -`operationId` must be unique across all the operations (except these one defined in the components). +`operationId` must be unique across all the operations (except the ones defined in the components). **Recommended:** Yes @@ -413,7 +413,7 @@ application/vnd.aai.asyncapi+yaml;version=2.0.0 At this point, explicitly setting `schemaFormat` is not supported by Spectral, so if you use it this rule will emit an info message and skip validating the payload. -Other formats such as OpenAPI Schema Object, JSON Schema Draft 07 and Avro will be added in various upcoming versions. +Other formats such as OpenAPI Schema Object, JSON Schema Draft 07, and Avro will be added in various upcoming versions. **Recommended:** Yes @@ -473,7 +473,7 @@ servers: ### asyncapi-server-not-example-com -Server URL should not point at example.com. +Server URL should not point to example.com. **Recommended:** No @@ -517,7 +517,7 @@ All server URL variables should be defined in the `variables` object of the serv ### asyncapi-servers -A non empty `servers` object is expected to be located at the root of the document. +A non-empty `servers` object is expected to be located at the root of the document. **Recommended:** Yes @@ -528,12 +528,12 @@ Tags alone are not very descriptive. Give folks a bit more information to work w ```yaml tags: - name: "Aardvark" - description: Funny nosed pig-head racoon. + description: Funny-nosed pig-head raccoon. - name: "Badger" description: Angry short-legged omnivores. ``` -If your tags are business objects then you can use the term to explain them a bit. An 'Account' could be a user account, company information, bank account, potential sales lead, anything. What is clear to the folks writing the document is probably not as clear to others. +If your tags are business objects then you can use the term to explain them a bit. An 'Account' could be a user account, company information, bank account, potential sales lead, or anything. What is clear to the folks writing the document is probably not as clear to others. ```yaml tags: diff --git a/docs/reference/functions.md b/docs/reference/functions.md index 984d1d6392..2e2e893d3c 100644 --- a/docs/reference/functions.md +++ b/docs/reference/functions.md @@ -56,11 +56,11 @@ whitelisted-tags: ## falsy -The value should be `false`, `""`, `0`, `null` or `undefined`. Basically anything that would not trigger this: `if (!!targetVal)`. +The value should be `false`, `""`, `0`, `null` or `undefined`. Basically, anything that would not trigger this: `if (!!targetVal)`. ## length -Count the length of a string an or array, the number of properties in an object, or a numeric value, and define minimum and/or maximum values. +Count the length of a string or an array, the number of properties in an object, or a numeric value, and define minimum and/or maximum values. @@ -69,7 +69,7 @@ Count the length of a string an or array, the number of properties in an object, | min | the minimum length to match | number | no | | max | the maximum length to match | number | no | -At the very least `min` or `max` have to be provided. You can specify both as well. +At the very least `min` or `max` has to be provided. You can specify both as well. @@ -186,7 +186,7 @@ oas3-api-servers: ## truthy -The value should not be `false`, `""`, `0`, `null` or `undefined`. Basically anything that would not trigger this: `if (targetVal)`. +The value should not be `false`, `""`, `0`, `null`, or `undefined`. Basically, anything that would not trigger this: `if (targetVal)`. @@ -205,8 +205,7 @@ important-fields: ## defined -The value must be defined, meaning it must be anything but `undefined`. -It's the opposite of what undefined function does. +The value must be defined, meaning it must be anything but `undefined`. It's the opposite of what the undefined function does. ## undefined diff --git a/docs/reference/openapi-rules.md b/docs/reference/openapi-rules.md index 37a1f91a6e..d295b15c85 100644 --- a/docs/reference/openapi-rules.md +++ b/docs/reference/openapi-rules.md @@ -10,7 +10,7 @@ These rules apply to both OpenAPI v2.0, v3.0, and most likely v3.1, although the ### contact-properties -The [info-contact](#info-contact) rule will ask you to put in a contact object, and this rule will make sure it's full of the most useful properties: `name`, `url` and `email`. +The [info-contact](#info-contact) rule will ask you to put in a contact object, and this rule will make sure it's full of the most useful properties: `name`, `url`, and `email`. Putting in the name of the developer/team/department/company responsible for the API, along with the support email and help-desk/GitHub Issues/whatever URL means people know where to go for help. This can mean more money in the bank, instead of developers just wandering off or complaining online. @@ -22,7 +22,7 @@ Putting in the name of the developer/team/department/company responsible for the openapi: "3.0.2" info: title: Awesome API - description: A very well defined API + description: A very well-defined API version: "1.0" contact: name: A-Team @@ -72,7 +72,7 @@ TheBadModel: Info object should contain `contact` object. -Hopefully your API description document is so good that nobody ever needs to contact you with questions, but that is rarely the case. The contact object has a few different options for contact details. +Hopefully, your API description document is so good that nobody ever needs to contact you with questions, but that is rarely the case. The contact object has a few different options for contact details. **Recommended:** Yes @@ -144,7 +144,7 @@ info: ### no-\$ref-siblings -Prior to OpenAPI v3.1, keywords next to `$ref` were be ignored by most tooling, but not all. This leads to inconsistent experiences depending on what combinations of tools are used. As of v3.1 $ref siblings are allowed, so this rule will not be applied. +Before OpenAPI v3.1, keywords next to `$ref` were ignored by most tooling, but not all. This leads to inconsistent experiences depending on what combinations of tools are used. As of v3.1 $ref siblings are allowed, so this rule will not be applied. **Recommended:** Yes @@ -159,7 +159,7 @@ TheBadModel: ### no-eval-in-markdown -This rule protects against an edge case, for anyone bringing in description documents from third parties and using the parsed content rendered in HTML/JS. If one of those third parties does something shady like inject `eval()` JavaScript statements, it could lead to an XSS attack. +This rule protects against an edge case, for anyone bringing in description documents from third parties and using the parsed content rendered in HTML/JS. If one of those third parties does something shady like injecting `eval()` JavaScript statements, it could lead to an XSS attack. **Recommended:** Yes @@ -173,7 +173,7 @@ info: ### no-script-tags-in-markdown -This rule protects against a potential hack, for anyone bringing in description documents from third parties then generating HTML documentation. If one of those third parties does something shady like inject `