fix: improve usefulness of path-params linting messages (#219)

* chore: nuke typedoc generation

* fix: improve usefulness of path-params messages

.circleci/config.yml

@@ -70,9 +70,7 @@ jobs:
       - checkout
       - cached-dependencies
       - run: yarn build
-      - run: yarn build.docs
       - run: yarn release
-      - run: yarn release.docs
 
 workflows:
   version: 2
@@ -87,4 +85,4 @@ workflows:
       - release:
           filters:
             branches:
-              only: master
+              only: master

package.json

@@ -41,13 +41,11 @@
   "scripts": {
     "build": "sl-scripts build && node ./scripts/prepare-cli",
     "build.binary": "yarn build && yarn build.manifest && cp yarn.lock dist && cd dist && yarn && pkg . --out-path ./bin",
-    "build.docs": "sl-scripts build:typedoc",
     "build.manifest": "cd dist && oclif-dev manifest",
     "commit": "git-cz",
     "lint": "tslint 'src/**/*.ts'",
     "lint.fix": "yarn lint --fix",
     "release": "sl-scripts release",
-    "release.docs": "sl-scripts release:docs",
     "release.dryRun": "sl-scripts release --dry-run --debug",
     "test": "jest",
     "test.prod": "yarn build && yarn lint && yarn test --coverage --maxWorkers=2",

src/rulesets/oas/functions/oasPathParam/__tests__/__snapshots__/index.test.ts.snap

@@ -4,7 +4,9 @@ exports[`oasPathParam Error if $ref path parameter definition is not required 1`
 Array [
   Object {
     "code": "path-params",
-    "message": "Path parameters are correct and valid.",
+    "message": "Path parameter \\"**bar**\\" must have a \`required\` that is set to \`true\`.
+
+To fix, mark this parameter as required.",
     "path": Array [
       "paths",
       "/foo/{bar}",
@@ -22,7 +24,9 @@ Array [
     },
     "severity": 0,
     "source": undefined,
-    "summary": "Path parameters are correct and valid.",
+    "summary": "Path parameter \\"**bar**\\" must have a \`required\` that is set to \`true\`.
+
+To fix, mark this parameter as required.",
   },
 ]
 `;
@@ -31,7 +35,11 @@ exports[`oasPathParam Error if duplicate path parameters with same name are used
 Array [
   Object {
     "code": "path-params",
-    "message": "Path parameters are correct and valid.",
+    "message": "The path \\"**/foo/{bar}/{bar}**\\" uses the parameter \\"**{bar}**\\" multiple times.
+
+Path parameters must be unique.
+
+To fix, update the path so that all parameter names are unique.",
     "path": Array [
       "paths",
       "/foo/{bar}/{bar}",
@@ -48,7 +56,11 @@ Array [
     },
     "severity": 0,
     "source": undefined,
-    "summary": "Path parameters are correct and valid.",
+    "summary": "The path \\"**/foo/{bar}/{bar}**\\" uses the parameter \\"**{bar}**\\" multiple times.
+
+Path parameters must be unique.
+
+To fix, update the path so that all parameter names are unique.",
   },
 ]
 `;
@@ -57,7 +69,9 @@ exports[`oasPathParam Error if no path parameter definition 1`] = `
 Array [
   Object {
     "code": "path-params",
-    "message": "Path parameters are correct and valid.",
+    "message": "The path \\"**/foo/{bar}**\\" uses a parameter \\"**{bar}**\\" that does not have a corresponding definition.
+
+To fix, add a path parameter with the name \\"**bar**\\".",
     "path": Array [
       "paths",
       "/foo/{bar}",
@@ -74,7 +88,9 @@ Array [
     },
     "severity": 0,
     "source": undefined,
-    "summary": "Path parameters are correct and valid.",
+    "summary": "The path \\"**/foo/{bar}**\\" uses a parameter \\"**{bar}**\\" that does not have a corresponding definition.
+
+To fix, add a path parameter with the name \\"**bar**\\".",
   },
 ]
 `;
@@ -83,7 +99,9 @@ exports[`oasPathParam Error if paths are functionally equivalent 1`] = `
 Array [
   Object {
     "code": "path-params",
-    "message": "Path parameters are correct and valid.",
+    "message": "The paths \\"**/foo/{boo}**\\" and \\"**/foo/{bar}**\\" are equivalent.
+
+To fix, remove one of the paths or merge them together.",
     "path": Array [
       "paths",
     ],
@@ -99,7 +117,9 @@ Array [
     },
     "severity": 0,
     "source": undefined,
-    "summary": "Path parameters are correct and valid.",
+    "summary": "The paths \\"**/foo/{boo}**\\" and \\"**/foo/{bar}**\\" are equivalent.
+
+To fix, remove one of the paths or merge them together.",
   },
 ]
 `;

src/rulesets/oas/functions/oasPathParam/__tests__/index.test.ts

@@ -34,7 +34,10 @@ describe('oasPathParam', () => {
     expect(results).toMatchSnapshot();
 
     expect(results[0].path).toEqual(['paths', '/foo/{bar}']);
-    expect(results[0].message).toEqual('Path parameters are correct and valid.');
+    expect(results[0].message)
+      .toEqual(`The path "**/foo/{bar}**" uses a parameter "**{bar}**" that does not have a corresponding definition.
+
+To fix, add a path parameter with the name "**bar**".`);
   });
 
   test('No error if path parameter definition is used (at the path level)', async () => {
@@ -115,7 +118,11 @@ describe('oasPathParam', () => {
     expect(results).toMatchSnapshot();
 
     expect(results[0].path).toEqual(['paths', '/foo/{bar}/{bar}']);
-    expect(results[0].message).toEqual('Path parameters are correct and valid.');
+    expect(results[0].message).toEqual(`The path "**/foo/{bar}/{bar}**" uses the parameter "**{bar}**" multiple times.
+
+Path parameters must be unique.
+
+To fix, update the path so that all parameter names are unique.`);
   });
 
   test('Error if $ref path parameter definition is not required', async () => {

src/rulesets/oas/index.ts

@@ -1,5 +1,6 @@
 import { DiagnosticSeverity } from '@stoplight/types';
 import { FunctionCollection, RuleCollection, RuleFunction, RuleType } from '../../types';
+import { message } from '../message';
 
 export const operationPath =
   "$..paths.*[?( name() === 'get' || name() === 'put' || name() === 'post'" +
@@ -62,6 +63,7 @@ export const commonOasRules = (): RuleCollection => ({
   },
   'path-params': {
     summary: 'Path parameters are correct and valid.',
+    message: message`${'error'}`,
     type: RuleType.VALIDATION,
     severity: DiagnosticSeverity.Error,
     given: '$',