chore: rename impact score to quality score

README.md

@@ -52,7 +52,7 @@ and [OpenAPI 3.1.x](https://github.com/OAI/OpenAPI-Specification/blob/master/ver
       - [outputFormat](#outputformat)
       - [ruleset](#ruleset)
       - [summaryOnly](#summaryonly)
-      - [produceImpactScore](#produceimpactscore)
+      - [produceQualityScore](#producequalityscore)
       - [markdownReport](#markdownreport)
   * [Programmatic Usage](#programmatic-usage)
 - [Validator Output](#validator-output)
@@ -176,7 +176,7 @@ Options:
   -n, --no-colors                disable colorizing of the output (default is false)
   -r, --ruleset <file>           use Spectral ruleset contained in `<file>` ("default" forces use of default IBM Cloud Validation Ruleset)
   -s, --summary-only             include only the summary information and skip individual errors and warnings (default is false)
-  -q, --impact-score             compute scores representing the API impact of rule violations and include with the results (default is false)
+  -q, --quality-score             compute scores representing the API quality of rule violations and include with the results (default is false)
   -m, --markdown-report          generate a Markdown file with a report on all validator results (default is false)
   -w, --warnings-limit <number>  set warnings limit to <number> (default is -1)
   --version                      output the version number
@@ -701,21 +701,21 @@ module.exports = {
 </tr>
 </table>
 
-##### produceImpactScore
+##### produceQualityScore
 
 <table border=1>
 <tr>
 <td><b>Description</b></td>
 <td width=25%><b>Default</b></td>
 </tr>
 <tr>
-<td>The <code>produceImpactScore</code> configuration property corresponds to the
-<code>-q</code>/<code>--impact-score</code> command-line option. If set to true,
+<td>The <code>produceQualityScore</code> configuration property corresponds to the
+<code>-q</code>/<code>--quality-score</code> command-line option. If set to true,
 the validator will, in addition to reporting individual rule violations, use the
-rule violation data to produce API impact scores based on the categories of usability,
+rule violation data to produce API quality scores based on the categories of usability,
 security, robustness, and cost of evolution. By default, the data demonstrating how
 the scores are calculated from each rule is displayed. If this option is combined with
-the "summary only" configuration option, only the categorized impact scores are displayed.
+the "summary only" configuration option, only the categorized quality scores are displayed.
 These scores are useful for "Automated Quality Screening". See [this documentation](docs/automated-quality-screening.md)
 for more information about the purpose of these scores and how they are computed.
 </td>
@@ -734,20 +734,20 @@ for more information about the purpose of these scores and how they are computed
 <tr>
 <td>
 <pre>
-produceImpactScore: true
+produceQualityScore: true
 </pre>
 </td>
 <td>
 <pre>
 {
-  "produceImpactScore": true
+  "produceQualityScore": true
 }
 </pre>
 </td>
 <td>
 <pre>
 module.exports = {
-  produceImpactScore: true
+  produceQualityScore: true
 };
 </pre>
 </td>
@@ -765,7 +765,7 @@ module.exports = {
 <td>The <code>markdownReport</code> configuration property corresponds to the
 <code>-m</code>/<code>--markdown-report</code> command-line option.
 If set to true, the validator will generate a Markdown file containing a report on all of the validator results,
-including the individual rule violations, the impact scores, and the data used to compute the impact scores.
+including the individual rule violations, the quality scores, and the data used to compute the quality scores.
 It provides a single location to see all of the information produced by the validator.
 A default filename is always used and is based on the name of the API definition file provided to the validator.
 If a file of the same name already exists, it will be overwritten by default. This is because the primary use-case
@@ -881,9 +881,9 @@ warnings, and finally a summary section.
 
 - The `-s`/`--summary-only` command-line option or the `summaryOnly` configuration property causes only the summary to be displayed.
 - The `-e`/`--errors-only` option or `errorsOnly` configuration property causes only error-level violations to be displayed.
-- The `-q`/`--impact-score` option or `produceImpactScore` configuration property causes the validator to show aggregated impact scores. See the example below:
+- The `-q`/`--quality-score` option or `produceQualityScore` configuration property causes the validator to show aggregated quality scores. See the example below:
 
-Example of impact score tables that are appended to the standard output:
+Example of quality score tables that are appended to the standard output:
 
 ```
 ┌────────────────┬───────────┐
@@ -896,7 +896,7 @@ Example of impact score tables that are appended to the standard output:
 │ overall (mean) │   91 /100 │
 └────────────────┴───────────┘
 ┌──────────────────────────────┬───────┬─────────────────┬──────────────────┬─────────────────┬───────────────────┬──────────────────┬────────────┐
-│                         rule │ count │            func │ usability impact │ security impact │ robustness impact │ evolution impact │ rule total │
+│                         rule │ count │            func │ usability quality │ security quality │ robustness quality │ evolution quality │ rule total │
 ├──────────────────────────────┼───────┼─────────────────┼──────────────────┼─────────────────┼───────────────────┼──────────────────┼────────────┤
 │ operation-operationId-unique │     1 │  1×3÷operations │                1 │                 │                 2 │                3 │          6 │
 │       ibm-no-array-responses │     2 │ 2×10÷operations │                  │                 │                   │               20 │         20 │
@@ -908,7 +908,7 @@ Example of impact score tables that are appended to the standard output:
 
 When displaying JSON output, the validator will produce a JSON object which complies with
 [this JSON schema](packages/validator/src/schemas/results-object.yaml). The JSON data will include information about all rule violations,
-as well as all impact score information computed from the rule violations.
+as well as all quality score information computed from the rule violations.
 Here is an example of JSON output:
 
 ```json
@@ -987,7 +987,7 @@ Here is an example of JSON output:
     }
   },
   "hasResults": true
-  "impactScore": {
+  "qualityScore": {
     "categorizedSummary": {
       "usability": 94,
       "security": 100,
@@ -1020,7 +1020,7 @@ Here is an example of JSON output:
 ```
 
 The JSON output is also affected by the `-s`/`--summary-only` and `-e`/`--errors-only` options as well as the `summaryOnly` and `errorsOnly`
-configuration properties. It is _not_ affected by the `-q`/`--impact-score` option or `produceImpactScore` property.
+configuration properties. It is _not_ affected by the `-q`/`--quality-score` option or `produceQualityScore` property.
 
 ## Logging
 

docs/automated-quality-screening.md

@@ -1,11 +1,11 @@
 # Automated Quality Screening
 
 The validator provides Automated Quality Screening (AQS) scores via the `-q` (or
-`--impact-score`) flag. These scores help you evaluate risk and make decisions about investing in
+`--quality-score`) flag. These scores help you evaluate risk and make decisions about investing in
 the quality of your service's API. AQS scores are not a substitute for expert review, but minimum
 AQS scores may be a prerequisite to a review.
 
-AQS scores give you insight about four impact dimensions for API quality: usability, security,
+AQS scores give you insight about four quality dimensions for API quality: usability, security,
 robustness, and cost of evolution. Each dimension will be scored from 0 to 100, and the overall
 score will be the average (mean) of the four individual scores.
 
@@ -23,26 +23,26 @@ of a recalibration. Recalibrations will occur as a part of minor (but not patch)
 validator.
 
 Findings (errors and warnings) produced by each rule of the validator will reduce the AQS score for
-one or more impact dimensions. The size of the reduction is determined by the number of findings for
+one or more quality dimensions. The size of the reduction is determined by the number of findings for
 the rule and a qualitative weight assigned to the rule, scaled to the overall size of the API.
 
-For each impact dimension, there is distinct criteria for assigning impact:
+For each quality dimension, there is distinct criteria for assigning impact:
 
 - **Usability** is the broadest category, as most problems with an API will manifest as (at least)
   usability problems. Anything from stylistic deviation from standards (for example `camelCase` vs.
   `snake_case`) to underspecified behavior has a usability impact.
-- **Security** impact can come from clear deviations from best practices within an API design, but
+- **Security** quality can come from clear deviations from best practices within an API design, but
   very often comes from undefined or excessively permissive validation constraints on values handled
   in an API. While some constraints may be enforced by a service implementation without being
   defined in its API definition, it must be assumed that they are not. Overly permissive constraints
   can indicate a susceptibility to code-injection or denial-of-service attacks.
-- **Robustness** impact comes from undefined behavior that a client may rely on, API design likely
+- **Robustness** quality comes from undefined behavior that a client may rely on, API design likely
   to be misunderstood or misapplied, and missing robustness features such as optimistic locking that
   may be needed to mitigate race conditions for certain kinds of requests.
-- **Evolution** impact comes from designing or specifying an API in such a way that it could be
+- **Evolution** quality comes from designing or specifying an API in such a way that it could be
   difficult, expensive, or impossible to provide backward compatibility when certain kinds of new
   features are added to a service.
 
-Note that rules that identify undefined behavior often have an impact across all four impact
+Note that rules that identify undefined behavior often have an impact across all four quality
 dimensions.
 

packages/validator/README.md

@@ -25,7 +25,7 @@ Options:
   -n, --no-colors                disable colorizing of the output (default is false)
   -r, --ruleset <file>           use Spectral ruleset contained in `<file>` ("default" forces use of default IBM Cloud Validation Ruleset)
   -s, --summary-only             include only the summary information and skip individual errors and warnings (default is false)
-  -q, --impact-score             compute scores representing the API impact of rule violations and include with the results (default is false)
+  -q, --quality-score             compute scores representing the API quality of rule violations and include with the results (default is false)
   -m, --markdown-report          generate a Markdown file with a report on all validator results (default is false)
   -w, --warnings-limit <number>  set warnings limit to <number> (default is -1)
   --version                      output the version number
@@ -38,4 +38,4 @@ Again, this page displays abbreviated information. The following links may be he
 
 - [Detailed information about the configuration options](../../README.md#configuration)
 - [Detailed information about the default ruleset](../../docs/ibm-cloud-rules.md)
-- [Detailed information about the `--impact-score` feature](../../docs/automated-quality-screening.md)
+- [Detailed information about the `--quality-score` feature](../../docs/automated-quality-screening.md)

packages/validator/src/cli-validator/run-validator.js

@@ -25,7 +25,7 @@ const {
 } = require('./utils');
 
 const { runSpectral } = require('../spectral');
-const { produceImpactScore, printScoreTables } = require('../scoring-tool');
+const { produceQualityScore, printScoreTables } = require('../scoring-tool');
 const { printMarkdownReport } = require('../markdown-report');
 
 let logger;
@@ -157,11 +157,11 @@ async function runValidator(cliArgs, parseOptions = {}) {
     return Promise.reject(2);
   }
 
-  // If multiple files were specified and the impact score is requested, exit with an error.
+  // If multiple files were specified and the quality score is requested, exit with an error.
   // We could change this behavior in the future.
-  if (filesToValidate.length > 1 && context.config.produceImpactScore) {
+  if (filesToValidate.length > 1 && context.config.produceQualityScore) {
     logger.error(
-      'At most one file can be specified when the impact score is requested.'
+      'At most one file can be specified when the quality score is requested.'
     );
     return Promise.reject(2);
   }
@@ -238,30 +238,30 @@ async function runValidator(cliArgs, parseOptions = {}) {
       continue;
     }
 
-    // Compute scoring information if 1) the user requested the "impact score"
+    // Compute scoring information if 1) the user requested the "quality score"
     // option, 2) if JSON output is requested, or 3) if the markdown report is
     // requested. The JSON output and markdown report always include all results,
     // including the standard rule violations and the scoring information.
-    let impactScoreInformation = {};
+    let qualityScoreInformation = {};
     if (
-      context.config.produceImpactScore ||
+      context.config.produceQualityScore ||
       outputIsJSON(context) ||
       context.config.markdownReport
     ) {
-      logger.info('Impact scores are being calculated...');
-      impactScoreInformation = await produceImpactScore(results, context);
+      logger.info('Quality scores are being calculated...');
+      qualityScoreInformation = await produceQualityScore(results, context);
     } else {
       logger.info(
-        'Impact scores are not being calculated. Scores are calculated when' +
+        'Quality scores are not being calculated. Scores are calculated when' +
           'requested, or when JSON output or a Markdown report is requested.'
       );
     }
 
-    // Combine validator and impact score results into one object.
+    // Combine validator and quality score results into one object.
     results = {
       ...results,
-      impactScore: {
-        ...impactScoreInformation,
+      qualityScore: {
+        ...qualityScoreInformation,
       },
     };
 
@@ -293,7 +293,7 @@ async function runValidator(cliArgs, parseOptions = {}) {
     // If summary output is requested, filter out extraneous information here.
     if (context.config.summaryOnly) {
       // Remove verbose scoring data.
-      results.impactScore.scoringData = [];
+      results.qualityScore.scoringData = [];
 
       // Remove individual rule violation results.
       ['error', 'warning', 'info', 'hint'].forEach(sev => {
@@ -307,9 +307,9 @@ async function runValidator(cliArgs, parseOptions = {}) {
     } else if (results.hasResults) {
       printResults(context, results);
 
-      // If the user requested the "impact score" option, print
+      // If the user requested the "quality score" option, print
       // the scoring tables in addition to the standard output.
-      if (context.config.produceImpactScore) {
+      if (context.config.produceQualityScore) {
         printScoreTables(context, results);
       }
     } else {

packages/validator/src/cli-validator/utils/cli-options.js

@@ -76,12 +76,12 @@ function createCLIOptions() {
       'include only the summary information and skip individual errors and warnings (default is false)'
     )
     .option(
-      '-q, --impact-score',
-      'compute scores representing the API impact of rule violations and include with the results'
+      '-q, --quality-score',
+      'compute scores representing the API quality of rule violations and include with the results'
     )
     .option(
       '-m, --markdown-report',
-      'write a markdown report to a file, consisting of rule violations and impact scores'
+      'write a markdown report to a file, consisting of rule violations and quality scores'
     )
     .option(
       '-w, --warnings-limit <number>',

packages/validator/src/cli-validator/utils/configuration-manager.js

@@ -42,7 +42,7 @@ const defaultConfig = {
   outputFormat: 'text',
   ruleset: null,
   summaryOnly: false,
-  produceImpactScore: false,
+  produceQualityScore: false,
   markdownReport: false,
 };
 
@@ -238,8 +238,8 @@ async function processArgs(args, cliParseOptions) {
     configObj.limits.warnings = opts.warningsLimit;
   }
 
-  if ('impactScore' in opts) {
-    configObj.produceImpactScore = true;
+  if ('qualityScore' in opts) {
+    configObj.produceQualityScore = true;
   }
 
   if ('markdownReport' in opts) {

packages/validator/src/markdown-report/report.js

@@ -20,7 +20,7 @@ Version: ${apiDefinition.info.version}
 ## Quick view
 ${primary(results)}
 
-The API impact score, also known as the "Automated Quality Screening" score, is calculated
+The API quality score, also known as the "Automated Quality Screening" score, is calculated
 by the IBM OpenAPI Validator to help users understand the impact of the rule violations
 reported by the validator. The scores are designed to help users evaluate risk and make
 decisions about investing in the quality of their service's API.
@@ -29,7 +29,7 @@ For more information, see [the AQS documentation](https://github.com/IBM/openapi
 ## Breakdown by category
 ${categorizedScores(results)}
 
-The "overall" impact score is the average (mean) of the categorized scores. The categorized scores are
+The "overall" quality score is the average (mean) of the categorized scores. The categorized scores are
 inherently weighted by the scoring algorithm, so that security violations are 5 times as severe
 as usability violations, evolution 3 times, and robustness 2 times.
 

packages/validator/src/markdown-report/tables/categorized-scores.js

@@ -5,9 +5,9 @@
 
 const MarkdownTable = require('../markdown-table');
 
-function getTable({ impactScore }) {
-  const { categorizedSummary } = impactScore;
-  const table = new MarkdownTable('Category', 'Impact Score');
+function getTable({ qualityScore }) {
+  const { categorizedSummary } = qualityScore;
+  const table = new MarkdownTable('Category', 'Quality Score');
 
   for (const [category, score] of Object.entries(categorizedSummary)) {
     // Bold the "overall" score.

packages/validator/src/markdown-report/tables/primary.js

@@ -5,15 +5,15 @@
 
 const MarkdownTable = require('../markdown-table');
 
-function getTable({ impactScore, error, warning }) {
+function getTable({ qualityScore, error, warning }) {
   const table = new MarkdownTable(
-    'Impact Score',
+    'Quality Score',
     'Error Count',
     'Warning Count'
   );
 
   table.addRow(
-    `${impactScore.categorizedSummary.overall} / 100`,
+    `${qualityScore.categorizedSummary.overall} / 100`,
     error.summary.total,
     warning.summary.total
   );

packages/validator/src/markdown-report/tables/scoring-data.js

@@ -5,16 +5,16 @@
 
 const MarkdownTable = require('../markdown-table');
 
-function getTable({ impactScore }) {
-  const { scoringData } = impactScore;
+function getTable({ qualityScore }) {
+  const { scoringData } = qualityScore;
   const table = new MarkdownTable(
     'Rule',
     'Count',
     'Func',
-    'Usability Impact',
-    'Security Impact',
-    'Robustness Impact',
-    'Evolution Impact',
+    'Usability Quality',
+    'Security Quality',
+    'Robustness Quality',
+    'Evolution Quality',
     'Rule Total'
   );