@sap/eslint-plugin-cds 3.0.5 → 3.1.0

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

@@ -1,7 +1,17 @@
+'use strict'
+
 const { findFuzzy, isEmptyString, isEmptyObject, isStringInArray } = require('../utils/rules')
 
-const REPLACE_AS_WRITE_EVENTS = ['READ', 'CREATE', 'UPDATE', 'DELETE']
-const VALID_EVENTS = REPLACE_AS_WRITE_EVENTS.concat(['INSERT', 'UPSERT', 'WRITE', '*'])
+// See https://cap.cloud.sap/docs/guides/security/authorization#restrict-annotation
+// The combination of these events is equivalent to the virtual 'WRITE' event.
+const SAME_AS_WRITE_EVENT = [ 'CREATE', 'DELETE', 'UPDATE', 'UPSERT' ]
+// Note that 'INSERT' is not meant to be used by users. They should use 'CREATE' instead.
+const VALID_EVENTS = [ ...SAME_AS_WRITE_EVENT, 'READ', 'INSERT', '*', 'WRITE']
+
+const TYPICAL_ISSUES = {
+  __proto__: null,
+  any: '*'
+}
 
 module.exports = {
   meta: {
@@ -9,99 +19,145 @@ module.exports = {
     docs: {
       description: '`@restrict.grant` must have valid values.',
       category: 'Model Validation',
-      recommended: true
+      recommended: true,
+      url: 'https://cap.cloud.sap/docs/tools/cds-lint/meta/auth-valid-restrict-grant',
     },
     messages: {
-      InvalidItem: "Invalid item '{{invalid}}'. Did you mean '{{candidates}}'?",
-      ReplaceItemWith: "Replace '{{invalid}}' with '{{candidates}}'"
+      invalidType: 'Invalid type for grant value. Must either be string or array of strings.',
+      invalidSingleType: 'Grant value must be a string.',
+      misspelledItem: "Invalid item '{{invalid}}'. Did you mean '{{candidates}}'?",
+      unknownItem: `Invalid item '{{invalid}}'. Valid: [ {{candidates}} ].`,
+      replaceBy: `Replace grant values '{{values}}' with '{{name}}'.`,
+      missingEventOrAction: "Missing event/action on '{{name}}' for `@restrict.grant`.",
+      star: 'Grant value \'*\' overrides all other grants. Replace by \'*\' only.'
     },
     type: 'problem',
     model: 'inferred'
   },
   create (context) {
     return {
-      entity: checkRestrictGrant
+      any: checkRestrictGrant
     }
 
-    function checkRestrictGrant (e) {
+    function checkRestrictGrant(e) {
+      if (!e?.['@restrict'] || !Array.isArray(e['@restrict']))
+        return
+
       const node = context.getNode(e)
       const file = e.$location.file
-      if (e['@restrict']) {
-        const actions = e.actions
-        const actionNames = actions ? Object.keys(actions).map((s) => actions[s].name) : []
-        const validEventsAndActions = VALID_EVENTS.concat(actionNames)
-
-        for (const entry of e['@restrict']) {
-          if (Object.keys(entry).includes('grant')) {
-            const grantValue = entry.grant
-            switch (typeof grantValue) {
-              case 'string': {
-                if (isEmptyString(grantValue)) {
-                  context.report({
-                    message: `Missing event/action on ${e.name} for \`@restrict.grant\`.`,
-                    node,
-                    file
-                  })
-                } else {
-                  if (!isStringInArray(grantValue, validEventsAndActions, true)) {
-                    const candidates = findFuzzy(grantValue, validEventsAndActions.sort())
-                    context.report({
-                      messageId: 'InvalidItem',
-                      data: { invalid: grantValue, candidates },
-                      node,
-                      file
-                    })
-                  }
-                }
-                break
-              }
-
-              case 'object':
-                if (isEmptyObject(grantValue)) {
-                  context.report({
-                    message: `Missing event/action on ${e.name} for \`@restrict.grant\`.`,
-                    node,
-                    file
-                  })
-                } else {
-                  const valuesForWrite = grantValue.filter(function (item) {
-                    return item !== 'READ' && item !== 'WRITE' && item !== '*'
-                  })
-                  for (const value of grantValue) {
-                    if (!validEventsAndActions.includes(value)) {
-                      const candidates = findFuzzy(value, validEventsAndActions.sort())
-                      context.report({
-                        messageId: 'InvalidItem',
-                        data: { invalid: value, candidates },
-                        node,
-                        file
-                      })
-                    }
-                  }
-                  // If values do not contain 'READ, WRITE, *', 'WRITE' only is enough
-                  const allValuesIncluded = grantValue.every((v) => valuesForWrite.includes(v))
-                  if (allValuesIncluded) {
-                    context.report({
-                      messageId: 'InvalidItem',
-                      data: { invalid: [`[${grantValue}]`], candidates: ['["WRITE"]'] },
-                      node,
-                      file
-                    })
-                  }
-                  // If values contain '*', '*' only is enough
-                  if (grantValue.length > 1 && grantValue.includes('*')) {
-                    context.report({
-                      messageId: 'InvalidItem',
-                      data: { invalid: `[${grantValue}]`, candidates: ['["*"]'] },
-                      node,
-                      file
-                    })
-                  }
-                }
-                break
-            }
+      const actionNames = e.actions ? Object.keys(e.actions) : []
+      const validEventsAndActions = [ ...VALID_EVENTS, ...actionNames ]
+
+      for (const entry of e['@restrict']) {
+        if (entry?.grant !== undefined) {
+          if (!checkRestrictEntry(entry)) {
+            // max. one message per annotation, to avoid spamming the user
+            break
+          }
+        }
+      }
+
+      /**
+       * Check an entry of the `@restrict` array.
+       * Returns `true` if the value is valid, `false` otherwise.
+       *
+       * @param {object} entry
+       * @returns {boolean}
+       */
+      function checkRestrictEntry( entry ) {
+        if (typeof entry.grant === 'string') {
+          return checkSingleGrantValue(entry.grant)
+
+        } else if (!Array.isArray(entry.grant)) {
+          // neither string nor array: report invalid type
+          context.report({ messageId: 'invalidType', node, file })
+          return false
+
+        } else {
+          if (entry.grant.length === 0) {
+            context.report({
+              messageId: 'missingEventOrAction',
+              data: { name: e.name }, node, file
+            })
+            return false
+          }
+
+          for (const value of entry.grant) {
+            if (!checkSingleGrantValue(value))
+              return false
+          }
+
+          // If grant values contain '*', '*' only is enough. It overrides everything.
+          if (entry.grant.length > 1 && entry.grant.includes('*')) {
+            context.report({ messageId: 'star',  node, file })
+            return false
+          }
+
+          // If the given values include all of SAME_AS_WRITE_EVENT, the user can
+          // replace them with 'WRITE'.
+          const includesWrite = SAME_AS_WRITE_EVENT.every(value => entry.grant.includes(value))
+          if (includesWrite) {
+            context.report({
+              messageId: 'replaceBy',
+              data: { values: SAME_AS_WRITE_EVENT.join(', '), name: 'WRITE' },
+              node, file
+            })
+            return false
+          }
+          return true
+        }
+      }
+
+      /**
+       * Returns `true` if the value is valid, `false` otherwise.
+       *
+       * @param grant
+       * @returns {boolean}
+       */
+      function checkSingleGrantValue(grant) {
+        if (typeof grant !== 'string') {
+          // single grant values must be strings
+          context.report({ messageId: 'invalidSingleType', node, file })
+          return false
+        }
+        if (grant.trim() === '') {
+          context.report({
+            messageId: 'missingEventOrAction',
+            data: { name: e.name }, node, file,
+          })
+          return false
+        }
+
+        if (!validEventsAndActions.includes(grant)) {
+          const candidates = TYPICAL_ISSUES[grant]
+            ? [ TYPICAL_ISSUES[grant] ]
+            : findFuzzy(grant, validEventsAndActions.sort(), null, false, 2)
+
+          if (candidates.length === 0) {
+            context.report({
+              messageId: 'unknownItem',
+              data: { invalid: grant, candidates: validEventsAndActions.join(', ') }, node, file,
+            })
+          } else {
+            context.report({
+              messageId: 'misspelledItem',
+              data: { invalid: grant, candidates: candidates.join(', ') }, node, file,
+            })
           }
+          return false
         }
+
+        if (grant === 'INSERT') {
+          // special case: 'INSERT' is an internal event name. Users should use 'CREATE' instead.
+          context.report({
+            messageId: 'replaceBy',
+            data: { values: 'INSERT', name: 'CREATE' },
+            node, file
+          })
+          return false
+        }
+
+        return true
       }
     }
   }

package/lib/rules/auth-valid-restrict-keys.js

@@ -1,40 +1,56 @@
+'use strict'
+
 const { isEmptyObject, findFuzzy } = require('../utils/rules')
 
-const VALID_RESTRICT_KEYS = ['grant', 'to', 'where']
+// These are the only valid properties inside `@restrict` annotations.
+// They are described in <https://cap.cloud.sap/docs/guides/security/authorization#restrict-annotation>
+const VALID_RESTRICT_PROPERTIES = ['grant', 'to', 'where']
 
 module.exports = {
   meta: {
     schema: [{/* to avoid deprecation warning for ESLint 9 */}],
     docs: {
-      description: '`@restrict` must have properly spelled `to`, `grant`, and `where` keys.',
+      description: '`@restrict` must not have properties besides `to`, `grant`, and `where`.',
       category: 'Model Validation',
-      recommended: true
+      recommended: true,
+      url: 'https://cap.cloud.sap/docs/tools/cds-lint/meta/auth-valid-restrict-keys',
     },
     messages: {
-      InvalidItem: "Misspelled key '{{invalid}}'. Did you mean '{{candidates}}'?"
+      misspelledProperty: "Misspelled or unknown property '{{invalid}}'. Did you mean '{{candidates}}'?",
+      unknownProperty: "Unknown property '{{invalid}}'. Possible: ['to', 'grant', 'where']",
     },
     type: 'problem',
     model: 'inferred'
   },
   create (context) {
     return {
-      entity: checkRestrictKeys
+      any: checkRestrictKeys
     }
 
     function checkRestrictKeys (e) {
-      if (e['@restrict']) {
-        for (const entry of e['@restrict']) {
-          if (typeof entry === 'object' && !isEmptyObject(entry)) {
-            for (const key of Object.keys(entry)) {
-              if (!VALID_RESTRICT_KEYS.includes(key)) {
-                const candidates = findFuzzy(key, VALID_RESTRICT_KEYS.sort())
-                context.report({
-                  messageId: 'InvalidItem',
-                  data: { invalid: key, candidates },
-                  node: context.getNode(e),
-                  file: e.$location.file
-                })
-              }
+      if (!Array.isArray(e?.['@restrict']))
+        return
+
+      for (const entry of e['@restrict']) {
+        if (typeof entry === 'object' && !isEmptyObject(entry)) {
+          for (const key of Object.keys(entry)) {
+            if (VALID_RESTRICT_PROPERTIES.includes(key))
+              continue
+            const candidates = findFuzzy(key, VALID_RESTRICT_PROPERTIES.sort(), null, false, 2)
+            if (candidates.length === 0) {
+              context.report({
+                messageId: 'unknownProperty',
+                data: { invalid: key },
+                node: context.getNode(e),
+                file: e.$location.file
+              })
+            } else {
+              context.report({
+                messageId: 'misspelledProperty',
+                data: { invalid: key, candidates },
+                node: context.getNode(e),
+                file: e.$location.file
+              })
             }
           }
         }

package/lib/rules/auth-valid-restrict-to.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const { isEmptyString, isStringInArray, findFuzzy, isEmptyObject } = require('../utils/rules')
 
 const VALID_PSEUDO_ROLES = ['authenticated-user', 'system-user', 'any']
@@ -8,12 +10,13 @@ module.exports = {
     docs: {
       description: '`@restrict.to` must have valid values.',
       category: 'Model Validation',
-      recommended: true
+      recommended: true,
+      url: 'https://cap.cloud.sap/docs/tools/cds-lint/meta/auth-valid-restrict-to',
     },
-    hasSuggestions: true,
     messages: {
-      InvalidItem: "Invalid item '{{invalid}}'. Did you mean '{{candidates}}'?",
-      ReplaceItemWith: "Replace '{{invalid}}' with '{{candidates}}'"
+      invalidItem: "Invalid item '{{invalid}}'. Did you mean '{{candidates}}'?",
+      missingRole: "Missing role on '{{name}}' for `@restrict.to`.",
+      missingRoles: "Missing roles on '{{name}}' for `@restrict.to`."
     },
     type: 'problem',
     model: 'inferred'
@@ -26,23 +29,25 @@ module.exports = {
     function checkRestrictTo (e) {
       const USER_ROLES = []
       const model = context.getModel()
+      if (!model)
+        return
 
-      model.foreach('entity', (e) => {
+      model.foreach('entity', e => {
         if (e['@restrict']) {
-          e['@restrict'].forEach((p) => {
+          e['@restrict'].forEach(p => {
             if (p.to) {
               switch (typeof p.to) {
-                case 'string':
-                  if (p.to !== p.to.toLowerCase() && !USER_ROLES.includes(p.to)) {
-                    USER_ROLES.push(p.to)
-                  }
-                  break
-                case 'object':
-                  for (const r in p.to) {
-                    if (r !== r.toLowerCase() && !USER_ROLES.includes(r)) {
-                      USER_ROLES.push(r)
-                    }
+              case 'string':
+                if (p.to !== p.to.toLowerCase() && !USER_ROLES.includes(p.to)) {
+                  USER_ROLES.push(p.to)
+                }
+                break
+              case 'object':
+                for (const r in p.to) {
+                  if (r !== r.toLowerCase() && !USER_ROLES.includes(r)) {
+                    USER_ROLES.push(r)
                   }
+                }
               }
             }
           })
@@ -71,60 +76,62 @@ module.exports = {
             const toValue = entry.to
 
             switch (typeof toValue) {
-              case 'string': {
-                if (isEmptyString(toValue)) {
+            case 'string': {
+              if (isEmptyString(toValue)) {
+                context.report({
+                  messageId: 'missingRole',
+                  data: { name: e.name },
+                  node,
+                  file,
+                })
+              } else {
+                const isPseudoRole = entry.to && entry.to === entry.to.toLowerCase()
+                if (!isStringInArray(toValue, ROLES, isPseudoRole)) {
+                  const candidates = findFuzzy(toValue, ROLES.sort())
                   context.report({
-                    message: `Missing role on ${e.name} for \`@restrict.to\`.`,
+                    messageId: 'invalidItem',
+                    data: { invalid: toValue, candidates },
                     node,
-                    file
+                    file,
                   })
-                } else {
-                  const isPseudoRole = entry.to && entry.to === entry.to.toLowerCase()
-                  if (!isStringInArray(toValue, ROLES, isPseudoRole)) {
-                    const candidates = findFuzzy(toValue, ROLES.sort())
-                    context.report({
-                      messageId: 'InvalidItem',
-                      data: { invalid: toValue, candidates },
-                      node,
-                      file
-                    })
-                  }
                 }
-                break
               }
+              break
+            }
 
-              case 'object':
-                if (isEmptyObject(toValue)) {
+            case 'object':
+              if (isEmptyObject(toValue)) {
+                context.report({
+                  messageId: 'missingRoles',
+                  data: { name: e.name },
+                  node,
+                  file,
+                })
+              } else {
+                // If values contain 'any', 'any' only is enough
+                if (toValue.length > 1 && toValue.includes('any')) {
                   context.report({
-                    message: `Missing roles on ${e.name} for \`@restrict.to\`.`,
+                    messageId: 'invalidItem',
+                    data: { invalid: `[${toValue}]`, candidates: ['["any"]'] },
                     node,
-                    file
-                  })
-                } else {
-                  // If values contain 'any', 'any' only is enough
-                  if (toValue.length > 1 && toValue.includes('any')) {
-                    context.report({
-                      messageId: 'InvalidItem',
-                      data: { invalid: `[${toValue}]`, candidates: ['["any"]'] },
-                      node,
-                      file
-                    })
-                  }
-                  toValue.forEach((value) => {
-                    if (!ROLES.includes(value)) {
-                      const candidates = findFuzzy(value, ROLES.sort(), undefined, false, 2)
-                      if (candidates.length > 0) {
-                        context.report({
-                          messageId: 'InvalidItem',
-                          data: { invalid: value, candidates },
-                          node,
-                          file
-                        })
-                      }
-                    }
+                    file,
                   })
                 }
-                break
+                toValue.forEach(value => {
+                  if (!ROLES.includes(value)) {
+                    const candidates = findFuzzy(value, ROLES.sort(), undefined, false, 2)
+                    if (candidates.length > 0) {
+                      context.report({
+                        messageId: 'invalidItem',
+                        data: { invalid: value, candidates },
+                        node,
+                        file,
+                      })
+                    }
+                  }
+                })
+              }
+              break
             }
           }
         }

package/lib/rules/auth-valid-restrict-where.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const cds = require('@sap/cds')
 
 module.exports = {
@@ -6,65 +8,50 @@ module.exports = {
     docs: {
       description: '`@restrict.where` must have valid values.',
       category: 'Model Validation',
-      recommended: true
+      recommended: true,
+      url: 'https://cap.cloud.sap/docs/tools/cds-lint/meta/auth-valid-restrict-where',
     },
     severity: 'error',
-    hasSuggestions: true,
     messages: {
-      InvalidItem: "Invalid item '{{invalid}}'. Did you mean '{{candidates}}'?",
-      ReplaceItemWith: "Replace '{{invalid}}' with '{{candidates}}'"
+      CompilationFailed: 'Invalid `where` expression, CDS compilation failed.',
     },
     type: 'problem',
     model: 'inferred'
   },
   create (context) {
     const model = context.getModel()
+    if (!model)
+      return
 
-    return {
-      entity: checkRestrictGrant
+    return function checkRestrictWhere() {
+      model.foreach('entity', checkEntityRestrict)
     }
 
-    function checkRestrictGrant (e) {
-      const USER_ROLES = []
+    function checkEntityRestrict (def) {
+      if (!Array.isArray(def['@restrict']))
+        return
 
-      model.foreach('entity', (e) => {
-        if (e['@restrict']) {
-          e['@restrict'].forEach((p) => {
-            if (p.to) {
-              switch (typeof p.to) {
-                case 'string':
-                  if (p.to !== p.to.toLowerCase() && !USER_ROLES.includes(p.to)) {
-                    USER_ROLES.push(p.to)
-                  }
-                  break
-                case 'object':
-                  for (const r in p.to) {
-                    if (r !== r.toLowerCase() && !USER_ROLES.includes(r)) {
-                      USER_ROLES.push(r)
-                    }
-                  }
-              }
-            }
-          })
+      for (const entry of def['@restrict']) {
+        if (entry.where) {
+          // TODO: Check return value (where xpr)
+          checkAndCompileWhereExpression(entry.where)
         }
-      })
+      }
 
-      if (e['@restrict']) {
-        const node = context.getNode(e)
-        const file = e.$location.file
-        for (const entry of e['@restrict']) {
-          const whereValues = entry.where
-          if (whereValues && typeof whereValues === 'string') {
-            try {
-              cds.parse.expr(entry.where)
-            } catch (_err) {
-              context.report({
-                message: 'Invalid `where` expression, CDS compilation failed.',
-                node,
-                file
-              })
-            }
-          }
+      function checkAndCompileWhereExpression(where) {
+        try {
+          const compileOptions = {}
+          return typeof where === 'string'
+            ? cds.parse.expr(where, compileOptions)
+            : where
+
+        } catch {
+          context.report({
+            messageId: 'CompilationFailed',
+            node: context.getNode(def),
+            file: def.$location.file,
+          })
+          return null
         }
       }
     }

package/lib/rules/extension-restrictions.js

@@ -1,13 +1,16 @@
+'use strict'
+
 const cds = requireMtx()
 
-const { dirname } = require('path')
+const { dirname } = require('node:path')
 
 const rule = module.exports = {
   meta: {
     docs: {
       description: 'Extensions must not violate restrictions set by the extended SaaS app.',
       category: 'Model Validation',
-      recommended: true
+      recommended: true,
+      url: 'https://cap.cloud.sap/docs/tools/cds-lint/meta/extension-restrictions',
     },
     hasSuggestions: false,
     type: 'problem',
@@ -41,6 +44,9 @@ const rule = module.exports = {
   }
 }
 
+/**
+ * @param {CDSRuleContext} context
+ */
 function baseModel (context) {
   let dir = context.getFilename()
   do {
@@ -61,9 +67,11 @@ function baseModel (context) {
 function requireMtx () {
   const cds = require('@sap/cds')
   try {
+    // eslint-disable-next-line
     const pkg = require.resolve('@sap/cds-mtxs', { paths: [cds.root, __dirname] })
     return require(pkg)
   } catch (e) {
-    if (e.code !== 'MODULE_NOT_FOUND') throw e
+    if (e.code !== 'MODULE_NOT_FOUND')
+      throw e
   }
 }

package/lib/rules/index.js

@@ -1,5 +1,7 @@
+'use strict'
+
 const Cache = require('../utils/Cache')
-const { createRule } = require('../api')
+const createRule = require('../utils/createRule')
 
 const rules = {
   'assoc2many-ambiguous-key': () => createRule(require('./assoc2many-ambiguous-key')),
@@ -12,8 +14,10 @@ const rules = {
   'auth-valid-restrict-where': () => createRule(require('./auth-valid-restrict-where')),
   'latest-cds-version': () => createRule(require('./latest-cds-version')),
   'no-db-keywords': () => createRule(require('./no-db-keywords')),
+  'no-java-keywords': () => createRule(require('./no-java-keywords')),
   'no-dollar-prefixed-names': () => createRule(require('./no-dollar-prefixed-names')),
   'no-join-on-draft': () => createRule(require('./no-join-on-draft')),
+  'sql-null-comparison': () => createRule(require('./sql-null-comparison')),
   'sql-cast-suggestion': () => createRule(require('./sql-cast-suggestion')),
   'start-elements-lowercase': () => createRule(require('./start-elements-lowercase')),
   'start-entities-uppercase': () => createRule(require('./start-entities-uppercase')),