@amazon-devices/eslint-plugin-kepler 0.1.8 → 0.1.13

package/README.md

@@ -36,11 +36,12 @@ To use Vega ESLint Plugin, complete the below steps in your Vega App Project.
     ```
 
     Available configs:
-    - `kepler` - All Kepler rules (performance + system distributed library checks + API privileges + backward compatibility)
+    - `kepler` - All Vega rules (performance + system distributed library checks + API privileges + backward compatibility + component migration)
     - `performance` - Performance-related rules only
     - `system-distributed-libs` - System distributed library checks (package.json validation and import informational flagging)
     - `api-privileges` - API privileges validation rules
-    - `backward-compatibility` - Backward compatibility validation rules for Kepler library projects
+    - `backward-compatibility` - Backward compatibility validation rules for Vega library projects
+    - `vega-ui-components` - Component migration and best practices rules (e.g., deprecated Carousel detection)
     
     You can use multiple configs:
     ```javascript
@@ -50,7 +51,7 @@ To use Vega ESLint Plugin, complete the below steps in your Vega App Project.
             "plugin:@amazon-devices/eslint-plugin-kepler/performance",
             "plugin:@amazon-devices/eslint-plugin-kepler/system-distributed-libs",
             "plugin:@amazon-devices/eslint-plugin-kepler/api-privileges",
-            "plugin:@amazon-devices/eslint-plugin-kepler/backward-compatibility"
+            "plugin:@amazon-devices/eslint-plugin-kepler/backward-compatibility",
         ],
     }
     ```
@@ -70,12 +71,15 @@ To use Vega ESLint Plugin, complete the below steps in your Vega App Project.
         extends: ["plugin:@amazon-devices/eslint-plugin-kepler/kepler"],
         rules: {
             "@amazon-devices/kepler/flat-list": "error",
+            "@amazon-devices/kepler/url-constructor-check": "warn",
             "@amazon-devices/kepler/sdl-package-version-check": "warn",
             "@amazon-devices/kepler/sdl-package-version-check-imports": "off",
+            "@amazon-devices/kepler/turbo-module-sdl-native-module-check": "error",
             "@amazon-devices/kepler/api-privileges-check": "error",
             "@amazon-devices/kepler/api-privilege-state-check": "error",
             "@amazon-devices/kepler/backward-compatibility": "error",
-            "@amazon-devices/kepler/backward-compatibility-copy-on-pack": "error"
+            "@amazon-devices/kepler/backward-compatibility-copy-on-pack": "error",
+            "@amazon-devices/kepler/package-migration": "error",
         }
     }
     ```
