@ovh-ux/manager-static-analysis-kit 0.8.0 → 0.9.0

package/bin/utils/runner-utils.js

@@ -0,0 +1,85 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+
+import { resolveAppInfo } from './apps-utils.js';
+import { generateCombinedReports } from './file-utils.js';
+import { logError, logInfo } from './log-utils.js';
+
+/**
+ * Ensure the given binary exists.
+ */
+export function ensureBinExists(binPath, label) {
+  if (!fs.existsSync(binPath)) {
+    logError(`❌ ${label} binary not found at ${binPath}`);
+    process.exit(1);
+  }
+}
+
+/**
+ * Run a child process with consistent defaults.
+ */
+export function runCommand(bin, args, cwd) {
+  const result = spawnSync(bin, args, {
+    cwd,
+    stdio: 'inherit',
+    shell: true,
+  });
+  return result.status === 0;
+}
+
+/**
+ * Generic per-app analysis runner with safety.
+ */
+export function runAppsAnalysis({
+  appsDir,
+  appFolders,
+  requireReact = false,
+  binaryLabel,
+  appRunner, // (appDir, appShortName, appInfo) => boolean
+  reportsRootDirName,
+  combinedJson,
+  combinedHtml,
+  collectFn,
+  generateHtmlFn,
+  outputRootDir,
+}) {
+  const analyzed = [];
+
+  for (const appFolder of appFolders) {
+    const appInfo = resolveAppInfo(appsDir, appFolder, { requireReact });
+    if (!appInfo) continue;
+
+    let ok = false;
+    try {
+      ok = appRunner(appInfo.appDir, appInfo.appShortName, appInfo);
+    } catch (err) {
+      logError(
+        `❌ Fatal error while analyzing ${appInfo.appShortName}: ${err.stack || err.message}`,
+      );
+    }
+    if (ok) analyzed.push(appInfo.appShortName);
+  }
+
+  if (analyzed.length > 0) {
+    if (typeof collectFn !== 'function' || typeof generateHtmlFn !== 'function') {
+      logError(`❌ Invalid collector or HTML generator passed to ${binaryLabel} analysis`);
+      process.exit(1);
+    }
+
+    generateCombinedReports(
+      path.join(outputRootDir, reportsRootDirName),
+      combinedJson,
+      combinedHtml,
+      collectFn,
+      generateHtmlFn,
+    );
+    logInfo(`✅ ${binaryLabel} reports generated (per-app + combined).`);
+  } else {
+    logError('❌ No apps successfully analyzed. Exiting.');
+    process.exit(1);
+  }
+
+  return analyzed;
+}

package/bin/utils/turbo-utils.js

