@cspell/cspell-junit-reporter 10.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 cspell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# `@cspell/cspell-junit-reporter`
+
+> CSpell reporter with JUnit XML output
+
+Emits a [JUnit](https://github.com/testmoapp/junitxml) compatible XML report of a cspell run, suitable for
+consumption by CI systems (GitHub Actions, GitLab, Jenkins, CircleCI, etc.) that understand the JUnit test
+result format.
+
+## Installation
+
+Install it as a development package in the repository that will use it.
+
+```sh
+npm install -SD @cspell/cspell-junit-reporter
+```
+
+## Usage
+
+### Using Command Line
+
+```sh
+cspell . --reporter @cspell/cspell-junit-reporter
+```
+
+### Using CSpell Configuration
+
+Add this to `cspell.yaml`:
+
+```yaml
+reporters: [['@cspell/cspell-junit-reporter', { outFile: 'cspell-junit.xml' }]]
+```
+
+or `cspell.json`
+
+```json
+{
+  "reporters": [["@cspell/cspell-junit-reporter", { "outFile": "cspell-junit.xml" }]]
+}
+```
+
+## Output format
+
+`@cspell/cspell-junit-reporter` maps a cspell run onto JUnit XML as follows:
+
+- one `<testsuites>` root element for the whole run
+- one `<testsuite>` per file checked, named after the file
+- one `<testcase>` per spelling issue found in a file, containing a `<failure>` with the misspelled word,
+  location, and message
+- a file with no issues gets a single passing `<testcase>` so the suite is never empty
+- a skipped file gets a single `<testcase>` containing a `<skipped>` element
+- processing errors that are not tied to a specific spelling issue (for example, a bad config file) are
+  reported in a dedicated `cspell-errors` testsuite using `<error>` instead of `<failure>`
+
+All file paths, words, and messages are escaped so the output is valid XML even when they contain
+`& < > " '` characters.
+
+Example output for a single file with one issue:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<testsuites name="cspell" tests="1" failures="1" errors="0" time="0.001">
+  <testsuite name="src/example.ts" tests="1" failures="1" errors="0" time="0.001">
+    <testcase name="teh (3:5)" classname="src/example.ts">
+      <failure type="spelling" message="Unknown word: &quot;teh&quot;">Unknown word: "teh"</failure>
+    </testcase>
+  </testsuite>
+</testsuites>
+```
+
+## Settings
+
+Possible settings:
+
+- `outFile` (default: stdout) - path for the XML file to emit
+- `suiteName` (default: `cspell`) - name used for the root `<testsuites>` element
+
+<details>
+<summary>Reporter Settings</summary>
+
+<!--- @@inject: src/CSpellJUnitReporterSettings.ts --->
+
+```ts
+/**
+ * cspell-junit-reporter settings type definition
+ */
+export type CSpellJUnitReporterSettings = {
+  /**
+   * Path to the output JUnit XML file.
+   *
+   * Relative paths are relative to the current working directory.
+   *
+   * Special values:
+   * - `stdout` - write the XML to `stdout`.
+   * - `stderr` - write the XML to `stderr`.
+   *
+   * @default stdout
+   */
+  outFile?: string;
+  /**
+   * Name to use for the root `<testsuites>` element.
+   *
+   * @default cspell
+   */
+  suiteName?: string;
+};
+```
+
+<!--- @@inject-end: src/CSpellJUnitReporterSettings.ts --->
+
+</details>

package/dist/esm/CSpellJUnitReporterSettings.d.ts

@@ -0,0 +1,24 @@
+/**
+ * cspell-junit-reporter settings type definition
+ */
+export type CSpellJUnitReporterSettings = {
+    /**
+     * Path to the output JUnit XML file.
+     *
+     * Relative paths are relative to the current working directory.
+     *
+     * Special values:
+     * - `stdout` - write the XML to `stdout`.
+     * - `stderr` - write the XML to `stderr`.
+     *
+     * @default stdout
+     */
+    outFile?: string;
+    /**
+     * Name to use for the root `<testsuites>` element.
+     *
+     * @default cspell
+     */
+    suiteName?: string;
+};
+//# sourceMappingURL=CSpellJUnitReporterSettings.d.ts.map

package/dist/esm/CSpellJUnitReporterSettings.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=CSpellJUnitReporterSettings.js.map

package/dist/esm/index.d.ts

@@ -0,0 +1,9 @@
+import type { CSpellReporter, ReporterConfiguration } from '@cspell/cspell-types';
+import type { CSpellJUnitReporterSettings } from './CSpellJUnitReporterSettings.js';
+type ReporterConsole = Pick<Console, 'log' | 'warn' | 'error'>;
+export interface CSpellJUnitReporterConfiguration extends ReporterConfiguration {
+    console?: ReporterConsole;
+}
+export declare function getReporter(settings: unknown | CSpellJUnitReporterSettings, cliOptions?: CSpellJUnitReporterConfiguration): Required<CSpellReporter>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/index.js

@@ -0,0 +1,68 @@
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { buildJUnitXml } from './utils/buildJUnitXml.js';
+import { validateSettings } from './utils/validateSettings.js';
+function mkdirp(p) {
+    return fs.mkdir(p, { recursive: true });
+}
+const STDOUT = 'stdout';
+const STDERR = 'stderr';
+export function getReporter(settings, cliOptions) {
+    const useSettings = normalizeSettings(settings);
+    const console = cliOptions?.console ?? globalThis.console;
+    const files = new Map();
+    const errors = [];
+    const fileOrder = [];
+    function getOrCreateFile(filename) {
+        const existing = files.get(filename);
+        if (existing)
+            return existing;
+        const created = { filename, issues: [] };
+        files.set(filename, created);
+        fileOrder.push(filename);
+        return created;
+    }
+    return {
+        issue: (issue) => {
+            const filename = issue.uri || '(unknown)';
+            getOrCreateFile(filename).issues.push(issue);
+        },
+        info: () => undefined,
+        debug: () => undefined,
+        error: (message, error) => {
+            errors.push({ message, error });
+        },
+        progress: (item) => {
+            if (item.type !== 'ProgressFileComplete')
+                return;
+            const file = getOrCreateFile(item.filename);
+            file.elapsedTimeMs = item.elapsedTimeMs;
+            file.processed = item.processed;
+            file.skippedReason = item.skippedReason;
+        },
+        result: async () => {
+            const orderedFiles = fileOrder.map((filename) => files.get(filename)).filter((f) => !!f);
+            const xml = buildJUnitXml(orderedFiles, errors, { suiteName: useSettings.suiteName || 'cspell' });
+            const outFile = useSettings.outFile || STDOUT;
+            if (outFile === STDOUT) {
+                console.log(xml);
+                return;
+            }
+            if (outFile === STDERR) {
+                console.error(xml);
+                return;
+            }
+            const outFilePath = path.join(cliOptions?.root ?? process.cwd(), outFile);
+            await mkdirp(path.dirname(outFilePath));
+            return fs.writeFile(outFilePath, xml);
+        },
+        features: undefined,
+    };
+}
+function normalizeSettings(settings) {
+    if (settings === undefined)
+        return { outFile: STDOUT, suiteName: 'cspell' };
+    validateSettings(settings);
+    return settings;
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/utils/buildJUnitXml.d.ts

@@ -0,0 +1,47 @@
+import type { ErrorLike, Issue } from '@cspell/cspell-types';
+/**
+ * A single file that was checked by cspell.
+ *
+ * Maps to one `<testsuite>` element. Each spelling {@link Issue} found in the
+ * file maps to one `<testcase>` containing a `<failure>`. A file with no
+ * issues is reported as a single passing `<testcase>` so the suite is never
+ * empty (this mirrors the convention used by other JUnit reporters, e.g. the
+ * ESLint JUnit formatter).
+ */
+export interface FileReport {
+    /** File name/uri as reported by cspell. */
+    filename: string;
+    /** Spelling issues found in the file. */
+    issues: Issue[];
+    /** Time, in milliseconds, spent processing the file (if known). */
+    elapsedTimeMs?: number | undefined;
+    /** `false` if the file was skipped (not processed). */
+    processed?: boolean | undefined;
+    /** Reason the file was skipped, if applicable. */
+    skippedReason?: string | undefined;
+}
+/**
+ * A processing error reported by cspell that is not tied to a specific
+ * spelling issue (e.g. a bad config file or an unreadable file).
+ */
+export interface ErrorReport {
+    message: string;
+    error: ErrorLike;
+}
+export interface JUnitXmlOptions {
+    /** Name for the root `<testsuites>` element. */
+    suiteName: string;
+}
+/**
+ * Builds a JUnit compatible XML document from the results of a cspell run.
+ *
+ * Mapping:
+ * - one `<testsuites>` root for the whole run
+ * - one `<testsuite>` per file checked
+ * - one `<testcase>` per spelling issue found in a file, containing a `<failure>`
+ * - a single passing `<testcase>` for files with no issues
+ * - processing errors (not tied to a spelling issue) are reported in a
+ *   dedicated `cspell-errors` testsuite using `<error>` instead of `<failure>`
+ */
+export declare function buildJUnitXml(files: FileReport[], errors: ErrorReport[], options: JUnitXmlOptions): string;
+//# sourceMappingURL=buildJUnitXml.d.ts.map

package/dist/esm/utils/buildJUnitXml.js

@@ -0,0 +1,99 @@
+import { IssueType } from '@cspell/cspell-types';
+import { escapeXmlAttribute, escapeXmlText } from './escapeXml.js';
+function formatTime(ms) {
+    return ((ms ?? 0) / 1000).toFixed(3);
+}
+function issueName(issue) {
+    const location = `${issue.row}:${issue.col}`;
+    return `${issue.text} (${location})`;
+}
+function issueMessage(issue) {
+    if (issue.message)
+        return issue.message;
+    return `Unknown word: "${issue.text}"`;
+}
+function buildTestCaseForIssue(filename, issue) {
+    const name = escapeXmlAttribute(issueName(issue));
+    const classname = escapeXmlAttribute(filename);
+    const failureType = escapeXmlAttribute(issue.issueType === IssueType.directive ? 'directive' : 'spelling');
+    const message = escapeXmlAttribute(issueMessage(issue));
+    const body = escapeXmlText(issueMessage(issue));
+    return (`    <testcase name="${name}" classname="${classname}">\n` +
+        `      <failure type="${failureType}" message="${message}">${body}</failure>\n` +
+        `    </testcase>\n`);
+}
+function buildPassingTestCase(filename) {
+    const classname = escapeXmlAttribute(filename);
+    return `    <testcase name="no issues found" classname="${classname}"/>\n`;
+}
+function buildSkippedTestCase(filename, reason) {
+    const classname = escapeXmlAttribute(filename);
+    const message = reason ? ` message="${escapeXmlAttribute(reason)}"` : '';
+    return `    <testcase name="skipped" classname="${classname}">\n      <skipped${message}/>\n    </testcase>\n`;
+}
+function fileSuiteCounts(file) {
+    if (file.processed === false)
+        return { tests: 1, failures: 0 };
+    const issueCount = file.issues.length;
+    return { tests: Math.max(issueCount, 1), failures: issueCount };
+}
+function buildTestSuiteForFile(file) {
+    const name = escapeXmlAttribute(file.filename);
+    const time = formatTime(file.elapsedTimeMs);
+    let testCases;
+    if (file.processed === false) {
+        testCases = buildSkippedTestCase(file.filename, file.skippedReason);
+    }
+    else if (file.issues.length) {
+        testCases = file.issues.map((issue) => buildTestCaseForIssue(file.filename, issue)).join('');
+    }
+    else {
+        testCases = buildPassingTestCase(file.filename);
+    }
+    const { tests, failures } = fileSuiteCounts(file);
+    return (`  <testsuite name="${name}" tests="${tests}" failures="${failures}" errors="0" time="${time}">\n` +
+        testCases +
+        `  </testsuite>\n`);
+}
+function buildTestSuiteForErrors(errors) {
+    const testCases = errors
+        .map(({ message, error }) => {
+        const name = escapeXmlAttribute(message);
+        const errorMessage = escapeXmlAttribute(error.message);
+        const body = escapeXmlText(error.message);
+        return (`    <testcase name="${name}" classname="cspell">\n` +
+            `      <error type="error" message="${errorMessage}">${body}</error>\n` +
+            `    </testcase>\n`);
+    })
+        .join('');
+    return (`  <testsuite name="cspell-errors" tests="${errors.length}" failures="0" errors="${errors.length}" time="0.000">\n` +
+        testCases +
+        `  </testsuite>\n`);
+}
+/**
+ * Builds a JUnit compatible XML document from the results of a cspell run.
+ *
+ * Mapping:
+ * - one `<testsuites>` root for the whole run
+ * - one `<testsuite>` per file checked
+ * - one `<testcase>` per spelling issue found in a file, containing a `<failure>`
+ * - a single passing `<testcase>` for files with no issues
+ * - processing errors (not tied to a spelling issue) are reported in a
+ *   dedicated `cspell-errors` testsuite using `<error>` instead of `<failure>`
+ */
+export function buildJUnitXml(files, errors, options) {
+    const suiteName = escapeXmlAttribute(options.suiteName);
+    const fileSuites = files.map(buildTestSuiteForFile);
+    const errorSuite = errors.length ? [buildTestSuiteForErrors(errors)] : [];
+    const suites = [...fileSuites, ...errorSuite];
+    const fileCounts = files.map(fileSuiteCounts);
+    const totalTests = fileCounts.reduce((sum, counts) => sum + counts.tests, errors.length);
+    const totalFailures = fileCounts.reduce((sum, counts) => sum + counts.failures, 0);
+    const totalErrors = errors.length;
+    const totalTime = files.reduce((sum, file) => sum + (file.elapsedTimeMs ?? 0), 0) / 1000;
+    return ('<?xml version="1.0" encoding="UTF-8"?>\n' +
+        `<testsuites name="${suiteName}" tests="${totalTests}" failures="${totalFailures}" errors="${totalErrors}" time="${totalTime.toFixed(3)}">\n` +
+        suites.join('') +
+        '</testsuites>\n');
+}
+//# sourceMappingURL=buildJUnitXml.js.map

package/dist/esm/utils/escapeXml.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Escapes text so it is safe to embed inside an XML element's text content.
+ */
+export declare function escapeXmlText(value: string): string;
+/**
+ * Escapes text so it is safe to embed inside a double-quoted XML attribute value.
+ */
+export declare function escapeXmlAttribute(value: string): string;
+//# sourceMappingURL=escapeXml.d.ts.map

package/dist/esm/utils/escapeXml.js

@@ -0,0 +1,27 @@
+// Control characters that should not appear literally in XML 1.0 output
+// (tab \t, newline \n, and carriage return \r are allowed).
+// eslint-disable-next-line no-control-regex
+const invalidXmlChars = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F-\x84\x86-\x9F]/g;
+/**
+ * Escapes text so it is safe to embed inside an XML element's text content.
+ */
+export function escapeXmlText(value) {
+    return value
+        .replaceAll(invalidXmlChars, '')
+        .replaceAll('&', '&')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;');
+}
+/**
+ * Escapes text so it is safe to embed inside a double-quoted XML attribute value.
+ */
+export function escapeXmlAttribute(value) {
+    return value
+        .replaceAll(invalidXmlChars, '')
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&apos;'); // cspell:ignore apos
+}
+//# sourceMappingURL=escapeXml.js.map

package/dist/esm/utils/validateSettings.d.ts

@@ -0,0 +1,6 @@
+import type { CSpellJUnitReporterSettings } from '../CSpellJUnitReporterSettings.js';
+/**
+ * Throws an error if passed cspell-junit-reporter settings are invalid
+ */
+export declare function validateSettings(settings: unknown): asserts settings is CSpellJUnitReporterSettings;
+//# sourceMappingURL=validateSettings.d.ts.map

package/dist/esm/utils/validateSettings.js

@@ -0,0 +1,29 @@
+import { AssertionError } from 'node:assert';
+/**
+ * Throws an error if passed cspell-junit-reporter settings are invalid
+ */
+export function validateSettings(settings) {
+    if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
+        throw new AssertionError({
+            message: 'cspell-junit-reporter settings must be an object',
+            actual: typeof settings,
+            expected: 'object',
+        });
+    }
+    const { outFile = 'stdout', suiteName = 'cspell' } = settings;
+    if (typeof outFile !== 'string') {
+        throw new AssertionError({
+            message: 'cspell-junit-reporter settings.outFile must be a string',
+            actual: typeof outFile,
+            expected: 'string',
+        });
+    }
+    if (typeof suiteName !== 'string') {
+        throw new AssertionError({
+            message: 'cspell-junit-reporter settings.suiteName must be a string',
+            actual: typeof suiteName,
+            expected: 'string',
+        });
+    }
+}
+//# sourceMappingURL=validateSettings.js.map

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@cspell/cspell-junit-reporter",
+  "version": "10.1.0",
+  "description": "JUnit XML reporter for CSpell",
+  "keywords": [
+    "cspell",
+    "spelling",
+    "reporter",
+    "junit",
+    "junit-xml",
+    "ci"
+  ],
+  "author": "Jason Dent",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/streetsidesoftware/cspell/labels/cspell-junit-reporter"
+  },
+  "homepage": "https://github.com/streetsidesoftware/cspell/tree/main/packages/cspell-junit-reporter#readme",
+  "type": "module",
+  "sideEffects": false,
+  "types": "dist/esm/index.d.ts",
+  "module": "dist/esm/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!**/*.tsbuildInfo",
+    "!**/__mocks__",
+    "!**/test/**",
+    "!**/*.test.*",
+    "!**/*.spec.*",
+    "!**/*.map"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/streetsidesoftware/cspell.git",
+    "directory": "packages/cspell-junit-reporter"
+  },
+  "scripts": {
+    "clean": "shx rm -rf dist temp coverage \"*.tsbuildInfo\"",
+    "build": "tsc -b . -f",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "clean-build": "pnpm run clean && pnpm run build",
+    "coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "test": "vitest run && pnpm test:run",
+    "test:run": "node ../../bin.mjs . --config cSpell.example.mjs",
+    "watch": "tsc -b . -w -f"
+  },
+  "dependencies": {
+    "@cspell/cspell-types": "10.1.0"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "gitHead": "401518c5e37c06fb406aedadb3fc7a1c27eca8e6"
+}