chore(components): create eslint rule for stencil props initialization

.github/workflows/lint.yaml

@@ -27,6 +27,9 @@ jobs:
       - name: Install dependencies of changed packages
         run: pnpm install
 
+      - name: Build eslint package
+        run: pnpm --filter @swisspost/design-system-eslint build
+
       # Test all changed packages and their dependents
       # https://pnpm.io/filtering#--filter-since
       - name: Lint packages

packages/components/eslint.config.mjs

@@ -8,6 +8,7 @@ import { fixupConfigRules, fixupPluginRules } from '@eslint/compat';
 import reactPlugin from 'eslint-plugin-react';
 import stencilCommunityPlugin from '@stencil-community/eslint-plugin';
 import pluginCypress from 'eslint-plugin-cypress/flat';
+import { configs as dsEslintConfigs } from '@swisspost/design-system-eslint';
 
 const compatStencilCommunityBaseRules = fixupConfigRules(stencilCommunityPlugin.configs.base)[0]
   .overrides[0].rules;
@@ -54,6 +55,7 @@ export default [
     },
   },
   ...ts.configs.recommended,
+  dsEslintConfigs.stencilRecommended,
   {
     files: ['**/*.{js,mjs,cjs}'],
     ...ts.configs.disableTypeChecked,

packages/components/package.json

@@ -47,6 +47,7 @@
     "@oddbird/popover-polyfill": "0.5.2",
     "@swisspost/design-system-icons": "workspace:10.0.0-next.38",
     "@swisspost/design-system-styles": "workspace:10.0.0-next.38",
+    "@swisspost/design-system-eslint": "workspace:1.0.1-next.0",
     "ally.js": "1.4.1",
     "long-press-event": "2.5.0",
     "nanoid": "5.1.5"

packages/components/src/components/post-tag/post-tag.tsx

@@ -29,7 +29,9 @@ export class PostTag {
    * <span className="banner banner-sm banner-info">If not set the icon will not show up.</span>
    * To learn which icons are available, please visit our <a href="/?path=/docs/0dcfe3c0-bfc0-4107-b43b-7e9d825b805f--docs">icon library</a>.
    */
-  @Prop() readonly icon: string;
+
+  @Prop() readonly icon?: string;
+
 
   constructor() {
     this.setClasses = this.setClasses.bind(this);

packages/eslint/docs/rules/strict-props-initialization.md

@@ -0,0 +1,29 @@
+# `strict-props-initialization`
+
+Reports any Stencil component `@Prop` that lacks an initial value and is neither marked as optional (?) or definitely assigned (!).',
+
+- Type: problem
+
+## Rule Options
+
+This rule does not have any configuration options.
+
+## Example
+
+### ❌ Invalid Code
+
+```ts
+@Prop() myProp: string;
+```
+
+### ✅ Valid Code
+
+```ts
+@Prop() myProp!: string;
+```
+
+Or
+
+```ts
+@Prop() myProp?: string;
+```

packages/eslint/package.json

@@ -5,7 +5,7 @@
   "description": "A set of custom ESLint rules to help keeping projects using the Swiss Post Design System up-to-date.",
   "author": "Swiss Post <[email protected]>",
   "license": "Apache-2.0",
-  "main": "dist/index.ts",
+  "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "repository": {
     "type": "git",

packages/eslint/src/configs/stencil/recommended.ts

@@ -0,0 +1,28 @@
+import type { TSESLint } from '@typescript-eslint/utils';
+
+// Define the recommended Stencil configuration
+const stencilRecommendedConfig = (
+  stencilPlugin: TSESLint.FlatConfig.Plugin,
+  parser: TSESLint.FlatConfig.Parser,
+): TSESLint.FlatConfig.Config => ({
+  name: '@swisspost/design-system-eslint/stencil/recommended',
+  files: ['**/*.{ts,tsx}'], // Apply to TypeScript and TSX files
+  languageOptions: {
+    parser, // Use the provided parser
+    parserOptions: {
+      ecmaVersion: 2020,
+      sourceType: 'module',
+      ecmaFeatures: {
+        jsx: true,
+      },
+    },
+  },
+  plugins: {
+    '@swisspost/design-system-eslint': stencilPlugin,
+  },
+  rules: {
+    '@swisspost/design-system-eslint/stencil-strict-props-initialization': 'error',
+  },
+});
+
+export default stencilRecommendedConfig;

packages/eslint/src/index.ts

@@ -4,11 +4,13 @@ import { htmlParser } from './parsers/html';
 
 import { htmlRules } from './rules/html';
 import { tsRules } from './rules/ts';
+import { dsLintingRules } from './rules';
 
 import htmlAllConfig from './configs/html/all';
 import htmlRecommendedConfig from './configs/html/recommended';
 import tsAllConfig from './configs/ts/all';
 import tsRecommendedConfig from './configs/ts/recommended';
+import stencilRecommendedConfig from './configs/stencil/recommended';
 
 const htmlPlugin: TSESLint.FlatConfig.Plugin = {
   rules: htmlRules,
@@ -18,7 +20,10 @@ const htmlPlugin: TSESLint.FlatConfig.Plugin = {
 };
 
 const tsPlugin: TSESLint.FlatConfig.Plugin = {
-  rules: tsRules,
+  rules: {
+    ...tsRules, // Include existing (currently empty) TS rules
+    ...dsLintingRules, // Include Design System Sepcific
+  },
   meta: {
     name: '@swisspost/eslint-plugin-design-system',
   },
@@ -29,6 +34,7 @@ const configs = {
   htmlRecommended: htmlRecommendedConfig(htmlPlugin, htmlParser),
   tsAll: tsAllConfig(tsPlugin, parser),
   tsRecommended: tsRecommendedConfig(tsPlugin, parser),
+  stencilRecommended: stencilRecommendedConfig(tsPlugin, parser),
 };
 
 /* default and named exports allow people to use this package from both CJS and ESM. */

packages/eslint/src/rules/index.ts

@@ -0,0 +1,7 @@
+import stencilStrictPropsInitializationRule, {
+  name as stencilStrictPropsInitializationRuleName,
+} from './stencil-strict-props-initialization';
+
+export const dsLintingRules = {
+  [stencilStrictPropsInitializationRuleName]: stencilStrictPropsInitializationRule,
+};

packages/eslint/src/rules/stencil-strict-props-initialization.ts

@@ -0,0 +1,59 @@
+import { createRule } from '../utils/create-rule';
+import { AST_NODE_TYPES } from '@typescript-eslint/utils';
+
+export const name = 'stencil-strict-props-initialization';
+
+export default createRule({
+  name,
+  meta: {
+    docs: {
+      dir: 'ts',
+      description:
+        'Reports any Stencil component @Prop properties that lack an initial value and are neither marked as optional (?) nor definitely assigned (!).',
+    },
+    messages: {
+      propStrictInit:
+        "The '@Prop' property '{{propertyName}}' must have an initial value, or be explicitly marked as optional (?) or definitely assigned (!).",
+    },
+    type: 'suggestion',
+    schema: [],
+  },
+  defaultOptions: [],
+
+  create(context) {
+    return {
+      PropertyDefinition(node) {
+        if (node.decorators && node.decorators.length > 0) {
+          // Check if any decorator is @Prop()
+          const isProp = node.decorators.some(decorator => {
+            // Check for CallExpression like @Prop()
+            if (decorator.expression.type === AST_NODE_TYPES.CallExpression) {
+              const callee = decorator.expression.callee;
+              // Check if the callee is an Identifier named 'Prop'
+              if (callee.type === AST_NODE_TYPES.Identifier && callee.name === 'Prop') {
+                return true;
+              }
+            }
+            return false; // Ignore other decorator types or CallExpressions with different callees
+          });
+          if (isProp) {
+            // Check if the property is optional (?) or definitely assigned (!)
+            const isOptional = node.optional;
+            const isDefinitelyAssigned = node.definite;
+            // Also check if the property has no initial value set
+            if (!isOptional && !isDefinitelyAssigned && node.value === null) {
+              context.report({
+                node,
+                messageId: 'propStrictInit',
+                data: {
+                  propertyName:
+                    node.key.type === AST_NODE_TYPES.Identifier ? node.key.name : 'unknown',
+                },
+              });
+            }
+          }
+        }
+      },
+    };
+  },
+});

packages/eslint/test/rules/stencil-strict-props-initialization.spec.ts

@@ -0,0 +1,45 @@
+import rule, { name } from '../../src/rules/stencil-strict-props-initialization';
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import { AST_NODE_TYPES } from '@typescript-eslint/utils'; // Import AST_NODE_TYPES
+
+const ruleTester = new RuleTester();
+
+ruleTester.run(name, rule, {
+  valid: [
+    //Code examples that should NOT trigger the rule
+    `
+    class MyComponent {
+      @Prop() myProp?:string;
+    }
+    `,
+    `
+    class MyComponent {
+      @Prop() myProp!:string;
+    }
+    `,
+    // Valid case for a property with an initial value
+    `
+    class MyComponent {
+      @Prop() myProp = 'initial value';
+    }
+    `,
+  ],
+  invalid: [
+    {
+      // Code that SHOULD trigger the rule
+      code: `
+        class MyComponent {
+          @Prop() myProp: string; // Not optional, not definitely assigned, no initial value
+        }
+      `,
+      errors: [
+        {
+          messageId: 'propStrictInit',
+          type: AST_NODE_TYPES.PropertyDefinition, // The AST node type the rule checks (PropertyDefinition for class properties)
+          line: 3,
+          column: 11,
+        },
+      ],
+    },
+  ],
+});