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

package/README.md

@@ -1,51 +1,137 @@
-
 # eslint-plugin-kepler
 
-An ESLint Plugin to suggest Kepler App Development best practices.
+An ESLint Plugin to suggest Vega App Development best practices.
 
 ## Install
-  1. Make sure that you can access kepler NPM repo: See [Start installing SDK](https://developer.amazon.com/docs/kepler/install-kepler-sdk.html).
-  2. Add this package to `devDependencies` section of `package.json`:
+  1. Add this package to `devDependencies` section of `package.json`:
 
-    ```bash
-     npm install --save-dev @amazon-devices/eslint-plugin-kepler
-    ```
+```
+npm install --save-dev @amazon-devices/eslint-plugin-kepler
+```
+
+  2. For package.json validation (System Distributed Library rules), you must install the ESLint JSON parser:
+
+```
+npm install --save-dev jsonc-eslint-parser
+```
+
+  You must also add the `package.json` to the `lint` command line in your `package.json` scripts as shown below.
+```
+"lint": "eslint src test package.json --ext .ts,.tsx --format node_modules/@amazon-devices/eslint-plugin-kepler/dist/formatters/default.js"
+```
 
 ## Set up
 
-To use Kepler ESLint Plugin, complete the below steps in your Kepler App Project.
+To use Vega ESLint Plugin, complete the below steps in your Vega App Project.
 
-1. Configure Kepler rules in the App's eslint config
+1. Configure Vega rules in the App's eslint config
 
-    KeplerESLintPlugin provides default configs that can be directly imported in App projects. To do so, add the following configuration in Kepler App's ESLint config file `.eslintrc.js`.
+    `eslint-plugin-kepler` provides default configs that can be directly imported in App projects. To do so, add the following configuration in Vega App's ESLint config file `.eslintrc.js`.
 
     ``` javascript
     module.exports = {
         plugins: ["@amazon-devices/eslint-plugin-kepler"],
-        extends: ["plugin:@amazon-devices/eslint-plugin-kepler/performance"],
+        extends: ["plugin:@amazon-devices/eslint-plugin-kepler/kepler"],
     }
     ```
 
-    You can also override severity of specific rules according do your use case like below
+    Available configs:
+    - `kepler` - All Kepler rules (performance + system distributed library checks + API privileges + backward compatibility)
+    - `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
+    
+    You can use multiple configs:
     ```javascript
     module.exports = {
         plugins: ["@amazon-devices/eslint-plugin-kepler"],
-        extends: ["plugin:@amazon-devices/eslint-plugin-kepler/performance"],
+        extends: [
+            "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"
+        ],
+    }
+    ```
+
+    Or use the comprehensive config:
+    ```javascript
+    module.exports = {
+        plugins: ["@amazon-devices/eslint-plugin-kepler"],
+        extends: ["plugin:@amazon-devices/eslint-plugin-kepler/kepler"],
+    }
+    ```
+
+    You can also override severity of specific rules:
+    ```javascript
+    module.exports = {
+        plugins: ["@amazon-devices/eslint-plugin-kepler"],
+        extends: ["plugin:@amazon-devices/eslint-plugin-kepler/kepler"],
         rules: {
             "@amazon-devices/kepler/flat-list": "error",
+            "@amazon-devices/kepler/sdl-package-version-check": "warn",
+            "@amazon-devices/kepler/sdl-package-version-check-imports": "off",
+            "@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"
         }
     }
     ```
 
+    ### System Distributed Library Rules Configuration
+
+    The system distributed library rules support a `semverGuidance` configuration option:
+
+    ```javascript
+    module.exports = {
+        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" }]
+        }
+    }
+    ```
+
+    **`semverGuidance` Options:**
+    - `"patch"` - Conservative mode: Only allows patch updates (`~` prefix)
+    - `"minor"` - Allows minor updates (`^` prefix) in addition to patch
+    - `"auto"` (default) - Automatically detects mode based on signatures in the project repo
+
+    The rules for System Distributed Libraries require an ESLint JSON parser to parse the `package.json` and the addition of this parser to the `.eslintrc` (or `.eslintrc.json`). To install the parser (if you did not above):
+
+    ``` bash
+    npm install -D jsonc-eslint-parser
+    ```
+
+    Then, in your ESLint config file, add the JSON parser for `package.json`:
+
+    ``` javascript
+     overrides: [
+    {
+      files: ['**/*.ts', '**/*.tsx'],
+      parser: '@typescript-eslint/parser',
+      parserOptions: {
+        project: './tsconfig.json',
+      },
+    },
+    {
+      files: ['package.json'],
+      parser: 'jsonc-eslint-parser',
+    },
+    ]
+    ```
+
 2. Specify formatter on lint tasks:
     ```javascript
       "scripts": {
             :
-        "lint": "eslint src test --ext .ts,.tsx --format node_modules/@amazon-devices/eslint-plugin-kepler/dist/formatters/default.js",
+        "lint": "eslint src test package.json --ext .ts,.tsx --format node_modules/@amazon-devices/eslint-plugin-kepler/dist/formatters/default.js",
         "lint:fix": "eslint src test --ext .ts,.tsx --fix --format node_modules/@amazon-devices/eslint-plugin-kepler/dist/formatters/default.js",
     ```
 
-3. Run Kepler ESLint Plugin
+3. Run ESLint
 
     ```bash 
     $ npm run lint
@@ -56,16 +142,105 @@ To use Kepler ESLint Plugin, complete the below steps in your Kepler App Project
     ```bash
     $ npm run lint
 
-    > @amazon-devices/kepler-eslint-testapp@0.1.0 lint
+    > @amazon-devices/vega-sample-app@0.1.0 lint
     > eslint src test --ext .ts,.tsx  --format node_modules/@amazon-devices/eslint-plugin-kepler/dist/formatters/default.js
-    
-    
-    /Volumes/workspace/KeplerESLint/src/KeplerESLintTestApp/src/components/Link.tsx
-     32:5 ❌ 'useNativeDriver' property is set to 'false'. Set useNativeDriver to 'true' to run animations on UI thread for better performance. See https://developer.amazon.com/docs/kepler-tv/best_practices.html#animations for more. @amazon-devices/kepler/animated
-     43:5 ⚠️ Subscription must be kept in variable so that it can be cleaned up on the component is detached. See https://developer.amazon.com/docs/kepler-tv/best_practices.html#listeners-event-subscriptions-and-timers for more. @amazon-devices/kepler/check-subscription
-     64:11 ⚠️ FlatList missing props: 'initialNumToRender,windowSize,removeClippedSubviews,maxToRenderPerBatch,updateCellsBatchingPeriod'. FlatList performance is not fully unlocked without these props. See https://developer.amazon.com/docs/kepler-tv/best_practices.html#flatlist for more. @amazon-devices/kepler/flat-list
+
+    /Volumes/workspace/VegaSampleApp/src/components/Link.tsx
+     32:5 ❌ 'useNativeDriver' property is set to 'false'.  Set useNativeDriver to 'true' to run animations on UI thread for better performance.  See https://developer.amazon.com/docs/vega/0.21/best_practices.html#the-animated-library for more. @amazon-devices/kepler/animated
+     43:5 ⚠️ Subscription must be kept in variable so that it can be cleaned up on the component is detached.  See https://developer.amazon.com/docs/vega/0.21/best_practices.html#listeners-event-subscriptions-and-timers for more. @amazon-devices/kepler/check-subscription
+     64:11 ⚠️ FlatList missing props: 'initialNumToRender,windowSize,removeClippedSubviews,maxToRenderPerBatch,updateCellsBatchingPeriod'.  FlatList performance is not fully unlocked without these props.  See https://developer.amazon.com/docs/vega/0.21/best_practices.html#flatlist for more. @amazon-devices/kepler/flat-list
+
+     ⚠️ useReportFullyDrawn() call not found in project.  Add useReportFullyDrawn() in your App to accurately measure Time To Fully Drawn (TTFD) KPI.  See https://developer.amazon.com/docs/vega/0.21/measure-app-kpis.html#fully-drawn-marker for more. @amazon-devices/kepler/detect-report-fully-drawn
+
+     ⚠️ usePreventHideSplashScreen() call not found in project.  Use usePreventHideSplashScreen() to natively render SplashScreen for better App launch performance.  See https://developer.amazon.com/docs/react-native-vega/0.72/splashscreenmanager.html for more. @amazon-devices/kepler/detect-splash-screen
+
+    Summary:
+     ❌ 1 error(s)
+     ⚠️ 4 warning(s)
+
+    Vega ESLint HTML report generated at: /Volumes/workspace/VegaSampleApp/generated/eslint-plugin-kepler/vega-eslint-report.html
     ```
 
-4. Kepler ESLint Plugin generated warnings will show in VS Code Editor when [ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) is installed.
+4. Vega ESLint Plugin generated warnings will show in VS Code Editor when [ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) is installed.
 
     ![](./assets/checkSubscription.png)
+
+5. Seeing errors and warnings in VSCode in the `package.json` requires an additional configuration step. In the VSCode `settings.json` file you will need to add `json` to the following entries, as shown:
+   
+``` javascript
+"eslint.validate": [
+    "javascript",
+    "javascriptreact",
+    "typescript",
+    "typescriptreact",
+    // add the line below
+    "json"
+  ],
+  "eslint.probe": [
+    "javascript",
+    "javascriptreact",
+    "typescript",
+    "typescriptreact",
+    // add the line below
+    "json"
+  ],
+```
+
+## System Distributed Library Rules
+
+The plugin includes two rules for managing system distributed libraries:
+
+### `@amazon-devices/kepler/sdl-package-version-check`
+Validates that SDL dependencies in `package.json` use proper semantic versioning:
+- **Patch only mode** (`semverGuidance: "patch"`): Only allows patch updates using `~` prefix.
+- **Minor and patch mode** (`semverGuidance: "minor"`): Allows minor updates using `^` prefix.
+- **Auto mode** (`semverGuidance: "auto"`): Automatically detects based on signatures in the project repo. This is the default.
+
+### `@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.
+
+## Backward Compatibility Rules
+
+The plugin includes rules for managing backward compatibility in Kepler library projects:
+
+### `@amazon-devices/kepler/backward-compatibility`
+Validates that Kepler 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
+
+### `@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
+- Required for proper version compatibility validation in published packages
+
+## API Privileges Rules
+
+The plugin includes two rules for validating API privilege requirements:
+
+### `@amazon-devices/kepler/api-privileges-check`
+Validates that APIs requiring permissions have the proper entries in the Vega `manifest.toml` file. Some Vega APIs require specific privileges to be declared in the manifest for the app to function correctly.
+
+**Supported privilege types:**
+- `[[needs.privilege]]` - Required privileges that must be present
+- `[[wants.privilege]]` - Optional privileges that should be present
+
+**Example error:**
+```
+Using the APIs in @amazon-devices/kepler-amazon-device-messaging requires the [[needs.privilege]] id="com.amazon.device-messaging.privilege.access" entry in the Vega manifest.toml.
+```
+
+The rule checks imports of known privilege-requiring packages and ensures the corresponding privilege entries exist in your project's `manifest.toml` file.
+
+### `@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.
+```

package/dist/formatters/KeplerReport.js

@@ -0,0 +1,40 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.exportHTMLReport = exportHTMLReport;
+var _eslint = require("eslint");
+var fs = _interopRequireWildcard(require("fs"));
+var path = _interopRequireWildcard(require("path"));
+var _Constants = require("../utils/Constants");
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
+// Copyright 2025 Amazon.com, Inc. or its affiliates. All rights reserved.
+// AMAZON PROPRIETARY/CONFIDENTIAL
+// You may not use this file except in compliance with the terms and conditions
+// set forth in the accompanying LICENSE.TXT file.
+// THESE MATERIALS ARE PROVIDED ON AN "AS IS" BASIS. AMAZON SPECIFICALLY
+// DISCLAIMS, WITH RESPECT TO THESE MATERIALS, ALL WARRANTIES, EXPRESS,
+// IMPLIED, OR STATUTORY, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
+
+const KEPLER_ESLINT_HTML_REPORT_FILE_NAME = path.join(_Constants.KEPLER_ESLINT_OUTPUT_DIR_PATH, 'vega-eslint-report.html');
+
+/**
+ * Exports ESLint results to HTML file.
+ * @param results
+ */
+async function exportHTMLReport(results, outputPath = KEPLER_ESLINT_HTML_REPORT_FILE_NAME) {
+  try {
+    const eslint = new _eslint.ESLint();
+    const htmlFormatter = await eslint.loadFormatter('html');
+    const output = htmlFormatter.format(results);
+    if (!output) {
+      throw new Error('No Results to write');
+    }
+    fs.writeFileSync(outputPath, output, 'utf8');
+    return outputPath;
+  } catch (error) {
+    throw error;
+  }
+}