apex-code-coverage-transformer 4.1.0 → 4.3.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [4.3.0](https://github.com/mcarvin8/apex-code-coverage-transformer/compare/v4.2.0...v4.3.0) (2026-11-09)
+
+
+### Features
+
+* publish dependency-free apex-code-coverage-transformer-core package ([#441](https://github.com/mcarvin8/apex-code-coverage-transformer/issues/441)) ([76d7f65](https://github.com/mcarvin8/apex-code-coverage-transformer/commit/76d7f650234bac780b22ffeb22728530e3b78375))
+
+## [4.2.0](https://github.com/mcarvin8/apex-code-coverage-transformer/compare/v4.1.0...v4.2.0) (2026-11-09)
+
+
+### Features
+
+* add programmatic API for library consumers ([#438](https://github.com/mcarvin8/apex-code-coverage-transformer/issues/438)) ([13679cd](https://github.com/mcarvin8/apex-code-coverage-transformer/commit/13679cd98ea71f3f077ccf17d594cd512b9a0878))
+
 ## [4.1.0](https://github.com/mcarvin8/apex-code-coverage-transformer/compare/v4.0.0...v4.1.0) (2026-11-05)
 
 

package/README.md

@@ -6,8 +6,6 @@
 [![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://raw.githubusercontent.com/mcarvin8/apex-code-coverage-transformer/main/LICENSE.md)
 [![codecov](https://codecov.io/gh/mcarvin8/apex-code-coverage-transformer/graph/badge.svg?token=4IQ4NWTPQZ)](https://codecov.io/gh/mcarvin8/apex-code-coverage-transformer)
 [![Mutation testing badge](https://img.shields.io/endpoint?style=flat&url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Fmcarvin8%2Fapex-code-coverage-transformer%2Fmain)](https://dashboard.stryker-mutator.io/reports/github.com/mcarvin8/apex-code-coverage-transformer/main)
-<!-- gh-dependents-info-used-by-start -->
-[![Generated by github-dependents-info](https://img.shields.io/static/v1?label=Used%20by&message=2&color=informational&logo=slickpic)](https://github.com/mcarvin8/apex-code-coverage-transformer/blob/main/docs/github-dependents-info.md)<!-- gh-dependents-info-used-by-end -->
 
 Transforms (and optionally merges) Apex code coverage JSON from Salesforce deployments or test runs into formats used by SonarQube, Codecov, GitHub, GitLab, Azure DevOps, Bitbucket, and other tools, keeping coverage visible across pull requests, CI/CD pipelines, and code quality platforms. Available as a **Salesforce CLI plugin** for any provider, and as a **native GitHub Action** for GitHub Actions users who want to skip installing the CLI.
 
@@ -26,6 +24,7 @@ Transforms (and optionally merges) Apex code coverage JSON from Salesforce deplo
 - [Coverage Report Formats](#coverage-report-formats)
 - [CI/CD Integration](#cicd-integration)
 - [Automatic Transformation (Hook)](#automatic-transformation-hook)
+- [Programmatic Usage](#programmatic-usage)
 - [Troubleshooting](#troubleshooting)
 - [Questions or Issues?](#questions-or-issues)
 - [License](#license)
@@ -197,7 +196,7 @@ EXAMPLES
   `sf acc-transformer transform -j "coverage1.json" -j "coverage2.json" -r "coverage.xml" -f "sonar"`
 ```
 
-_See code: [src/commands/acc-transformer/transform.ts](https://github.com/mcarvin8/apex-code-coverage-transformer/blob/v4.1.0/src/commands/acc-transformer/transform.ts)_
+_See code: [src/commands/acc-transformer/transform.ts](https://github.com/mcarvin8/apex-code-coverage-transformer/blob/v4.3.0/src/commands/acc-transformer/transform.ts)_
 <!-- commandsstop -->
 
 ## Coverage Report Formats
@@ -546,6 +545,52 @@ Sample configs: [Salesforce CLI](https://raw.githubusercontent.com/mcarvin8/apex
 | `maxAnnotations`           | No         | Maximum `::warning` annotations emitted when `format` includes `github-actions` (default: `50`).                                             |
 | `excludePatterns`          | No         | Comma-separated glob patterns for file paths to exclude (e.g. `**/*Test*,**/mock/**`). Matched against the relative path from the repo root. |
 
+## Programmatic Usage
+
+Other Node.js tools (CLI plugins, scripts, CI wrappers) can call the transformer directly instead of shelling out to `sf acc-transformer transform`. The API is ESM-only and ships in two npm packages, built from the same source and released with the same version:
+
+- **`apex-code-coverage-transformer-core`** (recommended for libraries): the API only, with **no runtime dependencies**.
+- **`apex-code-coverage-transformer`**: the Salesforce CLI plugin package, which also exports the API but installs the plugin's dependencies (`@salesforce/core`, `@oclif/core` and others).
+
+```bash
+npm install apex-code-coverage-transformer-core
+```
+
+The examples below import from `apex-code-coverage-transformer`; with the core package, import from `apex-code-coverage-transformer-core` instead. Everything else is identical.
+
+```ts
+import { transformCoverage, CoverageError } from 'apex-code-coverage-transformer';
+
+const { summary, reports, warnings, passed } = await transformCoverage({
+  inputs: ['coverage/coverage/coverage.json'], // file paths and/or already-parsed coverage JSON
+  formats: ['cobertura', 'markdown'],
+  write: false, // return report contents without writing files
+  cwd: '/path/to/sfdx/project', // where to look for sfdx-project.json (default: process.cwd())
+});
+
+console.log(`${(summary.lineRate * 100).toFixed(2)}% across ${summary.fileCount} files`);
+for (const file of summary.files) {
+  console.log(file.path, file.coveredLines, '/', file.totalLines, 'uncovered:', file.uncoveredLines);
+}
+const markdown = reports.find((r) => r.format === 'markdown')?.content;
+```
+
+| Option                     | Default         | Description                                                                                 |
+| -------------------------- | --------------- | ------------------------------------------------------------------------------------------- |
+| `inputs`                   | (required)      | Coverage JSON file paths and/or parsed objects. All must be the same type (deploy or test). |
+| `formats`                  | `['sonar']`     | Output formats. `COVERAGE_FORMATS` lists every supported value.                             |
+| `outputReport`             | `coverage.xml`  | Base path for written reports. Multiple formats add a suffix (e.g. `coverage-sonar.xml`).   |
+| `write`                    | `true`          | When `false`, nothing is written and each report's `path` is `undefined`.                   |
+| `cwd`                      | `process.cwd()` | Directory to search upward from for `sfdx-project.json`.                                    |
+| `ignorePackageDirectories` | `[]`            | Package directories to skip.                                                                |
+| `excludePatterns`          | `[]`            | Glob patterns for repo-relative file paths to exclude.                                      |
+| `minCoverage`              | none            | Sets `passed: false` when overall coverage is below this percentage. Nothing is thrown.     |
+| `maxAnnotations`           | `50`            | Annotation limit for the `github-actions` format.                                           |
+
+Known failures throw a `CoverageError` with a `code`: `UNKNOWN_INPUT_FORMAT`, `MIXED_INPUT_TYPES`, `UNSUPPORTED_FORMAT`, or `NO_SFDX_PROJECT`. Unreadable input files are skipped with a warning.
+
+Everything exported from the package root follows semver. Deep imports are not supported.
+
 ## Troubleshooting
 
 **File not in package directory** — File is omitted from the report:

package/lib/commands/acc-transformer/transform.js

@@ -4,6 +4,7 @@ import { Flags, SfCommand } from '@salesforce/sf-plugins-core';
 import { transformCoverageReport } from '../../transformers/coverageTransformer.js';
 import { DEFAULT_MAX_ANNOTATIONS } from '../../transformers/generators/generateGitHubActions.js';
 import { formatOptions } from '../../utils/constants.js';
+import { CoverageError } from '../../utils/errors.js';
 Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
 const messages = Messages.loadMessages('apex-code-coverage-transformer', 'transformer.transform');
 export default class TransformerTransform extends SfCommand {
@@ -45,7 +46,6 @@ export default class TransformerTransform extends SfCommand {
         }),
         'max-annotations': Flags.integer({
             summary: messages.getMessage('flags.max-annotations.summary'),
-            required: false,
             min: 1,
             default: DEFAULT_MAX_ANNOTATIONS,
         }),
@@ -59,18 +59,26 @@ export default class TransformerTransform extends SfCommand {
     async run() {
         const { flags } = await this.parse(TransformerTransform);
         const warnings = [];
-        const result = await transformCoverageReport(flags['coverage-json'], flags['output-report'], flags['format'] ?? ['sonar'], flags['ignore-package-directory'] ?? [], {
-            minCoverage: flags['min-coverage'],
-            maxAnnotations: flags['max-annotations'],
-            excludePatterns: flags['exclude-pattern'],
-        });
-        warnings.push(...result.warnings);
-        this.log(`The coverage report has been written to: ${result.finalPaths.join(', ')}`);
-        if (warnings.length > 0) {
-            warnings.forEach((warning) => {
-                this.warn(warning);
+        let result;
+        try {
+            result = await transformCoverageReport(flags['coverage-json'], flags['output-report'], flags['format'] ?? ['sonar'], flags['ignore-package-directory'] ?? [], {
+                minCoverage: flags['min-coverage'],
+                maxAnnotations: flags['max-annotations'],
+                excludePatterns: flags['exclude-pattern'],
             });
         }
+        catch (error) {
+            // SfCommand prints an error's `code` in place of the exit code ("Error (UNKNOWN_INPUT_FORMAT)").
+            // Rethrow as a plain Error so CLI output stays "Error (1): ..." as documented.
+            if (error instanceof CoverageError)
+                throw new Error(error.message, { cause: error });
+            throw error;
+        }
+        warnings.push(...result.warnings);
+        this.log(`The coverage report has been written to: ${result.finalPaths.join(', ')}`);
+        warnings.forEach((warning) => {
+            this.warn(warning);
+        });
         if (!result.success) {
             this.error(`Coverage of ${(result.lineRate * 100).toFixed(2)}% is below the required minimum of ${flags['min-coverage']}%.`);
         }

package/lib/commands/acc-transformer/transform.js.map

@@ -1 +1 @@
-{"version":3,"file":"transform.js","sourceRoot":"","sources":["../../../src/commands/acc-transformer/transform.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"transform.js","sourceRoot":"","sources":["../../../src/commands/acc-transformer/transform.ts"],"names":[],"mappings":"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"}

package/lib/index.d.ts

@@ -1,2 +1,7 @@
-declare const _default: {};
-export default _default;
+import { CoverageFormat } from './utils/types.js';
+export { transformCoverage } from './transformers/coverageTransformer.js';
+export type { CoverageErrorCode } from './utils/errors.js';
+export { CoverageError } from './utils/errors.js';
+export type { CoverageFormat, CoverageInput, CoverageSummary, DeployCoverageData, FileCoverageSummary, GeneratedReport, TestCoverageData, TransformCoverageOptions, TransformCoverageResult, } from './utils/types.js';
+/** All supported output formats, sorted alphabetically. */
+export declare const COVERAGE_FORMATS: readonly CoverageFormat[];

package/lib/index.js

@@ -1,2 +1,13 @@
-export default {};
+'use strict';
+/**
+ * Public programmatic API.
+ *
+ * Everything exported from this module follows semver. Anything imported from deeper paths
+ * is internal and may change in any release.
+ */
+import { formatOptions } from './utils/constants.js';
+export { transformCoverage } from './transformers/coverageTransformer.js';
+export { CoverageError } from './utils/errors.js';
+/** All supported output formats, sorted alphabetically. */
+export const COVERAGE_FORMATS = Object.freeze([...formatOptions]);
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,eAAe,EAAE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb;;;;;GAKG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAGrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAE1E,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAalD,2DAA2D;AAC3D,MAAM,CAAC,MAAM,gBAAgB,GAA8B,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,aAAa,CAAqB,CAAC,CAAC"}

package/lib/transformers/coverageProcessor.js

@@ -13,23 +13,17 @@ export function createHandlers(formats) {
     }
     return handlers;
 }
-async function readSourceFile(absolutePath) {
-    try {
-        return await readFile(absolutePath, 'utf-8');
-    }
-    catch {
-        return undefined;
-    }
-}
 async function loadSourceContent(path, context) {
     if (!context.handlers.has('html')) {
         return undefined;
     }
-    const content = await readSourceFile(join(context.repoRoot, path));
-    if (content === undefined) {
+    try {
+        return await readFile(join(context.repoRoot, path), 'utf-8');
+    }
+    catch {
         context.warnings.push(`Could not read source file ${path}; the HTML report will show coverage for this file without line contents.`);
+        return undefined;
     }
-    return content;
 }
 export function countLines(lines) {
     const totalLines = Object.keys(lines).length;
@@ -40,6 +34,7 @@ async function processEntries(items, context, getName, resolveLines) {
     let processed = 0;
     let totalLines = 0;
     let coveredLines = 0;
+    const files = [];
     await mapLimit(items, context.concurrencyLimit, async (item) => {
         const formattedName = getName(item).replace(/no-map[\\/]+/, '');
         const path = findFilePath(formattedName, context.filePathCache);
@@ -54,12 +49,29 @@ async function processEntries(items, context, getName, resolveLines) {
         const counts = countLines(lines);
         totalLines += counts.totalLines;
         coveredLines += counts.coveredLines;
+        files.push(summarizeFile(path, formattedName, lines, counts));
         for (const handler of context.handlers.values()) {
             handler.processFile(path, formattedName, lines, sourceContent);
         }
         processed++;
     });
-    return { processed, totalLines, coveredLines };
+    files.sort((a, b) => a.path.localeCompare(b.path));
+    return { processed, totalLines, coveredLines, files };
+}
+function summarizeFile(path, name, lines, counts) {
+    // Line numbers are integer-like keys, which JavaScript always enumerates in ascending
+    // numeric order, so no explicit sort is needed.
+    const uncoveredLines = Object.entries(lines)
+        .filter(([, hit]) => hit !== 1)
+        .map(([line]) => Number(line));
+    return {
+        path,
+        name,
+        totalLines: counts.totalLines,
+        coveredLines: counts.coveredLines,
+        lineRate: counts.totalLines > 0 ? counts.coveredLines / counts.totalLines : 0,
+        uncoveredLines,
+    };
 }
 export function processDeployCoverage(data, context) {
     return processEntries(Object.keys(data), context, (fileName) => fileName, async (fileName, path) => ({

package/lib/transformers/coverageProcessor.js.map

@@ -1 +1 @@
-{"version":3,"file":"coverageProcessor.js","sourceRoot":"","sources":["../../src/transformers/coverageProcessor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"coverageProcessor.js","sourceRoot":"","sources":["../../src/transformers/coverageProcessor.ts"],"names":[],"mappings":"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"}

package/lib/transformers/coverageTransformer.d.ts

@@ -1,5 +1,20 @@
-import { TransformOptions } from '../utils/types.js';
+import { TransformCoverageOptions, TransformCoverageResult, TransformOptions } from '../utils/types.js';
 export { TransformOptions };
+/**
+ * Transform Salesforce CLI Apex coverage JSON into one or more report formats.
+ *
+ * @example
+ * const { summary, reports } = await transformCoverage({
+ *   inputs: ['coverage/coverage/coverage.json'],
+ *   formats: ['cobertura', 'markdown'],
+ *   write: false,
+ * });
+ */
+export declare function transformCoverage(options: TransformCoverageOptions): Promise<TransformCoverageResult>;
+/**
+ * Positional-argument wrapper used by the CLI command and GitHub Action.
+ * Library consumers should use {@link transformCoverage}.
+ */
 export declare function transformCoverageReport(jsonFilePaths: string[], outputReportPath: string, formats: string[], ignoreDirs: string[], options?: TransformOptions): Promise<{
     finalPaths: string[];
     warnings: string[];

package/lib/transformers/coverageTransformer.js

@@ -1,32 +1,72 @@
 /* eslint-disable no-await-in-loop */
 'use strict';
+import { writeFile } from 'node:fs/promises';
+import { HandlerRegistry } from '../handlers/HandlerRegistry.js';
 import { buildFilePathCache } from '../utils/buildFilePathCache.js';
+import { CoverageError } from '../utils/errors.js';
 import { getConcurrencyThreshold } from '../utils/getConcurrencyThreshold.js';
 import { getPackageDirectories } from '../utils/getPackageDirectories.js';
 import { tryReadJson } from '../utils/readJson.js';
 import { checkCoverageDataType } from '../utils/setCoverageDataType.js';
 import { mergeDeployCoverageData, mergeTestCoverageData } from './coverageDataMerger.js';
 import { createHandlers, processDeployCoverage, processTestCoverage } from './coverageProcessor.js';
-import { generateAndWriteReport } from './reportGenerator.js';
-export async function transformCoverageReport(jsonFilePaths, outputReportPath, formats, ignoreDirs, options) {
+import { generateReportContent, getReportPath } from './reportGenerator.js';
+const DEFAULT_OUTPUT_REPORT = 'coverage.xml';
+async function loadInputs(inputs, warnings) {
+    const loaded = await Promise.all(inputs.map(async (input) => {
+        if (typeof input !== 'string')
+            return input;
+        const raw = await tryReadJson(input, warnings);
+        return raw === null ? null : JSON.parse(raw);
+    }));
+    return loaded.filter((item) => item !== null);
+}
+function validateFormats(formats) {
+    for (const format of formats) {
+        if (!HandlerRegistry.has(format)) {
+            throw new CoverageError(`Unsupported format: ${format}. Available formats: ${HandlerRegistry.getAvailableFormats().join(', ')}`, { code: 'UNSUPPORTED_FORMAT' });
+        }
+    }
+}
+function emptyResult(warnings) {
+    return {
+        reports: [],
+        summary: { lineRate: 0, coveredLines: 0, totalLines: 0, fileCount: 0, files: [] },
+        warnings,
+        passed: true,
+    };
+}
+/**
+ * Transform Salesforce CLI Apex coverage JSON into one or more report formats.
+ *
+ * @example
+ * const { summary, reports } = await transformCoverage({
+ *   inputs: ['coverage/coverage/coverage.json'],
+ *   formats: ['cobertura', 'markdown'],
+ *   write: false,
+ * });
+ */
+export async function transformCoverage(options) {
+    const formats = options.formats && options.formats.length > 0 ? options.formats : ['sonar'];
+    const outputReport = options.outputReport ?? DEFAULT_OUTPUT_REPORT;
+    const write = options.write ?? true;
     const warnings = [];
-    const finalPaths = [];
-    const formatAmount = formats.length;
-    const jsonDataItems = await Promise.all(jsonFilePaths.map((p) => tryReadJson(p, warnings)));
-    const validData = jsonDataItems.filter((d) => d !== null);
-    if (validData.length === 0)
-        return { finalPaths: [outputReportPath], warnings, lineRate: 0, success: true };
-    const parsedItems = validData.map((d) => JSON.parse(d));
+    validateFormats(formats);
+    const parsedItems = await loadInputs(options.inputs, warnings);
+    if (parsedItems.length === 0)
+        return emptyResult(warnings);
     const types = parsedItems.map(checkCoverageDataType);
     if (types.some((t) => t === 'Unknown')) {
-        throw new Error('The provided JSON does not match a known coverage data format from the Salesforce deploy or test command.');
+        throw new CoverageError('The provided JSON does not match a known coverage data format from the Salesforce deploy or test command.', { code: 'UNKNOWN_INPUT_FORMAT' });
     }
     const uniqueTypes = [...new Set(types)];
     if (uniqueTypes.length > 1) {
-        throw new Error('All coverage JSON files must be the same type (deploy or test).');
+        throw new CoverageError('All coverage JSON files must be the same type (deploy or test).', {
+            code: 'MIXED_INPUT_TYPES',
+        });
     }
     const commandType = uniqueTypes[0];
-    const { repoRoot, packageDirectories } = await getPackageDirectories(ignoreDirs);
+    const { repoRoot, packageDirectories } = await getPackageDirectories(options.ignorePackageDirectories ?? [], options.cwd);
     const handlers = createHandlers(formats);
     const concurrencyLimit = getConcurrencyThreshold();
     // Build file path cache upfront to avoid O(n*m) directory traversals
@@ -39,7 +79,7 @@ export async function transformCoverageReport(jsonFilePaths, outputReportPath, f
         concurrencyLimit,
         warnings,
         filePathCache,
-        excludePatterns: options?.excludePatterns ?? [],
+        excludePatterns: options.excludePatterns ?? [],
     };
     const processResult = commandType === 'DeployCoverageData'
         ? await processDeployCoverage(mergeDeployCoverageData(parsedItems), context)
@@ -48,13 +88,52 @@ export async function transformCoverageReport(jsonFilePaths, outputReportPath, f
         warnings.push('None of the files listed in the coverage JSON were processed. The coverage report will be empty.');
     }
     const lineRate = processResult.totalLines > 0 ? processResult.coveredLines / processResult.totalLines : 0;
-    const renderOptions = options?.maxAnnotations !== undefined ? { maxAnnotations: options.maxAnnotations } : undefined;
+    const renderOptions = options.maxAnnotations !== undefined ? { maxAnnotations: options.maxAnnotations } : undefined;
+    const reports = [];
     for (const [format, handler] of handlers.entries()) {
-        const coverageObj = handler.finalize();
-        const finalPath = await generateAndWriteReport(outputReportPath, coverageObj, format, formatAmount, renderOptions);
-        finalPaths.push(finalPath);
+        const content = generateReportContent(handler.finalize(), format, renderOptions);
+        const report = { format: format, content };
+        if (write) {
+            report.path = getReportPath(outputReport, format, formats.length);
+            await writeFile(report.path, content);
+        }
+        reports.push(report);
     }
-    const success = options?.minCoverage === undefined || lineRate * 100 >= options.minCoverage;
-    return { finalPaths, warnings, lineRate, success };
+    return {
+        reports,
+        summary: {
+            lineRate,
+            coveredLines: processResult.coveredLines,
+            totalLines: processResult.totalLines,
+            fileCount: processResult.files.length,
+            files: processResult.files,
+        },
+        warnings,
+        passed: options.minCoverage === undefined || lineRate * 100 >= options.minCoverage,
+    };
+}
+/**
+ * Positional-argument wrapper used by the CLI command and GitHub Action.
+ * Library consumers should use {@link transformCoverage}.
+ */
+export async function transformCoverageReport(jsonFilePaths, outputReportPath, formats, ignoreDirs, options) {
+    const result = await transformCoverage({
+        inputs: jsonFilePaths,
+        outputReport: outputReportPath,
+        formats: formats,
+        ignorePackageDirectories: ignoreDirs,
+        minCoverage: options?.minCoverage,
+        maxAnnotations: options?.maxAnnotations,
+        excludePatterns: options?.excludePatterns,
+    });
+    // The wrapper always writes (write defaults to true), so every report has a path.
+    const finalPaths = result.reports.map((r) => r.path);
+    return {
+        // Preserve historical behavior: report the requested path even when no inputs could be read.
+        finalPaths: finalPaths.length > 0 ? finalPaths : [outputReportPath],
+        warnings: result.warnings,
+        lineRate: result.summary.lineRate,
+        success: result.passed,
+    };
 }
 //# sourceMappingURL=coverageTransformer.js.map

package/lib/transformers/coverageTransformer.js.map

@@ -1 +1 @@
-{"version":3,"file":"coverageTransformer.js","sourceRoot":"","sources":["../../src/transformers/coverageTransformer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"coverageTransformer.js","sourceRoot":"","sources":["../../src/transformers/coverageTransformer.ts"],"names":[],"mappings":"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"}

package/lib/transformers/reportGenerator.d.ts

@@ -3,4 +3,6 @@ export type ReportRenderOptions = {
     maxAnnotations?: number;
 };
 export declare function generateAndWriteReport(outputPath: string, coverageObj: AnyCoverageObject, format: string, formatAmount: number, options?: ReportRenderOptions): Promise<string>;
+export declare function getReportPath(outputPath: string, format: string, formatAmount: number): string;
+export declare function generateReportContent(coverageObj: AnyCoverageObject, format: string, options?: ReportRenderOptions): string;
 export declare function getExtensionForFormat(format: string): string;

package/lib/transformers/reportGenerator.js

@@ -29,25 +29,24 @@ const STRING_FORMAT_RENDERERS = {
 };
 export async function generateAndWriteReport(outputPath, coverageObj, format, formatAmount, options) {
     const content = generateReportContent(coverageObj, format, options);
+    const filePath = getReportPath(outputPath, format, formatAmount);
+    await writeFile(filePath, content);
+    return filePath;
+}
+export function getReportPath(outputPath, format, formatAmount) {
     const extension = HandlerRegistry.getExtension(format);
     const base = basename(outputPath, extname(outputPath)); // e.g., 'coverage'
     const dir = dirname(outputPath);
     const suffix = formatAmount > 1 ? `-${format}` : '';
-    const filePath = join(dir, `${base}${suffix}${extension}`);
-    await writeFile(filePath, content, 'utf-8');
-    return filePath;
+    return join(dir, `${base}${suffix}${extension}`);
 }
-function generateReportContent(coverageObj, format, options) {
+export function generateReportContent(coverageObj, format, options) {
     const renderer = STRING_FORMAT_RENDERERS[format];
     return renderer ? renderer(coverageObj, options) : generateXmlContent(coverageObj, format);
 }
 function generateXmlContent(coverageObj, format) {
-    const isHeadless = isXmlReportFormat(format);
-    const builder = new XmlBuilder(builderOptions);
-    let xml = builder.build(coverageObj);
-    if (isHeadless) {
-        xml = xml.replace(/^<\?xml[^>]*>\s*/i, '');
-    }
+    // XmlBuilder never emits an XML declaration, so the format's header is simply prepended.
+    const xml = new XmlBuilder(builderOptions).build(coverageObj);
     return prependXmlHeader(xml, format).trimEnd();
 }
 function generateLcov(coverageObj) {
@@ -70,10 +69,8 @@ function generateLcov(coverageObj) {
         .join('\n');
 }
 function prependXmlHeader(xml, format) {
-    // Remove any existing XML declaration to avoid duplicates
-    const stripped = xml.replace(/^<\?xml[^>]*>\s*/i, '');
     const config = isXmlReportFormat(format) ? XML_HEADER_CONFIG[format] : undefined;
-    return [config?.xmlDecl ?? '<?xml version="1.0"?>', config?.doctype, stripped].filter(Boolean).join('\n');
+    return [config?.xmlDecl ?? '<?xml version="1.0"?>', config?.doctype, xml].filter(Boolean).join('\n');
 }
 export function getExtensionForFormat(format) {
     return HandlerRegistry.getExtension(format);

package/lib/transformers/reportGenerator.js.map

@@ -1 +1 @@
-{"version":3,"file":"reportGenerator.js","sourceRoot":"","sources":["../../src/transformers/reportGenerator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"reportGenerator.js","sourceRoot":"","sources":["../../src/transformers/reportGenerator.ts"],"names":[],"mappings":"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"}

package/lib/utils/errors.d.ts

@@ -0,0 +1,12 @@
+export type CoverageErrorCode = 'UNKNOWN_INPUT_FORMAT' | 'MIXED_INPUT_TYPES' | 'UNSUPPORTED_FORMAT' | 'NO_SFDX_PROJECT';
+/**
+ * Error thrown by the transformer for known failure cases.
+ * Check `code` instead of matching on `message`.
+ */
+export declare class CoverageError extends Error {
+    readonly code: CoverageErrorCode;
+    constructor(message: string, options: {
+        code: CoverageErrorCode;
+        cause?: unknown;
+    });
+}

package/lib/utils/errors.js

@@ -0,0 +1,14 @@
+'use strict';
+/**
+ * Error thrown by the transformer for known failure cases.
+ * Check `code` instead of matching on `message`.
+ */
+export class CoverageError extends Error {
+    code;
+    constructor(message, options) {
+        super(message, { cause: options.cause });
+        this.name = 'CoverageError';
+        this.code = options.code;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/lib/utils/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAIb;;;GAGG;AACH,MAAM,OAAO,aAAc,SAAQ,KAAK;IACtB,IAAI,CAAoB;IAExC,YAAmB,OAAe,EAAE,OAAqD;QACvF,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QACzC,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;CACF"}

package/lib/utils/getPackageDirectories.d.ts

@@ -1,4 +1,4 @@
-export declare function getPackageDirectories(ignoreDirectories: string[]): Promise<{
+export declare function getPackageDirectories(ignoreDirectories: string[], cwd?: string): Promise<{
     repoRoot: string;
     packageDirectories: string[];
 }>;

package/lib/utils/getPackageDirectories.js

@@ -2,8 +2,8 @@
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { getRepoRoot } from './getRepoRoot.js';
-export async function getPackageDirectories(ignoreDirectories) {
-    const { repoRoot, dxConfigFilePath } = (await getRepoRoot());
+export async function getPackageDirectories(ignoreDirectories, cwd) {
+    const { repoRoot, dxConfigFilePath } = (await getRepoRoot(cwd));
     const sfdxProjectRaw = await readFile(dxConfigFilePath, 'utf-8');
     const sfdxProject = JSON.parse(sfdxProjectRaw);
     const packageDirectories = sfdxProject.packageDirectories

package/lib/utils/getPackageDirectories.js.map

@@ -1 +1 @@
-{"version":3,"file":"getPackageDirectories.js","sourceRoot":"","sources":["../../src/utils/getPackageDirectories.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAG/C,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,iBAA2B;IAE3B,MAAM,EAAE,QAAQ,EAAE,gBAAgB,EAAE,GAAG,CAAC,MAAM,WAAW,EAAE,CAG1D,CAAC;IAEF,MAAM,cAAc,GAAW,MAAM,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC;IACzE,MAAM,WAAW,GAAgB,IAAI,CAAC,KAAK,CAAC,cAAc,CAAgB,CAAC;IAE3E,MAAM,kBAAkB,GAAG,WAAW,CAAC,kBAAkB;SACtD,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,iBAAiB,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,4BAA4B;SAC/F,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;IAEzD,OAAO,EAAE,QAAQ,EAAE,kBAAkB,EAAE,CAAC;AAC1C,CAAC"}
+{"version":3,"file":"getPackageDirectories.js","sourceRoot":"","sources":["../../src/utils/getPackageDirectories.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAG/C,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,iBAA2B,EAC3B,GAAY;IAEZ,MAAM,EAAE,QAAQ,EAAE,gBAAgB,EAAE,GAAG,CAAC,MAAM,WAAW,CAAC,GAAG,CAAC,CAG7D,CAAC;IAEF,MAAM,cAAc,GAAW,MAAM,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC;IACzE,MAAM,WAAW,GAAgB,IAAI,CAAC,KAAK,CAAC,cAAc,CAAgB,CAAC;IAE3E,MAAM,kBAAkB,GAAG,WAAW,CAAC,kBAAkB;SACtD,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,iBAAiB,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,4BAA4B;SAC/F,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;IAEzD,OAAO,EAAE,QAAQ,EAAE,kBAAkB,EAAE,CAAC;AAC1C,CAAC"}

package/lib/utils/getRepoRoot.d.ts

@@ -1,4 +1,4 @@
-export declare function getRepoRoot(): Promise<{
+export declare function getRepoRoot(cwd?: string): Promise<{
     repoRoot: string | undefined;
     dxConfigFilePath: string | undefined;
 }>;

package/lib/utils/getRepoRoot.js

@@ -1,6 +1,7 @@
 'use strict';
 import { access } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
+import { CoverageError } from './errors.js';
 async function findRepoRoot(dir) {
     const filePath = join(dir, 'sfdx-project.json');
     try {
@@ -12,14 +13,16 @@ async function findRepoRoot(dir) {
         const parentDir = dirname(dir);
         if (dir === parentDir) {
             // Reached the root without finding the file, throw an error
-            throw new Error('sfdx-project.json not found in any parent directory.', { cause: error });
+            throw new CoverageError('sfdx-project.json not found in any parent directory.', {
+                code: 'NO_SFDX_PROJECT',
+                cause: error,
+            });
         }
         // Recursively search in the parent directory
         return findRepoRoot(parentDir);
     }
 }
-export async function getRepoRoot() {
-    const currentDir = process.cwd();
-    return findRepoRoot(currentDir);
+export async function getRepoRoot(cwd) {
+    return findRepoRoot(cwd === undefined ? process.cwd() : resolve(cwd));
 }
 //# sourceMappingURL=getRepoRoot.js.map

package/lib/utils/getRepoRoot.js.map

@@ -1 +1 @@
-{"version":3,"file":"getRepoRoot.js","sourceRoot":"","sources":["../../src/utils/getRepoRoot.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AACb,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C,KAAK,UAAU,YAAY,CAAC,GAAW;IACrC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,mBAAmB,CAAC,CAAC;IAChD,IAAI,CAAC;QACH,6DAA6D;QAC7D,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC;QACvB,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,gBAAgB,EAAE,QAAQ,EAAE,CAAC;IACvD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,4DAA4D;YAC5D,MAAM,IAAI,KAAK,CAAC,sDAAsD,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5F,CAAC;QACD,6CAA6C;QAC7C,OAAO,YAAY,CAAC,SAAS,CAAC,CAAC;IACjC,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW;IAC/B,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IACjC,OAAO,YAAY,CAAC,UAAU,CAAC,CAAC;AAClC,CAAC"}
+{"version":3,"file":"getRepoRoot.js","sourceRoot":"","sources":["../../src/utils/getRepoRoot.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AACb,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,KAAK,UAAU,YAAY,CAAC,GAAW;IACrC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,mBAAmB,CAAC,CAAC;IAChD,IAAI,CAAC;QACH,6DAA6D;QAC7D,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC;QACvB,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,gBAAgB,EAAE,QAAQ,EAAE,CAAC;IACvD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,4DAA4D;YAC5D,MAAM,IAAI,aAAa,CAAC,sDAAsD,EAAE;gBAC9E,IAAI,EAAE,iBAAiB;gBACvB,KAAK,EAAE,KAAK;aACb,CAAC,CAAC;QACL,CAAC;QACD,6CAA6C;QAC7C,OAAO,YAAY,CAAC,SAAS,CAAC,CAAC;IACjC,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,GAAY;IAEZ,OAAO,YAAY,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;AACxE,CAAC"}

package/lib/utils/types.d.ts

@@ -49,14 +49,80 @@ export type LineTotals = {
     totalLines: number;
     coveredLines: number;
 };
+/** Per-file coverage totals returned by the programmatic API. */
+export type FileCoverageSummary = {
+    /** Path relative to the repo root, using forward slashes. */
+    path: string;
+    /** Apex class or trigger name as reported by Salesforce. */
+    name: string;
+    totalLines: number;
+    coveredLines: number;
+    /** Covered lines divided by total lines (0-1). 0 when the file has no coverable lines. */
+    lineRate: number;
+    /** Line numbers with no coverage, ascending. */
+    uncoveredLines: number[];
+};
 export type ProcessResult = {
     processed: number;
+    files: FileCoverageSummary[];
 } & LineTotals;
 export type TransformOptions = {
     minCoverage?: number;
     maxAnnotations?: number;
     excludePatterns?: string[];
 };
+/** Output formats supported by the transformer. */
+export type CoverageFormat = 'clover' | 'cobertura' | 'github-actions' | 'html' | 'jacoco' | 'json' | 'json-summary' | 'lcovonly' | 'markdown' | 'opencover' | 'simplecov' | 'sonar';
+/** Options for {@link transformCoverage}. */
+export type TransformCoverageOptions = {
+    /**
+     * Coverage inputs: paths to Salesforce CLI coverage JSON files and/or already-parsed JSON.
+     * All inputs must be the same type (deploy or test). Covered lines are unioned across inputs.
+     */
+    inputs: Array<string | CoverageInput>;
+    /** Output formats. Defaults to `['sonar']`. */
+    formats?: CoverageFormat[];
+    /**
+     * Base path for written reports. Defaults to `coverage.xml`. With multiple formats, the format
+     * name is appended (e.g. `coverage-sonar.xml`). Ignored when `write` is false.
+     */
+    outputReport?: string;
+    /** Write reports to disk. Defaults to true. When false, report contents are only returned. */
+    write?: boolean;
+    /** Directory to search upward from for `sfdx-project.json`. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /** Package directory paths (as written in `sfdx-project.json`) to skip. */
+    ignorePackageDirectories?: string[];
+    /** Glob patterns matched against repo-relative file paths to exclude. */
+    excludePatterns?: string[];
+    /** Minimum overall line coverage percentage (0-100). Sets `passed` to false when not met. */
+    minCoverage?: number;
+    /** Maximum annotations for the `github-actions` format. */
+    maxAnnotations?: number;
+};
+export type GeneratedReport = {
+    format: CoverageFormat;
+    /** Path the report was written to. Undefined when `write` is false. */
+    path?: string;
+    content: string;
+};
+export type CoverageSummary = {
+    /** Overall covered lines divided by total lines (0-1). */
+    lineRate: number;
+    coveredLines: number;
+    totalLines: number;
+    fileCount: number;
+    /** Per-file totals, sorted by path. */
+    files: FileCoverageSummary[];
+};
+/** Result of {@link transformCoverage}. */
+export type TransformCoverageResult = {
+    reports: GeneratedReport[];
+    summary: CoverageSummary;
+    warnings: string[];
+    /** False only when `minCoverage` is set and overall coverage is below it. */
+    passed: boolean;
+};
 type SonarLine = {
     '@lineNumber': number;
     '@covered': boolean;

package/oclif.manifest.json

@@ -91,7 +91,6 @@
         },
         "max-annotations": {
           "name": "max-annotations",
-          "required": false,
           "summary": "Maximum number of GitHub Actions ::warning annotations to emit when using --format github-actions. Defaults to 50. Annotations beyond this limit are summarised in a ::notice line.",
           "default": 50,
           "hasDynamicHelp": false,
@@ -131,5 +130,5 @@
       ]
     }
   },
-  "version": "4.1.0"
+  "version": "4.3.0"
 }

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "apex-code-coverage-transformer",
   "description": "Transform Salesforce Apex code coverage JSON for SonarQube, SonarCloud, GitHub, GitLab, Azure, and Bitbucket",
-  "version": "4.1.0",
+  "version": "4.3.0",
   "dependencies": {
-    "@oclif/core": "5.1.10",
+    "@oclif/core": "5.1.11",
     "@salesforce/core": "9.4.4",
     "@salesforce/sf-plugins-core": "13.0.8"
   },
@@ -12,12 +12,12 @@
     "@biomejs/biome": "2.6.5",
     "@commitlint/cli": "21.2.4",
     "@commitlint/config-conventional": "21.2.4",
-    "@salesforce/cli-plugins-testkit": "5.3.83",
+    "@salesforce/cli-plugins-testkit": "5.3.90",
     "@salesforce/dev-config": "4.3.3",
     "@stryker-mutator/core": "10.1.1",
     "@stryker-mutator/vitest-runner": "10.1.1",
     "@types/node": "26.6.6",
-    "@vitest/coverage-v8": "5.0.5",
+    "@vitest/coverage-v8": "5.1.0",
     "esbuild": "0.28.2",
     "husky": "9.1.7",
     "knip": "6.44.1",
@@ -27,7 +27,7 @@
     "shx": "0.4.0",
     "tsx": "4.23.15",
     "typescript": "7.0.2",
-    "vitest": "5.0.5",
+    "vitest": "5.1.0",
     "wireit": "0.15.0"
   },
   "engines": {
@@ -88,6 +88,7 @@
   "scripts": {
     "build": "wireit",
     "build:action": "wireit",
+    "build:core": "wireit",
     "clean": "wireit",
     "clean:build": "wireit",
     "clean:package-manager": "wireit",
@@ -145,7 +146,8 @@
       "dependencies": [
         "compile",
         "lint",
-        "build:action"
+        "build:action",
+        "build:core"
       ]
     },
     "build:action": {
@@ -162,6 +164,25 @@
       ],
       "clean": false
     },
+    "build:core": {
+      "command": "tsc -p tsconfig.core.json && shx cp LICENSE.md packages/core/LICENSE.md && node scripts/verify-core-package.mjs",
+      "files": [
+        "src/**/*.ts",
+        "!src/commands/**",
+        "!src/hooks/**",
+        "!src/action/**",
+        "tsconfig.json",
+        "tsconfig.core.json",
+        "packages/core/package.json",
+        "LICENSE.md",
+        "scripts/verify-core-package.mjs"
+      ],
+      "output": [
+        "packages/core/lib/**",
+        "packages/core/LICENSE.md"
+      ],
+      "clean": true
+    },
     "compile": {
       "command": "tsc -p . --pretty --incremental",
       "files": [
@@ -324,7 +345,14 @@
       "output": []
     }
   },
-  "exports": "./lib/index.js",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./lib/index.d.ts",
   "type": "module",
   "author": "Matt Carvin",
   "repository": {