@salesforce-ux/slds-linter 1.0.0 → 1.0.2-alpha.0

package/README.md

@@ -2,33 +2,29 @@
 
 ## Overview
 
-SLDS Linter provides custom linting rules built for Salesforce Lightning Design System 2 (SLDS 2 beta). Lint your components against SLDS 2 best practices to ensure they adhere to the latest styling standards. 
+SLDS Linter is an installable npm package that analyzes your code against Salesforce Lightning Design System 2 (SLDS 2) rules and offers suggestions to better align your code with SLDS 2 guidelines. SLDS Linter can also apply the suggestions in bulk across your repository and automatically fix your code.
 
-SLDS Linter checks your Aura and Lightning web components' CSS and markup files to identify styling issues that you can fix for SLDS 2 compatibility. SLDS Linter helps you maintain consistent styling and identify common issues with custom Lightning components.
+For detailed information about SLDS Linter, see the [SLDS Linter developer guide](https://developer.salesforce.com/docs/platform/slds-linter/overview).
 
 ## Features
 
-SLDS Linter is a custom-built linting solution based on open source [ESLint](https://eslint.org/) with CSS support. It supports linting for both types of Lightning components. 
+SLDS Linter is a custom-built linting solution based on open-source [ESLint](https://eslint.org/) projects. It supports linting for both types of Lightning components. 
 
-SLDS Linter runs on these types of files.
+- Lightning web components: HTML and Cascading Style Sheet (CSS) files
+- Aura components: Component (CMP) and CSS files
 
-- Lightning web component *.html markup and Cascading Style Sheet (CSS) files
-- Aura component *.cmp markup and CSS files
+Run SLDS Linter in a terminal window or in Visual Studio (VS) Code. We recommend running in VS Code.
 
-You can run SLDS Linter in a terminal window or in Visual Studio (VS) Code. We recommend running in VS Code.
-
-Follow these instructions to integrate SLDS Linter into your project.
+Follow these steps to integrate SLDS Linter into your project.
 
 ---
 
 ## Prerequisites
 
-Install these items if they aren't installed already.
-
-- [VS Code](https://code.visualstudio.com/)
-- [SARIF Viewer](https://marketplace.visualstudio.com/items?itemName=MS-SarifVSCode.sarif-viewer) VS Code extension. This extension enables you to view SLDS Linter violation reports.
-- [Node.js](https://nodejs.org/)
-  - The minimum supported version is **v18.18.0** 
+- Install [VS Code](https://code.visualstudio.com/)
+- Install the [SARIF Viewer](https://marketplace.visualstudio.com/items?itemName=MS-SarifVSCode.sarif-viewer) VS Code extension. With this extension, you can view SLDS Linter violation reports.
+- Install [Node.js](https://nodejs.org/)
+  - The minimum supported version is **v18.4.0**
   - We recommend using the latest [Active LTS](https://nodejs.org/en/about/previous-releases) version of Node.js.  
 
 ## Install SLDS Linter
@@ -62,7 +58,7 @@ Commands:
 
 Run SLDS Linter against your project in the VS Code terminal to check for any violations and generate a SARIF report. This report helps you identify the components you need to update.
 
-In your project root directory, follow these steps.
+In your project root directory, follow these instructions.
 
 1. In your project in VS Code, open Terminal.
 2. Run `npx @salesforce-ux/slds-linter lint`. 
@@ -73,12 +69,12 @@ In your project root directory, follow these steps.
 5. Open the generated `.sarif` report file.
 6. Make a note of how many components SLDS Linter has identified that you must update.
 7. (Optional) To automatically fix validation errors in bulk, run the `lint` command with the `fix` option, `npx @salesforce-ux/slds-linter lint --fix`.
-8. (Optional) To emit the configuration files used by `slds-linter`, run `npx @salesforce-ux/slds-linter emit` in your component source directory. Note that this command defaults to current working directory. These configuration files are discovered by your VS Code ESLint and Stylelint extensions to display squiggly lines in CSS and HTML files when opened in your code editor.  
+8. (Optional) To emit the configuration files used by `slds-linter`, run `npx @salesforce-ux/slds-linter emit` in your component source directory. Note that this command defaults to current working directory. These configuration files are discovered by your VS Code ESLint extension to display squiggly lines in HTML, CSS and CMP files when opened in your code editor.  
 
 
 ### Troubleshoot SARIF Viewer Navigation
 
-If the SARIF viewer doesn't automatically go to the line of code when you click on an error or warning, follow these steps.
+If the SARIF viewer doesn’t automatically go to the line of code when you click on an error or warning, follow these steps.
 
 1. In the SARIF viewer pop-up window, click Locate.
 2. In the file explorer or code editor, locate the file.
@@ -89,7 +85,7 @@ If the SARIF viewer doesn't automatically go to the line of code when you click
 
 Use these commands to run SLDS Linter rules. Review the output violations and fix any issues to uplift your code to SLDS best practices.
 
-- `npx @salesforce-ux/slds-linter lint`. Runs ESlint and Stylelint rules on HTML, CSS, and CMP files.
+- `npx @salesforce-ux/slds-linter lint`. Runs ESLint rules on HTML, CSS, and CMP files.
 - `npx @salesforce-ux/slds-linter report`. Generates a SARIF report for static analysis.
 - `npx @salesforce-ux/slds-linter emit`. Emits the configuration files used by `slds-linter`. Defaults to current directory. 
 
@@ -101,17 +97,16 @@ These options are available on SLDS Linter commands.
 | `-o, --output <path>`    | Output directory for reports (defaults to current directory)                 | `report`                                     |
 | `--fix`                  | Automatically fix problems                                                   | `lint`         |
 | `--config-eslint <path>` | Path to eslint config file                    | `lint`, `report`|
-| `--editor <editor>`      | Editor to open files with (e.g., vscode, atom, sublime). Auto-detects if not specified | `lint` |
-| `--format <type>`        | Output format (sarif, csv). Defaults to sarif | `report` |
+| `--editor <editor>`      | Editor to open files with (e.g., vscode, atom, sublime). Defaults to vscode | `lint` |
 
 To view help for these options, add `--help` to each command. For example, run `npx @salesforce-ux/slds-linter lint --help` to see which options you can use with `lint`.
 
 
 ## Extensions
 
-To enhance your linting and error analysis experience, we recommend that you install these VS Code extensions. These extensions significantly improve your development workflow and make it easier to navigate and address linting issues.
+To enhance your linting and error analysis experience, we recommend that you install these VS Code extensions. This extension significantly improves your development workflow and makes it easier to navigate and address linting issues.
 
-- *[ESLint Extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)*:  Essential for JavaScript, TypeScript, HTML, and CSS linting, it checks your code and flags any violations of the ESLint rules with squiggly lines to show you what to fix.
+- *[ESLint Extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)*:  Essential for JavaScript, TypeScript, HTML, CMP, and CSS linting. It checks your code and highlights any violations of the ESLint rules with squiggly lines.
 
 ## Best Practices
 
@@ -166,119 +161,5 @@ Linting all `.html` and `.cmp` files:
 npx @salesforce-ux/slds-linter lint "**/*.{html,cmp}"
 ```
 
-For any questions or issues, open an issue in this repository.
-
-## Node.js API
-
-The SLDS Linter provides a programmatic API for Node.js applications. This allows you to integrate the linter directly into your build process or other tools without relying on the command-line interface.
-
-### Installation
-
-```bash
-npm install @salesforce-ux/slds-linter
-```
-
-### Usage
-
-```javascript
-import { lint, report } from '@salesforce-ux/slds-linter/executor';
-
-// Lint files in a directory
-const results = await lint({
-  directory: './src',
-  fix: false // Set to true to auto-fix issues where possible
-});
-
-console.log(`Found ${results.length} files with issues`);
-
-// Generate a report
-const reportStream = await report({
-  directory: './src',
-  format: 'sarif'
-}, results);  // Pass the lint results as second parameter
-
-// Process the report stream
-let reportData = '';
-reportStream.on('data', chunk => {
-  reportData += chunk;
-});
-
-reportStream.on('end', () => {
-  console.log('Report:', reportData);
-});
-```
-
-### TypeScript Support
-
-The Node.js API includes comprehensive TypeScript type definitions. You can import both the API functions and their associated types:
-
-```typescript
-// Import from the executor entrypoint
-import {
-  lint,
-  report,
-  type LintConfig,
-  type ReportConfig,
-  type LintResult
-} from '@salesforce-ux/slds-linter/executor';
-
-// Define configuration with typed interface
-const config: LintConfig = {
-  directory: './src',
-  fix: false
-};
-
-// Results will be properly typed
-const results: LintResult[] = await lint(config);
-```
-
-All relevant types (such as `LintConfig`, `ReportConfig`, `LintResult`, etc.) are exported from the executor entrypoint for use in your TypeScript projects.
-
-### API Reference
-
-The Node.js API provides the following methods:
-
-#### `lint(options)`
-
-Lints files for SLDS compliance.
-
-**Options:**
-- `directory`: Path to directory to scan for files to lint
-- `fix`: Boolean indicating whether to automatically fix issues when possible
-- `configStylelint`: Path to custom stylelint configuration file
-- `configEslint`: Path to custom eslint configuration file
-
-**Returns:** Promise resolving to an array of result objects containing linting issues
-
-#### `report(options)`
-
-Generates a report of linting issues.
-
-**Options:**
-- `directory`: Path to directory to scan (if `results` is not provided)
-- `format`: Report format ('sarif' or 'csv')
-- `configStylelint`: Path to custom stylelint configuration file (if `directory` is used)
-- `configEslint`: Path to custom eslint configuration file (if `directory` is used)
-
-**Parameters:**
-- `options`: Configuration options as detailed above
-- `results`: Optional array of lint results (from `lint()`). If not provided, will run lint on the specified directory
-
-**Returns:** A readable stream containing the report data
-
-### Utility Functions
-
-The package also provides utility functions to help with configuration:
-
-#### `normalizeConfig(options)`
-
-Normalizes configuration options with default values. Import from `@salesforce-ux/slds-linter/utils/config-utils`.
-
-**Options:** Same as the options for `lint()` or `report()`
-
-**Returns:** A normalized configuration object with default values applied
-
-### Examples
-
-For complete examples, see the [examples directory](./examples/).
 
+For any questions or issues, open an issue in this repository.

package/build/commands/emit.js

@@ -6,7 +6,41 @@ import {
   DEFAULT_ESLINT_CONFIG_PATH
 } from "../services/config.resolver.js";
 import path from "path";
-import { copyFile } from "fs/promises";
+import { writeFile, readFile } from "fs/promises";
+import sldsPlugin from "@salesforce-ux/eslint-plugin-slds";
+function extractRulesFromConfig(configToExtract) {
+  configToExtract = Array.isArray(configToExtract) ? configToExtract : [configToExtract];
+  const allRules = {};
+  configToExtract.forEach((config) => {
+    if (config.rules) Object.assign(allRules, config.rules);
+  });
+  return Object.keys(allRules).length > 0 ? allRules : null;
+}
+async function loadRuleConfigs() {
+  try {
+    const plugin = sldsPlugin;
+    const configToExtract = plugin.configs?.["flat/recommended"] || plugin.configs?.["recommended"];
+    return extractRulesFromConfig(configToExtract);
+  } catch (error) {
+    return null;
+  }
+}
+function formatRulesForConfig(rules) {
+  return JSON.stringify(rules, null, 4).replace(/\n/g, "\n    ");
+}
+async function generateEnhancedESLintConfig(sourceConfigPath) {
+  const config = await readFile(sourceConfigPath, "utf8");
+  const rules = await loadRuleConfigs();
+  if (rules) {
+    const formattedRules = formatRulesForConfig(rules);
+    return config.replace(
+      /extends:\s*\["@salesforce-ux\/slds\/recommended"\]/,
+      `extends: ["@salesforce-ux/slds/recommended"],
+    rules: ${formattedRules}`
+    );
+  }
+  return config;
+}
 function registerEmitCommand(program) {
   program.command("emit").description("Emits the configuration files used by slds-linter cli").option(
     "-d, --directory <path>",
@@ -17,14 +51,13 @@ function registerEmitCommand(program) {
       const normalizedOptions = normalizeCliOptions(options, {
         configEslint: DEFAULT_ESLINT_CONFIG_PATH
       });
-      const destESLintConfigPath = path.join(
-        normalizedOptions.directory,
-        path.basename(normalizedOptions.configEslint)
-      );
-      await copyFile(normalizedOptions.configEslint, destESLintConfigPath);
+      const enhancedConfig = await generateEnhancedESLintConfig(normalizedOptions.configEslint);
+      const destESLintConfigPath = path.join(normalizedOptions.directory, path.basename(normalizedOptions.configEslint));
+      await writeFile(destESLintConfigPath, enhancedConfig, "utf8");
       Logger.success(chalk.green(`ESLint configuration created at:
 ${destESLintConfigPath}
 `));
+      Logger.info(chalk.cyan("Rules are dynamically loaded based on extends configuration."));
     } catch (error) {
       Logger.error(
         chalk.red(`Failed to emit configuration: ${error.message}`)

package/build/index.js

@@ -19,7 +19,7 @@ process.on("uncaughtException", (error) => {
 var program = new Command();
 program.name("npx @salesforce-ux/slds-linter@latest").showHelpAfterError();
 function registerVersion() {
-  program.description("SLDS Linter CLI tool for linting styles and components").version("1.0.0");
+  program.description("SLDS Linter CLI tool for linting styles and components").version("1.0.2-alpha.0");
 }
 registerLintCommand(program);
 registerReportCommand(program);

package/build/services/config-loader.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Config Loader Service
+ * Sets up NODE_PATH to make CLI's bundled dependencies available to user configs
+ * This allows users to import @salesforce-ux/eslint-plugin-slds without installing it
+ */
+export declare class ConfigLoader {
+    private static nodePath;
+    /**
+     * Initialize module resolution to include CLI's bundled dependencies
+     * This allows user configs to import the plugin directly from CLI's node_modules
+     */
+    static setupBundledDependencies(): void;
+    /**
+     * Get the path to CLI's node_modules (for reference)
+     */
+    static getBundledModulesPath(): string | null;
+}

package/build/services/config-loader.js

@@ -0,0 +1,42 @@
+// src/services/config-loader.ts
+import { createRequire } from "module";
+import { dirname } from "path";
+import { Logger } from "../utils/logger.js";
+var ConfigLoader = class {
+  static nodePath = null;
+  /**
+   * Initialize module resolution to include CLI's bundled dependencies
+   * This allows user configs to import the plugin directly from CLI's node_modules
+   */
+  static setupBundledDependencies() {
+    if (this.nodePath) {
+      return;
+    }
+    try {
+      const require2 = createRequire(import.meta.url);
+      const pluginMainPath = require2.resolve("@salesforce-ux/eslint-plugin-slds");
+      const pluginDir = dirname(pluginMainPath);
+      const pluginRoot = dirname(pluginDir);
+      const scopeDir = dirname(pluginRoot);
+      const cliNodeModules = dirname(scopeDir);
+      const existingPath = process.env.NODE_PATH || "";
+      process.env.NODE_PATH = existingPath ? `${existingPath}:${cliNodeModules}` : cliNodeModules;
+      require2("module").Module._initPaths();
+      this.nodePath = cliNodeModules;
+      Logger.debug(`Using bundled dependencies from: ${cliNodeModules}`);
+      Logger.debug("User configs can now import @salesforce-ux/eslint-plugin-slds");
+    } catch (error) {
+      Logger.error(`Failed to setup bundled dependencies: ${error.message}`);
+      throw new Error(`Could not initialize bundled dependencies: ${error.message}`);
+    }
+  }
+  /**
+   * Get the path to CLI's node_modules (for reference)
+   */
+  static getBundledModulesPath() {
+    return this.nodePath;
+  }
+};
+export {
+  ConfigLoader
+};

package/build/services/config.resolver.js

@@ -137,7 +137,7 @@ var rule_messages_default = {
   },
   "no-hardcoded-values-slds2": {
     "description": "Replace static values with SLDS 2 styling hooks. For more information, look up design tokens on lightningdesignsystem.com.",
-    "url": "https://developer.salesforce.com/docs/platform/slds-linter/guide/reference-rules.html#no-hardcoded-value",
+    "url": "https://developer.salesforce.com/docs/platform/slds-linter/guide/reference-rules.html#no-hardcoded-values-slds2",
     "type": "suggestion",
     "messages": {
       "hardcodedValue": "Consider replacing the {{oldValue}} static value with an SLDS 2 styling hook that has a similar value: {{newValue}}.",
@@ -156,10 +156,10 @@ var rule_messages_default = {
 
 // src/services/config.resolver.ts
 var DEFAULT_ESLINT_CONFIG_PATH = resolvePath("@salesforce-ux/eslint-plugin-slds/config", import.meta);
-var ESLINT_VERSION = "9.35.0";
-var LINTER_CLI_VERSION = "1.0.0";
+var ESLINT_VERSION = "9.36.0";
+var LINTER_CLI_VERSION = "1.0.2-alpha.0";
 var getRuleDescription = (ruleId) => {
-  const ruleIdWithoutNameSpace = `${ruleId}`.replace(/\@salesforce-ux\//, "");
+  const ruleIdWithoutNameSpace = `${ruleId}`.replace(/\@salesforce-ux\//, "").replace(/^slds\//, "");
   return rule_messages_default[ruleIdWithoutNameSpace]?.description || "--";
 };
 export {

package/build/services/lint-runner.js

@@ -3,6 +3,7 @@ import path from "path";
 import { BatchProcessor } from "./batch-processor.js";
 import { Logger } from "../utils/logger.js";
 import { resolveDirName } from "../utils/nodeVersionUtil.js";
+import { ConfigLoader } from "./config-loader.js";
 var LintRunner = class {
   /**
    * Run linting on batches of files
@@ -14,6 +15,7 @@ var LintRunner = class {
         "../workers",
         "eslint.worker.js"
       );
+      ConfigLoader.setupBundledDependencies();
       const workerConfig = {
         configPath: options.configPath,
         fix: options.fix

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce-ux/slds-linter",
-  "version": "1.0.0",
+  "version": "1.0.2-alpha.0",
   "description": "SLDS Linter CLI tool for linting styles and components",
   "keywords": [
     "lightning design system linter",
@@ -29,7 +29,7 @@
   ],
   "bin": "build/index.js",
   "dependencies": {
-    "@salesforce-ux/eslint-plugin-slds": "1.0.0",
+    "@salesforce-ux/eslint-plugin-slds": "1.0.2-alpha.0",
     "@typescript-eslint/eslint-plugin": "^8.36.0",
     "@typescript-eslint/parser": "^8.36.0",
     "chalk": "^4.1.2",