@@ -0,0 +1,139 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { logError, logInfo, logWarn } from './log-utils.js';
+
+/**
+ * Convert app folder names into Turbo filters by resolving their package.json names.
+ *
+ * Each app folder must contain a valid `package.json`. If not found, the app is skipped.
+ *
+ * @param {string} appsDir - Absolute path to the apps root directory.
+ * @param {string[]} appFolders - List of app folder names inside the apps directory.
+ * @returns {string[]} Array of package names to be used as Turbo filters.
+ *
+ * @example
+ * // appsDir = "/workspace/manager/apps"
+ * // appFolders = ["zimbra", "web"]
+ * // Returns: ["@ovh-ux/manager-zimbra-app", "@ovh-ux/manager-web-app"]
+ */
+function resolveTurboFiltersFromAppFolders(appsDir, appFolders) {
+  return appFolders
+    .map((appFolder) => {
+      const pkgPath = path.join(appsDir, appFolder, 'package.json');
+      if (!fs.existsSync(pkgPath)) {
+        logError(`❌ No package.json for app folder ${appFolder}, skipping`);
+        return null;
+      }
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+      return pkg.name;
+    })
+    .filter(Boolean);
+}
+
+/**
+ * Resolve Turbo filters (package names) based on input mode.
+ *
+ * - If only `appFolders` are provided, resolves their corresponding package names.
+ * - If `packageNames` are provided, they are used directly as filters.
+ *
+ * @param {Object} options
+ * @param {string} options.appsDir - Absolute path to the apps root directory.
+ * @param {string[]} options.appFolders - List of app folders to analyze.
+ * @param {string[]} options.packageNames - List of package names (overrides appFolders).
+ * @returns {string[]} List of resolved Turbo filters (package names).
+ *
+ * @example
+ * resolveTurboFilters({
+ *   appsDir: "/workspace/manager/apps",
+ *   appFolders: ["zimbra"],
+ *   packageNames: []
+ * });
+ * // → ["@ovh-ux/manager-zimbra-app"]
+ *
+ * @example
+ * resolveTurboFilters({
+ *   appsDir: "/workspace/manager/apps",
+ *   appFolders: [],
+ *   packageNames: ["@ovh-ux/manager-web-app"]
+ * });
+ * // → ["@ovh-ux/manager-web-app"]
+ */
+export function resolveTurboFilters({ appsDir, appFolders, packageNames }) {
+  let filters = [];
+
+  if (appFolders.length > 0 && packageNames.length === 0) {
+    filters = resolveTurboFiltersFromAppFolders(appsDir, appFolders);
+  } else if (packageNames.length > 0) {
+    filters = packageNames;
+  }
+
+  return filters;
+}
+
+/**
+ * Run a Turbo build for the provided filters.
+ *
+ * - Executes `turbo run build` with `--filter` for each package name.
+ * - Runs in the specified root directory.
+ * - If no filters are provided, the build step is skipped with a warning.
+ *
+ * @param {string} rootDir - Root directory where Turbo should be executed.
+ * @param {string[]} filters - List of Turbo build filters (package names).
+ * @returns {void}
+ *
+ * @example
+ * runTurboBuild("/workspace", ["@ovh-ux/manager-zimbra-app"]);
+ * // Executes: turbo run build --filter @ovh-ux/manager-zimbra-app
+ */
+export function runTurboBuild(rootDir, filters) {
+  if (filters.length === 0) {
+    logWarn('⚠️ No Turbo build filters provided, skipping build step.');
+    return;
+  }
+
+  const turboArgs = ['run', 'build', ...filters.flatMap((pkgName) => ['--filter', pkgName])];
+  logInfo(`Building with Turbo (filters: ${filters.join(', ')})`);
+
+  const buildResult = spawnSync('turbo', turboArgs, {
+    cwd: rootDir,
+    stdio: 'inherit',
+    shell: true,
+  });
+
+  if (buildResult.status !== 0) {
+    logWarn('⚠️ Turbo build failed for one or more targets. Will still try to analyze apps.');
+  }
+}
+
+/**
+ * Run Turbo tests with optional filters and extra arguments.
+ *
+ * This function spawns a synchronous Turbo process to run tests,
+ * applying filters for specific packages if provided. It logs
+ * progress and warns if any tests fail, but does not throw.
+ *
+ * @param {string} rootDir - Root directory to run Turbo in (typically the monorepo root).
+ * @param {string[]} filters - List of package filters (Turbo `--filter` flags).
+ * @param {string[]} [extraArgs=[]] - Additional arguments to forward to Turbo.
+ * @returns {void}
+ *
+ * @example
+ * // Run tests for "web" and "zimbra" apps with coverage
+ * runTurboTests(process.cwd(), ['web', 'zimbra'], ['--', '--coverage']);
+ */
+export function runTurboTests(rootDir, filters, extraArgs = []) {
+  const args = ['run', 'test', ...filters.flatMap((pkg) => ['--filter', pkg]), ...extraArgs];
+  logInfo(`Testing with Turbo (filters: ${filters.join(', ')})`);
+
+  const res = spawnSync('turbo', args, {
+    cwd: rootDir,
+    stdio: 'inherit',
+    shell: true,
+  });
+
+  if (res.status !== 0) {
+    logWarn('⚠️ Turbo tests failed for one or more targets. Will still harvest coverage if any.');
+  }
+}

package/dist/adapters/code-duplication/helpers/code-duplication-analysis-helper.d.ts

@@ -0,0 +1,6 @@
+import { CombinedCodeDuplicationSummary, JscpdReportV4, WorstCodeDuplicationFile } from '../types/CodeDuplication.js';
+export declare const extPriority: (file: string) => number;
+export declare function extractWorstFiles(report: JscpdReportV4): WorstCodeDuplicationFile[];
+export declare function collectCodeDuplication(reportOutputDir: string): CombinedCodeDuplicationSummary;
+export declare function generateCodeDuplicationHtml(summary: CombinedCodeDuplicationSummary): string;
+//# sourceMappingURL=code-duplication-analysis-helper.d.ts.map