@@ -89,7 +93,7 @@ To use Vega ESLint Plugin, complete the below steps in your Vega App Project.
         plugins: ["@amazon-devices/eslint-plugin-kepler"],
         rules: {
             "@amazon-devices/kepler/sdl-package-version-check": ["error", { "semverGuidance": "auto" }],
-            "@amazon-devices/kepler/sdl-package-version-check-imports": ["warn", { "semverGuidance": "auto" }]
+            "@amazon-devices/kepler/sdl-package-version-check-imports": ["warn", { "semverGuidance": "auto" }],
         }
     }
     ```
@@ -188,7 +192,7 @@ To use Vega ESLint Plugin, complete the below steps in your Vega App Project.
 
 ## System Distributed Library Rules
 
-The plugin includes two rules for managing system distributed libraries:
+The plugin includes rules for managing system distributed libraries:
 
 ### `@amazon-devices/kepler/sdl-package-version-check`
 Validates that SDL dependencies in `package.json` use proper semantic versioning:
@@ -199,22 +203,95 @@ Validates that SDL dependencies in `package.json` use proper semantic versioning
 ### `@amazon-devices/kepler/sdl-package-version-check-imports`
 Flags imports of system distributed libraries with informational messages to ensure developers understand the implications of using these libraries.
 
+### `@amazon-devices/kepler/turbo-module-sdl-native-module-check`
+Validates that System Distributed Library (SDL) dependencies with native modules are properly declared in the `kepler-system-conf.toml` file for Turbo Modules:
+- Checks that SDL packages are installed in `node_modules`
+- Validates that SDL packages include required `kepler-compatibility.json` files
+- Ensures native module dependencies are declared in `kepler-system-conf.toml`
+- Verifies that installed SDL versions are supported by the compatibility configuration
+
+**Example errors:**
+```
+System Distributed Library (SDL) dependency '@amazon-devices/kepler-example' is not installed in node_modules. Run npm install to resolve.
+```
+```
+System Distributed Library (SDL) dependency '@amazon-devices/kepler-example@1.0.0' requires native module 'ExampleNativeModule' to be declared in kepler-system-conf.toml
+```
+
 ## Backward Compatibility Rules
 
-The plugin includes rules for managing backward compatibility in Kepler library projects:
+The plugin includes rules for managing backward compatibility in Vega library projects:
 
 ### `@amazon-devices/kepler/backward-compatibility`
-Validates that Kepler library projects have proper version compatibility configuration:
+Validates that Vega library projects have proper version compatibility configuration:
 - Checks for the existence of `kepler-compatibility.json` file in the project root
 - Validates that the current package version is listed in the compatibility file
-- Only runs in Brazil repositories with SDL project configuration
+- Only runs in repositories with SDL project configuration
 
 ### `@amazon-devices/kepler/backward-compatibility-copy-on-pack`
 Ensures that the `kepler-compatibility.json` file is included in npm packages:
 - Validates that `kepler-compatibility.json` is listed in the `files` array of `package.json`
-- Only runs in Brazil repositories with SDL project configuration
+- Only runs in repositories with SDL project configuration
 - Required for proper version compatibility validation in published packages
 
+### `@amazon-devices/kepler/backward-compatibility-sysconf-check`
+Validates that SDL library projects properly declare their native modules in the system configuration:
+- Checks that `kepler-system-conf.toml` exists in SDL library projects
+- Validates that the library's native modules are declared in the system configuration
+- Ensures proper integration with the Vega system distributed library architecture
+- Only runs in repositories with SDL project configuration
+
+**Example error:**
+```
+SDL library project must declare native module 'ExampleNativeModule' in kepler-system-conf.toml
+```
+
+## Component Migration Rules
+
+The plugin includes rules for detecting deprecated component usage and suggesting migrations:
+
+### `@amazon-devices/kepler/carousel-deprecated`
+Detects deprecated Carousel V1 usage from @amazon-devices/kepler-ui-components and suggests migration to @amazon-devices/vega-carousel. This rule helps identify code that needs to be updated for better performance and features.
+
+**What it detects:**
+- Carousel imports from `@amazon-devices/kepler-ui-components`
+- Usage of deprecated props on Carousel components (from `@amazon-devices/kepler-ui-components`)
+
+**Deprecated V1 props detected:**
+- Props removed/replaced: `data`, `keyProvider`, `rowId`, `itemDimensions`, `getItemForIndex`, `selectionBorderStrategy`
+- Props renamed: `maxToRenderPerBatch`, `hasTVPreferredFocus`, `trapFocusOnAxis`, `itemPadding`, `itemSelectionExpansion`, `itemScrollDelay`, `focusIndicatorType`, `pinnedFocusOffset`
+
+**Example warnings:**
+```
+Carousel imported from @amazon-devices/kepler-ui-components. Consider migrating to @amazon-devices/vega-carousel for better performance and features.
+Carousel uses deprecated props (data, keyProvider). Consider migrating to @amazon-devices/vega-carousel.
+```
+
+This rule provides the same detection capabilities as the Vega Studio Performance Extension's Carousel detection system, ensuring consistent warnings across different development environments.
+
+### `@amazon-devices/kepler/package-migration`
+Validates that packages requiring migration to system distributed libraries are updated to newer versions:
+- Checks specific packages that have been released as system distributed libraries
+- Provides package version recommendations to make use of SDL released libs
+
+## URL Constructor Check Rule
+
+The plugin includes a rule for managing URL polyfill usage in Kepler projects:
+
+### `@amazon-devices/kepler/url-constructor-check`
+Flags usage of `react-native-url-polyfill` when it's no longer needed in Kepler versions > 2.0.0. Amazon has fixed the URL implementation issues in newer releases of React Native for Vega, making the polyfill unnecessary.
+
+**Rule behavior:**
+- Only activates when Kepler version > 2.0.0 AND `react-native-url-polyfill` is in dependencies
+- Flags imports from `react-native-url-polyfill` package
+- Flags usage of `new URL()` and `new URLSearchParams()` constructors
+- Does nothing if Kepler <= 2.0.0 or polyfill is not a dependency
+
+**Example error:**
+```
+URL polyfill is not needed in this version of "@amazon-devices/react-native-kepler" as Amazon has fixed the issues with the stock React Native implementation.
+```
+
 ## API Privileges Rules
 
 The plugin includes two rules for validating API privilege requirements:
@@ -236,11 +313,57 @@ The rule checks imports of known privilege-requiring packages and ensures the co
 ### `@amazon-devices/kepler/api-privilege-state-check`
 Validates that APIs requiring user privilege prompts have proper SecurityManager implementation. Some APIs require explicit user consent through privilege request dialogs.
 
-**Requirements for APIs with user prompts:**
-- SecurityManager package dependency (`@amazon-devices/security-manager-lib` or `@amazon-devices/security-manager-lib`) in `package.json`
-- SecurityManager method calls (`SecurityManager.getPrivilegeState` and `SecurityManager.requestPrivilege`) in the codebase
-
 **Example error:**
 ```
