@salesforce-ux/slds-linter 0.0.12-alpha.0 → 0.0.12-alpha.6

package/README.md

@@ -0,0 +1,85 @@
+# SLDS Linter
+
+## Overview
+
+SLDS Linter provides custom linting rules specifically built for Salesforce Lightning Design System 2 (SLDS 2 beta). SLDS Linter is designed to uplift your Cascading Style Sheet (CSS), Lightning Web Component (LWC), and Aura component files to SLDS 2 and to conform to SLDS best practices. SLDS Linter rules allow you to maintain consistent styling and identify common issues when working with Lightning components.
+
+## Features
+
+- Component Linting:
+  The utility supports linting for two types of Salesforce Lightning components:
+
+  - LWC and Aura components.
+    LWC Components (.html): Linting is applied to Lightning Web Components.
+  - Aura Components (.cmp): Linting is applied to Aura Components.
+
+* Stylelint for CSS Files:
+  Stylelint rules are applied to .css files associated with the components. This ensures consistent styling practices are followed throughout the project.
+
+Follow the below instructions to integrate SLDS Linter into your project.
+
+---
+
+## Set Up SLDS Linter in Your Component Repository
+
+### Pre-requisites
+
+SLDS Linter CLI tool works best with the [Active LTS](https://nodejs.org/en/about/previous-releases) version of Node.js.  
+
+#### **Minimum Required Node.js Version**  
+- The minimum supported Node.js version is **v20.18.3**.  
+- We recommend using the latest **Active LTS** release for the best performance and compatibility.  
+
+
+### Command-Line Interface (CLI)
+
+To see what all options does slds-linter provide please run `npx @salesforce-ux/slds-linter@latest --help` which gives the below output.
+For the first time, it will ask to install the package. Please reply with `y` as yes to install the package.
+
+```
+Usage:  npx @salesforce-ux/slds-linter@latest [options] [command]
+
+A CLI tool for linting styles and components
+
+Options:
+-V, --version              output the version number
+-h, --help                 display help for command
+
+Commands:
+lint:styles [options]      Run stylelint on all style files
+lint:components [options]  Run eslint on all markup files
+lint [options]             Run both style and component linting
+report [options]           Generate SARIF report from linting results
+help [command]             display help for command
+```
+
+- `npx @salesforce-ux/slds-linter lint` - Runs the ESlint and Stylelint rules on your HTML/CSS/CMP files and outputs issues.
+- `npx @salesforce-ux/slds-linter lint:styles` - Runs the Stylelint rules on your CSS files and outputs issues.
+- `npx @salesforce-ux/slds-linter lint:components` - Runs the ESlint rules on your HTML/CMP files and outputs issues.
+- `npx @salesforce-ux/slds-linter fix`: Attempts to automatically fix violations.
+- `npx @salesforce-ux/slds-linter report`: Generates a SARIF report for static analysis.
+
+#### Options available with each command
+
+| **Options**              | **Description**                                                              | **Availability**                           |
+| ------------------------ | ---------------------------------------------------------------------------- | ------------------------------------------ |
+| `-d, --directory <path>` | Target directory to scan (defaults to current directory)                     | lint, lint:styles, lint:components, report |
+| `-o, --output <path>`    | Output directory for reports (defaults to current directory)                 | report                                     |
+| `--fix`                  | Automatically fix problems                                                   | lint, lint:styles, lint:components         |
+| `--config <path>`        | Path to eslint/stylelint config file', DEFAULT_ESLINT_CONFIG_PATH            | lint:styles, lint:components               |
+| `--config-style <path>`  | PPath to stylelint config file', DEFAULT_STYLELINT_CONFIG_PATH               | lint                                       |
+| `--config-eslint <path>` | Path to eslint config file', DEFAULT_ESLINT_CONFIG_PATH                      | lint                                       |
+| `--editor <editor>`      | Editor to open files with (e.g., vscode, atom, sublime). Defaults to vscode | lint,lint:styles, lint:components          |
+
+
+These options can also be visualised by using `--help` with each command. For example: Running `slds-linter lint --help` will give the options which can be used along with `lint`.
+
+#### Detailed Steps
+
+1. Run `npx @salesforce-ux/slds-linter lint` to see the lint output on terminal. For specific files, you can go ahead with either `npx @salesforce-ux/slds-linter lint:styles` for lint errors within css files or `npx @salesforce-ux/slds-linter lint:components` for lint errors within html/cmp files. To run the linting only on a specific folder, use the option `-d` to specify the directory to be linted.
+2. To run SLDS Linter, in Terminal, run `npx @salesforce-ux/slds-linter report` to generate a Sarif report in the project root directory. To run it on a different directory, use `-d` to run the report on that directory. For output, `-o` can be used to specify a different output folder for the genreated sarif. It will be named as `slds-linter-report.sarif`.
+3. Open the generated Sarif file.
+4. Make a note of how many components SLDS Linter has identified that you must update.
+5. Run `npx @salesforce-ux/slds-linter fix` to automatically fix validation errors in bulk.
+
+For any questions or issues, feel free to reach out to the maintainers or open an issue in the repository.

package/build/commands/lint-components.js

@@ -8,11 +8,13 @@ import { ComponentFilePatterns } from "../services/file-patterns.js";
 import { LintRunner } from "../services/lint-runner.js";
 import { DEFAULT_ESLINT_CONFIG_PATH } from "../services/config.resolver.js";
 function registerLintComponentsCommand(program) {
-  program.command("lint:components").description("Run eslint on all markup files").option("-d, --directory <path>", "Target directory to scan (defaults to current directory)").option("--fix", "Automatically fix problems").option("--config <path>", "Path to eslint config file", DEFAULT_ESLINT_CONFIG_PATH).option("--editor <editor>", "Editor to open files with (vscode, atom, sublime). Defaults to vscode", "vscode").action(async (options) => {
+  program.command("lint:components").description("Run eslint on all markup files").option("-d, --directory <path>", "Target directory to scan (defaults to current directory)").option("--fix", "Automatically fix problems").option("--config <path>", "Path to eslint config file").option("--editor <editor>", "Editor to open files with (vscode, atom, sublime). Defaults to vscode", "vscode").action(async (options) => {
     const startTime = Date.now();
     try {
       Logger.info(chalk.blue("Starting linting of component files..."));
-      const normalizedOptions = normalizeCliOptions(options);
+      const normalizedOptions = normalizeCliOptions(options, {
+        config: DEFAULT_ESLINT_CONFIG_PATH
+      });
       Logger.info(chalk.blue("Scanning for files..."));
       const fileBatches = await FileScanner.scanFiles(normalizedOptions.directory, {
         patterns: ComponentFilePatterns,

package/build/commands/lint-styles.js

@@ -8,11 +8,13 @@ import { StyleFilePatterns } from "../services/file-patterns.js";
 import { LintRunner } from "../services/lint-runner.js";
 import { DEFAULT_STYLELINT_CONFIG_PATH } from "../services/config.resolver.js";
 function registerLintStylesCommand(program) {
-  program.command("lint:styles").description("Run stylelint on all style files").option("-d, --directory <path>", "Target directory to scan (defaults to current directory)").option("--fix", "Automatically fix problems").option("--config <path>", "Path to stylelint config file", DEFAULT_STYLELINT_CONFIG_PATH).option("--editor <editor>", "Editor to open files with (vscode, atom, sublime). Defaults to vscode", "vscode").action(async (options) => {
+  program.command("lint:styles").description("Run stylelint on all style files").option("-d, --directory <path>", "Target directory to scan (defaults to current directory)").option("--fix", "Automatically fix problems").option("--config <path>", "Path to stylelint config file").option("--editor <editor>", "Editor to open files with (vscode, atom, sublime). Defaults to vscode", "vscode").action(async (options) => {
     const startTime = Date.now();
     try {
       Logger.info(chalk.blue("Starting linting of style files..."));
-      const normalizedOptions = normalizeCliOptions(options);
+      const normalizedOptions = normalizeCliOptions(options, {
+        configStyle: DEFAULT_STYLELINT_CONFIG_PATH
+      });
       Logger.info(chalk.blue("Scanning for style files..."));
       const fileBatches = await FileScanner.scanFiles(normalizedOptions.directory, {
         patterns: StyleFilePatterns,

package/build/commands/lint.js

@@ -10,11 +10,14 @@ import { StyleFilePatterns, ComponentFilePatterns } from "../services/file-patte
 import { LintRunner } from "../services/lint-runner.js";
 import { DEFAULT_ESLINT_CONFIG_PATH, DEFAULT_STYLELINT_CONFIG_PATH } from "../services/config.resolver.js";
 function registerLintCommand(program) {
-  program.command("lint").description("Run both style and component linting").option("-d, --directory <path>", "Target directory to scan (defaults to current directory)").option("--fix", "Automatically fix problems").option("--config-style <path>", "Path to stylelint config file", DEFAULT_STYLELINT_CONFIG_PATH).option("--config-eslint <path>", "Path to eslint config file", DEFAULT_ESLINT_CONFIG_PATH).option("--editor <editor>", "Editor to open files with (e.g., vscode, atom, sublime). Defaults to vscode", "vscode").action(async (options) => {
+  program.command("lint").description("Run both style and component linting").option("-d, --directory <path>", "Target directory to scan (defaults to current directory)").option("--fix", "Automatically fix problems").option("--config-style <path>", "Path to stylelint config file").option("--config-eslint <path>", "Path to eslint config file").option("--editor <editor>", "Editor to open files with (e.g., vscode, atom, sublime). Defaults to vscode", "vscode").action(async (options) => {
     const startTime = Date.now();
     try {
       Logger.info(chalk.blue("Starting full linting process..."));
-      const normalizedOptions = normalizeCliOptions(options);
+      const normalizedOptions = normalizeCliOptions(options, {
+        configStyle: DEFAULT_STYLELINT_CONFIG_PATH,
+        configEslint: DEFAULT_ESLINT_CONFIG_PATH
+      });
       Logger.info(chalk.blue("\nScanning style files..."));
       const styleFileBatches = await FileScanner.scanFiles(normalizedOptions.directory, {
         patterns: StyleFilePatterns,

package/build/commands/report.js

@@ -9,10 +9,13 @@ import { LintRunner } from "../services/lint-runner.js";
 import { ReportGenerator } from "../services/report-generator.js";
 import { DEFAULT_ESLINT_CONFIG_PATH, DEFAULT_STYLELINT_CONFIG_PATH, LINTER_CLI_VERSION } from "../services/config.resolver.js";
 function registerReportCommand(program) {
-  program.command("report").description("Generate SARIF report from linting results").option("-d, --directory <path>", "Target directory to scan (defaults to current directory)").option("-o, --output <path>", "Output directory for reports (defaults to current directory)").option("--config-style <path>", "Path to stylelint config file", DEFAULT_STYLELINT_CONFIG_PATH).option("--config-eslint <path>", "Path to eslint config file", DEFAULT_ESLINT_CONFIG_PATH).action(async (options) => {
+  program.command("report").description("Generate SARIF report from linting results").option("-d, --directory <path>", "Target directory to scan (defaults to current directory)").option("-o, --output <path>", "Output directory for reports (defaults to current directory)").option("--config-style <path>", "Path to stylelint config file").option("--config-eslint <path>", "Path to eslint config file").action(async (options) => {
     const spinner = ora("Starting report generation...").start();
     try {
-      const normalizedOptions = normalizeCliOptions(options);
+      const normalizedOptions = normalizeCliOptions(options, {
+        configStyle: DEFAULT_STYLELINT_CONFIG_PATH,
+        configEslint: DEFAULT_ESLINT_CONFIG_PATH
+      });
       spinner.text = "Running styles linting...";
       const styleFileBatches = await FileScanner.scanFiles(normalizedOptions.directory, {
         patterns: StyleFilePatterns,

package/build/index.js

@@ -7,6 +7,7 @@ import { registerLintComponentsCommand } from "./commands/lint-components.js";
 import { registerLintCommand } from "./commands/lint.js";
 import { registerReportCommand } from "./commands/report.js";
 import { Logger } from "./utils/logger.js";
+import pkg from "../package.json" with { type: "json" };
 process.on("unhandledRejection", (error) => {
   Logger.error(`Unhandled rejection: ${error}`);
   process.exit(1);
@@ -16,7 +17,7 @@ process.on("uncaughtException", (error) => {
   process.exit(1);
 });
 var program = new Command();
-program.name("linting-cli").description("A CLI tool for linting styles and components").version("1.0.0");
+program.name("npx @salesforce-ux/slds-linter@latest").description(pkg.description).version(pkg.version).showHelpAfterError();
 registerLintStylesCommand(program);
 registerLintComponentsCommand(program);
 registerLintCommand(program);

package/build/services/__tests__/file-scanner.test.js

@@ -3,8 +3,11 @@ import path from "path";
 import { FileScanner } from "../file-scanner.js";
 import { StyleFilePatterns } from "../file-patterns.js";
 import { mkdir, writeFile, rm } from "fs/promises";
+import { fileURLToPath } from "url";
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = path.dirname(__filename);
 describe("FileScanner", () => {
-  const testDir = path.join(import.meta.dirname, "fixtures");
+  const testDir = path.join(__dirname, "fixtures");
   beforeAll(async () => {
     await mkdir(testDir, { recursive: true });
     await writeFile(

package/build/services/report-generator.js

@@ -95,7 +95,7 @@ var ReportGenerator = class {
         startLine: error.line,
         startColumn: error.column,
         endLine: error.line,
-        endColumn: error.column + 1
+        endColumn: error.endColumn
       });
       runBuilder.addResult(resultBuilder);
     }
@@ -108,7 +108,7 @@ var ReportGenerator = class {
         startLine: warning.line,
         startColumn: warning.column,
         endLine: warning.line,
-        endColumn: warning.column + 1
+        endColumn: warning.endColumn
       });
       runBuilder.addResult(resultBuilder);
     }

package/build/types/index.d.ts

@@ -12,6 +12,7 @@ export interface LintResult {
     errors: Array<{
         line: number;
         column: number;
+        endColumn: number;
         message: string;
         ruleId: string;
         severity: number;
@@ -19,6 +20,7 @@ export interface LintResult {
     warnings: Array<{
         line: number;
         column: number;
+        endColumn: number;
         message: string;
         ruleId: string;
         severity: number;
@@ -35,12 +37,14 @@ export interface WorkerResult {
     warnings?: Array<{
         line: number;
         column: number;
+        endColumn: number;
         message: string;
         ruleId: string;
     }>;
     errors?: Array<{
         line: number;
         column: number;
+        endColumn: number;
         message: string;
         ruleId: string;
     }>;

package/build/utils/cli-args.d.ts

@@ -1,3 +1,3 @@
 import { CliOptions } from '../types';
 export declare function validateAndNormalizePath(inputPath?: string): string;
-export declare function normalizeCliOptions(options: CliOptions): Required<CliOptions>;
+export declare function normalizeCliOptions(options: CliOptions, defultOptions?: Partial<CliOptions>): Required<CliOptions>;

package/build/utils/cli-args.js

@@ -13,15 +13,16 @@ function validateAndNormalizePath(inputPath) {
     throw new Error(`Invalid path: ${inputPath}`);
   }
 }
-function normalizeCliOptions(options) {
+function normalizeCliOptions(options, defultOptions = {}) {
   return {
+    fix: false,
+    editor: "vscode",
+    config: "",
+    configStyle: "",
+    configEslint: "",
+    ...defultOptions,
     directory: validateAndNormalizePath(options.directory),
-    output: validateAndNormalizePath(options.output),
-    fix: options.fix || false,
-    config: options.config || "",
-    configStyle: options.configStyle || "",
-    configEslint: options.configEslint || "",
-    editor: options.editor || "vscode"
+    output: validateAndNormalizePath(options.output)
   };
 }
 export {

package/build/workers/eslint.worker.js

@@ -23,12 +23,14 @@ var ESLintWorker = class extends BaseWorker {
         warnings: fileResult.messages.filter((msg) => msg.severity === 1).map((warning) => ({
           line: warning.line,
           column: warning.column,
+          endColumn: warning.endColumn,
           message: warning.message,
           ruleId: warning.ruleId || "unknown"
         })),
         errors: fileResult.messages.filter((msg) => msg.severity === 2).map((error) => ({
           line: error.line,
           column: error.column,
+          endColumn: error.endColumn,
           message: error.message,
           ruleId: error.ruleId || "unknown"
         }))

package/build/workers/stylelint.worker.js

@@ -18,6 +18,7 @@ var StylelintWorker = class extends BaseWorker {
         warnings: fileResult.warnings.map((warning) => ({
           line: warning.line,
           column: warning.column,
+          endColumn: warning.endColumn,
           message: warning.text,
           ruleId: warning.rule
         })),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce-ux/slds-linter",
-  "version": "0.0.12-alpha.0",
+  "version": "0.0.12-alpha.6",
   "description": "SLDS CLI tool for linting styles and components",
   "keywords": [
     "lint",
@@ -22,8 +22,8 @@
     "slds-linter": "./build/index.js"
   },
   "dependencies": {
-    "@salesforce-ux/eslint-plugin-slds": "0.0.12-alpha.0",
-    "@salesforce-ux/stylelint-plugin-slds": "0.0.12-alpha.0",
+    "@salesforce-ux/eslint-plugin-slds": "0.0.12-alpha.6",
+    "@salesforce-ux/stylelint-plugin-slds": "0.0.12-alpha.6",
     "@typescript-eslint/eslint-plugin": "^5.0.0",
     "@typescript-eslint/parser": "^5.0.0",
     "chalk": "^4.1.2",
@@ -43,5 +43,8 @@
   "bugs": {
     "url": "https://github.com/yourusername/linting-cli/issues"
   },
-  "homepage": "https://github.com/yourusername/linting-cli#readme"
+  "homepage": "https://github.com/yourusername/linting-cli#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  }
 }