@sap/cds-compiler 2.11.4 → 2.12.0

package/CHANGELOG.md

@@ -7,12 +7,69 @@
 Note: `beta` fixes, changes and features are usually not listed in this ChangeLog but [here](doc/CHANGELOG_BETA.md).
 The compiler behavior concerning `beta` features can change at any time without notice.
 
+## Version 2.12.0 - 2022-01-25
+
+### Added
+
+- CDL parser: You can now use multiline string literals and text blocks.  
+  Use backticks (\`) for string literals that can span multiple lines and can use JavaScript-like escape
+  sequences such as `\u{0020}`.  You can also use three backticks (\`\`\`) for strings (a.k.a. text blocks)
+  which are automatically indentation-stripped and can have an optional language identifier that is used
+  for syntax highlighting, similar to markdown.  In difference to the former, text blocks require the
+  opening and closing backticks to be on separate lines.
+  Example:
+
+      @annotation: `Multi
+       line\u{0020}strings`
+  
+      @textblock: ```xml
+                  <summary>
+                    <detail>The root tag has no indentation in this example</detail>
+                  </summary>
+                  ```
+      ...
+
+- Enhance the ellipsis operator `...` for array annotations by an `up to ‹val›`:
+  only values in the array of the base annotation up to (including) the first match
+  of the specified `‹val›` are included at the specified place in the final array value.
+  An array annotation can have more than on `... up to ‹val›` items and must also
+  have a pure `...` item after them.  
+  A structured `‹val›` matches if the array item is also a structure and all property
+  values in `‹val›` are equal to the corresponding property value in the array value;
+  it is not necessary to specify all properties of the array value items in `‹val›`.
+  Example
+
+      @Anno: [{name: one, val: 1}, {name: two, val: 2}, {name: four, val: 4}]
+      type T: Integer;
+      @Anno: [{name: zero, val: 0}, ... up to {name: two}, {name: three, val: 3}, ...]
+      annotate T;
+
+- for.odata: Support `@cds.on {update|insert}` as replacement for deprecated `@odata.on { update|insert }` to
+  set `@Core.Computed`.
+
+### Changed
+
+- Update OData Vocabularies 'Aggregation', 'Capabilities', 'Common', 'Core', PersonalData, 'Session', 'UI'
+
+### Fixed
+
+- to.sql/hdi/hdbcds: With `exists`, ensure that the precedence of the existing association-on-conditions and where-conditions is kept by adding braces.
+- to.sql/hdi: Window function suffixes are now properly rendered.
+- to.sql: `$self` comparisons inside aspects are not checked and won't result in an error anymore.
+- to.hdbcds:
+  + Correctly apply the "."-to-"_"-translation algorithm to artifacts that are marked with `@cds.persistence.exists`.
+  + Message with ID `anno-hidden-exists` (former `anno-unstable-hdbcds`) is now
+    only issued if the compiler generates a SAP HANA CDS artifact which would hide
+    a native database object from being resolved in a SAP HANA CDS `using … as …`.
+- to.cdl: Annotation paths containing special characters such as spaces or `@` are now quoted, e.g. `@![some@annotation]`.
+- compiler: A warning is emitted for elements of views with localized keys as the localized property is ignored for them.
+
 ## Version 2.11.4 - 2021-12-21
 
 ### Fixed
 
 - CDL parser: in many situations, improve message when people use reserved keywords as identifier
-- Improve error text and error location for ambiguious auto-redirection target
+- Improve error text and error location for ambiguous auto-redirection target
 - to.sql/hdi/hdbcds:
   + Correctly detect `exists` in projections
   + Correctly handle elements starting with `$` in the on-condition of associations

package/bin/cds_update_identifiers.js

@@ -30,22 +30,22 @@ const fs = require('fs');
 const path = require('path');
 
 const cliArgs = process.argv.slice(2);
-const filename = cliArgs[0];
+const filepath = cliArgs[0];
 
 if (cliArgs.length !== 1)
   exitError(`Expected exactly one argument, ${cliArgs.length} given`);
 
-if (!filename)
-  exitError('Expected non-empty filename as argument!');
+if (!filepath)
+  exitError('Expected non-empty filepath as argument!');
 
 // Do not use allow-list approach.
 // There may be CDS files with other extensions than `.cds`.
-if (filename.endsWith('.csn') || filename.endsWith('.json'))
+if (filepath.endsWith('.csn') || filepath.endsWith('.json'))
   exitError('Only CDS files can be passed! Found CSN file!');
 
-let source = fs.readFileSync(filename, 'utf-8');
-source = modernizeIdentifierStyle(source, filename);
-fs.writeFileSync(filename, source);
+let sourceStr = fs.readFileSync(filepath, 'utf-8');
+sourceStr = modernizeIdentifierStyle(sourceStr, filepath);
+fs.writeFileSync(filepath, sourceStr);
 process.exit(0); // success
 
 // --------------------------------------------------------

package/bin/cdsc.js

@@ -227,7 +227,7 @@ function displayUsage(error, helpText, code) {
   out.write(`${helpText}\n`);
   if (error) {
     if (error instanceof Array)
-      out.write(`${error.map(error => `cdsc: ERROR: ${error}`).join('\n')}\n`);
+      out.write(`${error.map(err => `cdsc: ERROR: ${err}`).join('\n')}\n`);
     else
       out.write(`cdsc: ERROR: ${error}\n`);
   }
@@ -301,11 +301,11 @@ function executeCommandLine(command, options, args) {
   // Return the original model (for chaining)
   function toCsn( model ) {
     if (options.directBackend) {
-      displayNamedCsn(model, 'csn', options);
+      displayNamedCsn(model, 'csn');
     }
     else {
       // Result already provided by caller
-      displayNamedXsn(model, 'csn', options);
+      displayNamedXsn(model, 'csn');
     }
     return model;
   }
@@ -316,7 +316,7 @@ function executeCommandLine(command, options, args) {
     const csn = options.directBackend ? model : compactModel(model, options);
 
     if (options.toHana && options.toHana.csn) {
-      displayNamedCsn(for_hdbcds(csn, remapCmdOptions(options, options.toHana)), 'hana_csn', options);
+      displayNamedCsn(for_hdbcds(csn, remapCmdOptions(options, options.toHana)), 'hana_csn');
     }
     else {
       const hanaResult = main.to.hdbcds(csn, remapCmdOptions(options, options.toHana));
@@ -339,7 +339,7 @@ function executeCommandLine(command, options, args) {
     const csn = options.directBackend ? model : compactModel(model, options);
     const odataCsn = main.for.odata(csn, remapCmdOptions(options, options.toOdata));
     if (options.toOdata && options.toOdata.csn) {
-      displayNamedCsn(odataCsn, 'odata_csn', options);
+      displayNamedCsn(odataCsn, 'odata_csn');
     }
     else if (options.toOdata && options.toOdata.json) {
       const result = main.to.edm.all(odataCsn, options);
@@ -392,7 +392,7 @@ function executeCommandLine(command, options, args) {
     const csn = options.directBackend ? model : compactModel(model, options);
     if (options.toSql && options.toSql.src === 'hdi') {
       if (options.toSql.csn) {
-        displayNamedCsn(for_hdi(csn, remapCmdOptions(options, options.toSql)), 'hdi_csn', options);
+        displayNamedCsn(for_hdi(csn, remapCmdOptions(options, options.toSql)), 'hdi_csn');
       }
       else {
         const hdiResult = main.to.hdi(csn, remapCmdOptions(options, options.toSql));
@@ -401,7 +401,7 @@ function executeCommandLine(command, options, args) {
       }
     }
     else if (options.toSql && options.toSql.csn) {
-      displayNamedCsn(for_sql(csn, remapCmdOptions(options, options.toSql)), 'sql_csn', options);
+      displayNamedCsn(for_sql(csn, remapCmdOptions(options, options.toSql)), 'sql_csn');
     }
     else {
       const sqlResult = main.to.sql(csn, remapCmdOptions(options, options.toSql));
@@ -505,7 +505,7 @@ function executeCommandLine(command, options, args) {
   // or display it to stdout if 'options.out' is '-'.
   // Depending on 'options.rawOutput', the model is either compacted to 'name.json' or
   // written in raw form to '<name>_raw.txt'.
-  function displayNamedXsn(xsn, name, options) {
+  function displayNamedXsn(xsn, name) {
     if (options.rawOutput) {
       writeToFileOrDisplay(options.out, `${name}_raw.txt`, util.inspect(reveal(xsn, options.rawOutput), false, null), true);
     }
@@ -525,9 +525,8 @@ function executeCommandLine(command, options, args) {
   /**
    * @param {CSN.Model} csn
    * @param {string} name
-   * @param {CSN.Options} options
    */
-  function displayNamedCsn(csn, name, options) {
+  function displayNamedCsn(csn, name) {
     if (!csn) // only print CSN if it is set.
       return;
     if (options.internalMsg) {

package/doc/CHANGELOG_ARCHIVE.md

@@ -1516,7 +1516,7 @@ Changes
 * Preserve the `key` properties of elements selected in a view (like we do in projections).
 * Improve the CSN representation for views.
   Represent the `where` and `on` condition of `select`s like other conditions.
-* Project name in github is now `cdx/cds-compiler`.
+* Project name in github is now `cap/cds-compiler`.
 
 Features
 * Support `select *` in views.

package/doc/CHANGELOG_BETA.md

@@ -8,6 +8,12 @@ Note: `beta` fixes, changes and features are listed in this ChangeLog just for i
 The compiler behavior concerning `beta` features can change at any time without notice.
 **Don't use `beta` fixes, changes and features in productive mode.**
 
+## Version 2.12.0 - 2022-01-25
+
+### Added `sqlSnippets`
+
+- to.sql/hdi/hdbcds: Introduce the annotations `@sql.prepend` and `@sql.append` that allow inserting user-written SQL snippets into the compiler generated content.
+
 ## Version 2.11.0
 
 ### Removed `foreignKeyConstraints`
@@ -163,6 +169,12 @@ The association to join transformation treats foreign key accesses with priority
 
 Unique constraints are now generally available.
 
+## Version 1.33.0 - 2020-08-24
+
+### Added `hanaAssocRealCardinality`
+
+Render JOIN cardinality in native HANA association if provided. If no cardinality has been specified.
+
 ## Version 1.32.0 - 2020-07-10
 
 ### Removed `aspectCompositions`

package/lib/api/main.js

@@ -165,6 +165,7 @@ function cdl(csn, externalOptions = {}) {
  */
 function forSql(csn, options = {}) {
   const internalOptions = prepareOptions.to.sql(options);
+  internalOptions.transformation = 'sql';
   internalOptions.toSql.csn = true;
   return backends.toSqlWithCsn(csn, internalOptions).csn;
 }
@@ -207,6 +208,7 @@ function forHdbcds(csn, options = {}) {
  */
 function sql(csn, options = {}) {
   const internalOptions = prepareOptions.to.sql(options);
+  internalOptions.transformation = 'sql';
 
   // we need the CSN for view sorting
   internalOptions.toSql.csn = true;

package/lib/api/options.js

@@ -84,9 +84,9 @@ function translateOptions(input = {}, defaults = {}, hardRequire = {},
   for (const name of overallOptions) {
     // Ensure that arrays are not passed as a reference!
     // This caused issues with the way messages are handled in processMessages
-    if (Array.isArray(input[name]) && inputOptionNames.indexOf(name) !== -1)
+    if (Array.isArray(input[name]) && inputOptionNames.includes(name))
       options[name] = [ ...input[name] ];
-    else if (inputOptionNames.indexOf(name) !== -1)
+    else if (inputOptionNames.includes(name))
       options[name] = input[name];
   }
 

package/lib/base/message-registry.js

@@ -42,12 +42,15 @@ const centralMessages = {
   'anno-definition':        { severity: 'Warning' },
   'anno-duplicate':         { severity: 'Error', configurableFor: true }, // does not hurt us
   'anno-duplicate-unrelated-layer': { severity: 'Error', configurableFor: true }, // does not hurt us
+  'anno-invalid-sql-element': { severity: 'Error'},  // @sql.prepend/append
+  'anno-invalid-sql-struct': { severity: 'Error'},  // @sql.prepend/append
+  'anno-invalid-sql-view': { severity: 'Error' },  // @sql.prepend/append
+  'anno-invalid-sql-view-element': { severity: 'Error'},  // @sql.prepend/append
   'anno-undefined-action':  { severity: 'Info' },
   'anno-undefined-art':     { severity: 'Info' }, // for annotate statement (for CDL path root)
   'anno-undefined-def':     { severity: 'Info' }, // for annotate statement (for CSN or CDL path cont)
   'anno-undefined-element': { severity: 'Info' },
   'anno-undefined-param':   { severity: 'Info' },
-  'anno-unstable-hdbcds':   { severity: 'Warning' },
 
   'args-expected-named':  { severity: 'Error', configurableFor: 'deprecated' }, // future --sloppy
   'args-no-params':       { severity: 'Error', configurableFor: 'deprecated' }, // future --sloppy
@@ -128,6 +131,11 @@ const centralMessages = {
   'syntax-fragile-alias': { severity: 'Error', configurableFor: true },
   'syntax-fragile-ident': { severity: 'Error', configurableFor: true },
 
+  'syntax-invalid-text-block' : { severity: 'Error' },
+  'syntax-unknown-escape': { severity: 'Error', configurableFor: true },
+  'syntax-invalid-escape': { severity: 'Error' },
+  'syntax-missing-escape': { severity: 'Error' },
+
   'type-managed-composition': { severity: 'Error', configurableFor: 'deprecated' }, // TODO: non-config
 
   'def-missing-element': { severity: 'Error' },
@@ -149,7 +157,7 @@ const centralMessages = {
 // For messageIds, where no text has been provided via code (central def)
 const centralMessageTexts = {
   'anno-mismatched-ellipsis': 'An array with $(CODE) can only be used if there is an assignment below with an array value',
-  'anno-unexpected-ellipsis': 'Unexpected $(CODE) in annotation assignment',
+  'anno-unexpected-ellipsis': 'No base annotation available to apply $(CODE)',
   'missing-type-parameter': 'Missing value for type parameter $(NAME) in reference to type $(ID)',
   'syntax-csn-expected-object': 'Expected object for property $(PROP)',
   'syntax-csn-expected-column': 'Expected object or string \'*\' for property $(PROP)',
@@ -171,6 +179,22 @@ const centralMessageTexts = {
     one: 'Expected array in $(PROP) to have at least one item',
     suffix: 'With sibling property $(OTHERPROP), expected array in $(PROP) to have at least one item',
   },
+  'syntax-invalid-text-block': 'Missing newline in text block',
+  'syntax-unknown-escape': 'Unknown escape sequence $(CODE)',
+  'syntax-invalid-escape': {
+    std: 'Invalid escape sequence $(CODE)',
+    octal: 'Octal escape sequences are not supported. Use unicode escapes instead',
+    whitespace: 'Unknown escape sequence: Can\'t escape whitespace',
+    codepoint: 'Undefined code-point for $(CODE)',
+    'unicode-hex': 'Expected hexadecimal numbers for unicode escape but found $(CODE)',
+    'hex-count': 'Expected $(NUMBER) hexadecimal numbers for escape sequence but found $(CODE)',
+    'unicode-brace': 'Missing closing brace for unicode escape sequence',
+    'language-identifier': 'Escape sequences in text-block\'s language identifier are not allowed',
+  },
+  'syntax-missing-escape':  {
+    std: 'Missing escape. Replace $(CODE) with $(NEWCODE)',
+    placeholder: 'Placeholders are not supported. Replace $(CODE) with $(NEWCODE)',
+  },
   'ref-undefined-def': {
     std: 'Artifact $(ART) has not been found',
     // TODO: proposal 'No definition of $(NAME) found',
@@ -289,6 +313,11 @@ const centralMessageTexts = {
   'odata-spec-violation-type': 'Expected element to have a type',
   'odata-spec-violation-property-name': 'Expected element name to be different from declaring $(KIND)',
   'odata-spec-violation-namespace': 'Expected service name not to be one of the reserved names $(NAMES)',
+  // Other odata/edm errors
+  'odata-definition-exists': {
+    std: 'Entity can\'t be created due to name collision with existing definition $(NAME)',
+    proxy: 'No proxy entity created due to name collision with existing definition $(NAME) of kind $(KIND)'
+  }
 }
 
 /**

package/lib/base/model.js

@@ -27,6 +27,7 @@ const availableBetaFlags = {
   ignoreAssocPublishingInUnion: true,
   nestedProjections: true,
   enableUniversalCsn: true,
+  sqlSnippets: true,
   // disabled by --beta-mode
   nestedServices: false,
 };

package/lib/base/optionProcessorHelper.js

@@ -1,27 +1,31 @@
 'use strict'
 
-// Create a command line option processor and define valid commands, options and parameters.
-// In order to understand a command line like this:
-//   $ node cdsc.js -x 1 --foo toXyz -y --bar-wiz bla arg1 arg2
-//
-// The following definitions should be made
-//
-//   const optionProcessor = createOptionProcessor();
-//   optionProcessor
-//     .help(`General help text`);
-//     .option('-x, --x-in-long-form <i>')
-//     .option('    --foo')
-//   optionProcessor.command('toXyz')
-//     .help(`Help text for command "toXyz")
-//     .option('-y  --y-in-long-form')
-//     .option('    --bar-wiz <w>', ['bla', 'foo'])
-//
-// Options *must* have a long form, can have at most one <param>, and optionally
-// an array of valid param values as strings. Commands and param values must not
-// start with '--'. The whole processor and each command may carry a help text.
-// To actually parse a command line, use
-//   optionProcessor.processCmdLine(process.argv);
-// (see below)
+/**
+ * Create a command line option processor and define valid commands, options and parameters.
+ * In order to understand a command line like this:
+ *   $ node cdsc.js -x 1 --foo toXyz -y --bar-wiz bla arg1 arg2
+ *
+ * The following definitions should be made:
+ *
+ * ```js
+ *   const optionProcessor = createOptionProcessor();
+ *   optionProcessor
+ *     .help(`General help text`);
+ *     .option('-x, --long-form <i>')
+ *     .option('    --foo')
+ *   optionProcessor.command('toXyz')
+ *     .help(`Help text for command "toXyz")
+ *     .option('-y  --y-in-long-form')
+ *     .option('    --bar-wiz <w>', ['bla', 'foo'])
+ * ```
+ *
+ * Options *must* have a long form, can have at most one <param>, and optionally
+ * an array of valid param values as strings.  Commands and param values must not
+ * start with '-'. The whole processor and each command may carry a help text.
+ * To actually parse a command line, use
+ *   const cli = optionProcessor.processCmdLine(process.argv);
+ * (see below)
+ */
 function createOptionProcessor() {
   const optionProcessor = {
     commands: {},
@@ -32,13 +36,14 @@ function createOptionProcessor() {
     command,
     positionalArgument: (argumentDefinition) => {
       // Default positional arguments; may be overwritten by commands.
-      _positionalArguments(argumentDefinition);
+      _setPositionalArguments(argumentDefinition);
       return optionProcessor;
     },
     help,
     processCmdLine,
     verifyOptions,
     camelOptionsForCommand,
+    // TODO: Why exported?
     _parseCommandString,
     _parseOptionString,
   }
@@ -48,9 +53,10 @@ function createOptionProcessor() {
    * API: Define a general option.
    * @param {string} optString Option string describing the command line option.
    * @param {string[]} [validValues] Array of valid values for the options.
+   * @param {object} [options] Further options such as `ignoreCase: true`
    */
-  function option(optString, validValues) {
-    return _addOption(optionProcessor, optString, validValues);
+  function option(optString, validValues, options) {
+    return _addOption(optionProcessor, optString, validValues, options);
   }
 
   /**
@@ -64,7 +70,7 @@ function createOptionProcessor() {
 
   /**
    * API: Define a command
-   * @param {string} cmdString Command name, e.g. 'S, toSql'
+   * @param {string} cmdString Command name, short and long form, e.g. 'S, toSql'
    */
   function command(cmdString) {
     /** @type {object} */
@@ -73,7 +79,7 @@ function createOptionProcessor() {
       positionalArguments: [],
       option,
       positionalArgument: (argumentDefinition) => {
-        _positionalArguments(argumentDefinition, command.positionalArguments);
+        _setPositionalArguments(argumentDefinition, command.positionalArguments);
         return command;
       },
       help,
@@ -92,12 +98,12 @@ function createOptionProcessor() {
     }
     return command;
 
-    // API: Define a command option
-    function option(optString, validValues) {
-      return _addOption(command, optString, validValues);
+    // Command API: Define a command option
+    function option(optString, validValues, options) {
+      return _addOption(command, optString, validValues, options);
     }
 
-    // API: Define the command help text
+    // Command API: Define the command help text
     function help(text) {
       command.helpText = text;
       return command;
@@ -112,8 +118,9 @@ function createOptionProcessor() {
    *
    * @param {string}   argumentDefinition Positional arguments, e.g. '<input> <output>' or '<files...>'
    * @param {object[]} argList            Array, to which the parsed arguments will be added.  Default is global scope.
+   * @private
    */
-  function _positionalArguments(argumentDefinition, argList = optionProcessor.positionalArguments) {
+  function _setPositionalArguments(argumentDefinition, argList = optionProcessor.positionalArguments) {
     if (argList.find((arg) => arg.isDynamic)) {
       throw new Error(`Can't add positional arguments after a dynamic one`);
     }
@@ -149,8 +156,10 @@ function createOptionProcessor() {
    * @private
    * @see option()
    */
-  function _addOption(command, optString, validValues) {
+  function _addOption(command, optString, validValues, options) {
     const opt = _parseOptionString(optString, validValues);
+    Object.assign(opt, options);
+
     if (command.options[opt.longName]) {
       throw new Error(`Duplicate assignment for long option ${opt.longName}`);
     } else if (optionProcessor.options[opt.longName]) {
@@ -217,7 +226,6 @@ function createOptionProcessor() {
     let longName;
     let shortName;
     let param;
-    let camelName;
 
     // split at spaces (with optional preceding comma)
     const tokens = optString.trim().split(/,? +/);
@@ -261,26 +269,16 @@ function createOptionProcessor() {
           throw new Error(`Valid values must be of type string: ${optString}`);
       });
     }
-    camelName = _camelify(longName);
+
     return {
       longName,
       shortName,
-      camelName,
+      camelName: camelifyLongOption(longName),
       param,
       validValues
     }
   }
 
-  // Return a camelCase name "fooBar" for a long option "--foo-bar"
-  function _camelify(opt) {
-    return opt.substring(2).replace(/-./g, s => s.substring(1).toUpperCase());
-  }
-
-  // Return a long option name like "--foo-bar" for a camel-case name "fooBar"
-  function _unCamelify(opt) {
-    return `--${opt.replace(/[A-Z]/g, s => '-' + s.toLowerCase())}`;
-  }
-
   // API: Let the option processor digest a command line 'argv'
   // The expectation is to get a commandline like this:
   //       $ node cdsc.js -x 1 --foo toXyz -y --bar-wiz bla arg1 arg2
@@ -336,7 +334,12 @@ function createOptionProcessor() {
         argv = [ ...argv.slice(0, i), ...arg.split('='), ...argv.slice(i + 1)];
         arg = argv[i];
       }
-      if (!seenDashDash && arg.startsWith('-') && arg !== '--') {
+
+      if (arg === '--') {
+        // No more options after '--'
+        seenDashDash = true;
+      }
+      else if (!seenDashDash && arg.startsWith('-')) {
         if (result.command) {
           // We already have a command
           const opt = optionProcessor.commands[result.command].options[arg];
@@ -378,10 +381,7 @@ function createOptionProcessor() {
           }
         }
       }
-      else if (arg === '--') {
-        // No more options after '--'
-        seenDashDash = true;
-      } else {
+      else {
         // Command or arg
         if (result.command === undefined) {
           if (optionProcessor.commands[arg]) {
@@ -420,8 +420,7 @@ function createOptionProcessor() {
      */
     function getCurrentPositionArguments() {
       const cmd = optionProcessor.commands[result.command];
-      const args = ( cmd && cmd.positionalArguments && cmd.positionalArguments.length ) ? cmd.positionalArguments : optionProcessor.positionalArguments;
-      return args;
+      return ( cmd && cmd.positionalArguments && cmd.positionalArguments.length ) ? cmd.positionalArguments : optionProcessor.positionalArguments;
     }
 
     function processPositionalArgument(argumentValue) {
@@ -478,13 +477,13 @@ function createOptionProcessor() {
               result.unknownOptions.push(`Unknown option "${argv[i]}" for the command "${command.longName}"`);
             } else {
               result.options[command][opt.camelName] = value;
-              if (opt.validValues && !opt.validValues.includes(value)) {
+              if (!isValidOptionValue(opt, value)) {
                 result.cmdErrors.push(`Invalid value "${value}" for option "${shortOption}${opt.longName}" - use one of [${opt.validValues}]`);
               }
             }
           } else {
             result.options[opt.camelName] = value;
-            if (opt.validValues && !opt.validValues.some( validValue => validValue.toLowerCase() === value.toLowerCase() ) ) {
+            if (!isValidOptionValue(opt, value)) {
               result.errors.push(`Invalid value "${value}" for option "${shortOption}${opt.longName}" - use one of [${opt.validValues}]`);
             }
           }
@@ -545,7 +544,7 @@ function createOptionProcessor() {
     }
     // Look at each supplied option
     for (const camelName in options) {
-      const opt = opts[_unCamelify(camelName)];
+      const opt = opts[uncamelifyLongOption(camelName)];
       let error;
       if (!opt) {
         // Don't report commands in top-level options
@@ -570,7 +569,7 @@ function createOptionProcessor() {
         // Parameter is required for this option
         if (typeof param === 'boolean') {
           return `Missing value for option "${prefix}${opt.camelName}"`;
-        } else if (opt.validValues && !opt.validValues.includes(String(param))) {
+        } else if (!isValidOptionValue(opt, param)) {
           return `Invalid value "${param}" for option "${prefix}${opt.camelName}" - use one of [${opt.validValues}]`;
         }
         return false;
@@ -585,36 +584,65 @@ function createOptionProcessor() {
     }
   }
 
+  function isValidOptionValue(opt, value) {
+    // Explicitly convert to string, input 'value' may be boolean
+    value = String(value);
+    if (!opt.validValues || !opt.validValues.length)
+      return true;
+    if (opt.ignoreCase)
+      return opt.validValues.some( valid => valid.toLowerCase() === value.toLowerCase() );
+    return opt.validValues.includes(value);
+  }
+
   // Return an array of unique camelNames of the options for the specified command
   // If invalid command -> an empty array
   function camelOptionsForCommand(command) {
-    if (command && optionProcessor.commands[command]) {
-      const cmd = optionProcessor.commands[command];
-      return [... new Set(
-        Object.keys(cmd.options).map(optName => cmd.options[optName].camelName)
-      )];
-    } else {
-      return [];
-    }
+    if (!command || !optionProcessor.commands[command])
+      return []
+    const cmd = optionProcessor.commands[command];
+    const names = Object.keys(cmd.options).map(name => cmd.options[name].camelName);
+    return [...new Set(names)];
   }
 }
 
-// Check if 'opt' looks like a "-f" short option
+/**
+ * Return a camelCase name "fooBar" for a long option "--foo-bar"
+ */
+function camelifyLongOption(opt) {
+  return opt.substring(2).replace(/-./g, s => s.substring(1).toUpperCase());
+}
+
+/**
+ * Return a long option name like "--foo-bar" for a camel-case name "fooBar"
+ */
+function uncamelifyLongOption(opt) {
+  return `--${opt.replace(/[A-Z]/g, s => '-' + s.toLowerCase())}`;
+}
+
+/**
+ * Check if 'opt' looks like a "-f" short option
+ */
 function isShortOption(opt) {
   return /^-[a-zA-Z?]$/.test(opt);
 }
 
-// Check if 'opt' looks like a "--foo-bar" long option
+/**
+ * Check if 'opt' looks like a "--foo-bar" long option
+ */
 function isLongOption(opt) {
   return /^--[a-zA-Z0-9-]+$/.test(opt);
 }
 
-// Check if 'opt' looks like a "<foobar>" parameter
+/**
+ * Check if 'opt' looks like a "<foobar>" parameter
+ */
 function isParam(opt) {
   return /^<[a-zA-Z-]+>$/.test(opt);
 }
 
-// Check if 'arg' looks like "<foobar...>"
+/**
+ * Check if 'arg' looks like "<foobar...>"
+ */
 function isDynamicPositionalArgument(arg) {
   return /^<[a-zA-Z-]+[.]{3}>$/.test(arg);
 }

package/lib/checks/.eslintrc.json

@@ -12,6 +12,8 @@
     "jsdoc/no-undefined-types": 0,
     // eslint-plugin-jsdoc warning
     "jsdoc/require-property": 0,
+    // most of the main functions have the normal forEachArtifact/Member signature anyway
+    "jsdoc/require-param-description": 0,
     // =airbnb, >eslint:
     "max-len": [ "error", {
       "code": 110,