-The API @amazon-devices/kepler-identifiers requires you prompt the user for privilige acceptance. See the Vega documentation for this API as well as for SecurityManager.
-```
+The API @amazon-devices/kepler-identifiers requires you prompt the user for privilege acceptance. See the Vega documentation for this API as well as for SecurityManager.
+```
+
+### `@amazon-devices/kepler/privilege-request-pattern-check`
+Validates that APIs requiring user prompts properly handle both `PrivilegeState.ALLOW` and `PrivilegeState.DENY` cases when calling `SecurityManager.requestPrivilege()`. This rule ensures developers implement the complete privilege request pattern to prevent runtime errors and improve user experience.
+
+**Supported patterns:**
+- Promise chains with `.then()` callbacks
+- Async/await with if/else or switch statements
+- Nested conditionals and ternary operators
+
+**Example of correct implementation (Promise chain):**
+```typescript
+import { SecurityManager, PrivilegeState } from '@amazon-devices/kepler-security-manager';
+
+SecurityManager.requestPrivilege('com.amazon.device-messaging.privilege.access')
+  .then((state) => {
+    if (state === PrivilegeState.ALLOW) {
+      // Handle permission granted
+      console.log('Permission granted');
+    } else if (state === PrivilegeState.DENY) {
+      // Handle permission denied
+      console.log('Permission denied');
+    }
+  });
+```
+
+**Example of correct implementation (async/await):**
+```typescript
+import { SecurityManager, PrivilegeState } from '@amazon-devices/kepler-security-manager';
+
+const requestPermission = async () => {
+  const state = await SecurityManager.requestPrivilege('com.amazon.device-messaging.privilege.access');
+  if (state === PrivilegeState.ALLOW) {
+    // Handle permission granted
+    console.log('Permission granted');
+  } else if (state === PrivilegeState.DENY) {
+    // Handle permission denied
+    console.log('Permission denied');
+  }
+};
+```
+
+**Example errors:**
+```
+API @amazon-devices/kepler-amazon-device-messaging requires proper privilege request pattern implementation. Your code is missing the DENY case handling for privilege 'com.amazon.device-messaging.privilege.access' in the Promise chain.
+```
+```
+API @amazon-devices/kepler-amazon-device-messaging requires proper privilege request pattern implementation. Your code is missing the ALLOW and DENY case handling for privilege 'com.amazon.device-messaging.privilege.access' in the Promise chain.
+```
+
+The rule automatically applies to APIs configured in `API_PRIV_NEEDED` with `requiresUserPrompt: true`, and provides detailed error messages with code examples and documentation links.