package/dist/adapters/code-duplication/helpers/code-duplication-analysis-helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-duplication-analysis-helper.d.ts","sourceRoot":"","sources":["../../../../src/adapters/code-duplication/helpers/code-duplication-analysis-helper.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,8BAA8B,EAC9B,aAAa,EACb,wBAAwB,EAEzB,MAAM,0BAA0B,CAAC;AAUlC,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,KAAG,MAc1C,CAAC;AAkEF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa,GAAG,wBAAwB,EAAE,CAsEnF;AAkED,wBAAgB,sBAAsB,CAAC,eAAe,EAAE,MAAM,GAAG,8BAA8B,CA+B9F;AAyGD,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,8BAA8B,GAAG,MAAM,CAmC3F"}

package/dist/adapters/code-duplication/helpers/code-duplication-analysis-helper.js

@@ -0,0 +1,240 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { codeDuplicationConfig } from '../../../configs/code-duplication-config.js';
+export const extPriority = (file) => {
+    const f = file.toLowerCase();
+    if (/\.(d\.ts)$/.test(f))
+        return 2;
+    if (/\.(tsx?|mts|cts)$/.test(f))
+        return 0;
+    if (/\.(jsx?|mjs|cjs)$/.test(f))
+        return 1;
+    return 2;
+};
+const safeCountLines = (file) => {
+    try {
+        const txt = fs.readFileSync(file, 'utf8');
+        return txt.split(/\r?\n/).length;
+    }
+    catch {
+        return 0;
+    }
+};
+function shortPathFromAppsRoot(filePath, app) {
+    const norm = filePath.replace(/\\/g, '/');
+    const appsIdx = norm.indexOf('/apps/');
+    if (appsIdx >= 0) {
+        return norm.slice(appsIdx + 1);
+    }
+    const parts = norm.split('/');
+    return parts.slice(Math.max(0, parts.length - 5)).join('/');
+}
+export function extractWorstFiles(report) {
+    const dups = Array.isArray(report?.duplicates) ? report.duplicates : [];
+    if (dups.length === 0)
+        return [];
+    const { threshold, count } = codeDuplicationConfig.worstFiles;
+    const fileMap = {};
+    for (const dup of dups) {
+        const lines = Number(dup?.lines ?? 0);
+        if (!lines)
+            continue;
+        for (const side of [dup.firstFile, dup.secondFile]) {
+            const file = side?.name;
+            if (!file)
+                continue;
+            const endLine = Number(side?.endLoc?.line ?? 0);
+            const entry = fileMap[file] ?? { dup: 0, estimatedTotal: 0 };
+            entry.dup += lines;
+            if (endLine > entry.estimatedTotal)
+                entry.estimatedTotal = endLine;
+            fileMap[file] = entry;
+        }
+    }
+    for (const file of Object.keys(fileMap)) {
+        const realTotal = safeCountLines(file);
+        const estTotal = fileMap[file].estimatedTotal;
+        fileMap[file].total = Math.max(realTotal || estTotal || 0, fileMap[file].dup);
+    }
+    return Object.entries(fileMap)
+        .map(([file, { dup, total = 0 }]) => {
+        const percentage = total > 0 ? (dup / total) * 100 : 0;
+        const stats = {
+            duplicatedLines: dup,
+            totalLines: total,
+            percentage,
+        };
+        return [file, stats];
+    })
+        .filter(([, s]) => s.percentage >= threshold)
+        .sort((a, b) => {
+        const pa = extPriority(a[0]);
+        const pb = extPriority(b[0]);
+        if (pa !== pb)
+            return pa - pb;
+        const pct = b[1].percentage - a[1].percentage;
+        if (pct !== 0)
+            return pct;
+        if (b[1].duplicatedLines !== a[1].duplicatedLines) {
+            return b[1].duplicatedLines - a[1].duplicatedLines;
+        }
+        if (b[1].totalLines !== a[1].totalLines) {
+            return b[1].totalLines - a[1].totalLines;
+        }
+        return a[0].localeCompare(b[0]);
+    })
+        .slice(0, count);
+}
+function parseAppCodeDuplicationReport(jsonPath) {
+    try {
+        const report = JSON.parse(fs.readFileSync(jsonPath, 'utf-8'));
+        const total = report.statistics?.total ?? {};
+        const totalLines = total.lines ?? 0;
+        const duplicateLines = total.duplicatedLines ?? 0;
+        return {
+            totalLines,
+            totalTokens: total.tokens ?? 0,
+            duplicateLines,
+            duplicateTokens: total.duplicatedTokens ?? 0,
+            clonesCount: total.clones ?? 0,
+            percentage: total.percentage ?? (totalLines > 0 ? (duplicateLines / totalLines) * 100 : 0),
+            worstFiles: extractWorstFiles(report),
+        };
+    }
+    catch (err) {
+        return {
+            totalLines: 0,
+            totalTokens: 0,
+            duplicateLines: 0,
+            duplicateTokens: 0,
+            clonesCount: 0,
+            percentage: 0,
+            error: err.message,
+            worstFiles: [],
+        };
+    }
+}
+function aggregateTotals(apps) {
+    return Object.values(apps).reduce((acc, app) => {
+        acc.totalLines += app.totalLines;
+        acc.totalTokens += app.totalTokens;
+        acc.totalDuplicateLines += app.duplicateLines;
+        acc.totalDuplicateTokens += app.duplicateTokens;
+        return acc;
+    }, { totalLines: 0, totalTokens: 0, totalDuplicateLines: 0, totalDuplicateTokens: 0 });
+}
+export function collectCodeDuplication(reportOutputDir) {
+    if (!fs.existsSync(reportOutputDir)) {
+        return {
+            apps: {},
+            totalLines: 0,
+            totalTokens: 0,
+            totalDuplicateLines: 0,
+            totalDuplicateTokens: 0,
+            percentage: 0,
+        };
+    }
+    const apps = {};
+    const appDirs = fs
+        .readdirSync(reportOutputDir)
+        .filter((entry) => fs.statSync(path.join(reportOutputDir, entry)).isDirectory());
+    for (const appDirName of appDirs) {
+        const jsonPath = path.join(reportOutputDir, appDirName, 'jscpd-report.json');
+        if (fs.existsSync(jsonPath)) {
+            apps[appDirName] = parseAppCodeDuplicationReport(jsonPath);
+        }
+    }
+    const totals = aggregateTotals(apps);
+    return {
+        apps,
+        ...totals,
+        percentage: totals.totalLines > 0 ? (totals.totalDuplicateLines / totals.totalLines) * 100 : 0,
+    };
+}
+const getColorForDuplicationStatus = (pct) => {
+    const green = codeDuplicationConfig.thresholds?.green ?? 10;
+    const orange = codeDuplicationConfig.thresholds?.orange ?? 20;
+    return pct < green ? 'green' : pct < orange ? 'orange' : 'red';
+};
+function renderWorstFiles(app, worstFiles = []) {
+    if (!worstFiles.length) {
+        return `
+      <details>
+        <summary>⚠️ Worst duplicated files</summary>
+        <p style="margin:0.5rem 0; color:#888;">No files above threshold 🎉</p>
+      </details>`;
+    }
+    const rows = worstFiles
+        .map(([file, f]) => {
+        const short = shortPathFromAppsRoot(file, app);
+        const color = getColorForDuplicationStatus(f.percentage);
+        return `
+      <tr>
+        <td colspan="2" title="${file}">${short}</td>
+        <td>${f.duplicatedLines}/${f.totalLines}</td>
+        <td style="color:${color}">${f.percentage.toFixed(2)}%</td>
+      </tr>`;
+    })
+        .join('');
+    return `
+    <details>
+      <summary>⚠️ Worst duplicated files (≥ ${codeDuplicationConfig.worstFiles.threshold}%)</summary>
+      <table style="margin:0.5rem 0; border:1px solid #ccc; width:95%;">
+        <tbody>${rows}</tbody>
+      </table>
+    </details>`;
+}
+function buildAppRow(app, stats) {
+    if (stats.error) {
+        return `<tr style="background:#ffe0e0">
+      <td>${app}</td>
+      <td colspan="5" style="color:red">${stats.error}</td>
+    </tr>`;
+    }
+    const color = getColorForDuplicationStatus(stats.percentage);
+    const bg = color === 'green' ? '#e6ffed' : color === 'orange' ? '#fff8e1' : '#ffe6e6';
+    return `
+<tr style="background:${bg}">
+  <td>${app}</td>
+  <td>${stats.totalLines}</td>
+  <td>${stats.duplicateLines}</td>
+  <td>${stats.clonesCount}</td>
+  <td style="font-weight:bold; color:${color};">${stats.percentage.toFixed(2)}%</td>
+</tr>
+<tr><td colspan="5">${renderWorstFiles(app, stats.worstFiles)}</td></tr>`;
+}
+export function generateCodeDuplicationHtml(summary) {
+    const rows = Object.entries(summary.apps)
+        .map(([app, stats]) => buildAppRow(app, stats))
+        .join('');
+    return `<!DOCTYPE html>
+    <html lang="en">
+      <head>
+        <meta charset="UTF-8"/>
+        <title>Code Duplication Report</title>
+        <style>
+          body { font-family: Arial, sans-serif; margin: 2rem; }
+          table { border-collapse: collapse; width: 100%; }
+          th, td { border: 1px solid #ccc; padding: 0.5rem; text-align: left; }
+          th { background: #f0f0f0; }
+        </style>
+      </head>
+      <body>
+        <h1>Code Duplication Report</h1>
+        <p>Total lines: ${summary.totalLines}, Duplicate lines: ${summary.totalDuplicateLines},
+        Percentage: ${summary.percentage.toFixed(2)}%</p>
+        <table>
+          <thead>
+            <tr>
+              <th>App</th>
+              <th>Total lines</th>
+              <th>Duplicate lines</th>
+              <th>Clones</th>
+              <th>Duplication %</th>
+            </tr>
+          </thead>
+          <tbody>${rows}</tbody>
+        </table>
+      </body>
+    </html>`;
+}

