@ovh-ux/manager-static-analysis-kit 0.10.0 → 0.11.0

package/bin/tests-coverage-cli-tests.js

@@ -3,14 +3,12 @@ import { spawnSync } from 'node:child_process';
 
 import { logError, logInfo } from './utils/log-utils.js';
 
+// Define the set of validation test cases
 const cases = [
-  // Debug only — very slow, runs across all apps
-  // { name: 'Auto-discovery (all apps)', cmd: 'yarn manager-tests-coverage', expect: 0 },
-
   { name: 'Single app (zimbra)', cmd: 'yarn manager-tests-coverage --app zimbra', expect: 0 },
   {
-    name: 'Multiple apps (container,zimbra,web-ongoing-operations,key-management-service)',
-    cmd: 'yarn manager-tests-coverage --apps container,zimbra,web-ongoing-operations,key-management-service',
+    name: 'Multiple apps (container,zimbra)',
+    cmd: 'yarn manager-tests-coverage --apps container,zimbra',
     expect: 0,
   },
   {
@@ -23,6 +21,36 @@ const cases = [
     cmd: 'yarn manager-tests-coverage --packages @ovh-ux/manager-zimbra-app,@ovh-ux/manager-pci-workflow-app',
     expect: 0,
   },
+  {
+    name: 'Single library static path by folder name (manager-react-components)',
+    cmd: 'yarn manager-tests-coverage --library manager-react-components',
+    expect: 0,
+  },
+  {
+    name: 'Single library static path by package name (manager-react-components)',
+    cmd: 'yarn manager-tests-coverage --library @ovh-ux/manager-react-components',
+    expect: 0,
+  },
+  {
+    name: 'Single library dynamic path by folder name (shell-client)',
+    cmd: 'yarn manager-tests-coverage --library shell-client',
+    expect: 0,
+  },
+  {
+    name: 'Single library static path by package name (shell-client)',
+    cmd: 'yarn manager-tests-coverage --library @ovh-ux/manager-react-shell-client',
+    expect: 0,
+  },
+  {
+    name: 'Multiple libraries by folder names (manager-wiki,manager-react-components,shell-client,logs-to-customer)',
+    cmd: 'yarn manager-tests-coverage --libraries manager-wiki,manager-react-components,shell-client,logs-to-customer',
+    expect: 0,
+  },
+  {
+    name: 'Multiple libraries by package names (manager-wiki,manager-react-components,shell-client,logs-to-customer)',
+    cmd: 'yarn manager-tests-coverage --libraries @ovh-ux/manager-wiki,@ovh-ux/manager-react-components,@ovh-ux/manager-react-shell-client,@ovh-ux/logs-to-customer',
+    expect: 0,
+  },
   {
     name: 'Mixed valid+invalid apps',
     cmd: 'yarn manager-tests-coverage --apps zimbra,unknown-app,container',
@@ -30,7 +58,12 @@ const cases = [
   },
   {
     name: 'Mixed valid+invalid packages',
-    cmd: 'yarn manager-tests-coverage --packages @ovh-ux/manager-zimbra-app,@ovh-ux/manager-ghost-app',
+    cmd: 'yarn manager-tests-coverage --packages @ovh-ux/manager-wiki,manager-react-components,@ovh-ux/manager-ghost-app',
+    expect: 0,
+  },
+  {
+    name: 'Mixed valid+invalid libraries',
+    cmd: 'yarn manager-tests-coverage --libraries @ovh-ux/manager-zimbra-app,@ovh-ux/manager-ghost-app',
     expect: 0,
   },
   {
@@ -43,6 +76,11 @@ const cases = [
     cmd: 'yarn manager-tests-coverage --packages @ovh-ux/manager-ghost-app,@ovh-ux/manager-missing-app',
     expect: 1,
   },
+  {
+    name: 'Turbo build failure simulation (pci-ai-tools)',
+    cmd: 'yarn manager-tests-coverage --app pci-ai-tools',
+    expect: 0,
+  },
 ];
 
 let failed = 0;

package/bin/tests-coverage-cli.js

@@ -8,17 +8,16 @@ import {
   generateTestsCoverageHtml,
 } from '../dist/adapters/tests-coverage/helpers/tests-coverage-analysis-helper.js';
 import {
-  appsDir,
-  outputRootDir,
   rootDir,
   testsCoverageCombinedHtmlReportName,
   testsCoverageCombinedJsonReportName,
+  testsCoverageOutputRootDir,
   testsCoverageReportsRootDirName,
 } from './cli-path-config.js';
 import { parseCliTargets } from './utils/args-parse-utils.js';
 import { logError, logInfo, logWarn } from './utils/log-utils.js';
-import { runAppsAnalysis } from './utils/runner-utils.js';
-import { resolveTurboFilters, runTurboBuild, runTurboTests } from './utils/turbo-utils.js';
+import { runModulesAnalysis } from './utils/runner-utils.js';
+import { runTurboBuild, runTurboTests } from './utils/turbo-utils.js';
 
 /**
  * Locate common coverage artifacts inside an app directory.
@@ -63,7 +62,11 @@ function findCoverageFiles(appDir) {
  */
 function harvestAppCoverage(appDir, appShortName) {
   const { summary, lcov } = findCoverageFiles(appDir);
-  const outDir = path.join(outputRootDir, testsCoverageReportsRootDirName, appShortName);
+  const outDir = path.join(
+    testsCoverageOutputRootDir,
+    testsCoverageReportsRootDirName,
+    appShortName,
+  );
   fs.mkdirSync(outDir, { recursive: true });
 
   if (!summary) {
@@ -89,34 +92,39 @@ function harvestAppCoverage(appDir, appShortName) {
  */
 function main() {
   try {
-    const { appFolders, packageNames } = parseCliTargets(appsDir);
-    const turboFilters = resolveTurboFilters({ appsDir, appFolders, packageNames });
+    const modules = parseCliTargets();
 
     // 1) Build all selected targets (best-effort)
-    runTurboBuild(rootDir, turboFilters, ['--continue']);
+    runTurboBuild(
+      rootDir,
+      modules.map((item) => item.packageName),
+      ['--continue'],
+    );
 
     // 2) Run tests with coverage; keep args minimal for Vitest/Jest compatibility
     //    (Projects should already be configured to emit json-summary/lcov.)
-    runTurboTests(rootDir, turboFilters, [
-      '--continue', // turbo: keep going even if some tests fail
-      '--', // pass the rest to the test runner
-      '--coverage',
-      '--coverage.reportOnFailure',
-      '--coverage.reporter',
-      'json-summary',
-      '--coverage.reporter',
-      'lcov',
-      '--coverage.reporter',
-      'html',
-    ]);
+    runTurboTests(
+      rootDir,
+      modules.map((item) => item.packageName),
+      [
+        '--continue', // turbo: keep going even if some tests fail
+        '--', // pass the rest to the test runner
+        '--coverage',
+        '--coverage.reportOnFailure',
+        '--coverage.reporter',
+        'json-summary',
+        '--coverage.reporter',
+        'lcov',
+        '--coverage.reporter',
+        'html',
+      ],
+    );
 
     // 3) Per-app harvest + combined reports
-    runAppsAnalysis({
-      appsDir,
-      appFolders,
-      requireReact: false,
+    runModulesAnalysis({
+      modules,
       binaryLabel: 'Tests coverage',
-      appRunner: harvestAppCoverage,
+      analysisRunner: harvestAppCoverage,
       reportsRootDirName: testsCoverageReportsRootDirName,
       combinedJson: testsCoverageCombinedJsonReportName,
       combinedHtml: testsCoverageCombinedHtmlReportName,
@@ -124,9 +132,9 @@ function main() {
       generateHtmlFn: (combined) =>
         generateTestsCoverageHtml(
           combined,
-          path.join(outputRootDir, testsCoverageReportsRootDirName),
+          path.join(testsCoverageOutputRootDir, testsCoverageReportsRootDirName),
         ),
-      outputRootDir,
+      outputRootDir: testsCoverageOutputRootDir,
     });
   } catch (err) {
     logError(`Fatal error: ${err.stack || err.message}`);

package/bin/types-coverage-cli.js

@@ -9,16 +9,15 @@ import {
   generateTypesCoverageHtml,
 } from '../dist/adapters/types-coverage/helpers/types-coverage-analysis-helper.js';
 import {
-  appsDir,
-  outputRootDir,
   tsTypesCoverageBin,
   typesCoverageCombinedHtmlReportName,
   typesCoverageCombinedJsonReportName,
+  typesCoverageOutputRootDir,
   typesCoverageReportsRootDirName,
 } from './cli-path-config.js';
 import { buildTypesCoverageArgs, parseCliTargets } from './utils/args-parse-utils.js';
 import { logError, logInfo, logWarn } from './utils/log-utils.js';
-import { ensureBinExists, runAppsAnalysis, runCommand } from './utils/runner-utils.js';
+import { ensureBinExists, runCommand, runModulesAnalysis } from './utils/runner-utils.js';
 
 /**
  * Temporarily strip "extends" from tsconfig.json before analysis,
@@ -131,7 +130,7 @@ export function countLooseTypes(appDir) {
 function runAppTypesCoverage(appDir, appShortName) {
   return patchTsConfig(appDir, () => {
     const absoluteOutputDir = path.join(
-      outputRootDir,
+      typesCoverageOutputRootDir,
       typesCoverageReportsRootDirName,
       appShortName,
     );
@@ -171,20 +170,18 @@ function main() {
   try {
     ensureBinExists(tsTypesCoverageBin, 'typescript-coverage-report');
 
-    const { appFolders } = parseCliTargets(appsDir);
+    const modules = parseCliTargets();
 
-    runAppsAnalysis({
-      appsDir,
-      appFolders,
-      requireReact: true,
+    runModulesAnalysis({
+      modules,
       binaryLabel: 'Type coverage',
-      appRunner: runAppTypesCoverage,
+      analysisRunner: runAppTypesCoverage,
       reportsRootDirName: typesCoverageReportsRootDirName,
       combinedJson: typesCoverageCombinedJsonReportName,
       combinedHtml: typesCoverageCombinedHtmlReportName,
       collectFn: collectTypesCoverage,
       generateHtmlFn: generateTypesCoverageHtml,
-      outputRootDir,
+      outputRootDir: typesCoverageOutputRootDir,
     });
   } catch (err) {
     logError(`Fatal error: ${err.stack || err.message}`);

package/bin/types-coverage-tests-cli.js

@@ -3,15 +3,12 @@ import { spawnSync } from 'node:child_process';
 
 import { logError, logInfo } from './utils/log-utils.js';
 
-// Define the set of validation test cases for types-coverage-tests CLI
+// Define the set of validation test cases
 const cases = [
-  // Debug only — very slow, runs across all apps
-  // { name: 'Auto-discovery (all apps)', cmd: 'yarn manager-types-coverage', expect: 0 },
-
   { name: 'Single app (zimbra)', cmd: 'yarn manager-types-coverage --app zimbra', expect: 0 },
   {
-    name: 'Multiple apps (container,zimbra,web-ongoing-operations,key-management-service)',
-    cmd: 'yarn manager-types-coverage --apps container,zimbra,web-ongoing-operations,key-management-service',
+    name: 'Multiple apps (container,zimbra)',
+    cmd: 'yarn manager-types-coverage --apps container,zimbra',
     expect: 0,
   },
   {
@@ -24,6 +21,36 @@ const cases = [
     cmd: 'yarn manager-types-coverage --packages @ovh-ux/manager-zimbra-app,@ovh-ux/manager-pci-workflow-app',
     expect: 0,
   },
+  {
+    name: 'Single library static path by folder name (manager-react-components)',
+    cmd: 'yarn manager-types-coverage --library manager-react-components',
+    expect: 0,
+  },
+  {
+    name: 'Single library static path by package name (manager-react-components)',
+    cmd: 'yarn manager-types-coverage --library @ovh-ux/manager-react-components',
+    expect: 0,
+  },
+  {
+    name: 'Single library dynamic path by folder name (shell-client)',
+    cmd: 'yarn manager-types-coverage --library shell-client',
+    expect: 0,
+  },
+  {
+    name: 'Single library static path by package name (shell-client)',
+    cmd: 'yarn manager-types-coverage --library @ovh-ux/manager-react-shell-client',
+    expect: 0,
+  },
+  {
+    name: 'Multiple libraries by folder names (manager-wiki,manager-react-components,shell-client,logs-to-customer)',
+    cmd: 'yarn manager-types-coverage --libraries manager-wiki,manager-react-components,shell-client,logs-to-customer',
+    expect: 0,
+  },
+  {
+    name: 'Multiple libraries by package names (manager-wiki,manager-react-components,shell-client,logs-to-customer)',
+    cmd: 'yarn manager-types-coverage --libraries @ovh-ux/manager-wiki,@ovh-ux/manager-react-components,@ovh-ux/manager-react-shell-client,@ovh-ux/logs-to-customer',
+    expect: 0,
+  },
   {
     name: 'Mixed valid+invalid apps',
     cmd: 'yarn manager-types-coverage --apps zimbra,unknown-app,container',
@@ -31,7 +58,12 @@ const cases = [
   },
   {
     name: 'Mixed valid+invalid packages',
-    cmd: 'yarn manager-types-coverage --packages @ovh-ux/manager-zimbra-app,@ovh-ux/manager-ghost-app',
+    cmd: 'yarn manager-types-coverage --packages @ovh-ux/manager-wiki,manager-react-components,@ovh-ux/manager-ghost-app',
+    expect: 0,
+  },
+  {
+    name: 'Mixed valid+invalid libraries',
+    cmd: 'yarn manager-types-coverage --libraries @ovh-ux/manager-zimbra-app,@ovh-ux/manager-ghost-app',
     expect: 0,
   },
   {
@@ -44,6 +76,11 @@ const cases = [
     cmd: 'yarn manager-types-coverage --packages @ovh-ux/manager-ghost-app,@ovh-ux/manager-missing-app',
     expect: 1,
   },
+  {
+    name: 'Turbo build failure simulation (pci-ai-tools)',
+    cmd: 'yarn manager-types-coverage --app pci-ai-tools',
+    expect: 0,
+  },
 ];
 
 let failed = 0;

package/bin/utils/args-parse-utils.js

@@ -1,143 +1,106 @@
-import fs from 'node:fs';
-import path from 'node:path';
 import process from 'node:process';
 
 import { codeDuplicationConfig } from '../../dist/configs/code-duplication-config.js';
 import { typesCoverageConfig } from '../../dist/configs/types-coverage-config.js';
-import { isReactApp } from './apps-utils.js';
-import { logError, logInfo, logWarn } from './log-utils.js';
+import { logError, logInfo } from './log-utils.js';
+import { getModule } from './module-utils.js';
 
 /**
- * Extract an app folder name from an OVH Manager package name.
+ * Parse CLI arguments to resolve target modules (apps, packages, or libraries).
  *
- * Example:
- *   "@ovh-ux/manager-zimbra-app" → "zimbra"
+ * This function looks for one of the supported flags in `process.argv`:
+ * - `--apps` or `--app`
+ * - `--packages` or `--package`
+ * - `--libraries` or `--library`
  *
- * @param {string} packageName - Full npm package name.
- * @returns {string|null} The extracted app folder name, or null if the format is invalid.
- */
-function extractAppFolderFromPackageName(packageName) {
-  const match = packageName.match(/^@ovh-ux\/manager-(.+)-app$/);
-  if (!match) {
-    logError(`❌ Invalid package name format: ${packageName}`);
-    return null;
-  }
-  return match[1];
-}
-
-/**
- * Parse CLI arguments for `--apps` or `--app` flags.
+ * Each flag must be followed by a comma-separated list of module identifiers.
+ * Each identifier is resolved using {@link getModule}, which returns a module descriptor.
  *
- * Accepts a comma-separated list of app folder names. Example:
- *   `--apps zimbra,web`
+ * For every valid pattern:
+ * - The corresponding module descriptor (containing `fullPath`, `shortPath`, and `packageName`)
+ *   is added to the result list.
+ * - If a module cannot be resolved, an error is logged and it is skipped.
  *
- * @param {string} appsDir - Absolute path to the apps root directory.
- * @returns {{appFolders: string[], packageNames: string[]} | null}
- *   Object containing valid app folders and an empty `packageNames` array,
- *   or null if no `--apps`/`--app` flag is provided.
- */
-function parseAppsArg(appsDir) {
-  const appsArg = process.argv.find((arg) => arg === '--apps' || arg === '--app');
-  if (!appsArg) return null;
-
-  const index = process.argv.indexOf(appsArg);
-  const rawValue = process.argv[index + 1] || '';
-  const appFolders = rawValue
-    .split(',')
-    .map((n) => n.trim())
-    .filter(Boolean);
-
-  const validFolders = appFolders.filter((folder) => {
-    if (!fs.existsSync(path.join(appsDir, folder))) {
-      logError(`❌ App not found: ${folder} → skipping`);
-      return false;
-    }
-    return true;
-  });
-
-  logInfo(`Running in apps mode for: ${validFolders.join(', ')}`);
-  return { appFolders: validFolders, packageNames: [] };
-}
-
-/**
- * Parse CLI arguments for `--packages` or `--package` flags.
+ * @typedef {Object} ModuleDescriptor
+ * @property {string} fullPath - Absolute path to the module directory.
+ * @property {string} shortPath - Folder name (short identifier) of the module.
+ * @property {string} packageName - Full npm package name (e.g. "@ovh-ux/manager-core-shell").
  *
- * Accepts a comma-separated list of package names. Example:
- *   `--packages @ovh-ux/manager-zimbra-app,@ovh-ux/manager-web-app`
+ * @returns {ModuleDescriptor[] | null}
+ * Array of resolved module descriptors, or `null` if no supported CLI flags were provided.
  *
- * Each package name is mapped to its corresponding app folder.
+ * @example
+ * // Example 1: Apps mode
+ * // CLI: --apps zimbra,web
+ * parseArgs();
+ * // → [
+ * //   { fullPath: "/.../manager/apps/zimbra", shortPath: "zimbra", packageName: "@ovh-ux/manager-zimbra-app" },
+ * //   { fullPath: "/.../manager/apps/web", shortPath: "web", packageName: "@ovh-ux/manager-web-app" }
+ * // ]
  *
- * @param {string} appsDir - Absolute path to the apps root directory.
- * @returns {{appFolders: string[], packageNames: string[]} | null}
- *   Object mapping package names to discovered app folders,
- *   or null if no `--packages`/`--package` flag is provided.
+ * @example
+ * // Example 2: Libraries mode
+ * // CLI: --libraries core-shell,react-components
+ * parseArgs();
+ * // → [
+ * //   { fullPath: "/.../packages/manager/core/core-shell", shortPath: "core-shell", packageName: "@ovh-ux/manager-core-shell" },
+ * //   { fullPath: "/.../packages/components/react-components", shortPath: "react-components", packageName: "@ovh-ux/manager-react-components" }
+ * // ]
  */
-function parsePackagesArg(appsDir) {
+export function parseArgs() {
+  const libsArg = process.argv.find((arg) => arg === '--libraries' || arg === '--library');
   const packagesArg = process.argv.find((arg) => arg === '--packages' || arg === '--package');
-  if (!packagesArg) return null;
+  const appsArg = process.argv.find((arg) => arg === '--apps' || arg === '--app');
+
+  const moduleModeArgs = libsArg || packagesArg || appsArg;
 
-  const index = process.argv.indexOf(packagesArg);
+  if (!moduleModeArgs) return null;
+
+  const index = process.argv.indexOf(moduleModeArgs);
   const rawValue = process.argv[index + 1] || '';
-  const packageNames = rawValue
+
+  const modulePatterns = rawValue
     .split(',')
     .map((n) => n.trim())
     .filter(Boolean);
 
-  const mappedFolders = [];
-  for (const pkgName of packageNames) {
-    const folder = extractAppFolderFromPackageName(pkgName);
-    if (folder && fs.existsSync(path.join(appsDir, folder))) {
-      mappedFolders.push(folder);
+  /** @type {ModuleDescriptor[]} */
+  const modules = [];
+
+  for (const modulePattern of modulePatterns) {
+    const discoveredModule = getModule(modulePattern, !!libsArg);
+    if (discoveredModule) {
+      modules.push(discoveredModule);
     } else {
-      logError(`❌ Package ${pkgName} → app folder ${folder} not found, skipping`);
+      logError(
+        `❌ Module ${modulePattern} → folder ${discoveredModule?.shortPath || 'unknown'} not found, skipping`,
+      );
     }
   }
 
   logInfo(
-    `Running in packages mode for: ${packageNames.join(', ')} → apps: ${mappedFolders.join(', ')}`,
+    `patterns ${modulePatterns.join(', ')} → folders: ${modules
+      .map((item) => item.fullPath)
+      .join(', ')}`,
   );
-  return { appFolders: mappedFolders, packageNames };
-}
 
-/**
- * Discover all React apps in the apps directory when no CLI flags are provided.
- *
- * Only apps that contain a `package.json` file and are identified as React apps
- * (via `isReactApp`) will be included.
- *
- * @param {string} appsDir - Absolute path to the apps root directory.
- * @returns {{appFolders: string[], packageNames: string[]}}
- *   Object containing discovered app folders and an empty `packageNames` array.
- */
-function discoverApps(appsDir) {
-  const discoveredAppFolders = fs.readdirSync(appsDir).filter((dir) => {
-    const pkgPath = path.join(appsDir, dir, 'package.json');
-    return fs.existsSync(pkgPath) && isReactApp(pkgPath);
-  });
-
-  if (discoveredAppFolders.length === 0) {
-    logWarn('⚠️ No React apps found to analyze.');
-    return { appFolders: [], packageNames: [] };
-  }
-
-  logInfo(`Running in auto-discovery mode (${discoveredAppFolders.length} apps).`);
-  return { appFolders: discoveredAppFolders, packageNames: [] };
+  return modules;
 }
 
 /**
- * Parse CLI arguments to resolve which apps or packages should be analyzed.
+ * Alias for {@link parseArgs}, used for semantic clarity in CLI entrypoints.
+ *
+ * This function simply delegates to {@link parseArgs} and returns the same result.
  *
- * Priority order:
- *  1. Explicit `--apps` flag
- *  2. Explicit `--packages` flag
- *  3. Auto-discovery fallback
+ * @returns {ModuleDescriptor[] | null}
+ * Array of resolved module descriptors, or `null` if no valid flags were provided.
  *
- * @param {string} appsDir - Absolute path to the apps root directory.
- * @returns {{appFolders: string[], packageNames: string[]}}
- *   Object containing app folder names and package names for analysis.
+ * @example
+ * parseCliTargets();
+ * // Equivalent to parseArgs(), typically used in CLI commands.
  */
-export function parseCliTargets(appsDir) {
-  return parseAppsArg(appsDir) || parsePackagesArg(appsDir) || discoverApps(appsDir);
+export function parseCliTargets() {
+  return parseArgs();
 }
 
 /**

package/bin/utils/module-utils.js

@@ -0,0 +1,121 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { appsDir, librariesBasePaths, staticDiscoveredLibraries } from '../cli-path-config.js';
+import { readJsonSafe } from './file-utils.js';
+import { logWarn } from './log-utils.js';
+
+/**
+ * Determine whether a given package directory represents a React-based module.
+ *
+ * This function inspects the `package.json` file located at `pkgPath`
+ * and checks whether any of its dependencies, devDependencies, or peerDependencies
+ * include `react`. If the file does not exist, cannot be parsed, or the
+ * dependency is missing, it returns `false`.
+ *
+ * @param {string} pkgPath - Absolute path to a `package.json` file.
+ * @returns {boolean} `true` if the module depends on React, otherwise `false`.
+ *
+ * @example
+ * isReactModule('/path/to/package.json');
+ * // → true if the package declares React as a dependency
+ */
+export function isReactModule(pkgPath) {
+  try {
+    if (!fs.existsSync(pkgPath)) return false;
+
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    if (!pkg || typeof pkg !== 'object') return false;
+
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies, ...pkg.peerDependencies };
+    return Boolean(deps.react);
+  } catch (err) {
+    logWarn(`Failed to read or parse ${pkgPath}: ${err.message}`);
+    return false;
+  }
+}
+
+/**
+ * Discover all valid application or library modules by scanning predefined directories.
+ *
+ * Depending on the `isLibrary` flag, this function inspects:
+ * - Libraries under: `packages/manager/core`, `packages/manager/modules`, and `packages/components`
+ * - Applications under: `manager/apps`
+ *
+ * For each folder containing a `package.json` that represents a React module,
+ * a module descriptor object is created with metadata.
+ *
+ * @param {boolean} [isLibrary=false] - Whether to scan for libraries (`true`) or apps (`false`).
+ * @returns {Array<{ fullPath: string, shortPath: string, packageName: string }>}
+ * Array of discovered module descriptors.
+ *
+ * @example
+ * // Discover apps
+ * discoverModules();
+ * // → [{ fullPath: '/.../manager/apps/zimbra', shortPath: 'zimbra', packageName: '@ovh-ux/manager-zimbra-app' }]
+ *
+ * @example
+ * // Discover libraries
+ * discoverModules(true);
+ * // → [{ fullPath: '/.../packages/manager/core/core-shell', shortPath: 'core-shell', packageName: '@ovh-ux/manager-core-shell' }]
+ */
+export function discoverModules(isLibrary = false) {
+  const discovered = [];
+  const modulesPaths = isLibrary ? librariesBasePaths : [appsDir];
+
+  for (const moduleBasePath of modulesPaths) {
+    if (!fs.existsSync(moduleBasePath)) continue;
+
+    const items = fs.readdirSync(moduleBasePath, { withFileTypes: true });
+    for (const item of items) {
+      if (item.isDirectory()) {
+        const appFolder = path.join(moduleBasePath, item.name);
+        const pkgPath = path.join(appFolder, 'package.json');
+        if (fs.existsSync(pkgPath) && isReactModule(pkgPath)) {
+          const pkgDetails = readJsonSafe(pkgPath);
+          discovered.push({
+            fullPath: appFolder,
+            shortPath: item.name,
+            packageName: pkgDetails.name,
+          });
+        }
+      }
+    }
+  }
+
+  return isLibrary ? [...discovered, ...staticDiscoveredLibraries] : discovered;
+}
+
+/**
+ * Retrieve a single module (app or library) matching a given pattern.
+ *
+ * This function searches through discovered modules (via {@link discoverModules})
+ * and returns the first one matching any of the following:
+ * - The module's absolute path (`fullPath`)
+ * - The folder name (`shortPath`)
+ * - The npm package name (`packageName`)
+ *
+ * @param {string} modulePattern - Pattern to match against module identifiers.
+ * @param {boolean} [isLibrary=false] - Whether to search within libraries (`true`) or apps (`false`).
+ * @returns {{ fullPath: string, shortPath: string, packageName: string }}
+ * The matched module descriptor, or `undefined` if no match is found.
+ *
+ * @example
+ * // Match by folder name
+ * getModule('zimbra');
+ * // → { fullPath: '/.../manager/apps/zimbra', shortPath: 'zimbra', packageName: '@ovh-ux/manager-zimbra-app' }
+ *
+ * @example
+ * // Match by package name
+ * getModule('@ovh-ux/manager-core-shell', true);
+ * // → { fullPath: '/.../packages/manager/core/core-shell', shortPath: 'core-shell', packageName: '@ovh-ux/manager-core-shell' }
+ */
+export function getModule(modulePattern, isLibrary = false) {
+  const discoveredLibraries = discoverModules(isLibrary) || [];
+  return discoveredLibraries.find(
+    (library) =>
+      library.fullPath === modulePattern ||
+      library.shortPath === modulePattern ||
+      library.packageName === modulePattern,
+  );
+}