@sap/eslint-plugin-cds 3.0.5 → 3.1.1

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')),

package/lib/rules/latest-cds-version.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const cp = require('child_process')
 const semver = require('semver')
 
@@ -5,12 +7,11 @@ module.exports = {
   meta: {
     schema: [{/* to avoid deprecation warning for ESLint 9 */}],
     docs: {
-      description: 'Checks whether the latest `@sap/cds` version is being used.'
+      description: 'Checks whether the latest `@sap/cds` version is being used.',
     },
     type: 'suggestion',
-    hasSuggestions: true,
     messages: {
-      latestCDSVersion: 'A newer CDS version is available!'
+      latestCdsVersion: 'A newer CDS version is available!'
     },
     severity: 'off',
     model: 'none'
@@ -36,7 +37,7 @@ module.exports = {
         // If current cds version is not the latest
         if (Object.keys(cdsVersions).length !== 0 && !semver.satisfies(cdsVersions.latest, cdsVersions.current)) {
           context.report({
-            messageId: 'latestCDSVersion',
+            messageId: 'latestCdsVersion',
             node: context.getNode()
           })
         }

package/lib/rules/no-db-keywords.js

@@ -1,11 +1,22 @@
+'use strict'
+
 const cds = require('@sap/cds')
 
+// REVISIT: Replace by compiler-provided check
+const RESERVED = cds.compile.to.sql.sqlite
+  ? cds.compile.to.sql.sqlite.keywords
+  : [ 'ORDER', 'GROUP', 'LIMIT' ]
+
 module.exports = {
   meta: {
     schema: [{/* to avoid deprecation warning for ESLint 9 */}],
     docs: {
       description: 'Avoid using reserved SQL keywords.',
-      recommended: true
+      recommended: true,
+      url: 'https://cap.cloud.sap/docs/tools/cds-lint/meta/no-db-keywords',
+    },
+    messages: {
+      reservedKeyword: `'{{name}}' is a reserved keyword in SQLite`,
     },
     type: 'problem',
     model: 'inferred'
@@ -29,7 +40,8 @@ module.exports = {
         if (srv && srv['@cds.external']) return
         if (d.kind === 'entity' && d['@cds.persistence.skip'] === true) return
         context.report({
-          message: `'${d.name}' is a reserved keyword in SQLite`,
+          messageId: 'reservedKeyword',
+          data: { name: d.name },
           node: context.getNode(d),
           file: d.$location.file
         })
@@ -37,6 +49,3 @@ module.exports = {
     }
   }
 }
-
-// REVISIT: Replace by compiler-provided check
-const RESERVED = cds.compile.to.sql.sqlite ? cds.compile.to.sql.sqlite.keywords : ['ORDER', 'GROUP', 'LIMIT']

package/lib/rules/no-dollar-prefixed-names.js

@@ -1,9 +1,15 @@
+'use strict'
+
 module.exports = {
   meta: {
     schema: [{/* to avoid deprecation warning for ESLint 9 */}],
     docs: {
       description: 'Names must not start with $ to avoid possible shadowing of reserved variables.',
-      recommended: true
+      recommended: true,
+      url: 'https://cap.cloud.sap/docs/tools/cds-lint/meta/no-dollar-prefixed-names',
+    },
+    messages: {
+      dollarPrefix: `'{{name}}' is prefixed with a dollar sign ($)`,
     },
     type: 'problem'
   },
@@ -15,7 +21,8 @@ module.exports = {
       if (srv && srv['@cds.external']) return
       if (d.name.startsWith('$')) {
         context.report({
-          message: `'${d.name}' is prefixed with a dollar sign ($)`,
+          messageId: 'dollarPrefix',
+          data: { name: d.name },
           node: context.getNode(d)
         })
       }

package/lib/rules/no-java-keywords.js

@@ -0,0 +1,181 @@
+'use strict'
+
+// Check that Java keywords are not used as identifiers unless they have
+// a Java-specific annotation that renames/ignores them.  This avoids issues
+// later on in code-generation of CAP Java classes.
+// Test Java code via godbolt.org: https://godbolt.org/z/1c5s49qjo
+
+const { splitDefName } = require('../utils/rules')
+
+// There is also `@cds.java.this.name`, which is not relevant for this check.
+const ANNO_JAVA_NAME = '@cds.java.name'
+const ANNO_JAVA_IGNORE = '@cds.java.ignore'
+
+// CSN kinds that are relevant for code generation with possible keyword
+// conflicts.  For example, types are not relevant, because they use
+// PascalCase, i.e. it can never be a keyword conflict, since all keywords
+// are lowercase.
+const relevantKinds = [
+  'element',
+  'param',
+  'action',
+  'function',
+]
+
+module.exports = {
+  meta: {
+    schema: [{/* to avoid deprecation warning for ESLint 9 */}],
+    docs: {
+      description: 'Reject reserved Java keywords as CDS identifiers.',
+      recommended: true
+    },
+    type: 'problem',
+    model: 'inferred',
+    messages: {
+      keywordJava: `'{{name}}' is a reserved keyword in Java. Use '@cds.java.name' to override the name for Java code generation.`,
+    },
+  },
+  create (context) {
+    const rootPath = context.getRootPath()
+    if (!rootPath)
+      return
+
+    return function checkForJavaKeywords(){
+      const model = context.getModel()
+      if (!model)
+        return
+      for (const name in model.definitions)
+        checkDefinition(model.definitions[name])
+    }
+
+    function checkDefinition(def) {
+      checkNameIsNotReserved(def)
+      if (def.elements) {
+        for (const name in def.elements)
+          checkDefinition(def.elements[name])
+      }
+      if (def.actions) {
+        for (const name in def.actions)
+          checkDefinition(def.actions[name])
+      }
+      if (def.kind === 'action' || def.kind === 'function') {
+        for (const name in def.params)
+          checkDefinition(def.params[name])
+      }
+    }
+
+    function checkNameIsNotReserved(artifact) {
+      if (!artifact.$location?.file || !relevantKinds.includes(artifact.kind))
+        return
+      if (artifact[ANNO_JAVA_IGNORE])
+        return // ignored; no Java code generated
+      if (artifact[ANNO_JAVA_NAME])
+        return // explicitly renamed; assume the user uses a valid name
+
+      const name = artifact.is('element')
+        ? artifact.name
+        : splitDefName(artifact).name
+
+      if (isValueReservedJavaKeyword(name)) {
+        context.report({
+          messageId: 'keywordJava',
+          data: { name },
+          node: context.getNode(artifact),
+          file: artifact.$location.file,
+        })
+      }
+    }
+  }
+}
+
+// List from https://docs.oracle.com/javase/tutorial/java/nutsandbolts/_keywords.html
+// Also available at https://github.com/openjdk/jdk/blob/f92c60e1a9968620cbc92b52aa546b57c09da487/src/java.compiler/share/classes/javax/lang/model/SourceVersion.java#L651
+// though that list includes fewer items.
+const JAVA_RESERVED = [
+  '_',
+  'abstract',
+  'assert',
+  'boolean',
+  'break',
+  'byte',
+  'case',
+  'catch',
+  'char',
+  'class',
+  'const',
+  'continue',
+  'default',
+  'do',
+  'double',
+  'else',
+  'enum',
+  'extends',
+  'final',
+  'finally',
+  'float',
+  'for',
+  'goto',
+  'if',
+  'implements',
+  'import',
+  'instanceof',
+  'int',
+  'interface',
+  'long',
+  'native',
+  'new',
+  'package',
+  'private',
+  'protected',
+  'public',
+  'return',
+  'short',
+  'static',
+  'strictfp',
+  'super',
+  'switch',
+  'synchronized',
+  'this',
+  'throw',
+  'throws',
+  'transient',
+  'try',
+  'void',
+  'volatile',
+  'while',
+  // literals
+  'true',
+  'false',
+  'null',
+]
+
+/**
+ * Check if the given value is a reserved keyword.
+ *
+ * @param {any} name
+ * @returns {boolean}
+ */
+function isValueReservedJavaKeyword(name) {
+  if (!name || typeof name !== 'string')
+    return false
+  const normalized = identifierForJava(name)
+  return JAVA_RESERVED.includes(normalized)
+}
+
+/**
+ * Returns the check-relevant identifier for Java.
+ * CAP Java does not use lowercase for the full identifier, but instead
+ * uses lowerCamelCase, i.e. it is enough to change the first character
+ * of the identifier.
+ *
+ * @param {string} name
+ * @returns {string}
+ */
+function identifierForJava(name) {
+  if (!name)
+    return name
+  const firstChar = name.charAt(0)
+  if (firstChar === firstChar.toLowerCase())
+    return name
+  return `${firstChar.toLowerCase()}${name.slice(1)}`
+}

package/lib/rules/no-join-on-draft.js

@@ -1,9 +1,15 @@
+'use strict'
+
 module.exports = {
   meta: {
     schema: [{/* to avoid deprecation warning for ESLint 9 */}],
     docs: {
-      description: "Draft-enabled entities shall not be used in views that make use of `JOIN`.",
-      recommended: true
+      description: 'Draft-enabled entities shall not be used in views that make use of `JOIN`.',
+      recommended: true,
+      url: 'https://cap.cloud.sap/docs/tools/cds-lint/meta/no-join-on-draft',
+    },
+    messages: {
+      draftJoin:  'Do not use draft-enabled entities in views that make use of `JOIN`.',
     },
     type: 'suggestion',
     model: 'inferred'
@@ -15,7 +21,7 @@ module.exports = {
       if (e['@odata.draft.enabled']) {
         if (e?.query?.SELECT?.from?.join) {
           context.report({
-            message: 'Do not use draft-enabled entities in views that make use of `JOIN`.',
+            messageId: 'draftJoin',
             node: context.getNode(e),
             file: e.$location.file
           })

package/lib/rules/sql-cast-suggestion.js

@@ -1,13 +1,14 @@
+'use strict'
 
 module.exports = {
   meta: {
     schema: [{/* to avoid deprecation warning for ESLint 9 */}],
     docs: {
       description: 'Should make suggestions for possible missing SQL casts.',
-      recommended: true
+      recommended: true,
+      url: 'https://cap.cloud.sap/docs/tools/cds-lint/meta/sql-cast-suggestion',
     },
     type: 'suggestion',
-    hasSuggestions: true,
     messages: {
       missingSQLCast: 'Potential issue - Missing SQL cast for column expression?'
     }
@@ -16,19 +17,22 @@ module.exports = {
     return { view: checkSqlCast }
 
     function checkSqlCast (v) {
-      if (v.query && v.query.SET) {
-        for (const { SELECT } of v.query.SET.args) {
-          // Only in UNION cases?
-          for (const each of SELECT.columns || []) {
-            const { xpr, cast } = each
-            if (cast && xpr) {
-              if (xpr[0].xpr && xpr[0].cast) {
-                continue
-              } else {
-                context.report({
-                  messageId: 'missingSQLCast',
-                  node: context.getNode(v)
-                })
+      // TODO: restructure and make more robust (#507)
+      if (v?.query?.SET?.args) {
+        for (const arg of v.query.SET.args) {
+          if (arg?.SELECT) {
+            // Only in UNION cases?
+            for (const each of arg.SELECT.columns || []) {
+              if (each) {
+                const { xpr, cast } = each
+                if (cast && xpr) {
+                  if (!(xpr[0]?.xpr && xpr[0]?.cast)) {
+                    context.report({
+                      messageId: 'missingSQLCast',
+                      node: context.getNode(v)
+                    })
+                  }
+                }
               }
             }
           }

package/lib/rules/sql-null-comparison.js

@@ -0,0 +1,60 @@
+'use strict'
+
+const { forEachXprInDefinition } = require('../utils/csnTraversal')
+
+const invalidComparisonOperators = [ '=', '!=', '<>' ]
+
+module.exports = {
+  meta: {
+    schema: [{/* to avoid deprecation warning for ESLint 9 */}],
+    docs: {
+      description: 'Ensure SQL comparisons with \'null\' are valid',
+      category: 'Model Validation',
+      recommended: false,
+      // TODO: Add documentation
+      // url: 'https://cap.cloud.sap/docs/tools/cds-lint/meta/sql-null-comparison',
+    },
+    type: 'problem',
+    model: 'parsed',
+    messages: {
+      nullComparison: `Comparisons against 'null' are always null. Did you mean 'is not null'?`,
+    }
+  },
+  create(context) {
+    return {
+      view(v) {
+        forEachXprInDefinition(v, checkExpression)
+
+        function checkExpression(xpr, ctx) {
+          if (!xpr || !Array.isArray(xpr))
+            return
+
+          for (let i = 0; i < xpr.length; i++) {
+            if (typeof xpr[i] !== 'object')
+              continue // scalar value, etc.
+
+            if (xpr[i]?.val === null) {
+              const prev = i > 0 && typeof xpr[i-1] === 'string' ? xpr[i-1] : null
+              if (prev && invalidComparisonOperators.includes(prev)) {
+                reportComparison(xpr, ctx)
+                continue
+              }
+              const next = i+1 < xpr.length && typeof xpr[i+1] === 'string' ? xpr[i+1] : null
+              if (next && invalidComparisonOperators.includes(next))
+                reportComparison(xpr, ctx)
+            }
+          }
+        }
+
+        function reportComparison(xpr, ctx) {
+          context.report({
+            messageId: 'nullComparison',
+            loc: context.getLocation(null, ctx),
+            file: ctx.$location?.file,
+          })
+        }
+
+      }
+    }
+  }
+}

package/lib/rules/start-elements-lowercase.js

@@ -1,8 +1,11 @@
+'use strict'
+
 module.exports = {
   meta: {
     schema: [{/* to avoid deprecation warning for ESLint 9 */}],
     docs: {
-      description: 'Regular element names should start with lowercase letters.'
+      description: 'Regular element names should start with lowercase letters.',
+      url: 'https://cap.cloud.sap/docs/tools/cds-lint/meta/start-elements-lowercase',
     },
     type: 'suggestion',
     hasSuggestions: true,
@@ -10,7 +13,8 @@ module.exports = {
       startLowercase: "Element name '{{entityName}}.{{elementName}}' should start with a lowercase letter.",
       fixLowercase: 'Start element name with a lowercase letter.'
     },
-    fixable: 'code'
+    fixable: 'code',
+    model: 'parsed',
   },
   create: function (context) {
     const sourcecode = context.getSourceCode()

package/lib/rules/start-entities-uppercase.js

@@ -1,10 +1,13 @@
+'use strict'
+
 const { splitDefName } = require('../utils/rules')
 
 module.exports = {
   meta: {
     schema: [{/* to avoid deprecation warning for ESLint 9 */}],
     docs: {
-      description: 'Regular entity names should start with uppercase letters.'
+      description: 'Regular entity names should start with uppercase letters.',
+      url: 'https://cap.cloud.sap/docs/tools/cds-lint/meta/start-entities-uppercase',
     },
     type: 'suggestion',
     hasSuggestions: true,
@@ -12,20 +15,24 @@ module.exports = {
       startUppercase: "Entity name '{{entityName}}' should start with an uppercase letter.",
       fixUppercase: 'Start entity name with an uppercase letter.'
     },
-    fixable: 'code'
+    fixable: 'code',
+    model: 'parsed',
   },
-  create: function (context) {
+  create(context) {
     const sourcecode = context.getSourceCode()
 
     return { entity: checkStartsUppercase }
 
     function checkStartsUppercase (e) {
+      if (e.kind !== 'entity')
+        return // workaround for #424
+
       const entityName = splitDefName(e).name
       if (entityName.charAt(0) !== entityName.charAt(0).toUpperCase()) {
-        if (e.$location && e.$location.file) {
+        if (e.$location?.file) {
           const file = e.$location.file
           const loc = context.getLocation(entityName, e)
-          const fix = (fixer) => {
+          const fix = fixer => {
             const entityNameSanitized = entityName.charAt(0).toUpperCase() + entityName.slice(1)
             const rangeEnd = sourcecode.getIndexFromLoc({
               line: loc.end.line,

package/lib/rules/valid-csv-header.js

@@ -1,5 +1,7 @@
+'use strict'
+
 const cds = require('@sap/cds')
-const { basename, extname } = require('path')
+const { basename, extname } = require('node:path')
 const findFuzzy = require('../utils/findFuzzy')
 const SEP = '[,;\t]'
 const EOL = '\\r?\\n'
@@ -10,7 +12,8 @@ module.exports = {
     docs: {
       description: 'CSV files for entities must refer to valid element names.',
       category: 'Model Validation',
-      recommended: true
+      recommended: true,
+      url: 'https://cap.cloud.sap/docs/tools/cds-lint/meta/valid-csv-header',
     },
     severity: 'warn',
     type: 'problem',
@@ -33,7 +36,15 @@ module.exports = {
       if (!filePath.endsWith('.csv')) return
       if (!model) return
 
-      model = cds.compile.for.sql(model, { names: cds.env.sql.names, messages: [] })
+      try {
+        model = cds.compile.for.sql(model, { names: cds.env.sql.names, messages: [] })
+      } catch(e) {
+        // ignore invalid models; the compiler emits errors already
+        if (e.code !== 'ERR_CDS_COMPILATION_FAILURE')
+          throw e
+      }
+
+      if (!model) return
 
       const filename = basename(filePath)
       const entityName = filename.replace(/-/g, '.').slice(0, -extname(filename).length)
@@ -41,20 +52,20 @@ module.exports = {
       if (!entity) return
 
       const elements = Object.values(entity.elements)
-        .filter((e) => !!e['@cds.persistence.name'])
-        .map((e) => e['@cds.persistence.name'].toUpperCase())
+        .filter(e => !!e['@cds.persistence.name'])
+        .map(e => e['@cds.persistence.name'].toUpperCase())
 
       const [cols] = cds.parse.csv(code)
-      const missing = cols.filter((col) => !elements.includes(col.toUpperCase()))
+      const missing = cols.filter(col => !elements.includes(col.toUpperCase()))
       for (const miss of missing) {
         const index = _findInCode(miss, code)
         const loc = sourcecode.getLocFromIndex(index)
         const candidates = findFuzzy(miss, Object.keys(entity.elements).sort())
-        const suggest = candidates.map((cand) => {
+        const suggest = candidates.map(cand => {
           return {
             messageId: 'ReplaceColumnWith',
             data: { column: miss, candidates: cand },
-            fix: (fixer) => fixer.replaceTextRange([index, index + miss.length], cand)
+            fix: fixer => fixer.replaceTextRange([index, index + miss.length], cand)
           }
         })
         context.report({
@@ -69,20 +80,29 @@ module.exports = {
   }
 }
 
-function _findInCode (miss, code) {
+/**
+ * @param {string} needle
+ * @param {string} code
+ * @returns {number} -1 if not found
+ */
+function _findInCode(needle, code) {
   // middle
-  let match = new RegExp(SEP + miss + SEP).exec(code)
+  let match = new RegExp(SEP + needle + SEP).exec(code)
   if (match) return match.index + 1
   // end of line
-  match = new RegExp(SEP + miss + EOL).exec(code)
+  match = new RegExp(SEP + needle + EOL).exec(code)
   if (match) return match.index + 1
   // start of doc
-  match = new RegExp('^' + miss + SEP).exec(code)
+  match = new RegExp('^' + needle + SEP).exec(code)
   if (match) return match.index
   // somewhere (fallback)
-  return code.indexOf(miss)
+  return code.indexOf(needle)
 }
 
+/**
+ * @param {string} name
+ * @param {object} csn
+ */
 function _entity4 (name, csn) {
   const entity = csn.definitions[name]
   if (!entity) {

package/lib/types.d.ts

@@ -1,5 +1,5 @@
 
-import { Linter, Rule, RuleTester, SourceCode } from "eslint";
+import { Rule, RuleTester, SourceCode } from "eslint";
 
 export interface CDSRuleContext extends Rule.RuleContext {
     cds: any;
@@ -9,13 +9,13 @@ export interface CDSRuleContext extends Rule.RuleContext {
     options: [];
     id: string;
     sourcecode: SourceCode;
-    getModel: function;
-    report: (CDSRuleReport) => void;
+    getModel: Function;
+    report: (descriptor: CDSRuleReport) => void;
     err: Error;
 }
 
 export interface Rule {
-    meta: RuleMetaData,
+    meta: Rule.RuleMetaData,
     create: (context: CDSRuleContext) => void;
 }