@sap/eslint-plugin-cds 3.0.4 → 3.1.0

package/CHANGELOG.md

@@ -6,9 +6,48 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 The format is based on [Keep a Changelog](http://keepachangelog.com/).
 
+## [3.1.0] - 2024-09-26
+
+### Added
+
+- api:
+  + rules now have a `name` property, containing the rule name
+  + new exported property `parser`
+- rules: there is now an `experimental` rule group, containing new rules that can be tested
+- new experimental rules were added:
+  + `@sap/cds/sql-null-comparison`
+  + `@sap/cds/no-java-keywords`
+- `auth-valid-restrict-grant` now proposes '*' when incorrect `@restrict.grant` value 'any' is used
+
+### Removed
+
+- api: `genDocs` was removed
+
+### Fixed
+
+- cli: Running `eslint` on the command line now runs `inferred` rules again
+- `start-entities-uppercase` no longer reports false positives for elements
+- Typescript errors in `lib/types.d.ts` were fixed
+- Rule property `hasSuggestions: true` was removed from rules that did not have suggestions
+- Custom rule tests using `runRuleTester` did not catch errors in files inside `valid/`.
+  Tests can now also be run with other test runners such as `mocha` and `node --test` instead of just `jest`
+- `auth-` lint rules have been reworked to reduce the number of false positives and negatives
+  + `auth-valid-restrict-where` no longer runs in quadratic time and now handles "expressions as annotation values"
+  + `auth-no-empty-restrictions` now runs for actions and functions, too
+  + `auth-use-requires` will not propose `@requires` anymore, if the `@restrict` has a `where` condition
+  + `auth-valid-restrict-grants` incorrectly proposed to use `WRITE` instead of other events; it no longer crashes for invalid value types and now runs on all CSN artifacts
+  + `auth-valid-restrict-keys` has improved reporting about misspelled vs unknown properties; it now runs on all CSN artifacts
+
+## [3.0.5] - 2024-09-11
+
+### Fixed
+
+- Inferred rules did not run when executed via `eslint` or `cds lint`.
+
 ## [3.0.4] - 2024-06-19
 
 ### Changed
+
 - Internal refactorings
 
 ## [3.0.3] - 2024-05-08

package/README.md

@@ -3,4 +3,4 @@
 
 The [ESLint](https://eslint.org) plugin includes a set of recommended [SAP Cloud Application Programming Model (CAP)](https://cap.cloud.sap) model and environment rules.	The aim of CDS linting is to catch issues with CDS models and with the environment early. To use this module we recommend to install [@sap/cds-dk](https://www.npmjs.com/package/@sap/cds-dk) globally.
 
-See the [CDS Linting documentation](https://cap.cloud.sap/docs/tools/#cds-lint) for more details, or jump directly to a complete [list of rules](https://cap.cloud.sap/docs/tools/#cds-lint-rules). CAP provides a set of recommended rules. On top, you can create your own, application-specific rules.
+See the [CDS Linting documentation](https://cap.cloud.sap/docs/tools/cds-lint/) for more details, or jump directly to a complete [list of rules](https://cap.cloud.sap/docs/tools/cds-lint/#cds-lint-rules). CAP provides a set of recommended rules. On top, you can create your own, application-specific rules.

package/lib/api/index.js

@@ -4,23 +4,23 @@
  * Our custom ESLint plugin API should:
  * - Expose 'createRule' and 'runRuleTester' to
  *   support the addition of *custom* CDS Lint rules at runtime
- * - Expose 'getFileExtensions', and 'genDocs' for usage in
+ * - Expose 'getFileExtensions' for usage in
  *   'cds lint' client (@sap/cds-dk)
  * - Expose 'parserPath' for CDS Lint rule unit tests with ESLint's ruleTester
  */
 
 const runRuleTester = require('../utils/runRuleTester')
 const createRule = require('../utils/createRule')
-const genDocs = require('../utils/genDocs')
 const getConfigPath = require('../utils/getConfigPath')
 const getConfiguredFileTypes = require('../utils/getConfiguredFileTypes')
 const parserPath = require.resolve('../parser')
+const parser = require('../parser')
 
 module.exports = {
   runRuleTester,
   createRule,
-  genDocs,
   getConfigPath,
   getFileExtensions: getConfiguredFileTypes,
-  parserPath
+  parserPath,
+  parser,
 }

package/lib/conf/all.js

@@ -1,21 +1,21 @@
 'use strict'
 
 module.exports = {
-  '@sap/cds/assoc2many-ambiguous-key': 2,
-  '@sap/cds/auth-no-empty-restrictions': 2,
-  '@sap/cds/auth-use-requires': 2,
-  '@sap/cds/auth-restrict-grant-service': 2,
-  '@sap/cds/auth-valid-restrict-grant': 2,
-  '@sap/cds/auth-valid-restrict-keys': 2,
-  '@sap/cds/auth-valid-restrict-to': 2,
-  '@sap/cds/auth-valid-restrict-where': 2,
-  '@sap/cds/latest-cds-version': 2,
-  '@sap/cds/no-db-keywords': 2,
-  '@sap/cds/no-dollar-prefixed-names': 2,
-  '@sap/cds/no-join-on-draft': 2,
-  '@sap/cds/sql-cast-suggestion': 2,
-  '@sap/cds/start-elements-lowercase': 2,
-  '@sap/cds/start-entities-uppercase': 2,
-  '@sap/cds/valid-csv-header': 2,
-  '@sap/cds/extension-restrictions': 2
+  '@sap/cds/assoc2many-ambiguous-key': 'error',
+  '@sap/cds/auth-no-empty-restrictions': 'error',
+  '@sap/cds/auth-use-requires': 'error',
+  '@sap/cds/auth-restrict-grant-service': 'error',
+  '@sap/cds/auth-valid-restrict-grant': 'error',
+  '@sap/cds/auth-valid-restrict-keys': 'error',
+  '@sap/cds/auth-valid-restrict-to': 'error',
+  '@sap/cds/auth-valid-restrict-where': 'error',
+  '@sap/cds/latest-cds-version': 'error',
+  '@sap/cds/no-db-keywords': 'error',
+  '@sap/cds/no-dollar-prefixed-names': 'error',
+  '@sap/cds/no-join-on-draft': 'error',
+  '@sap/cds/sql-cast-suggestion': 'error',
+  '@sap/cds/start-elements-lowercase': 'error',
+  '@sap/cds/start-entities-uppercase': 'error',
+  '@sap/cds/valid-csv-header': 'error',
+  '@sap/cds/extension-restrictions': 'error',
 }

package/lib/conf/experimental.js

@@ -0,0 +1,12 @@
+'use strict'
+
+// Experimental Rules
+// ------------------
+// New rules that we want to publish, but don't activate per default.
+// We want to give users the chance to test them, before moving them
+// to "all" or even "recommended".
+
+module.exports = {
+  '@sap/cds/sql-null-comparison': 'warn',
+  '@sap/cds/no-java-keywords': 'error',
+}

package/lib/conf/index.js

@@ -1,10 +1,17 @@
-const path = require('path')
+'use strict'
+
+const path = require('node:path')
 const { FILES, GLOBALS, PLUGIN_NAME } = require('../constants')
 const { parserPath } = require('../api')
 
-function _createConfig (plugin, configName, legacy = false) {
+/**
+ * @param {object} plugin Plugin implementation used for new configuration layout.
+ * @param {string} configName
+ * @param {boolean} [isLegacy]
+ */
+function _createConfig (plugin, configName, isLegacy = false) {
   const config = require(path.join(__dirname, configName))
-  if (legacy) {
+  if (isLegacy) {
     return {
       root: true,
       globals: GLOBALS,
@@ -19,6 +26,7 @@ function _createConfig (plugin, configName, legacy = false) {
     }
   }
   return {
+    name: `@sap/cds/${configName}`,
     languageOptions: {
       globals: GLOBALS,
       parser: require(parserPath)
@@ -37,6 +45,7 @@ module.exports = function (plugin) {
   return {
     all: _createConfig(plugin, 'all'),
     recommended: _createConfig(plugin, 'recommended'),
+    experimental: _createConfig(plugin, 'experimental'),
     // Legacy configs (for backwards compatibility)
     'all-legacy': _createConfig(plugin, 'all', true),
     'recommended-legacy': _createConfig(plugin, 'recommended', true)

package/lib/conf/recommended.js

@@ -1,18 +1,18 @@
 'use strict'
 
 module.exports = {
-  '@sap/cds/assoc2many-ambiguous-key': 2,
-  '@sap/cds/auth-no-empty-restrictions': 2,
-  '@sap/cds/auth-use-requires': 1,
-  '@sap/cds/auth-restrict-grant-service': 2,
-  '@sap/cds/auth-valid-restrict-grant': 1,
-  '@sap/cds/auth-valid-restrict-keys': 1,
-  '@sap/cds/auth-valid-restrict-to': 1,
-  '@sap/cds/auth-valid-restrict-where': 1,
-  '@sap/cds/no-db-keywords': 1,
-  '@sap/cds/no-dollar-prefixed-names': 1,
-  '@sap/cds/no-join-on-draft': 1,
-  '@sap/cds/sql-cast-suggestion': 1,
-  '@sap/cds/valid-csv-header': 1,
-  '@sap/cds/extension-restrictions': 2
+  '@sap/cds/assoc2many-ambiguous-key': 'error',
+  '@sap/cds/auth-no-empty-restrictions': 'error',
+  '@sap/cds/auth-use-requires': 'warn',
+  '@sap/cds/auth-restrict-grant-service': 'error',
+  '@sap/cds/auth-valid-restrict-grant': 'warn',
+  '@sap/cds/auth-valid-restrict-keys': 'warn',
+  '@sap/cds/auth-valid-restrict-to': 'warn',
+  '@sap/cds/auth-valid-restrict-where': 'warn',
+  '@sap/cds/no-db-keywords': 'warn',
+  '@sap/cds/no-dollar-prefixed-names': 'warn',
+  '@sap/cds/no-join-on-draft': 'warn',
+  '@sap/cds/sql-cast-suggestion': 'warn',
+  '@sap/cds/valid-csv-header': 'warn',
+  '@sap/cds/extension-restrictions': 'error',
 }

package/lib/constants.js

@@ -1,3 +1,5 @@
+'use strict'
+
 /**
  * This file is used to store/share any constants for this plugin:
  * - DEFAULT_RULE_CATEGORY: Default rule category (must be one of plugin's rule categories)

package/lib/index.js

@@ -1,4 +1,5 @@
-// index.js
+'use strict'
+
 /**
  * ## Plugin structure
  * This is the main entry point of our [custom ESLint plugin](https://eslint.org/docs/developer-guide/working-with-plugins),

package/lib/parser.js

@@ -1,3 +1,5 @@
+'use strict'
+
 /**
  * Custom ESLint parser:
  * https://eslint.org/docs/developer-guide/working-with-custom-parsers
@@ -28,7 +30,7 @@ module.exports = {
           const messages = []
           try {
             compiledModel = cds.parse(code)
-          } catch (_err) {
+          } catch {
             // Do nothing
           }
           if (compiledModel) {
@@ -124,6 +126,7 @@ module.exports = {
           let loc
           if (obj) {
             let name = obj.name
+            // TODO: 'action'/'function' not correct for bound action/function
             if (['action', 'entity', 'function', 'service'].includes(obj.kind)) {
               name = splitDefName(obj).name
             }
@@ -143,7 +146,9 @@ module.exports = {
 
 /**
  * Generates dummy AST with just single Program node
+ *
  * @param code Parse file contents
+ * @param {object} [loc]
  * @returns AST
  */
 function createProgramAST (code, loc) {
@@ -168,6 +173,10 @@ function createProgramAST (code, loc) {
   }
 }
 
+/**
+ * @param {object} dictFiles
+ * @param options
+ */
 function compileModelFromDict (dictFiles, options) {
   let reflectedModel
   const messages = []

package/lib/rules/assoc2many-ambiguous-key.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const cds = require('@sap/cds')
 
 /** @type {import('../types').Rule} */
@@ -9,7 +11,11 @@ module.exports = {
       description:
         'Ambiguous key with a `TO MANY` relationship since entries could appear multiple times with the same key.',
       category: 'Model Validation',
-      recommended: true
+      recommended: true,
+      url: 'https://cap.cloud.sap/docs/tools/cds-lint/meta/assoc2many-ambiguous-key',
+    },
+    messages: {
+      ambiguous: `Ambiguous key in '{{name}}'. Element '{{column-name}}' leads to multiple entries so that key '{{key-name}}' is not unique.`,
     },
     type: 'problem',
     model: 'inferred'
@@ -22,14 +28,23 @@ module.exports = {
       const m = context.getModel()
       if (!m) return
       if (m && m.definitions) {
-        csnOdata = cds.compile.for.odata(m)
-        const csnOdataLinked = cds.linked(csnOdata)
-        associationCardinalityFlaw(csnOdataLinked, context)
+        try {
+          csnOdata = cds.compile.for.odata(m)
+          const csnOdataLinked = cds.linked(csnOdata)
+          associationCardinalityFlaw(csnOdataLinked, context)
+        } catch {
+          // FIXME: there are currently too many issues with this rule, e.g.
+          //        assumptions that properties exist, etc.
+        }
       }
     }
   }
 }
 
+/**
+ * @param {object} csn
+ * @param {CDSRuleContext} context
+ */
 function associationCardinalityFlaw (csn, context) {
   processEntity(csn, (definition, sourceEntity, sourceAlias) => {
     let refCardinalityMult = false
@@ -52,7 +67,7 @@ function associationCardinalityFlaw (csn, context) {
           refPlainElement = true
         }
       },
-      (column) => {
+      column => {
         if (
           definition.keys &&
           Object.keys(definition.keys).length === 1 &&
@@ -65,7 +80,8 @@ function associationCardinalityFlaw (csn, context) {
           const keyLoc = context.getLocation(keyName, key, csn)
           const colName = column.as ? column.as : column.name
           context.report({
-            message: `Ambiguous key in '${definition.name}'. Element '${colName}' leads to multiple entries so that key '${keyName}' is not unique.`,
+            messageId: 'ambiguous',
+            data: { name: definition.name, 'column-name': colName, 'key-name': keyName },
             loc: keyLoc,
             file: key.$location.file
           })
@@ -75,8 +91,12 @@ function associationCardinalityFlaw (csn, context) {
   })
 }
 
+/**
+ * @param {object} csn
+ * @param {Function} eachCallback
+ */
 function processEntity (csn, eachCallback) {
-  Object.keys(csn.definitions).forEach((name) => {
+  Object.keys(csn.definitions).forEach(name => {
     if (name.startsWith('localized.')) {
       return
     }
@@ -99,7 +119,7 @@ function processEntity (csn, eachCallback) {
       } else if (definition.query.SELECT.from.args && definition.query.SELECT.from.args[0].ref) {
         // Join
         sourceEntity = csn.definitions[definition.query.SELECT.from.args[0].ref.join('_')]
-        definition.query.SELECT.from.args.forEach((arg) => {
+        definition.query.SELECT.from.args.forEach(arg => {
           sourceAlias.push({
             from: arg.ref.join('_'),
             as: arg.as || arg.ref.slice(-1)[0].split('.').pop()
@@ -114,16 +134,25 @@ function processEntity (csn, eachCallback) {
   })
 }
 
+/**
+ * @param {object} csn
+ * @param {object} definition
+ * @param {object} sourceEntity
+ * @param {string} sourceAlias
+ * @param {Function} beforeCallback
+ * @param {Function} eachCallback
+ * @param {Function} afterCallback
+ */
 function processElement (csn, definition, sourceEntity, sourceAlias, beforeCallback, eachCallback, afterCallback) {
-  definition.query.SELECT.columns.forEach((column) => {
+  definition.query.SELECT.columns.forEach(column => {
     if (column.ref && column.ref.length > 1) {
       let refEntity = sourceEntity
       let refAlias = sourceAlias
       beforeCallback()
-      column.ref.forEach((ref) => {
+      column.ref.forEach(ref => {
         ref = ref.id || ref
         // Alias
-        const matchAlias = refAlias.find((alias) => {
+        const matchAlias = refAlias.find(alias => {
           return alias.as === ref
         })
         let refElement

package/lib/rules/auth-no-empty-restrictions.js

@@ -1,4 +1,6 @@
-const LABELS = ['@restrict', '@requires']
+'use strict'
+
+const AUTH_ANNOTATIONS = [ '@restrict', '@requires' ]
 
 module.exports = {
   meta: {
@@ -6,12 +8,11 @@ module.exports = {
     docs: {
       description: '`@restrict` and `@requires` must not be empty.',
       category: 'Model Validation',
-      recommended: true
+      recommended: true,
+      url: 'https://cap.cloud.sap/docs/tools/cds-lint/meta/auth-no-empty-restrictions',
     },
-    hasSuggestions: true,
     messages: {
-      InvalidItem: "Invalid item '{{invalid}}'. Did you mean '{{candidates}}'?",
-      ReplaceItemWith: "Replace '{{invalid}}' with '{{candidates}}'"
+      missingRestriction: 'No explicit restrictions provided on {{kind}} `{{name}}` at `{{label}}`.',
     },
     type: 'problem',
     model: 'inferred'
@@ -19,15 +20,17 @@ module.exports = {
   create (context) {
     return {
       entity: checkRestrictions,
-      service: checkRestrictions
+      service: checkRestrictions,
+      action: checkRestrictions,
+      function: checkRestrictions,
     }
 
     function checkRestrictions (e) {
-      for (const l of LABELS) {
-        const invalid = (typeof e[l] === 'object' && e[l].length === 0) || (typeof e[l] === 'string' && e[l] === '')
-        if (invalid) {
+      for (const anno of AUTH_ANNOTATIONS) {
+        if (isEmptyRestriction(e[anno])) {
           context.report({
-            message: `No explicit restrictions provided on ${e.kind} \`${e.name}\` at \`${l}\`.`,
+            messageId: 'missingRestriction',
+            data: { kind: e.kind, name: e.name, label: anno },
             node: context.getNode(e),
             file: e.$location.file
           })
@@ -36,3 +39,26 @@ module.exports = {
     }
   }
 }
+
+/**
+ * Checks if the given annotation value is an empty restriction.
+ * Examples which would return `true`:
+ *   ```
+ *   @requires: ''
+ *   @requires: ['']
+ *   @restrict: [ { to: '' } ]
+ *   @restrict: [ { to: [''] } ]
+ *   ```
+ *
+ * @param {*} obj
+ * @returns {boolean}
+ */
+function isEmptyRestriction(obj) {
+  if (typeof obj === 'string')
+    return obj === ''
+  if (Array.isArray(obj))
+    return obj.length === 0 || obj.some(isEmptyRestriction)
+  if (typeof obj === 'object')
+    return isEmptyRestriction(obj.to)
+  return false
+}

package/lib/rules/auth-restrict-grant-service.js

@@ -1,10 +1,16 @@
+'use strict'
+
 module.exports = {
   meta: {
     schema: [{/* to avoid deprecation warning for ESLint 9 */ }],
     docs: {
       description: '`@restrict.grant` on service level and for bound/unbound actions and functions is limited to grant: \'*\'',
       category: 'Model Validation',
-      recommended: true
+      recommended: true,
+      url: 'https://cap.cloud.sap/docs/tools/cds-lint/meta/auth-restrict-grant-service',
+    },
+    messages: {
+      limitedGrant: `The grant value provided in @restrict is limited to '*' for {{kind}} '{{name}}'`,
     },
     type: 'problem',
     model: 'inferred'
@@ -23,26 +29,19 @@ module.exports = {
         for (const entry of d['@restrict']) {
           if (Object.keys(entry).includes('grant')) {
             const grantValue = entry.grant
-            const message = `The grant value provided in @restrict is limited to '*' for ${d.kind} '${d.name}'`
+            const messageId = 'limitedGrant'
+            const data = { kind: d.kind, name: d.name }
             switch (typeof grantValue) {
-              case 'string':
-                if (grantValue !== '*') {
-                  context.report({
-                    message,
-                    node,
-                    file
-                  })
-                }
-                break
-              case 'object':
-                if (grantValue.length > 1 || grantValue[0] !== '*') {
-                  context.report({
-                    message,
-                    node,
-                    file
-                  })
-                }
-                break
+            case 'string':
+              if (grantValue !== '*') {
+                context.report({ messageId, data, node, file })
+              }
+              break
+            case 'object':
+              if (grantValue.length > 1 || grantValue[0] !== '*') {
+                context.report({ messageId, data, node, file })
+              }
+              break
             }
           }
         }

package/lib/rules/auth-use-requires.js

@@ -1,3 +1,5 @@
+'use strict'
+
 module.exports = {
   meta: {
     schema: [{/* to avoid deprecation warning for ESLint 9 */}],
@@ -5,12 +7,11 @@ module.exports = {
       description: 'Use `@requires` instead of `@restrict.to` in actions and services with unrestricted events.',
       category: 'Model Validation',
       recommended: true,
-      version: '2.4.1'
+      version: '2.4.1',
+      url: 'https://cap.cloud.sap/docs/tools/cds-lint/meta/auth-use-requires',
     },
-    hasSuggestions: true,
     messages: {
-      InvalidItem: "Invalid item '{{invalid}}'. Did you mean '{{candidates}}'?",
-      ReplaceItemWith: "Replace '{{invalid}}' with '{{candidates}}'"
+      useRequires: 'Use `@requires` instead of `@restrict.to` at {{kind}} `{{name}}`.'
     },
     type: 'problem',
     model: 'inferred'
@@ -18,22 +19,31 @@ module.exports = {
   create (context) {
     return {
       service: checkRestrict,
-      action: checkRestrict
+      action: checkRestrict,
+      function: checkRestrict,
     }
 
     function checkRestrict (e) {
-      if (e && e['@restrict'] && typeof e['@restrict'] === 'object') {
-        for (const entry of e['@restrict']) {
-          const keys = Object.keys(entry)
-          if (keys.includes('to') && keys.includes('grant') && entry.grant === '*') {
-            context.report({
-              message: `Use \`@requires\` instead of \`@restrict.to\` at ${e.kind} \`${e.name}\`.`,
-              node: context.getNode(e),
-              file: e.$location.file
-            })
-          }
+      if (!e?.['@restrict'] || !Array.isArray(e['@restrict']))
+        return
+
+      for (const entry of e['@restrict']) {
+        // Scenario: `@restrict: [ { to: 'Foo', grant: '*' } ]`
+        // There must be no `where` condition, as otherwise it wouldn't be equivalent
+        // to `@requires`.
+        // See https://cap.cloud.sap/docs/guides/security/authorization#supported-combinations-with-cds-resources
+        // for documentation.
+        if (entry?.to !== undefined && (entry.grant === '*' || !entry.grant) && entry.where === undefined) {
+          context.report({
+            messageId: 'useRequires',
+            data: { kind: e.kind, name: e.name },
+            node: context.getNode(e),
+            file: e.$location.file
+          })
+          return // max one report per annotation
         }
       }
     }
+
   }
 }