@ohlori/gherkin-lint 4.3.0

package/src/formatters/stylish.js

@@ -0,0 +1,81 @@
+/*eslint no-console: "off"*/
+require('core-js/stable/string');
+
+const style = {
+  gray: function(text) {
+    return '\x1b[38;5;243m' + text + '\x1b[0m';
+  },
+
+  underline: function(text) {
+    return '\x1b[0;4m' + text + '\x1b[24m';
+  }
+
+};
+
+function stylizeFilePath(filePath) {
+  return style.underline(filePath);
+}
+
+function stylizeError(error, maxLineLength, maxMessageLength, addColors) {
+  const indent = '  '; // indent 2 spaces so it looks pretty
+  const padding = '    '; //padding of 4 spaces, will be used between line numbers, error msgs and rule names, for readability
+  const errorLinePadded = error.line.toString().padEnd(maxLineLength);
+  const errorLineStylized = addColors ? style.gray(errorLinePadded) : errorLinePadded;
+
+  const errorRuleStylized = addColors ? style.gray(error.rule) : error.rule;
+  return indent + errorLineStylized + padding + error.message.padEnd(maxMessageLength) + padding + errorRuleStylized;
+}
+
+function getMaxLineLength(result) {
+  let length = 0;
+  result.errors.forEach(error => {
+    const errorStr = error.line.toString();
+    if (errorStr.length > length) {
+      length = errorStr.length;
+    }
+  });
+  return length;
+}
+
+function getMaxMessageLength(result, maxLineLength, consoleWidth) {
+  let length = 0;
+  result.errors.forEach(error => {
+    const errorStr = error.message.toString();
+
+    // Get the length of the formatted error message when no extra padding is applied
+    // If the formatted message is longer than the console width, we will ignore its length
+    const expandedErrorStrLength = stylizeError(error, maxLineLength, 0, false).length;
+
+    if (errorStr.length > length && expandedErrorStrLength < consoleWidth) {
+      length = errorStr.length;
+    }
+  });
+
+  return length;
+}
+
+function printResults(results) {
+  // If the console is tty, get its width and use it to ensure we don't try to write messages longer
+  // than the console width when possible
+  let consoleWidth = Infinity;
+  if (process.stdout.isTTY) {
+    consoleWidth = process.stdout.columns;
+  }
+
+  results.forEach(result => {
+    if (result.errors.length > 0) {
+      const maxLineLength = getMaxLineLength(result);
+      const maxMessageLength = getMaxMessageLength(result, maxLineLength, consoleWidth);
+      console.error(stylizeFilePath(result.filePath));
+
+      result.errors.forEach(error => {
+        console.error(stylizeError(error, maxLineLength, maxMessageLength, true));
+      });
+      console.error('\n');
+    }
+  });
+}
+
+module.exports = {
+  printResults: printResults
+};

package/src/formatters/xunit.js

@@ -0,0 +1,36 @@
+function printResults(results) {
+  const testCases = results.map(result => ({
+    _attributes: {
+      name : result.filePath
+    },
+    error: result.errors.map(error => ({
+      _attributes: {
+        message: error.message,
+        type: 'gherkin-lint-error'
+      },
+      _cdata: `${result.filePath}:${error.line} (${error.rule}) ${error.message}`        
+    }))    
+  }));
+  const testSuiteReport = {
+    _declaration:{
+      _attributes: {
+        version: '1.0',
+        encoding: 'utf-8'
+      }
+    },
+    testsuite : {
+      _attributes: {
+        name: 'gherkin-lint',
+      },
+      testcase : testCases
+    }
+  };
+  let convert = require('xml-js');
+  const xunitXml = convert.js2xml(testSuiteReport, {compact: true, spaces: 4});
+  /*eslint no-console: "off"*/
+  console.error(xunitXml);
+}
+
+module.exports = {
+  printResults: printResults
+};

package/src/linter.js