package/dist/adapters/code-duplication/types/CodeDuplication.d.ts

@@ -0,0 +1,60 @@
+export interface AppCodeDuplicationSummary {
+    totalLines: number;
+    totalTokens: number;
+    duplicateLines: number;
+    duplicateTokens: number;
+    percentage: number;
+    clonesCount: number;
+    error?: string;
+    worstFiles?: WorstCodeDuplicationFile[];
+}
+export interface CombinedCodeDuplicationSummary {
+    apps: Record<string, AppCodeDuplicationSummary>;
+    totalLines: number;
+    totalTokens: number;
+    totalDuplicateLines: number;
+    totalDuplicateTokens: number;
+    percentage: number;
+}
+export type WorstCodeDuplicationFile = [
+    string,
+    {
+        duplicatedLines: number;
+        totalLines: number;
+        percentage: number;
+    }
+];
+export interface WorstFileStats {
+    duplicatedLines: number;
+    totalLines: number;
+    percentage: number;
+}
+interface JscpdDuplicateSide {
+    name: string;
+    startLoc?: {
+        line?: number;
+    };
+    endLoc?: {
+        line?: number;
+    };
+}
+interface JscpdDuplicate {
+    lines: number;
+    firstFile: JscpdDuplicateSide;
+    secondFile: JscpdDuplicateSide;
+}
+export interface JscpdReportV4 {
+    statistics?: {
+        total?: {
+            lines?: number;
+            tokens?: number;
+            duplicatedLines?: number;
+            duplicatedTokens?: number;
+            clones?: number;
+            percentage?: number;
+        };
+    };
+    duplicates?: JscpdDuplicate[];
+}
+export {};
+//# sourceMappingURL=CodeDuplication.d.ts.map

