lint: move rule docs and samples closer together (#2112)

The current split into `rules/` and `examples/` folders is a bit hard to
grasp. Move the sample and docs for a rule in one folder, eliminating
the `examples` folder.

URLs change slightly:
- `cds-lint/rules/foobar` (before)
- `cds-lint/rules/foobar/` (now)

Author: chgeo

.github/eslint-plugin/index.js

@@ -10,19 +10,15 @@
 import * as fs from 'node:fs'
 import * as path from 'node:path'
 
-const RULES_BASE_PATH = path.join('tools', 'cds-lint', 'rules');
-const EXAMPLES_BASE_PATH = path.join('tools', 'cds-lint', 'examples');
+const RULES_BASE_PATH    = path.join(import.meta.dirname, '../../tools/cds-lint/rules');
+const EXAMPLES_BASE_PATH = RULES_BASE_PATH
 const MENU_FILE_NAME = '_menu.md';
 
 /**
  * Get a list of all rule description files.
  * @returns {string[]} An array of rule description file names.
  */
-const getRuleDescriptionFiles = () =>
-    fs.readdirSync(RULES_BASE_PATH)
-        .filter(file => file.endsWith('.md'))
-        .filter(file => !['index.md', MENU_FILE_NAME].includes(file))
-        .sort()
+const getRuleDescriptionFiles = () => fs.globSync(path.join(RULES_BASE_PATH, '*/index.md')).sort()
 
 /**
  * Generates the menu markdown file
@@ -33,12 +29,13 @@ const getRuleDescriptionFiles = () =>
 function generateMenuMarkdown () {
     const rules = getRuleDescriptionFiles();
     const menu = rules.map(rule => {
-        const clean = rule.replace('.md', '');
-        return `# [${clean}](${clean})`
+        const folderPath = path.posix.dirname(path.relative(RULES_BASE_PATH, rule));
+        const name = path.basename(folderPath);
+        return `# [${name}](${folderPath}/)`
     }).join('\n');
-    const menuFilePath = path.join(RULES_BASE_PATH, '_menu.md')
+    const menuFilePath = path.join(RULES_BASE_PATH, MENU_FILE_NAME)
     fs.writeFileSync(menuFilePath, menu);
-    console.info(`generated menu to ${menuFilePath}`)
+    console.info(`generated menu to ${path.relative(process.cwd(), menuFilePath)}`);
 }
 
 /**
@@ -52,11 +49,12 @@ function generateJsRuleStub (ruleName) {
         console.error('Please provide a rule name, e.g. "no-shared-handler-variables" as second argument');
         process.exit(1);
     }
-    const stubFilePath = path.join(RULES_BASE_PATH, ruleName + '.md');
+    const stubFilePath = path.join(RULES_BASE_PATH, ruleName, 'index.md');
     if (fs.existsSync(stubFilePath)) {
         console.error(`file ${stubFilePath} already exists, will not overwrite`);
         process.exit(2);
     }
+    fs.mkdirSync(path.dirname(stubFilePath), { recursive: true });
     const stub = fs.readFileSync(path.join(import.meta.dirname, 'js-rule-stub.md'), 'utf-8').replaceAll('$RULE_NAME', ruleName);
     fs.writeFileSync(stubFilePath, stub);
     console.info(`generated stub to ${stubFilePath}`);

.github/eslint-plugin/js-rule-stub.md

@@ -3,7 +3,7 @@ status: released
 ---
 
 <script setup>
-  import PlaygroundBadge from '../components/PlaygroundBadge.vue'
+  import PlaygroundBadge from '../../components/PlaygroundBadge.vue'
 </script>
 
 # $RULE_NAME
@@ -22,7 +22,7 @@ This rule was introduced in `@sap/eslint-plugin-cds x.y.z`.
 DESCRIPTION OF CORRECT EXAMPLE
 
 ::: code-group
-<<< ../examples/$RULE_NAME/correct/srv/admin-service.js#snippet{js:line-numbers} [srv/admin-service.js]
+<<< correct/srv/admin-service.js#snippet{js:line-numbers} [srv/admin-service.js]
 :::
 <PlaygroundBadge
   name="$RULE_NAME"
@@ -35,7 +35,7 @@ DESCRIPTION OF CORRECT EXAMPLE
 DESCRIPTION OF INCORRECT EXAMPLE
 
 ::: code-group
-<<< ../examples/$RULE_NAME/incorrect/srv/admin-service.js#snippet{js:line-numbers} [srv/admin-service.js]
+<<< incorrect/srv/admin-service.js#snippet{js:line-numbers} [srv/admin-service.js]
 :::
 <PlaygroundBadge
   name="$RULE_NAME"

tools/cds-lint/components/PlaygroundBadge.vue

@@ -11,7 +11,7 @@ interface Props {
 withDefaults(defineProps<Props>(), { nolink: false })
 import { compress, prettyStringify } from './eslint-online-playground/utils';
 // @ts-ignore
-import { data } from '../examples/examples.data.ts';
+import { data } from '../rules/examples.data.ts';
 
 const configFileName = "eslint.config.js";
 const packageJsonFileName = "package.json";
@@ -29,7 +29,7 @@ export default [
 
 const defaultPackageJson = JSON.parse(data['package.json']);
 
-const is_object = x => typeof x === 'object' && x !== null && !Array.isArray(x)
+const is_object = (x:any) => typeof x === 'object' && x !== null && !Array.isArray(x)
 function merge (o:any,...xs:any) {
   let v:any; for (let x of xs) for (let k in x)
     if (k === '__proto__' || k === 'constructor') continue //> avoid prototype pollution

tools/cds-lint/examples/no-shared-handler-variable/correct/srv/admin-service.js

@@ -58,7 +58,7 @@ To turn on lint checking in your VS Code Editor simply download the [ESLint exte
 CDS Lint seamlessly integrates with it. For _SAP Business Application Studio_ this comes preinstalled.
 
 Now you can see lint reports also in your editor. You can see all rules [marked as **Editor default** here](./rules/). Any other (project-based) rules are not turned on by
-default but can be turned on via the `show` rule option. For example, if we want to show the [`valid-csv-header`](./rules/valid-csv-header) rule reports in the Editor, we would add the following to our ESLint
+default but can be turned on via the `show` rule option. For example, if we want to show the [`valid-csv-header`](./rules/valid-csv-header/) rule reports in the Editor, we would add the following to our ESLint
 `rules` configuration:
 
 ```json

tools/cds-lint/examples/no-shared-handler-variable/incorrect/srv/admin-service.js

@@ -1,24 +1,24 @@
-# [assoc2many-ambiguous-key](assoc2many-ambiguous-key)
-# [auth-no-empty-restrictions](auth-no-empty-restrictions)
-# [auth-restrict-grant-service](auth-restrict-grant-service)
-# [auth-use-requires](auth-use-requires)
-# [auth-valid-restrict-grant](auth-valid-restrict-grant)
-# [auth-valid-restrict-keys](auth-valid-restrict-keys)
-# [auth-valid-restrict-to](auth-valid-restrict-to)
-# [auth-valid-restrict-where](auth-valid-restrict-where)
-# [case-sensitive-well-known-events](case-sensitive-well-known-events)
-# [extension-restrictions](extension-restrictions)
-# [latest-cds-version](latest-cds-version)
-# [no-cross-service-import](no-cross-service-import)
-# [no-db-keywords](no-db-keywords)
-# [no-deep-sap-cds-import](no-deep-sap-cds-import)
-# [no-dollar-prefixed-names](no-dollar-prefixed-names)
-# [no-java-keywords](no-java-keywords)
-# [no-join-on-draft](no-join-on-draft)
-# [no-shared-handler-variable](no-shared-handler-variable)
-# [sql-cast-suggestion](sql-cast-suggestion)
-# [sql-null-comparison](sql-null-comparison)
-# [start-elements-lowercase](start-elements-lowercase)
-# [start-entities-uppercase](start-entities-uppercase)
-# [use-cql-select-template-strings](use-cql-select-template-strings)
-# [valid-csv-header](valid-csv-header)
+# [assoc2many-ambiguous-key](assoc2many-ambiguous-key/)
+# [auth-no-empty-restrictions](auth-no-empty-restrictions/)
+# [auth-restrict-grant-service](auth-restrict-grant-service/)
+# [auth-use-requires](auth-use-requires/)
+# [auth-valid-restrict-grant](auth-valid-restrict-grant/)
+# [auth-valid-restrict-keys](auth-valid-restrict-keys/)
+# [auth-valid-restrict-to](auth-valid-restrict-to/)
+# [auth-valid-restrict-where](auth-valid-restrict-where/)
+# [case-sensitive-well-known-events](case-sensitive-well-known-events/)
+# [extension-restrictions](extension-restrictions/)
+# [latest-cds-version](latest-cds-version/)
+# [no-cross-service-import](no-cross-service-import/)
+# [no-db-keywords](no-db-keywords/)
+# [no-deep-sap-cds-import](no-deep-sap-cds-import/)
+# [no-dollar-prefixed-names](no-dollar-prefixed-names/)
+# [no-java-keywords](no-java-keywords/)
+# [no-join-on-draft](no-join-on-draft/)
+# [no-shared-handler-variable](no-shared-handler-variable/)
+# [sql-cast-suggestion](sql-cast-suggestion/)
+# [sql-null-comparison](sql-null-comparison/)
+# [start-elements-lowercase](start-elements-lowercase/)
+# [start-entities-uppercase](start-entities-uppercase/)
+# [use-cql-select-template-strings](use-cql-select-template-strings/)
+# [valid-csv-header](valid-csv-header/)

tools/cds-lint/index.md

@@ -7,14 +7,14 @@ status: released
 ---
 
 <script setup>
-  import PlaygroundBadge from '../components/PlaygroundBadge.vue'
+  import PlaygroundBadge from '../../components/PlaygroundBadge.vue'
 </script>
 
 # assoc2many-ambiguous-key
 
 ## Rule Details
 
-An [association/composition to/of `MANY`](../../../cds/cdl#to-many-associations) that targets an entity without an `ON` condition is not allowed because it is an `n:1` relationship. Always specify an `ON` condition following the canonical expression pattern `<assoc>.<backlink> = $self`. The backlink can be any managed to-one association on the many side pointing back to the one side.
+An [association/composition to/of `MANY`](../../../../cds/cdl#to-many-associations) that targets an entity without an `ON` condition is not allowed because it is an `n:1` relationship. Always specify an `ON` condition following the canonical expression pattern `<assoc>.<backlink> = $self`. The backlink can be any managed to-one association on the many side pointing back to the one side.
 
 ## Examples
 
@@ -23,7 +23,7 @@ An [association/composition to/of `MANY`](../../../cds/cdl#to-many-associations)
 In the following example, we define a unique association from `Authors` to `Books` with a well-defined `ON` condition and backlink, thus satisfying the rule's conditions:
 
 ::: code-group
-<<< ../examples/assoc2many-ambiguous-key/correct/db/schema.cds#snippet{cds:line-numbers} [db/schema.cds]
+<<< correct/db/schema.cds#snippet{cds:line-numbers} [db/schema.cds]
 :::
 <PlaygroundBadge
   name="assoc2many-ambiguous-key"
@@ -37,7 +37,7 @@ In the following example, we define a unique association from `Authors` to `Book
 If you extend this example by creating a view `AuthorView` with a key `ID` and the element `bookIDs` without an `ON` condition, the rule is triggered because the key is no longer unique and `bookIDs` leads to multiple entries:
 
 ::: code-group
-<<< ../examples/assoc2many-ambiguous-key/incorrect/db/schema.cds#snippet{cds:line-numbers} [db/schema.cds]
+<<< incorrect/db/schema.cds#snippet{cds:line-numbers} [db/schema.cds]
 :::
 <PlaygroundBadge
   name="assoc2many-ambiguous-key"