@@ -0,0 +1,140 @@
+const _ = require('lodash');
+const {generateMessages} = require('@cucumber/gherkin');
+const {IdGenerator, SourceMediaType} = require('@cucumber/messages');
+const fs = require('fs');
+const rules = require('./rules.js');
+const logger = require('./logger.js');
+
+function readAndParseFile(filePath) {
+  return new Promise((resolve, reject) => {
+    const source = fs.readFileSync(filePath, 'utf8');
+    const options = {
+      includeGherkinDocument: true,
+      includePickles: false,
+      includeSource: false,
+      newId: IdGenerator.incrementing(),
+    };
+
+    try {
+      const envelopes = generateMessages(
+        source,
+        filePath,
+        SourceMediaType.TEXT_X_CUCUMBER_GHERKIN_PLAIN,
+        options
+      );
+      const parsingErrors = envelopes
+        .filter(envelope => envelope.parseError)
+        .map(envelope => envelope.parseError);
+
+      if (parsingErrors.length) {
+        reject(processFatalErrors(parsingErrors));
+        return;
+      }
+
+      const documentEnvelope = envelopes.find(envelope => envelope.gherkinDocument);
+      const file = {
+        relativePath: filePath,
+        lines: source.split(/\r\n|\r|\n/),
+      };
+      resolve({
+        feature: documentEnvelope ? documentEnvelope.gherkinDocument.feature : undefined,
+        file,
+      });
+    } catch (error) {
+      logger.error(`Gherkin emitted an error while parsing ${filePath}: ${error}`);
+      reject(processFatalErrors([error]));
+    }
+  });
+}
+
+
+function lint(files, configuration, additionalRulesDirs) {
+  let results = [];
+
+  return Promise.all(files.map((f) => {
+    let perFileErrors = [];
+
+    return readAndParseFile(f)
+      .then(
+        // Handle Promise.resolve 
+        ({feature, file}) => {
+          perFileErrors = rules.runAllEnabledRules(feature, file, configuration, additionalRulesDirs);
+        },
+        // Handle Promise.reject 
+        (parsingErrors) => {
+          perFileErrors = parsingErrors;
+        })
+      .finally(()=> {
+        let fileBlob = {
+          filePath: fs.realpathSync(f), 
+          errors: _.sortBy(perFileErrors, 'line')
+        };
+
+        results.push(fileBlob);
+      });
+  })).then(() => results);
+}
+
+function processFatalErrors(errors) {
+  const firstError = errors[0];
+  const firstMessage = getErrorMessage(firstError);
+
+  // A tag before a Background causes cascading parser errors. Report the root
+  // cause once instead of emitting every recovery error that follows it.
+  if (firstMessage.includes('got \'Background') &&
+      firstMessage.includes('expected: #TagLine, #RuleLine')) {
+    return [{
+      message: 'Tags on Backgrounds are disallowed',
+      rule: 'no-tags-on-backgrounds',
+      line: getErrorLine(firstError)
+    }];
+  }
+
+  return errors.map(getFormattedFatalError);
+}
+
+
+/*eslint no-console: "off"*/
+function getFormattedFatalError(error) {
+  const errorData = getErrorMessage(error);
+  const errorLine = getErrorLine(error);
+  let errorMsg;
+  let rule;
+  if (errorData.includes('got \'Background')) {
+    errorMsg = 'Multiple "Background" definitions in the same Feature or Rule are disallowed';
+    rule = 'up-to-one-background-per-scope';
+  } else if(errorData.includes('got \'Feature')) {
+    errorMsg = 'Multiple "Feature" definitions in the same file are disallowed';
+    rule = 'one-feature-per-file';
+  } else if (
+    errorData.includes('expected: #EOF, #TableRow, #DocStringSeparator, #StepLine, #TagLine, #ScenarioLine, #RuleLine, #Comment, #Empty, got') ||
+    errorData.includes('expected: #EOF, #TableRow, #DocStringSeparator, #StepLine, #TagLine, #ExamplesLine, #ScenarioLine, #RuleLine, #Comment, #Empty, got')
+  ) {
+    errorMsg = 'Steps should begin with "Given", "When", "Then", "And" or "But". Multiline steps are disallowed';
+    rule = 'no-multiline-steps';
+
+  } else {
+    errorMsg = errorData;
+    rule = 'unexpected-error';
+  }
+  return {message: errorMsg,
+    rule   : rule,
+    line   : errorLine};
+}
+
+function getErrorMessage(error) {
+  return error.message || error.data || String(error);
+}
+
+function getErrorLine(error) {
+  if (error.source && error.source.location) {
+    return error.source.location.line;
+  }
+  const match = getErrorMessage(error).match(/\((\d+):/);
+  return match ? Number(match[1]) : 0;
+}
+
+module.exports = {
+  lint: lint,
+  readAndParseFile: readAndParseFile
+};

package/src/logger.js

@@ -0,0 +1,14 @@
+/* eslint-disable no-console */
+
+function boldError(msg) {
+  console.error(`\x1b[31m\x1b[1m${msg}\x1b[0m`);
+}
+
+function error(msg) {
+  console.error(`\x1b[31m${msg}\x1b[0m`);
+}
+
+module.exports = {
+  error: error,
+  boldError: boldError
+};

package/src/main.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+const program = require('commander');
+const linter = require('./linter.js');
+const featureFinder = require('./feature-finder.js');
+const configParser = require('./config-parser.js');
+const logger = require('./logger.js');
+
+function list(val) {
+  return val.split(',');
+}
+
+function collect(val, memo) {
+  memo.push(val);
+  return memo;
+}
+
+program
+  .usage('[options] <feature-files>')
+  .option('-f, --format [format]', 'output format. Possible values: json, stylish, xunit. Defaults to stylish')
+  .option('-i, --ignore <...>', 'comma seperated list of files/glob patterns that the linter should ignore, overrides ' + featureFinder.defaultIgnoreFileName + ' file', list)
+  .option('-c, --config [config]', 'configuration file, defaults to ' + configParser.defaultConfigFileName)
+  .option('-r, --rulesdir <...>', 'additional rule directories', collect, [])
+  .parse(process.argv);
+
+const options = program.opts();
+const additionalRulesDirs = options.rulesdir;
+const files = featureFinder.getFeatureFiles(program.args, options.ignore);
+const config = configParser.getConfiguration(options.config, additionalRulesDirs);
+linter.lint(files, config, additionalRulesDirs)
+  .then((results) => {
+    printResults(results, options.format);
+    process.exit(getExitCode(results));
+  });
+
+function getExitCode(results) {
+  let exitCode = 0;
+  results.forEach(result => {
+    if (result.errors.length > 0) {
+      exitCode = 1;
+    }
+  });
+  return exitCode;
+}
+
+function printResults(results, format) {
+  let formatter;
+  if (format === 'json') {
+    formatter = require('./formatters/json.js');
+  } else if (format === 'xunit') {
+    formatter = require('./formatters/xunit.js');
+  } else if (!format || format === 'stylish') {
+    formatter = require('./formatters/stylish.js');
+  } else {
+    logger.boldError('Unsupported format. The supported formats are json, xunit and stylish.');
+    process.exit(1);
+  }
+  formatter.printResults(results);
+}

package/src/rules/allowed-tags.js

@@ -0,0 +1,55 @@
+const _ = require('lodash');
+const gherkinUtils = require('./utils/gherkin.js');
+const rule = 'allowed-tags';
+
+const availableConfigs = {
+  'tags': [],
+  'patterns': []
+};
+
+function run(feature, unused, configuration) {
+  if (!feature) {
+    return [];
+  }
+
+  let errors = [];
+  const allowedTags = configuration.tags;
+  const allowedPatterns = getAllowedPatterns(configuration);
+
+  gherkinUtils.getTaggableNodes(feature).forEach(node => {
+    checkTags(node, allowedTags, allowedPatterns, errors);
+  });
+
+  return errors;
+}
+
+function getAllowedPatterns(configuration) {
+  return (configuration.patterns || []).map((pattern) => new RegExp(pattern));
+}
+
+function checkTags(node, allowedTags, allowedPatterns, errors) {
+  return (node.tags || [])
+    .filter(tag => !isAllowed(tag, allowedTags, allowedPatterns))
+    .forEach(tag => {
+      errors.push(createError(node, tag));
+    });
+}
+
+function isAllowed(tag, allowedTags, allowedPatterns) {
+  return _.includes(allowedTags, tag.name)
+    || allowedPatterns.some((pattern) => pattern.test(tag.name));
+}
+
+function createError(node, tag) {
+  return {
+    message: 'Not allowed tag ' + tag.name + ' on ' + node.keyword,
+    rule   : rule,
+    line   : tag.location.line
+  };
+}
+
+module.exports = {
+  name: rule,
+  run: run,
+  availableConfigs: availableConfigs
+};

package/src/rules/file-name.js

@@ -0,0 +1,40 @@
+const path = require('path');
+const _ = require('lodash');
+
+const rule = 'file-name';
+const availableConfigs = {
+  'style': 'PascalCase'
+};
+const checkers = {
+  'PascalCase': filename => _.startCase(filename).replace(/ /g, ''),
+  'Title Case': filename => _.startCase(filename),
+  'camelCase': filename => _.camelCase(filename),
+  'kebab-case': filename => _.kebabCase(filename),
+  'snake_case': filename => _.snakeCase(filename)
+};
+
+function run(feature, file, configuration) {
+  if (!file) {
+    return [];
+  }
+  const {style} = _.merge(availableConfigs, configuration);
+  const filename = path.basename(file.relativePath, '.feature');
+  if (!checkers[style]) {
+    throw new Error('style "' + style + '" not supported for file-name rule');
+  }
+  const expected = checkers[style](filename);
+  if (filename === expected) {
+    return [];
+  }
+  return [{
+    message: `File names should be written in ${style} e.g. "${expected}.feature"`,
+    rule: rule,
+    line: 0
+  }];
+}
+
+module.exports = {
+  name: rule,
+  run: run,
+  availableConfigs: availableConfigs
+};

package/src/rules/indentation.js

@@ -0,0 +1,106 @@
+const _ = require('lodash');
+const gherkinUtils = require('./utils/gherkin.js');
+
+const rule = 'indentation';
+const defaultConfig = {
+  'Feature': 0,
+  'Background': 0,
+  'Rule': 0,
+  'Scenario': 0,
+  'Step': 2,
+  'Examples': 0,
+  'example': 2,
+  'given': 2,
+  'when': 2,
+  'then': 2,
+  'and': 2,
+  'but': 2
+};
+
+const availableConfigs = _.merge({}, defaultConfig, {
+  // The values here are unused by the config parsing logic.
+  'feature tag': -1,
+  'scenario tag': -1
+});
+
+function mergeConfiguration(configuration) {
+  let mergedConfiguration = _.merge({}, defaultConfig, configuration);
+  if (!Object.prototype.hasOwnProperty.call(mergedConfiguration, 'feature tag')) {
+    mergedConfiguration['feature tag'] = mergedConfiguration['Feature'];
+  }
+  if (!Object.prototype.hasOwnProperty.call(mergedConfiguration, 'scenario tag')) {
+    mergedConfiguration['scenario tag'] = mergedConfiguration['Scenario'];
+  }
+  return mergedConfiguration;
+}
+
+function run(feature, unused, configuration) {
+  if (!feature) {
+    return [];
+  }
+
+  let errors = [];
+  const mergedConfiguration = mergeConfiguration(configuration);
+
+  function test(parsedLocation, type) {
+    // location.column is 1 index based so, when we compare with the expected
+    // indentation we need to subtract 1
+    if (parsedLocation.column - 1 !== mergedConfiguration[type]) {
+      errors.push({
+        message: 'Wrong indentation for "' + type +
+                            '", expected indentation level of ' + mergedConfiguration[type] +
+                            ', but got ' + (parsedLocation.column - 1),
+        rule   : rule,
+        line   : parsedLocation.line
+      });
+    }
+  }
+
+  function testStep(step) {
+    let stepType = gherkinUtils.getLanguageInsitiveKeyword(step, feature.language);
+    stepType = stepType in configuration ? stepType : 'Step';
+    test(step.location, stepType);
+  }
+
+  function testTags(tags, type) {
+    _(tags).groupBy('location.line').forEach(tagLocationGroup => {
+      const firstTag = _(tagLocationGroup).sortBy('location.column').head();
+      test(firstTag.location, type);
+    });
+  }
+
+  test(feature.location, 'Feature');
+  testTags(feature.tags, 'feature tag');
+
+  feature.children.forEach(child => {
+    if (child.rule) {
+      test(child.rule.location, 'Rule');
+    } else if (child.background) {
+      test(child.background.location, 'Background');
+      child.background.steps.forEach(testStep);
+    } else {
+      test(child.scenario.location, 'Scenario');
+      testTags(child.scenario.tags, 'scenario tag');
+      child.scenario.steps.forEach(testStep);
+
+      child.scenario.examples.forEach(examples => {
+        test(examples.location, 'Examples');
+
+        if (examples.tableHeader) {
+          test(examples.tableHeader.location, 'example');
+          examples.tableBody.forEach(row => {
+            test(row.location, 'example');
+          });
+        }
+      });
+    }
+  });
+
+  return errors;
+}
+
+module.exports = {
+  name: rule,
+  run: run,
+  availableConfigs: availableConfigs
+};

package/src/rules/keywords-in-logical-order.js

@@ -0,0 +1,65 @@
+const gherkinUtils = require('./utils/gherkin.js');
+
+const rule = 'keywords-in-logical-order';
+
+function run(feature) {
+  if (!feature) {
+    return [];
+  }
+
+  let errors = [];
+
+  let simpleStepContainers = feature.children
+    .filter(child => child.background || child.scenario);
+
+  let ruleStepContainers = feature.children
+    .filter(child => child.rule)
+    .map(child => child.rule.children)
+    // .flat(); NOTE: flat not available until nodejs 11, which this project does not require
+    // using reduce() equivalent instead
+    // When revisiting wth nodejs 11, consider using flatmap()
+    .reduce((flattened, element) => flattened.concat(element), []);
+
+  let allStepContainers = simpleStepContainers.concat(ruleStepContainers);
+
+  allStepContainers.forEach(child => {
+    const node = child.background || child.scenario;
+
+    const keywordList = ['given', 'when', 'then'];
+
+    let maxKeywordPosition = undefined;
+
+    node.steps.forEach((step) => {
+      const keyword = gherkinUtils.getLanguageInsitiveKeyword(step, feature.language);
+      let keywordPosition = keywordList.indexOf(keyword);
+
+      if (keywordPosition === -1) {
+        //   not found
+        return;
+      }
+
+      if (keywordPosition < maxKeywordPosition) {
+        let maxKeyword = keywordList[maxKeywordPosition];
+        errors.push(createError(step, maxKeyword));
+      }
+
+      maxKeywordPosition =
+        Math.max(maxKeywordPosition, keywordPosition) || keywordPosition;
+    });
+  });
+
+  return errors;
+}
+
+function createError(step, maxKeyword) {
+  return {
+    message: `Step "${step.keyword}${step.text}" should not appear after step using keyword ${maxKeyword}`,
+    rule: rule,
+    line: step.location.line,
+  };
+}
+
+module.exports = {
+  name: rule,
+  run: run,
+};

package/src/rules/max-scenarios-per-file.js

@@ -0,0 +1,46 @@
+const _ = require('lodash');
+const rule = 'max-scenarios-per-file';
+
+const defaultConfig = {
+  'maxScenarios': 10,
+  'countOutlineExamples': true
+};
+
+function run(feature, unused, config) {
+  if (!feature) {
+    return [];
+  }
+  let errors = [];
+  const mergedConfiguration = _.merge({}, defaultConfig, config);
+  const maxScenarios = mergedConfiguration.maxScenarios;
+  let count = feature.children.length;
+
+  feature.children.forEach(child => {
+    if (child.background) {
+      count = count - 1;
+    } else if (child.scenario.examples.length  && mergedConfiguration.countOutlineExamples) {
+      count = count - 1;
+      child.scenario.examples.forEach(example => {
+        if (example.tableBody) {
+          count = count + example.tableBody.length;
+        }
+      });
+    }
+  });
+
+  if (count > maxScenarios) {
+    errors.push({
+      message: 'Number of scenarios exceeds maximum: ' + count + '/' + maxScenarios,
+      rule,
+      line: 0
+    });
+  }
+
+  return errors;
+}
+
+module.exports = {
+  name: rule,
+  run: run,
+  availableConfigs: defaultConfig
+};