package/dist/adapters/code-duplication/types/CodeDuplication.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CodeDuplication.d.ts","sourceRoot":"","sources":["../../../../src/adapters/code-duplication/types/CodeDuplication.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,yBAAyB;IAExC,UAAU,EAAE,MAAM,CAAC;IAGnB,WAAW,EAAE,MAAM,CAAC;IAGpB,cAAc,EAAE,MAAM,CAAC;IAGvB,eAAe,EAAE,MAAM,CAAC;IAMxB,UAAU,EAAE,MAAM,CAAC;IAMnB,WAAW,EAAE,MAAM,CAAC;IAMpB,KAAK,CAAC,EAAE,MAAM,CAAC;IAMf,UAAU,CAAC,EAAE,wBAAwB,EAAE,CAAC;CACzC;AAKD,MAAM,WAAW,8BAA8B;IAK7C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;IAGhD,UAAU,EAAE,MAAM,CAAC;IAGnB,WAAW,EAAE,MAAM,CAAC;IAGpB,mBAAmB,EAAE,MAAM,CAAC;IAG5B,oBAAoB,EAAE,MAAM,CAAC;IAM7B,UAAU,EAAE,MAAM,CAAC;CACpB;AAcD,MAAM,MAAM,wBAAwB,GAAG;IACrC,MAAM;IACN;QAEE,eAAe,EAAE,MAAM,CAAC;QAGxB,UAAU,EAAE,MAAM,CAAC;QAGnB,UAAU,EAAE,MAAM,CAAC;KACpB;CACF,CAAC;AAKF,MAAM,WAAW,cAAc;IAE7B,eAAe,EAAE,MAAM,CAAC;IAGxB,UAAU,EAAE,MAAM,CAAC;IAGnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAKD,UAAU,kBAAkB;IAE1B,IAAI,EAAE,MAAM,CAAC;IAMb,QAAQ,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAM7B,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC5B;AAKD,UAAU,cAAc;IAKtB,KAAK,EAAE,MAAM,CAAC;IAGd,SAAS,EAAE,kBAAkB,CAAC;IAG9B,UAAU,EAAE,kBAAkB,CAAC;CAChC;AAMD,MAAM,WAAW,aAAa;IAK5B,UAAU,CAAC,EAAE;QACX,KAAK,CAAC,EAAE;YAEN,KAAK,CAAC,EAAE,MAAM,CAAC;YAGf,MAAM,CAAC,EAAE,MAAM,CAAC;YAGhB,eAAe,CAAC,EAAE,MAAM,CAAC;YAGzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;YAG1B,MAAM,CAAC,EAAE,MAAM,CAAC;YAMhB,UAAU,CAAC,EAAE,MAAM,CAAC;SACrB,CAAC;KACH,CAAC;IAMF,UAAU,CAAC,EAAE,cAAc,EAAE,CAAC;CAC/B"}

