docs(cli): clarified info and changes applied

stoplightio · Jan 25, 2023 · aeb85a4 · aeb85a4
1 parent 5f33c1b
commit aeb85a4
Show file tree

Hide file tree

Showing 13 changed files with 32 additions and 19 deletions.
diff --git a/docs/guides/2-cli.md b/docs/guides/2-cli.md
@@ -112,7 +112,7 @@ Heres an example of this scoringFile config file:
           "E":0
         },
       "threshold":50,
-      "warningsSubtract": true,
+      "onlySubtractHigherSeverityLevel": true,
       "uniqueErrors": false
     }
 ```
@@ -121,8 +121,21 @@ Where:
 
 - scoringSubtract : An object with key/value pair objects for every result level we want to subtract percentage, with the percentage to subtract from number of results on every result type
 - scoringLetter : An object with key/value pairs with scoring letter and scoring percentage, that the result must be greater, for this letter
-- threshold : A number with minimum percentage value to provide valid the file we are checking
-- warningsSubtract : A boolean to accumulate the result types to less than the scoring percentage or to stop counting on most critical result types
+- threshold : A number with minimum percentage value to provide valid the file we are checking. Any scoring below this thresold will mark the API as a failure in the scoring.
+- onlySubtractHigherSeverityLevel : A boolean to decide if only the higher severity level who appears in the results for the API to analize, are subtracted from scoring or every severity level are subtracted from scoring.
+
+See sample:
+
+    true
+
+    API with Errors and Warnings, only Errors substract from scoring
+    API with Warnings, Warnings substract from scoring
+
+    false
+
+    API with Errors and Warnings, Errors and Warnings substracts from scoring
+    API with Warnings, Warnings substract from scoring
+
 - uniqueErrors : A boolean to count unique errors or all errors. An error is considered unique if its code and message have not been seen yet
 
 Example:

diff --git a/packages/cli/src/commands/lint.ts b/packages/cli/src/commands/lint.ts
@@ -308,7 +308,7 @@ const scoringThresholdNotEnough = (results: IRuleResult[], scoringConfig: Scorin
       getScoringLevel(
         getCountsBySeverity(groupedUniqueResults),
         scoringConfig.scoringSubtract,
-        scoringConfig.warningsSubtract,
+        scoringConfig.onlySubtractHigherSeverityLevel
       )
     );
   }

diff --git a/packages/cli/src/formatters/types.ts b/packages/cli/src/formatters/types.ts
@@ -15,7 +15,7 @@ export type ScoringConfig = {
   scoringSubtract: ScoringTable[];
   scoringLetter: ScoringLevel[];
   threshold: number;
-  warningsSubtract: boolean;
+  onlySubtractHigherSeverityLevel: boolean;
   uniqueErrors: boolean;
 };
 

diff --git a/packages/cli/src/formatters/utils/getScoring.ts b/packages/cli/src/formatters/utils/getScoring.ts
@@ -24,13 +24,13 @@ export const getScoringLevel = (
     [DiagnosticSeverity.Hint]: number;
   },
   scoringSubtract: ScoringTable[],
-  warningsSubtract: boolean,
+  onlySubtractHigherSeverityLevel: boolean,
 ): number => {
   let scoring = 100;
   Object.keys(issuesCount).forEach(key => {
     const scoringKey = Object.keys(SEVERITY_MAP).filter(mappedKey => SEVERITY_MAP[mappedKey] == key)[0];
     if (scoringSubtract[scoringKey] !== void 0) {
-      if (scoring < 100 && !warningsSubtract) return;
+      if (scoring < 100 && !onlySubtractHigherSeverityLevel) return;
       let subtractValue = 0;
       Object.keys(scoringSubtract[scoringKey] as ScoringSubtract[]).forEach((subtractKey: string): void => {
         subtractValue = (
@@ -42,7 +42,7 @@ export const getScoringLevel = (
       scoring -= subtractValue;
     }
   });
-  return scoring;
+  return scoring > 0 ? scoring : 0;
 };
 
 export const getScoringText = (
@@ -54,8 +54,8 @@ export const getScoringText = (
   },
   scoringConfig: ScoringConfig,
 ): string => {
-  const { scoringSubtract, scoringLetter, warningsSubtract } = scoringConfig;
-  const scoring = getScoringLevel(issuesCount, scoringSubtract, warningsSubtract);
+  const { scoringSubtract, scoringLetter, onlySubtractHigherSeverityLevel } = scoringConfig;
+  const scoring = getScoringLevel(issuesCount, scoringSubtract, onlySubtractHigherSeverityLevel);
   let scoringLevel: string = Object.keys(scoringLetter)[Object.keys(scoringLetter).length - 1];
   Object.keys(scoringLetter)
     .reverse()

diff --git a/packages/cli/src/services/__tests__/__fixtures__/scoring-config.json b/packages/cli/src/services/__tests__/__fixtures__/scoring-config.json
@@ -27,6 +27,6 @@
       "E": 0
     },
   "threshold": 50,
-  "warningsSubtract": true,
+  "onlySubtractHigherSeverityLevel": true,
   "uniqueErrors": false
 }
diff --git a/packages/cli/src/services/__tests__/output.test.ts b/packages/cli/src/services/__tests__/output.test.ts
@@ -28,7 +28,7 @@ const scoringConfig = {
     E: 0,
   } as unknown as ScoringLevel[],
   threshold: 50,
-  warningsSubtract: true,
+  onlySubtractHigherSeverityLevel: true,
   uniqueErrors: false,
 };
 

diff --git a/test-harness/scenarios/formats/results-default-format-scoring-json.scenario b/test-harness/scenarios/formats/results-default-format-scoring-json.scenario
@@ -79,7 +79,7 @@ info:
       "E": 0
     },
   "threshold": 50,
-  "warningsSubtract": true,
+  "onlySubtractHigherSeverityLevel": true,
   "uniqueErrors": false
 }
 ====command====

diff --git a/test-harness/scenarios/formats/results-default-scoring.scenario b/test-harness/scenarios/formats/results-default-scoring.scenario
@@ -79,7 +79,7 @@ info:
       "E": 0
     },
   "threshold": 50,
-  "warningsSubtract": true,
+  "onlySubtractHigherSeverityLevel": true,
   "uniqueErrors": false
 }
 ====command====

diff --git a/test-harness/scenarios/formats/results-format-stylish-scoring.scenario b/test-harness/scenarios/formats/results-format-stylish-scoring.scenario
@@ -80,7 +80,7 @@ paths: {}
       "E": 0
     },
   "threshold": 50,
-  "warningsSubtract": true,
+  "onlySubtractHigherSeverityLevel": true,
   "uniqueErrors": false
 }
 ====command====

diff --git a/test-harness/scenarios/overrides/aliases-scoring.scenario b/test-harness/scenarios/overrides/aliases-scoring.scenario
@@ -93,7 +93,7 @@ module.exports = {
       "E": 0
     },
   "threshold": 50,
-  "warningsSubtract": true,
+  "onlySubtractHigherSeverityLevel": true,
   "uniqueErrors": false
 }
 ====asset:v2/document.json====

diff --git a/test-harness/scenarios/severity/fail-on-error-no-error-scoring.scenario b/test-harness/scenarios/severity/fail-on-error-no-error-scoring.scenario
@@ -47,7 +47,7 @@ Will only fail if there is an error, and there is not. Can still see all warning
       "E": 0
     },
   "threshold": 50,
-  "warningsSubtract": true,
+  "onlySubtractHigherSeverityLevel": true,
   "uniqueErrors": false
 }
 ====command====

diff --git a/test-harness/scenarios/severity/fail-on-error-scoring.scenario b/test-harness/scenarios/severity/fail-on-error-scoring.scenario
@@ -58,7 +58,7 @@ Will fail and return 1 as exit code because errors exist with scoring data
       "E": 0
     },
   "threshold": 50,
-  "warningsSubtract": true,
+  "onlySubtractHigherSeverityLevel": true,
   "uniqueErrors": false
 }
 ====command-nix====

diff --git a/test-harness/scenarios/valid-no-errors.oas2-scoring.scenario b/test-harness/scenarios/valid-no-errors.oas2-scoring.scenario
@@ -47,7 +47,7 @@ module.exports = oas;
       "E": 0
     },
   "threshold": 50,
-  "warningsSubtract": true,
+  "onlySubtractHigherSeverityLevel": true,
   "uniqueErrors": false
 }
 ====command====