Repository: stoplightio/spectral
Pull request #219 (2019-05-20 23:43:41)

 fix: improve usefulness of path-params linting messages
### Please check if the PR fulfills these requirements
- [ ] Tests for the changes have been added (for bug fixes / features)
- [ ] Docs have been added / updated (for bug fixes / features)

### What kind of change does this PR introduce?

addresses https://github.com/stoplightio/spectral/pull/215#pullrequestreview-239753797
removes useless docs script

### What is the current behavior?

You can also link to an open issue here.

### If this is a feature change, what is the new behavior?

### Does this PR introduce a breaking change?

Nope :)

What changes might users need to make in their application due to this PR?

### Other information

(e.g. detailed explanation, related issues, links for us to have context, eg. stackoverflow, issues outside of the repo, forum, etc.)



Patch:
diff --git a/.circleci/config.yml b/.circleci/config.yml
index c34215e7..f825f5d5 100644
--- a/.circleci/config.yml
+++ b/.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
\ No newline at end of file
+              only: master
diff --git a/package.json b/package.json
index e61ecb41..70813f6c 100644
--- a/package.json
+++ b/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",
diff --git a/src/rulesets/oas/index.ts b/src/rulesets/oas/index.ts
index df2c962a..35cce1b6 100644
--- a/src/rulesets/oas/index.ts
+++ b/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: '$',


Test patch:
diff --git a/src/rulesets/oas/functions/oasPathParam/__tests__/__snapshots__/index.test.ts.snap b/src/rulesets/oas/functions/oasPathParam/__tests__/__snapshots__/index.test.ts.snap
index 4ce02cfa..f7193284 100644
--- a/src/rulesets/oas/functions/oasPathParam/__tests__/__snapshots__/index.test.ts.snap
+++ b/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.",
   },
 ]
 `;
diff --git a/src/rulesets/oas/functions/oasPathParam/__tests__/index.test.ts b/src/rulesets/oas/functions/oasPathParam/__tests__/index.test.ts
index 4aea0258..222b59bc 100644
--- a/src/rulesets/oas/functions/oasPathParam/__tests__/index.test.ts
+++ b/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 () => {