package/dist/adapters/code-duplication/types/CodeDuplication.js

@@ -0,0 +1 @@
+export {};

package/dist/adapters/eslint/rules/eslint-prettier.js

@@ -1,6 +1,6 @@
 import prettier from 'eslint-plugin-prettier';
+import { prettierConfig, prettierIgnorePatterns } from '../../../configs/code-formatter-config.js';
 import { commonTextFiles } from '../../../configs/file-globs-config.js';
-import { prettierConfig, prettierIgnorePatterns } from '../../../configs/prettier-config.js';
 export const prettierEslintConfig = {
     files: [commonTextFiles],
     ignores: prettierIgnorePatterns,

package/dist/adapters/html-a11y-validation/helpers/html-a11y-tests-setup.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview
+ * Ambient module augmentation for the custom Vitest matcher `toBeAccessible`.
+ * Import the setup file
+ * `@ovh-ux/manager-static-analysis-kit/tests/html-a11y-tests-setup`
+ * in your test setup to register the matcher at runtime and include these types.
+ */
+
+import 'vitest';
+
+/**
+ * Options object accepted by the accessibility matcher.
+ * This is intentionally generic so the underlying engine can evolve
+ * without a breaking public API. Keys/values are implementation-defined.
+ *
+ * @example
+ * await expect(container).toBeAccessible({
+ *   rules: { 'color-contrast': { enabled: false } },
+ *   runOnly: ['wcag2a', 'wcag2aa'],
+ * });
+ */
+export interface HtmlA11yOptions {
+  /** Arbitrary engine-specific options (e.g., rules, tags, runOnly, selectors). */
+  [key: string]: unknown;
+}
+
+declare module 'vitest' {
+  interface Assertion<T = any> {
+    /**
+     * Assert that a DOM container (Element/Document/DocumentFragment)
+     * has no accessibility violations, as determined by the toolkit’s
+     * internal engine.
+     *
+     * The matcher is registered by importing:
+     * `@ovh-ux/manager-static-analysis-kit/tests/html-a11y-tests-setup`
+     * in your test setup file.
+     *
+     * @param options Optional engine-specific configuration (see {@link HtmlA11yOptions}).
+     * @returns A promise that resolves when the assertion completes.
+     *
+     * @example
+     * const { container } = render(<Button />);
+     * await expect(container).toBeAccessible();
+     *
+     * @example
+     * await expect(container).toBeAccessible({
+     *   rules: { 'color-contrast': { enabled: false } },
+     * });
+     */
+    toBeAccessible(options?: HtmlA11yOptions): Promise<void>;
+  }
+
+  interface AsymmetricMatchersContaining {
+    /**
+     * Asymmetric form of {@link Assertion.toBeAccessible}.
+     * Useful with `.not` and partial matching expressions.
+     *
+     * @param options Optional engine-specific configuration.
+     */
+    toBeAccessible(options?: HtmlA11yOptions): Promise<void>;
+  }
+}

package/dist/adapters/html-a11y-validation/helpers/html-a11y-tests-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html-a11y-tests-setup.d.ts","sourceRoot":"","sources":["../../../../src/adapters/html-a11y-validation/helpers/html-a11y-tests-setup.ts"],"names":[],"mappings":""}

package/dist/adapters/html-a11y-validation/helpers/html-a11y-tests-setup.js

@@ -0,0 +1,73 @@
+import axe from 'axe-core';
+import { expect } from 'vitest';
+const NODE = { ELEMENT: 1, DOCUMENT: 9, FRAGMENT: 11 };
+function assertSupportedDomEnv() {
+    const ua = typeof navigator !== 'undefined' && navigator.userAgent
+        ? navigator.userAgent.toLowerCase()
+        : '';
+    if (ua.includes('happy-dom')) {
+        throw new Error('[a11y] The test DOM environment is not supported. Please use the "jsdom" environment.');
+    }
+}
+function isDomNode(x) {
+    return typeof x === 'object' && x !== null && 'nodeType' in x;
+}
+function isElement(x) {
+    return isDomNode(x) && x.nodeType === NODE.ELEMENT;
+}
+function isDocument(x) {
+    return isDomNode(x) && x.nodeType === NODE.DOCUMENT;
+}
+function isFragment(x) {
+    return isDomNode(x) && x.nodeType === NODE.FRAGMENT;
+}
+function toAxeContext(target) {
+    if (isElement(target) || isDocument(target)) {
+        return target;
+    }
+    if (isFragment(target)) {
+        const elements = Array.from(target.childNodes).filter((n) => n.nodeType === NODE.ELEMENT);
+        if (elements.length > 0) {
+            return { include: elements };
+        }
+        return { include: [target] };
+    }
+    return target;
+}
+async function runA11y(target, options) {
+    const context = toAxeContext(target);
+    const opts = options ?? {};
+    return axe.run(context, opts);
+}
+function formatViolations(results) {
+    const { violations } = results;
+    if (!violations.length)
+        return '';
+    return violations
+        .map((v) => {
+        const where = v.nodes
+            .map((n) => `  - ${n.target.join(' ')}${n.failureSummary ? `\n    ${n.failureSummary}` : ''}`)
+            .join('\n');
+        return `[${v.id}] ${v.help}\n${where}\nMore: ${v.helpUrl}`;
+    })
+        .join('\n\n');
+}
+expect.extend({
+    async toBeAccessible(received, options) {
+        assertSupportedDomEnv();
+        if (!isDomNode(received)) {
+            return {
+                pass: false,
+                message: () => 'toBeAccessible(): expected an Element/Document/DocumentFragment (e.g., RTL container).',
+            };
+        }
+        const results = await runA11y(received, options);
+        const pass = results.violations.length === 0;
+        return {
+            pass,
+            message: () => pass
+                ? 'expected container NOT to be accessible, but no violations were found'
+                : `Accessibility violations found (${results.violations.length}):\n\n${formatViolations(results)}`,
+        };
+    },
+});