@salesforce-ux/slds-linter 0.1.9 → 0.2.0-alpha.2

package/README.md

@@ -4,7 +4,7 @@
 
 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 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.
+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.
 
 ## Features
 
@@ -78,7 +78,7 @@ In your project root directory, follow these steps.
 
 ### 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.
@@ -103,6 +103,7 @@ These options are available on SLDS Linter commands.
 | `--config-stylelint <path>`  | Path to stylelint config file             | `lint`, `report`|
 | `--config-eslint <path>` | Path to eslint config file                    | `lint`, `report`|
 | `--editor <editor>`      | Editor to open files with (e.g., vscode, atom, sublime). Defaults to vscode | `lint` |
+| `--format <type>`        | Output format (sarif, csv). Defaults to sarif | `report` |
 
 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`.
 
@@ -167,4 +168,93 @@ 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.
+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);
+});
+```
+
+### 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/).
+

package/build/commands/emit.js

@@ -1,7 +1,7 @@
 // src/commands/emit.ts
 import chalk from "chalk";
 import { Logger } from "../utils/logger.js";
-import { normalizeCliOptions } from "../utils/cli-args.js";
+import { normalizeCliOptions } from "../utils/config-utils.js";
 import {
   DEFAULT_ESLINT_CONFIG_PATH,
   DEFAULT_STYLELINT_CONFIG_PATH

package/build/commands/lint.js

@@ -2,12 +2,10 @@
 import { Option } from "commander";
 import chalk from "chalk";
 import { printLintResults } from "../utils/lintResultsUtil.js";
-import { normalizeCliOptions, nomalizeDirPath } from "../utils/cli-args.js";
+import { normalizeCliOptions, normalizeDirectoryPath } from "../utils/config-utils.js";
 import { Logger } from "../utils/logger.js";
-import { FileScanner } from "../services/file-scanner.js";
-import { StyleFilePatterns, ComponentFilePatterns } from "../services/file-patterns.js";
-import { LintRunner } from "../services/lint-runner.js";
 import { DEFAULT_ESLINT_CONFIG_PATH, DEFAULT_STYLELINT_CONFIG_PATH } from "../services/config.resolver.js";
+import { lint } from "../executor/index.js";
 function registerLintCommand(program) {
   program.command("lint").aliases(["lint:styles", "lint:components"]).configureHelp({
     commandUsage: () => {
@@ -22,54 +20,30 @@ function registerLintCommand(program) {
         configEslint: DEFAULT_ESLINT_CONFIG_PATH
       });
       if (directory) {
-        normalizedOptions.directory = nomalizeDirPath(directory);
+        normalizedOptions.directory = normalizeDirectoryPath(directory);
       } else if (options.directory) {
         Logger.newLine().warning(chalk.yellow(
           `WARNING: --directory, -d option is deprecated. Supply as argument instead.
             Example: npx @salesforce-ux/slds-linter lint ${options.directory}`
         ));
       }
-      Logger.newLine().info(chalk.blue("Scanning style files..."));
-      const styleFileBatches = await FileScanner.scanFiles(normalizedOptions.directory, {
-        patterns: StyleFilePatterns,
-        batchSize: 100
-      });
-      const totalStyleFiles = styleFileBatches.reduce((sum, batch) => sum + batch.length, 0);
-      Logger.info(chalk.blue(`Found ${totalStyleFiles} style file(s). Running stylelint...`));
-      Logger.newLine().info(chalk.blue(`Running stylelint${normalizedOptions.fix ? " with autofix" : ""}...`));
-      const styleResults = await LintRunner.runLinting(styleFileBatches, "style", {
-        fix: normalizedOptions.fix,
-        configPath: normalizedOptions.configStylelint
-      });
-      printLintResults(styleResults, normalizedOptions.editor);
-      const styleErrorCount = styleResults.reduce((sum, r) => sum + r.errors.length, 0);
-      const styleWarningCount = styleResults.reduce((sum, r) => sum + r.warnings.length, 0);
-      Logger.newLine().info(chalk.blue("Scanning component files..."));
-      const componentFileBatches = await FileScanner.scanFiles(normalizedOptions.directory, {
-        patterns: ComponentFilePatterns,
-        batchSize: 100
-      });
-      const totalComponentFiles = componentFileBatches.reduce((sum, batch) => sum + batch.length, 0);
-      Logger.info(chalk.blue(`Found ${totalComponentFiles} component file(s). Running eslint...
-`));
-      Logger.info(chalk.blue(`Running linting${normalizedOptions.fix ? " with autofix" : ""}...`));
-      const componentResults = await LintRunner.runLinting(componentFileBatches, "component", {
+      const lintResults = await lint({
+        directory: normalizedOptions.directory,
         fix: normalizedOptions.fix,
-        configPath: normalizedOptions.configEslint
+        configStylelint: normalizedOptions.configStylelint,
+        configEslint: normalizedOptions.configEslint
       });
-      printLintResults(componentResults, normalizedOptions.editor);
-      const componentErrorCount = componentResults.reduce((sum, r) => sum + r.errors.length, 0);
-      const componentWarningCount = componentResults.reduce((sum, r) => sum + r.warnings.length, 0);
-      const totalErrors = styleErrorCount + componentErrorCount;
-      const totalWarnings = styleWarningCount + componentWarningCount;
+      printLintResults(lintResults, normalizedOptions.editor);
+      const errorCount = lintResults.reduce((sum, r) => sum + r.errors.length, 0);
+      const warningCount = lintResults.reduce((sum, r) => sum + r.warnings.length, 0);
       Logger.info(
         `
-${chalk.red(`${totalErrors} error${totalErrors !== 1 ? "s" : ""}`)}  ${chalk.yellow(`${totalWarnings} warning${totalWarnings !== 1 ? "s" : ""}`)}`
+${chalk.red(`${errorCount} error${errorCount !== 1 ? "s" : ""}`)}  ${chalk.yellow(`${warningCount} warning${warningCount !== 1 ? "s" : ""}`)}`
       );
       const elapsedTime = ((Date.now() - startTime) / 1e3).toFixed(2);
       Logger.success(chalk.green(`
 Linting completed in ${elapsedTime} seconds.`));
-      process.exit(totalErrors > 0 ? 1 : 0);
+      process.exit(errorCount > 0 ? 1 : 0);
     } catch (error) {
       Logger.error(chalk.red(`Failed to complete linting: ${error.message}`));
       process.exit(1);

package/build/commands/report.js

@@ -3,13 +3,11 @@ import { Option } from "commander";
 import path from "path";
 import ora from "ora";
 import chalk from "chalk";
-import { nomalizeDirPath, normalizeCliOptions } from "../utils/cli-args.js";
+import fs from "fs";
+import { normalizeCliOptions, normalizeDirectoryPath } from "../utils/config-utils.js";
 import { Logger } from "../utils/logger.js";
-import { FileScanner } from "../services/file-scanner.js";
-import { StyleFilePatterns, ComponentFilePatterns } from "../services/file-patterns.js";
-import { LintRunner } from "../services/lint-runner.js";
-import { ReportGenerator, CsvReportGenerator } from "../services/report-generator.js";
-import { DEFAULT_ESLINT_CONFIG_PATH, DEFAULT_STYLELINT_CONFIG_PATH, LINTER_CLI_VERSION } from "../services/config.resolver.js";
+import { DEFAULT_ESLINT_CONFIG_PATH, DEFAULT_STYLELINT_CONFIG_PATH } from "../services/config.resolver.js";
+import { report, lint } from "../executor/index.js";
 function registerReportCommand(program) {
   program.command("report").description("Generate report from linting results").argument("[directory]", "Target directory to scan (defaults to current directory). Support glob patterns").addOption(new Option("-d, --directory <path>", "Target directory to scan (defaults to current directory). Support glob patterns").hideHelp()).option("-o, --output <path>", "Output directory for reports (defaults to current directory)").option("--config-stylelint <path>", "Path to stylelint config file").option("--config-eslint <path>", "Path to eslint config file").addOption(new Option("--format <type>", "Output format").choices(["sarif", "csv"]).default("sarif")).action(async (directory, options) => {
     const spinner = ora("Starting report generation...");
@@ -19,7 +17,7 @@ function registerReportCommand(program) {
         configEslint: DEFAULT_ESLINT_CONFIG_PATH
       });
       if (directory) {
-        normalizedOptions.directory = nomalizeDirPath(directory);
+        normalizedOptions.directory = normalizeDirectoryPath(directory);
       } else if (options.directory) {
         Logger.newLine().warning(chalk.yellow(
           `WARNING: --directory, -d option is deprecated. Supply as argument instead.
@@ -27,41 +25,33 @@ function registerReportCommand(program) {
         ));
       }
       spinner.start();
-      spinner.text = "Running styles linting...";
-      const styleFileBatches = await FileScanner.scanFiles(normalizedOptions.directory, {
-        patterns: StyleFilePatterns,
-        batchSize: 100
+      const reportFormat = normalizedOptions.format?.toLowerCase() || "sarif";
+      const lintResults = await lint({
+        directory: normalizedOptions.directory,
+        configStylelint: normalizedOptions.configStylelint,
+        configEslint: normalizedOptions.configEslint
       });
-      const styleResults = await LintRunner.runLinting(styleFileBatches, "style", {
-        configPath: normalizedOptions.configStylelint
-      });
-      spinner.text = "Running components linting...";
-      const componentFileBatches = await FileScanner.scanFiles(normalizedOptions.directory, {
-        patterns: ComponentFilePatterns,
-        batchSize: 100
-      });
-      const componentResults = await LintRunner.runLinting(componentFileBatches, "component", {
-        configPath: normalizedOptions.configEslint
-      });
-      const reportFormat = options.format.toLowerCase();
+      const reportStream = await report({
+        format: reportFormat
+      }, lintResults);
+      let outputFilePath;
       if (reportFormat === "sarif") {
-        spinner.text = "Generating SARIF report...";
-        const combinedReportPath = path.join(normalizedOptions.output, "slds-linter-report.sarif");
-        await ReportGenerator.generateSarifReport([...styleResults, ...componentResults], {
-          outputPath: combinedReportPath,
-          toolName: "slds-linter",
-          toolVersion: LINTER_CLI_VERSION
-        });
-        Logger.success(`SARIF report generated: ${combinedReportPath}
-`);
+        spinner.text = "Saving SARIF report...";
+        outputFilePath = path.join(normalizedOptions.output, "slds-linter-report.sarif");
       } else if (reportFormat === "csv") {
-        spinner.text = "Generating CSV report...";
-        const csvReportPath = await CsvReportGenerator.generate([...styleResults, ...componentResults]);
-        Logger.success(`CSV report generated: ${csvReportPath}
-`);
+        spinner.text = "Saving CSV report...";
+        outputFilePath = path.join(normalizedOptions.output, "slds-linter-report.csv");
       } else {
         throw new Error(`Invalid format: ${reportFormat}. Supported formats: sarif, csv`);
       }
+      const writeStream = fs.createWriteStream(outputFilePath);
+      reportStream.pipe(writeStream);
+      await new Promise((resolve, reject) => {
+        writeStream.on("finish", resolve);
+        writeStream.on("error", reject);
+      });
+      Logger.success(`${reportFormat.toUpperCase()} report generated: ${outputFilePath}
+`);
       spinner.succeed("Report generation completed");
       process.exit(0);
     } catch (error) {

package/build/executor/__tests__/executor.test.js

@@ -0,0 +1,189 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/executor/index.ts
+var executor_exports = {};
+__export(executor_exports, {
+  lint: () => lint,
+  report: () => report
+});
+import { Readable } from "stream";
+import { FileScanner } from "../services/file-scanner.js";
+import { LintRunner } from "../services/lint-runner.js";
+import { StyleFilePatterns, ComponentFilePatterns } from "../services/file-patterns.js";
+import { ReportGenerator, CsvReportGenerator } from "../services/report-generator.js";
+import { LINTER_CLI_VERSION } from "../services/config.resolver.js";
+import { normalizeCliOptions } from "../utils/config-utils.js";
+import { Logger } from "../utils/logger.js";
+async function lint(config) {
+  try {
+    Logger.debug("Starting linting with Node API");
+    const normalizedConfig = normalizeCliOptions(config, {}, true);
+    const styleFiles = await FileScanner.scanFiles(normalizedConfig.directory, {
+      patterns: StyleFilePatterns,
+      batchSize: 100
+    });
+    const componentFiles = await FileScanner.scanFiles(normalizedConfig.directory, {
+      patterns: ComponentFilePatterns,
+      batchSize: 100
+    });
+    const lintOptions = {
+      fix: normalizedConfig.fix,
+      configPath: normalizedConfig.configStylelint
+    };
+    const styleResults = await LintRunner.runLinting(styleFiles, "style", {
+      ...lintOptions,
+      configPath: normalizedConfig.configStylelint
+    });
+    const componentResults = await LintRunner.runLinting(componentFiles, "component", {
+      ...lintOptions,
+      configPath: normalizedConfig.configEslint
+    });
+    const combinedResults = [...styleResults, ...componentResults];
+    return combinedResults;
+  } catch (error) {
+    const errorMessage = `Linting failed: ${error.message}`;
+    Logger.error(errorMessage);
+    throw new Error(errorMessage);
+  }
+}
+async function report(config, results) {
+  try {
+    Logger.debug("Starting report generation with Node API");
+    const normalizedConfig = normalizeCliOptions(config, {}, true);
+    const format = normalizedConfig.format || "sarif";
+    const lintResults = results || await lint({
+      directory: normalizedConfig.directory,
+      configStylelint: normalizedConfig.configStylelint,
+      configEslint: normalizedConfig.configEslint
+    });
+    switch (format) {
+      case "sarif":
+        return ReportGenerator.generateSarifReportStream(lintResults, {
+          toolName: "slds-linter",
+          toolVersion: LINTER_CLI_VERSION
+        });
+      case "csv":
+        const csvString = CsvReportGenerator.generateCsvString(lintResults);
+        const csvStream = new Readable();
+        csvStream.push(csvString);
+        csvStream.push(null);
+        return csvStream;
+      default:
+        const errorMessage = `Unsupported format: ${format}`;
+        Logger.error(errorMessage);
+        throw new Error(errorMessage);
+    }
+  } catch (error) {
+    const errorMessage = `Report generation failed: ${error.message}`;
+    Logger.error(errorMessage);
+    throw new Error(errorMessage);
+  }
+}
+var init_executor = __esm({
+  "src/executor/index.ts"() {
+  }
+});
+
+// src/executor/__tests__/executor.test.ts
+import { lint as lint2, report as report2 } from "../index.js";
+import { LintRunner as LintRunner2 } from "../../services/lint-runner.js";
+import { FileScanner as FileScanner2 } from "../../services/file-scanner.js";
+import { Readable as Readable2 } from "stream";
+import { jest } from "@jest/globals.js";
+var mockLintResult = {
+  filePath: "file1.css",
+  errors: [{ line: 1, column: 1, endColumn: 10, message: "Test error", ruleId: "test-rule", severity: 2 }],
+  warnings: []
+};
+jest.mock("../../services/lint-runner", () => {
+  return {
+    LintRunner: {
+      runLinting: jest.fn().mockImplementation(() => {
+        return Promise.resolve([mockLintResult]);
+      })
+    }
+  };
+});
+jest.mock("../../services/file-scanner", () => {
+  return {
+    FileScanner: {
+      scanFiles: jest.fn().mockImplementation(() => {
+        return Promise.resolve([["file1.css"]]);
+      })
+    }
+  };
+});
+jest.mock("fs/promises");
+xdescribe("Executor functions", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+  describe("lint", () => {
+    it("should scan directory and run linting when no files are provided", async () => {
+      const config = {
+        directory: "./src",
+        fix: true
+      };
+      const results = await lint2(config);
+      expect(FileScanner2.scanFiles).toHaveBeenCalledTimes(2);
+      expect(LintRunner2.runLinting).toHaveBeenCalledTimes(2);
+      expect(results).toHaveLength(2);
+    });
+    it("should use provided files and skip scanning when files are provided", async () => {
+      const config = {
+        files: ["file1.css", "component1.html"]
+      };
+      await lint2(config);
+      expect(FileScanner2.scanFiles).not.toHaveBeenCalled();
+      expect(LintRunner2.runLinting).toHaveBeenCalledTimes(2);
+    });
+  });
+  describe("report", () => {
+    it("should return a readable stream", async () => {
+      const config = {
+        directory: "./src",
+        format: "sarif"
+      };
+      const stream = await report2(config);
+      expect(stream).toBeInstanceOf(Readable2);
+    });
+    it("should use lint results to generate a report", async () => {
+      const lintMock = jest.spyOn((init_executor(), __toCommonJS(executor_exports)), "lint").mockResolvedValue([mockLintResult]);
+      const config = {
+        directory: "./src",
+        format: "sarif"
+      };
+      await report2(config);
+      expect(lintMock).toHaveBeenCalledWith({
+        directory: "./src",
+        configStylelint: expect.any(String),
+        configEslint: expect.any(String)
+      });
+      lintMock.mockRestore();
+    });
+  });
+});
+describe("Executor placeholder tests", () => {
+  it("should be implemented in the future", () => {
+    expect(true).toBe(true);
+  });
+});

package/build/executor/index.d.ts

@@ -0,0 +1,19 @@
+import { Readable } from 'stream';
+import { LintResult, LintConfig, ReportConfig } from '../types';
+/**
+ * Run linting on specified files or directory
+ *
+ * @param config Linting configuration options
+ * @returns Promise resolving to an array of lint results
+ * @throws Error if linting fails
+ */
+export declare function lint(config: LintConfig): Promise<LintResult[]>;
+/**
+ * Generate a report from linting results
+ *
+ * @param config Report configuration options
+ * @param results Optional lint results (if not provided, will run lint)
+ * @returns A readable stream containing the report data
+ * @throws Error if report generation fails
+ */
+export declare function report(config: ReportConfig, results?: LintResult[]): Promise<Readable>;

package/build/executor/index.js

@@ -0,0 +1,78 @@
+// src/executor/index.ts
+import { Readable } from "stream";
+import { FileScanner } from "../services/file-scanner.js";
+import { LintRunner } from "../services/lint-runner.js";
+import { StyleFilePatterns, ComponentFilePatterns } from "../services/file-patterns.js";
+import { ReportGenerator, CsvReportGenerator } from "../services/report-generator.js";
+import { LINTER_CLI_VERSION } from "../services/config.resolver.js";
+import { normalizeCliOptions } from "../utils/config-utils.js";
+import { Logger } from "../utils/logger.js";
+async function lint(config) {
+  try {
+    Logger.debug("Starting linting with Node API");
+    const normalizedConfig = normalizeCliOptions(config, {}, true);
+    const styleFiles = await FileScanner.scanFiles(normalizedConfig.directory, {
+      patterns: StyleFilePatterns,
+      batchSize: 100
+    });
+    const componentFiles = await FileScanner.scanFiles(normalizedConfig.directory, {
+      patterns: ComponentFilePatterns,
+      batchSize: 100
+    });
+    const lintOptions = {
+      fix: normalizedConfig.fix,
+      configPath: normalizedConfig.configStylelint
+    };
+    const styleResults = await LintRunner.runLinting(styleFiles, "style", {
+      ...lintOptions,
+      configPath: normalizedConfig.configStylelint
+    });
+    const componentResults = await LintRunner.runLinting(componentFiles, "component", {
+      ...lintOptions,
+      configPath: normalizedConfig.configEslint
+    });
+    const combinedResults = [...styleResults, ...componentResults];
+    return combinedResults;
+  } catch (error) {
+    const errorMessage = `Linting failed: ${error.message}`;
+    Logger.error(errorMessage);
+    throw new Error(errorMessage);
+  }
+}
+async function report(config, results) {
+  try {
+    Logger.debug("Starting report generation with Node API");
+    const normalizedConfig = normalizeCliOptions(config, {}, true);
+    const format = normalizedConfig.format || "sarif";
+    const lintResults = results || await lint({
+      directory: normalizedConfig.directory,
+      configStylelint: normalizedConfig.configStylelint,
+      configEslint: normalizedConfig.configEslint
+    });
+    switch (format) {
+      case "sarif":
+        return ReportGenerator.generateSarifReportStream(lintResults, {
+          toolName: "slds-linter",
+          toolVersion: LINTER_CLI_VERSION
+        });
+      case "csv":
+        const csvString = CsvReportGenerator.generateCsvString(lintResults);
+        const csvStream = new Readable();
+        csvStream.push(csvString);
+        csvStream.push(null);
+        return csvStream;
+      default:
+        const errorMessage = `Unsupported format: ${format}`;
+        Logger.error(errorMessage);
+        throw new Error(errorMessage);
+    }
+  } catch (error) {
+    const errorMessage = `Report generation failed: ${error.message}`;
+    Logger.error(errorMessage);
+    throw new Error(errorMessage);
+  }
+}
+export {
+  lint,
+  report
+};

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("0.1.9");
+  program.description("SLDS Linter CLI tool for linting styles and components").version("0.2.0-alpha.1");
 }
 registerLintCommand(program);
 registerReportCommand(program);

package/build/services/artifact-processor.d.ts

@@ -0,0 +1,6 @@
+import { Artifact as SarifArtifact } from 'sarif';
+/**
+ * Process artifacts and add file content properties
+ * @param artifacts Array of artifacts to process
+ */
+export declare function processArtifacts(artifacts: SarifArtifact[]): Promise<void>;

package/build/services/artifact-processor.js

@@ -0,0 +1,37 @@
+// src/services/artifact-processor.ts
+import path from "path";
+import fs from "fs/promises";
+import crypto from "crypto";
+var BATCH_SIZE = 10;
+async function processArtifacts(artifacts) {
+  const batches = Array.from(
+    { length: Math.ceil(artifacts.length / BATCH_SIZE) },
+    (_, i) => artifacts.slice(i * BATCH_SIZE, (i + 1) * BATCH_SIZE)
+  );
+  for (const batch of batches) {
+    await Promise.all(
+      batch.map(async (artifact) => {
+        try {
+          artifact.sourceLanguage = "html";
+          if (!artifact.location?.uri) {
+            console.warn("Warning: Artifact missing location URI");
+            return;
+          }
+          const filePath = path.join(process.cwd(), artifact.location.uri);
+          const content = await fs.readFile(filePath, "utf-8");
+          artifact.length = content.length;
+          const hash = crypto.createHash("sha256");
+          hash.update(content);
+          artifact.hashes = {
+            "sha-256": hash.digest("hex")
+          };
+        } catch (error) {
+          console.warn(`Warning: Could not process artifact ${artifact.location?.uri}: ${error.message}`);
+        }
+      })
+    );
+  }
+}
+export {
+  processArtifacts
+};

package/build/services/config.resolver.js

@@ -5,7 +5,7 @@ var DEFAULT_ESLINT_CONFIG_PATH = resolvePath("@salesforce-ux/eslint-plugin-slds/
 var DEFAULT_STYLELINT_CONFIG_PATH = resolvePath("@salesforce-ux/stylelint-plugin-slds/.stylelintrc.yml", import.meta);
 var STYLELINT_VERSION = "16.14.1";
 var ESLINT_VERSION = "8.57.1";
-var LINTER_CLI_VERSION = "0.1.9";
+var LINTER_CLI_VERSION = "0.2.0-alpha.1";
 var getRuleDescription = (ruleId) => {
   const ruleIdWithoutNameSpace = `${ruleId}`.replace(/\@salesforce-ux\//, "");
   return ruleMetadata(ruleIdWithoutNameSpace)?.ruleDesc || "--";

package/build/services/report-generator.d.ts

@@ -1,14 +1,23 @@
 import { LintResult } from '../types';
+import { Readable } from 'stream';
 export interface ReportOptions {
-    outputPath: string;
+    outputPath?: string;
     toolName: string;
     toolVersion: string;
 }
 export declare class ReportGenerator {
     /**
-     * Generate SARIF report from lint results
+     * Generate SARIF report from lint results with file output
      */
     static generateSarifReport(results: LintResult[], options: ReportOptions): Promise<void>;
+    /**
+     * Generate SARIF report as a stream without creating a file
+     */
+    static generateSarifReportStream(results: LintResult[], options: ReportOptions): Promise<Readable>;
+    /**
+     * Build SARIF report data in memory
+     */
+    static buildSarifReport(results: LintResult[], options: ReportOptions): Promise<any>;
     /**
      * Extract unique rules from results
      */
@@ -19,5 +28,16 @@ export declare class ReportGenerator {
     private static addResultsToSarif;
 }
 export declare class CsvReportGenerator {
+    /**
+     * Generate CSV report and write to file
+     */
     static generate(results: any[]): Promise<string>;
+    /**
+     * Generate CSV string from lint results
+     */
+    static generateCsvString(results: any[]): string;
+    /**
+     * Convert lint results to CSV-compatible data format
+     */
+    private static convertResultsToCsvData;
 }

package/build/services/report-generator.js

@@ -6,18 +6,56 @@ import { SarifBuilder, SarifRunBuilder, SarifResultBuilder, SarifRuleBuilder } f
 import { createWriteStream } from "fs";
 import { JsonStreamStringify } from "json-stream-stringify";
 import { getRuleDescription } from "./config.resolver.js";
-import { parseText, replaceNamespaceinRules } from "../utils/lintResultsUtil.js";
+import { parseText, replaceNamespaceinRules, transformedResults } from "../utils/lintResultsUtil.js";
+import { processArtifacts } from "./artifact-processor.js";
 var ReportGenerator = class {
   /**
-   * Generate SARIF report from lint results
+   * Generate SARIF report from lint results with file output
    */
   static async generateSarifReport(results, options) {
+    if (!options.outputPath) {
+      return;
+    }
+    const sarifReport = await this.buildSarifReport(results, options);
+    for (const run of sarifReport.runs) {
+      await processArtifacts(run.artifacts);
+    }
+    const outputDir = path.dirname(options.outputPath);
+    await fs.mkdir(outputDir, { recursive: true });
+    const writeStream = createWriteStream(options.outputPath);
+    const jsonStream = new JsonStreamStringify(sarifReport, null, 2);
+    await new Promise((resolve, reject) => {
+      jsonStream.pipe(writeStream).on("finish", resolve).on("error", reject);
+    });
+  }
+  /**
+   * Generate SARIF report as a stream without creating a file
+   */
+  static async generateSarifReportStream(results, options) {
+    const sarifReport = await this.buildSarifReport(results, options);
+    return new JsonStreamStringify(sarifReport, null, 2);
+  }
+  /**
+   * Build SARIF report data in memory
+   */
+  static async buildSarifReport(results, options) {
     const builder = new SarifBuilder();
-    const runBuilder = new SarifRunBuilder().initSimple({
+    const runBuilder = new SarifRunBuilder({
+      defaultSourceLanguage: "html"
+    }).initSimple({
       toolDriverName: options.toolName,
       toolDriverVersion: options.toolVersion,
       url: "https://github.com/salesforce-ux/slds-linter"
     });
+    runBuilder.run.properties = {
+      id: Number(Math.random().toString(10).substring(2, 10)),
+      version: options.toolVersion,
+      submissionDate: (/* @__PURE__ */ new Date()).toISOString().split("T")[0],
+      language: "html",
+      status: "accepted",
+      type: "source code"
+    };
+    runBuilder.run.tool.driver.organization = "Salesforce";
     const rules = this.extractRules(results);
     for (const rule of rules) {
       const ruleBuilder = new SarifRuleBuilder().initSimple({
@@ -30,14 +68,7 @@ var ReportGenerator = class {
       this.addResultsToSarif(runBuilder, result);
     }
     builder.addRun(runBuilder);
-    const sarifReport = builder.buildSarifOutput();
-    const outputDir = path.dirname(options.outputPath);
-    await fs.mkdir(outputDir, { recursive: true });
-    const writeStream = createWriteStream(options.outputPath);
-    const jsonStream = new JsonStreamStringify(sarifReport, null, 2);
-    await new Promise((resolve, reject) => {
-      jsonStream.pipe(writeStream).on("finish", resolve).on("error", reject);
-    });
+    return builder.buildSarifOutput();
   }
   /**
    * Extract unique rules from results
@@ -78,38 +109,39 @@ var ReportGenerator = class {
    * Add lint results to SARIF report
    */
   static addResultsToSarif(runBuilder, lintResult) {
-    for (const error of lintResult.errors) {
-      const resultBuilder = new SarifResultBuilder().initSimple({
-        ruleId: replaceNamespaceinRules(error.ruleId),
-        level: "error",
-        messageText: parseText(error.message),
-        fileUri: path.relative(process.cwd(), lintResult.filePath),
-        startLine: error.line,
-        startColumn: error.column,
-        endLine: error.line,
-        endColumn: error.endColumn
-      });
+    lintResult.errors.forEach((error) => {
+      const resultBuilder = new SarifResultBuilder().initSimple(transformedResults(lintResult, error, "error"));
       runBuilder.addResult(resultBuilder);
-    }
-    for (const warning of lintResult.warnings) {
-      const resultBuilder = new SarifResultBuilder().initSimple({
-        ruleId: replaceNamespaceinRules(warning.ruleId),
-        level: "warning",
-        messageText: parseText(warning.message),
-        fileUri: path.relative(process.cwd(), lintResult.filePath),
-        startLine: warning.line,
-        startColumn: warning.column,
-        endLine: warning.line,
-        endColumn: warning.endColumn
-      });
+    });
+    lintResult.warnings.forEach((warning) => {
+      const resultBuilder = new SarifResultBuilder().initSimple(transformedResults(lintResult, warning, "warning"));
       runBuilder.addResult(resultBuilder);
-    }
+    });
   }
 };
 var CsvReportGenerator = class {
+  /**
+   * Generate CSV report and write to file
+   */
   static async generate(results) {
+    const csvString = this.generateCsvString(results);
+    const csvReportPath = path.join(process.cwd(), "slds-linter-report.csv");
+    await writeFile(csvReportPath, csvString);
+    return csvReportPath;
+  }
+  /**
+   * Generate CSV string from lint results
+   */
+  static generateCsvString(results) {
+    const csvData = this.convertResultsToCsvData(results);
+    return asString(csvData);
+  }
+  /**
+   * Convert lint results to CSV-compatible data format
+   */
+  static convertResultsToCsvData(results) {
+    const cwd = process.cwd();
     const csvConfig = mkConfig({
-      filename: "slds-linter-report",
       fieldSeparator: ",",
       quoteStrings: true,
       decimalSeparator: ".",
@@ -117,8 +149,7 @@ var CsvReportGenerator = class {
       useBom: true,
       useKeysAsHeaders: true
     });
-    const cwd = process.cwd();
-    const transformedResults = results.flatMap(
+    const transformedResults2 = results.flatMap(
       (result) => [
         ...result.errors.map((error) => ({
           "File Path": path.relative(cwd, result.filePath),
@@ -146,12 +177,7 @@ var CsvReportGenerator = class {
         }))
       ]
     );
-    const csvData = generateCsv(csvConfig)(transformedResults);
-    const csvString = asString(csvData);
-    const csvReportPath = path.join(cwd, `${csvConfig.filename}.csv`);
-    return writeFile(csvReportPath, csvString).then(() => {
-      return csvReportPath;
-    });
+    return generateCsv(csvConfig)(transformedResults2);
   }
 };
 export {

package/build/types/index.d.ts

@@ -1,30 +1,44 @@
-export interface CliOptions {
+export interface BaseConfig {
     directory?: string;
-    output?: string;
-    fix?: boolean;
+    files?: string[];
     configStylelint?: string;
     configEslint?: string;
+}
+/**
+ * CLI options interface extends BaseConfig for shared properties
+ */
+export interface CliOptions extends BaseConfig {
+    output?: string;
+    fix?: boolean;
     editor?: string;
     format?: string;
 }
+/**
+ * Configuration for linting operation in the Node API
+ * Extends the common base configuration
+ */
+export interface LintConfig extends BaseConfig {
+    fix?: boolean;
+}
+/**
+ * Configuration for report generation in the Node API
+ * Extends the common base configuration
+ */
+export interface ReportConfig extends BaseConfig {
+    format?: 'sarif' | 'csv';
+}
+export interface LintResultEntry {
+    line: number;
+    column: number;
+    endColumn: number;
+    message: string;
+    ruleId: string;
+    severity: number;
+}
 export interface LintResult {
     filePath: string;
-    errors: Array<{
-        line: number;
-        column: number;
-        endColumn: number;
-        message: string;
-        ruleId: string;
-        severity: number;
-    }>;
-    warnings: Array<{
-        line: number;
-        column: number;
-        endColumn: number;
-        message: string;
-        ruleId: string;
-        severity: number;
-    }>;
+    errors: Array<LintResultEntry>;
+    warnings: Array<LintResultEntry>;
 }
 export type ExitCode = 0 | 1 | 2;
 export interface WorkerConfig {
@@ -49,3 +63,13 @@ export interface WorkerResult {
         ruleId: string;
     }>;
 }
+export interface SarifResultEntry {
+    level: any;
+    messageText: string;
+    ruleId: string;
+    fileUri?: string;
+    startLine?: number;
+    startColumn?: number;
+    endLine?: number;
+    endColumn?: number;
+}

package/build/utils/config-utils.d.ts

@@ -0,0 +1,33 @@
+import { LintConfig, ReportConfig, CliOptions } from '../types';
+/**
+ * Normalize and validate a file path
+ * This function ensures that the provided path exists and is accessible
+ * If no path is provided, it defaults to the current working directory
+ *
+ * @param inputPath Input file path or undefined
+ * @returns Normalized and validated absolute path
+ * @throws Error if the path is invalid or inaccessible
+ */
+export declare function normalizeAndValidatePath(inputPath?: string): string;
+/**
+ * Normalize directory path with special handling for glob patterns
+ * This function preserves glob patterns and resolves regular paths to absolute paths
+ * If no directory is provided, it defaults to the current working directory
+ *
+ * @param directory Input directory or glob pattern or undefined
+ * @returns Normalized directory path
+ */
+export declare function normalizeDirectoryPath(directory?: string): string;
+/**
+ * Normalize configuration with appropriate defaults
+ * This function ensures all required options have valid values
+ * It applies provided defaults, then user-provided options, then normalizes paths
+ * Used by both CLI commands and Node API functions
+ *
+ * @param options Options to normalize
+ * @param defaultOptions Default options to apply
+ * @param isNodeApi Whether this is being called from the Node API
+ * @returns Normalized options with appropriate defaults
+ */
+export declare function normalizeCliOptions<T extends CliOptions | LintConfig | ReportConfig>(options: T, defaultOptions?: Partial<T>, isNodeApi?: boolean): T;
+export declare const normalizeConfig: typeof normalizeCliOptions;

package/build/utils/config-utils.js

@@ -0,0 +1,68 @@
+// src/utils/config-utils.ts
+import path from "path";
+import { DEFAULT_ESLINT_CONFIG_PATH, DEFAULT_STYLELINT_CONFIG_PATH } from "../services/config.resolver.js";
+import { isDynamicPattern } from "globby";
+import { accessSync } from "fs";
+import { Logger } from "./logger.js";
+function normalizeAndValidatePath(inputPath) {
+  if (!inputPath) {
+    Logger.debug("No path provided, using current working directory");
+    return process.cwd();
+  }
+  const normalizedPath = path.resolve(inputPath);
+  Logger.debug(`Normalized path: ${normalizedPath}`);
+  try {
+    accessSync(normalizedPath);
+    return normalizedPath;
+  } catch (error) {
+    const errorMessage = `Invalid path: ${inputPath}`;
+    Logger.error(errorMessage);
+    throw new Error(errorMessage);
+  }
+}
+function normalizeDirectoryPath(directory) {
+  if (!directory) {
+    Logger.debug("No directory provided, using current working directory");
+    return process.cwd();
+  }
+  if (isDynamicPattern(directory)) {
+    Logger.debug(`Detected glob pattern: ${directory}`);
+    return directory;
+  }
+  Logger.debug(`Normalizing directory path: ${directory}`);
+  return path.resolve(directory);
+}
+function normalizeCliOptions(options, defaultOptions = {}, isNodeApi = false) {
+  const baseDefaults = {
+    files: [],
+    configStylelint: isNodeApi ? DEFAULT_STYLELINT_CONFIG_PATH : "",
+    configEslint: isNodeApi ? DEFAULT_ESLINT_CONFIG_PATH : ""
+  };
+  if (!isNodeApi) {
+    Object.assign(baseDefaults, {
+      fix: false,
+      editor: "vscode",
+      format: "sarif"
+    });
+  }
+  const normalizedOptions = {
+    ...baseDefaults,
+    ...defaultOptions,
+    ...options,
+    directory: normalizeDirectoryPath(options.directory)
+  };
+  if (!isNodeApi) {
+    normalizedOptions.output = options.output ? normalizeAndValidatePath(options.output) : process.cwd();
+  }
+  if ("format" in options && !options.format && isNodeApi) {
+    normalizedOptions.format = "sarif";
+  }
+  return normalizedOptions;
+}
+var normalizeConfig = normalizeCliOptions;
+export {
+  normalizeAndValidatePath,
+  normalizeCliOptions,
+  normalizeConfig,
+  normalizeDirectoryPath
+};

package/build/utils/lintResultsUtil.d.ts

@@ -1,4 +1,4 @@
-import { LintResult } from '../types';
+import { LintResult, LintResultEntry, SarifResultEntry } from '../types';
 /**
  *
  * @param id - Rule id
@@ -18,3 +18,4 @@ export declare function parseText(text: string): string;
  * @param editor - The chosen editor for clickable links (e.g., "vscode", "atom", "sublime").
  */
 export declare function printLintResults(results: LintResult[], editor: string): void;
+export declare function transformedResults(lintResult: LintResult, entry: LintResultEntry, level: 'error' | 'warning'): SarifResultEntry;

package/build/utils/lintResultsUtil.js

@@ -7,12 +7,14 @@ function replaceNamespaceinRules(id) {
   return id.includes("@salesforce-ux/") ? id.replace("@salesforce-ux/", "") : id;
 }
 function parseText(text) {
+  let safeText = text;
   try {
     const parsed = JSON.parse(text);
-    return parsed.message || JSON.stringify(parsed);
+    safeText = parsed.message || JSON.stringify(parsed);
   } catch (error) {
-    return text;
+    safeText = text;
   }
+  return safeText.endsWith(".") ? safeText : `${safeText}.`;
 }
 function printLintResults(results, editor) {
   results.forEach((result) => {
@@ -48,8 +50,21 @@ function printLintResults(results, editor) {
     }
   });
 }
+function transformedResults(lintResult, entry, level) {
+  return {
+    ruleId: replaceNamespaceinRules(entry.ruleId),
+    level,
+    messageText: parseText(entry.message),
+    fileUri: path.relative(process.cwd(), lintResult.filePath),
+    startLine: entry.line,
+    startColumn: entry.column,
+    endLine: entry.line,
+    endColumn: entry.endColumn
+  };
+}
 export {
   parseText,
   printLintResults,
-  replaceNamespaceinRules
+  replaceNamespaceinRules,
+  transformedResults
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce-ux/slds-linter",
-  "version": "0.1.9",
+  "version": "0.2.0-alpha.2",
   "description": "SLDS Linter CLI tool for linting styles and components",
   "keywords": [
     "lightning design system linter",
@@ -12,16 +12,18 @@
   "author": "UXF Tooling Team",
   "type": "module",
   "main": "build/index.js",
+  "exports": {
+    ".": "./build/index.js",
+    "./executor": "./build/executor/index.js"
+  },
   "files": [
     "build/**",
     "README.md"
   ],
-  "bin": {
-    "slds-linter": "./build/index.js"
-  },
+  "bin": "./build/index.js",
   "dependencies": {
-    "@salesforce-ux/eslint-plugin-slds": "0.1.9",
-    "@salesforce-ux/stylelint-plugin-slds": "0.1.9",
+    "@salesforce-ux/eslint-plugin-slds": "0.2.0-alpha.2",
+    "@salesforce-ux/stylelint-plugin-slds": "0.2.0-alpha.2",
     "@typescript-eslint/eslint-plugin": "^5.0.0",
     "@typescript-eslint/parser": "^5.0.0",
     "chalk": "^4.1.2",

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

@@ -1,4 +0,0 @@
-import { CliOptions } from "../types";
-export declare function nomalizeAndValidatePath(inputPath?: string): string;
-export declare function nomalizeDirPath(inputPath?: string): string;
-export declare function normalizeCliOptions(options: CliOptions, defultOptions?: Partial<CliOptions>): Required<CliOptions>;

package/build/utils/cli-args.js

@@ -1,43 +0,0 @@
-// src/utils/cli-args.ts
-import path from "path";
-import { accessSync } from "fs";
-import { isDynamicPattern } from "globby";
-function nomalizeAndValidatePath(inputPath) {
-  if (!inputPath) {
-    return process.cwd();
-  }
-  const normalizedPath = path.resolve(inputPath);
-  try {
-    accessSync(normalizedPath);
-    return normalizedPath;
-  } catch (error) {
-    throw new Error(`Invalid path: ${inputPath}`);
-  }
-}
-function nomalizeDirPath(inputPath) {
-  if (!inputPath) {
-    return process.cwd();
-  }
-  if (isDynamicPattern(inputPath)) {
-    return inputPath;
-  }
-  return nomalizeAndValidatePath(inputPath);
-}
-function normalizeCliOptions(options, defultOptions = {}) {
-  return {
-    fix: false,
-    editor: "vscode",
-    configStylelint: "",
-    configEslint: "",
-    format: "sarif",
-    ...defultOptions,
-    ...options,
-    directory: nomalizeDirPath(options.directory),
-    output: nomalizeAndValidatePath(options.output)
-  };
-}
-export {
-  nomalizeAndValidatePath,
-  nomalizeDirPath,
-  normalizeCliOptions
-};