@zohodesk/codestandard-validator 1.2.4-exp-5 → 1.2.4-exp-6

package/README.md

@@ -1,3 +1,172 @@
 # Pre-commit Tool
 
- This Pre commit tool to identify rule violation (impact based) in development cycle
+ This Pre commit tool to identify rule violation (impact based) in development cycle
+
+---
+
+## Mutation Testing
+
+The mutation module uses [Stryker Mutator](https://stryker-mutator.io/) to run mutation testing on files that changed relative to a release branch. It automatically:
+
+1. Detects changed source & test files via `git diff`
+2. Resolves source ↔ test file pairs (co-located, `__tests__/`, or mirrored directories)
+3. Runs Stryker on matched files
+4. Generates a **mutation summary report** (JSON) and a **SonarQube-compatible external issues report**
+
+### Dependencies
+
+The following packages are **required** (already listed in `package.json`):
+
+| Package | Version | Purpose |
+|---|---|---|
+| `@stryker-mutator/core` | `5.0.0` | Stryker mutation testing engine |
+| `@stryker-mutator/jest-runner` | `5.0.0` | Runs Jest tests for each mutant |
+| `jest` | `29.7.0` | Test runner (must already be present) |
+| `glob` | `^8.1.0` | File pattern matching for test resolution |
+
+Install all dependencies:
+
+```bash
+npm install
+```
+
+Or install mutation-specific packages manually:
+
+```bash
+npm install @stryker-mutator/core@5 @stryker-mutator/jest-runner@5 glob@8
+```
+
+### How to Run
+
+#### Via npx (recommended)
+
+```bash
+# Local / pre-commit mode — uses staged files + diff vs release branch
+npx ZDLintFramework mutate --mode=local --release=<branch>
+
+# CI mode — uses diff vs release branch only
+npx ZDLintFramework mutate --mode=ci --release=<branch>
+```
+
+#### Via npm scripts
+
+```bash
+# Local mode
+npm run mutate:local -- --release=release
+
+# CI mode
+npm run mutate:ci -- --release=release
+```
+
+#### Directly via node
+
+```bash
+node bin/cliCI.js mutate --mode=local --release=release
+node bin/cliCI.js mutate --mode=ci --release=release
+```
+
+### CLI Flags
+
+| Flag | Required | Default | Description |
+|---|---|---|---|
+| `--mode=local\|ci` | Yes | — | `local` = staged + branch diff; `ci` = branch diff only |
+| `--release=<branch>` | Yes | — | Release/target branch to diff against (e.g. `release`, `main`) |
+| `--outputDir=<dir>` | No | `reports/mutation` | Directory for output reports |
+| `--outputFileName=<name>` | No | `mutation-report.json` | Name of the mutation summary file |
+| `--logLevel=<level>` | No | `info` | Stryker log level (`off`, `fatal`, `error`, `warn`, `info`, `debug`, `trace`) |
+
+### Output
+
+Two report files are generated in the output directory (default `reports/mutation/`):
+
+1. **`mutation-report.json`** — Full mutation summary including mutation score, per-file breakdown, and mutant details.
+2. **`sonar-mutation-report.json`** — SonarQube generic issue import format. Survived and no-coverage mutants appear as issues.
+
+#### Example summary output
+
+```json
+{
+  "summary": {
+    "totalMutants": 42,
+    "killed": 35,
+    "survived": 5,
+    "timeout": 2,
+    "noCoverage": 0,
+    "ignored": 0,
+    "runtimeErrors": 0,
+    "compileErrors": 0,
+    "mutationScore": 88.10
+  }
+}
+```
+
+### How It Works
+
+| Mode | Step 1: File Collection | Step 2 | Step 3 | Step 4 |
+|---|---|---|---|---|
+| **local** | `git diff --staged` + `git diff <release>` | Resolve source↔test pairs | Run Stryker on matched files | Write JSON reports |
+| **ci** | `git diff <release>` | Resolve source↔test pairs | Run Stryker on matched files | Write JSON reports |
+
+### Programmatic API
+
+```js
+const { MutationRunner, MutationCli, StrykerWrapper } = require('./src/mutation');
+
+// Option 1: Use MutationCli (parses CLI args)
+const cli = new MutationCli();
+cli.execute(['mutate', '--mode=local', '--release=release']).then(result => {
+  console.log(result);
+});
+
+// Option 2: Use MutationRunner directly
+const runner = new MutationRunner({
+  outputDir: 'reports/mutation',
+  logLevel: 'info'
+});
+runner.runLocal('release').then(result => {
+  console.log('Score:', result.report.summary.mutationScore);
+});
+
+// Option 3: Use StrykerWrapper for full control
+const stryker = new StrykerWrapper({ concurrency: 4 });
+stryker.run(['src/utils/hash.js'], {
+  testFiles: ['src/utils/__tests__/hash.test.js']
+}).then(result => {
+  console.log(result.summary);
+});
+```
+
+### Default Mutate Pattern
+
+When no specific source files are provided, Stryker uses the default pattern from `mutatePattern.json`:
+
+```
+src/**/*.js
+```
+
+### File Resolution Strategies
+
+The `FileResolver` automatically finds test files for source files using these strategies (in order):
+
+1. **Co-located**: `src/foo.js` → `src/foo.test.js`
+2. **`__tests__` subdir**: `src/foo.js` → `src/__tests__/foo.test.js`
+3. **Mirror structure**: `src/x/foo.js` → `test/x/foo.test.js`
+
+Supported test suffixes: `.test.js`, `.test.ts`, `.test.jsx`, `.test.tsx`
+
+### SonarQube Integration
+
+Add the sonar report path to your `sonar-project.properties`:
+
+```properties
+sonar.externalIssuesReportPaths=reports/mutation/sonar-mutation-report.json
+```
+
+### Troubleshooting
+
+| Issue | Fix |
+|---|---|
+| `Failed to load @stryker-mutator/core` | Run `npm install @stryker-mutator/core@5 @stryker-mutator/jest-runner@5` |
+| `Branch 'X' not found` | Run `git fetch origin <branch>` first |
+| No files to mutate | Ensure changed files have matching test files |
+| Low mutation score | Add tests that assert specific behavior, not just "no error" |

package/bin/cliCI.js

@@ -3,9 +3,29 @@
 /**
  *  @author rajasekar 17710
  *  @fileoverview This script is a Node.js executable that imports and runs the module `runner` from the `../build/lib/` directory.
+ *  Also supports mutation testing via:  npx ZDLintFramework mutate --mode=local|ci --release=<branch>
  */
 
 (async function () {
+  // var args = process.argv.slice(2);
+  // if (args.indexOf('mutate') !== -1) {
+  //   var MutationCli = require('../build/mutation/mutationCli');
+  //   var cli = new MutationCli();
+  //   cli.execute(args).then(function (result) {
+  //     if (!result.success) {
+  //       console.error('Mutation testing failed:', result.error);
+  //       process.exitCode = 1;
+  //     } else {
+  //       if (result.filePath) console.log('Mutation report written to:', result.filePath);
+  //       if (result.message) console.log(result.message);
+  //     }
+  //   }).catch(function (err) {
+  //     console.error('Mutation testing error:', err.message || err);
+  //     process.exitCode = 1;
+  //   });
+  //   return;
+  // }
+
   const { initConfig, getConfigPathExecute, postInstallExecution } = require('../build/utils/General/Config');
   await initConfig(getConfigPathExecute());
   await postInstallExecution()

package/bin/zdcodequality.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+/**
+ * zdcodequality — mutation testing CLI.
+ *
+ * Commands:
+ *   mutate --local [--branch=<branch>]   Pre-commit: staged + branch diff (default branch: release)
+ *   mutate --ci    [--branch=<branch>]   CI: branch diff only (default branch: release)
+ *
+ * Examples:
+ *   npx zdcodequality mutate --local
+ *   npx zdcodequality mutate --local --branch=main
+ *   npx zdcodequality mutate --ci --branch=release
+ */
+
+var args = process.argv.slice(2);
+
+initConfig(getConfigPathExecute());
+
+if (args.indexOf('mutate') === -1) {
+  console.error('Usage: npx zdcodequality mutate --local [--branch=<branch>]');
+  console.error('       npx zdcodequality mutate --ci    [--branch=<branch>]');
+  console.error('Default branch: release');
+  process.exitCode = 1;
+  return;
+}
+
+var MutationCli = require('../build/mutation/mutationCli');
+const { initConfig } = require('../build/utils/General/Config');
+var cli = new MutationCli({
+  token: process.env.ZGIT_TOKEN,
+  gitEndPoint: process.env.GIT_END_POINT,
+  branchDiffPath: process.env.BRANCH_DIFF_PATH,
+  compareBranch: process.env.COMPARE_BRANCH,
+  projectId: process.env.PROJECT_ID
+});
+console.log('cli:', cli);
+cli.execute(args).then(function (result) {
+  if (!result.success) {
+    console.error('Mutation testing failed:', result.error);
+    process.exitCode = 1;
+  } else {
+    if (result.filePath) console.log('Mutation report written to:', result.filePath);
+    if (result.message) console.log(result.message);
+  }
+}).catch(function (err) {
+  console.error('Mutation testing error:', err.message || err);
+  process.exitCode = 1;
+});

package/build/mutation/_config.json

@@ -0,0 +1,55 @@
+// {
+//   "mutate": [
+//     "/Users/raja-17710/deskApp/desk_client_app/jsapps/supportapp/src/components/commonlist/subtab/NestedConversation/hooks/useContainerResize.js",
+//     "/Users/raja-17710/deskApp/desk_client_app/jsapps/supportapp/src/components/commonlist/subtab/NestedConversation/hooks/useNestedConversationActions.js",
+//     "/Users/raja-17710/deskApp/desk_client_app/jsapps/supportapp/src/components/commonlist/subtab/NestedConversation/hooks/useNestedConversationEditors.js",
+//     "/Users/raja-17710/deskApp/desk_client_app/jsapps/supportapp/src/components/commonlist/subtab/NestedConversation/hooks/useNestedConversationFetch.js",
+//     "/Users/raja-17710/deskApp/desk_client_app/jsapps/supportapp/src/modules/_containers/CriteriaV1/Criteria/utills/dangerAlert.js",
+//     "!src/**/__tests__/**",
+//     "!src/**/__test__/**",
+//     "!src/**/*.test.js",
+//     "!src/**/*.spec.js"
+//   ],
+//   "testRunner": "command",
+//   "commandRunner": {
+//     "command": "npm test -- --testPathPattern=\"useContainerResize|useNestedConversationActions|useNestedConversationEditors|useNestedConversationFetch|dangerAlert\""
+//   },
+//   "reporters": [
+//     "json",
+//     "clear-text"
+//   ],
+//   "coverageAnalysis": "off",
+//   "timeoutMS": 120000,
+//   "jest": {
+//     "projectType": "custom",
+//     "enableFindRelatedTests": true
+//   }
+// }
+
+// {
+//   "mutate": [
+//     "src/components/commonlist/subtab/NestedConversation/hooks/useNestedConversationActions.js",
+//     "src/components/commonlist/subtab/NestedConversation/hooks/utils/actionUtils.js",
+//     "!src/**/__tests__/**",
+//     "!src/**/__test__/**",
+//     "!src/**/*.test.js",
+//     "!src/**/*.spec.js"
+//   ],
+//   "testRunner": "command",
+//   "commandRunner": {
+//     "command": "npm test -- --testPathPattern='useNestedConversationActions|actionUtils'"
+//   },
+//   "reporters": [
+//     "json",
+//     "clear-text",
+//     "progress"
+//   ],
+//   "jsonReporter": {
+//     "fileName": "/Users/raja-17710/deskApp/desk_client_app/jsapps/supportapp/reports/mutation/mutation-report.json"
+//   },
+//   "coverageAnalysis": "off",
+//   "timeoutMS": 120000,
+//   "timeoutFactor": 1.5,
+//   "logLevel": "info",
+//   "concurrency": 2
+// }