chore: improve coverage transparency (#612)

* chore: remove default coverage file

* chore: remove c8 comments

* chore: add build for dynamic coverage

* chore: fix windows and mac

* docs: add coverage disclaimer

* chore: few adjustments

* ci: restaure defineConfigs test

* chore: ensure clean build

* docs: update link to coverage discussion

.gitignore

@@ -11,3 +11,4 @@ node_modules
 /test-src
 /test-tests
 /test-before-and-after-each.json
+.nycrc.json

.nycrc/README.md

@@ -0,0 +1,34 @@
+# ☔️ Coverage
+
+## Specific cases and approaches don't generate coverage reports properly
+
+### Different behaviors due to platform versions
+
+- Compatibility with `c8` starts with [**Node.js** `v18`](https://github.com/bcoe/c8/blob/ff146b4dde004c62651b57c33cedd8353c94c423/package.json#L67).
+- Compatibility with `monocart-coverage-reports` starts with [**Node.js** `v18`](https://github.com/cenfun/monocart-coverage-reports/issues/60).
+
+### Different behaviors due to **Deno** and **Bun** platforms
+
+- At the moment, there is no way to generate the coverage report for them using `c8` or `monocart-coverage-reports`.
+
+### process-based
+
+> E.g., `process.on`, `process.once`, `pid`, etc.
+
+- I intend to do more research.
+
+---
+
+### Conclusion
+
+The choice not to consider these topics in the coverage comes from the fact that it isn't possible, not that they are ignored. For example, even if exhaustive tests are created for **Node.js** `v8`, there is no way to generate the coverage report for these tests.
+
+> Similarly, there are specific tests for **Bun** and **Deno** that don't generate coverage reports.
+
+- In order to keep the minimum possible number of coverage instructions within the code, I have concentrated the cases of impossible coverage in individual files.
+
+> [!NOTE]
+>
+> If you don't agree with any of these not covered topics, please feel free to comment. I'm totally open to discussions and opinions.
+>
+> - In disagreements, please see and discuss through [discussion#613](https://github.com/wellwelwel/poku/discussions/613).

.nycrc/_.jsonc

@@ -0,0 +1,19 @@
+/**
+ *  Global setttings
+ *
+ * The final compatibility file is generated by merging this file with the file based on the current operating system.
+ * You can see the compilation process at: ./tools/biuld/c8-file.ts and generate it by running `npm run pretest:c8`, then check the generated file at ./.nycrc.json.
+ */
+{
+  "clean": true,
+  "all": true,
+  "include": ["src/**"],
+  "reporter": ["v8", "codecov", "console-details"],
+  "branches": 95,
+  "statements": 95,
+  "lines": 95,
+  "functions": 95,
+  "checkCoverage": true,
+  "import": ["tsx"],
+  "extension": [".ts"]
+}

.nycrc/darwin.jsonc

@@ -0,0 +1,21 @@
+/**
+ *  Global setttings
+ *
+ * In addition to the ./README.md in this directory, each deleted file explains the reason for its deletion.
+ * Please note that excluded files aren't ignored, but that the coverage report can't be properly generated.
+ */
+{
+  "exclude": [
+    "src/@types", // Typings exports only
+    "src/polyfills", // They involve compatibility between older versions of platforms or assist in cross-platform compatibility
+    "src/modules/helpers/create-service.ts", // Varies of platform (Node.js, Bun, and Deno)
+    "src/modules/helpers/container.ts", // On macOS, the memory consumption and installation time plus the processing required cause constant failures due to timeouts or resource limit usage.
+    "src/modules/helpers/get-pids.ts", // 100% Process-based
+    "src/modules/helpers/kill.ts", // 100% Process-based
+    "src/services/container.ts", // On macOS, the memory consumption and installation time plus the processing required cause constant failures due to timeouts or resource limit usage.
+    "src/parsers/get-runner.ts", // Varies of platform (npm, yarn, bun, deno, pnpm, etc.)
+    "src/parsers/get-runtime.ts", // Varies of platform (Node.js, Bun, and Deno)
+    "src/services/pid.ts", // 100% Process-based
+    "src/bin" // TODO: Remove after expose `inpectCLI` and `watchCLI` methods.
+  ]
+}

.nycrc/linux.jsonc

@@ -0,0 +1,19 @@
+/**
+ *  Global setttings
+ *
+ * In addition to the ./README.md in this directory, each deleted file explains the reason for its deletion.
+ * Please note that excluded files aren't ignored, but that the coverage report can't be properly generated.
+ */
+{
+  "exclude": [
+    "src/@types", // Typings exports only
+    "src/polyfills", // They involve compatibility between older versions of platforms or assist in cross-platform compatibility
+    "src/modules/helpers/create-service.ts", // Varies of platform (Node.js, Bun, and Deno)
+    "src/modules/helpers/get-pids.ts", // 100% Process-based
+    "src/modules/helpers/kill.ts", // 100% Process-based
+    "src/parsers/get-runner.ts", // Varies of platform (Node.js, Bun, and Deno)
+    "src/parsers/get-runtime.ts", // Varies of platform (Node.js, Bun, and Deno)
+    "src/services/pid.ts", // 100% Process-based
+    "src/bin" // TODO: Remove after expose `inpectCLI` and `watchCLI` methods.
+  ]
+}

.nycrc/win32.jsonc

@@ -0,0 +1,21 @@
+/**
+ *  Global setttings
+ *
+ * In addition to the ./README.md in this directory, each deleted file explains the reason for its deletion.
+ * Please note that excluded files aren't ignored, but that the coverage report can't be properly generated.
+ */
+{
+  "exclude": [
+    "src/@types", // Typings exports only
+    "src/polyfills", // They involve compatibility between older versions of platforms or assist in cross-platform compatibility
+    "src/modules/helpers/create-service.ts", // Varies of platform (Node.js, Bun, and Deno)
+    "src/modules/helpers/container.ts", // On Windows-based GitHub Actions, it's not possible to pull images based on manifest windows/amd64
+    "src/modules/helpers/get-pids.ts", // 100% Process-based
+    "src/modules/helpers/kill.ts", // 100% Process-based
+    "src/services/container.ts", // On Windows-based GitHub Actions, it's not possible to pull images based on manifest windows/amd64
+    "src/parsers/get-runner.ts", // Varies of platform (Node.js, Bun, and Deno)
+    "src/parsers/get-runtime.ts", // Varies of platform (Node.js, Bun, and Deno)
+    "src/services/pid.ts", // 100% Process-based
+    "src/bin" // TODO: Remove after expose `inpectCLI` and `watchCLI` methods.
+  ]
+}

.prettierignore

@@ -3,3 +3,4 @@
 /CHANGELOG.md
 /website
 /fixtures/sintax
+/.nycrc.json

README.md

@@ -7,7 +7,7 @@ Enjoying **Poku**? Give him a star to show your support 🌟
 
 [![NPM Downloads](https://img.shields.io/npm/v/poku.svg?label=&color=70a1ff&logo=npm&logoColor=white)](https://www.npmjs.com/package/poku)
 [![NPM Downloads](https://img.shields.io/npm/dt/poku.svg?label=&logo=npm&logoColor=white&color=45aaf2)](https://www.npmjs.com/package/poku)
-[![Coverage](https://img.shields.io/codecov/c/github/wellwelwel/poku?label=&logo=codecov&logoColor=white&color=98cc00)](https://app.codecov.io/github/wellwelwel/poku)<br />
+[![Coverage](https://img.shields.io/codecov/c/github/wellwelwel/poku?label=&logo=codecov&logoColor=white&color=98cc00)](https://github.com/wellwelwel/poku/tree/main/.nycrc)<br />
 [![GitHub Workflow Status (Linux)](https://img.shields.io/github/actions/workflow/status/wellwelwel/poku/ci_coverage-linux.yml?event=push&label=&branch=main&logo=ubuntu&logoColor=8897a9&color=dfe4ea)](https://github.com/wellwelwel/poku/actions/workflows/ci_coverage-linux.yml?query=branch%3Amain)
 [![GitHub Workflow Status (OSX)](https://img.shields.io/github/actions/workflow/status/wellwelwel/poku/ci_coverage-osx.yml?event=push&label=&branch=main&logo=apple&logoColor=8897a9&color=dfe4ea)](https://github.com/wellwelwel/poku/actions/workflows/ci_coverage-osx.yml?query=branch%3Amain)
 [![GitHub Workflow Status (Windows)](https://img.shields.io/github/actions/workflow/status/wellwelwel/poku/ci_coverage-windows.yml?event=push&label=&branch=main&logo=data:image/svg+xml;base64,PHN2ZyByb2xlPSJpbWciIHZpZXdCb3g9IjAgMCAxMjggMTI4IiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjx0aXRsZT5XaW5kb3dzIDExPC90aXRsZT48cGF0aCBmaWxsPSIjODg5N2E5IiBkPSJNMTI2IDEuNjM3bC02NyA5LjgzNHY0OS44MzFsNjctLjUzNHpNMS42NDcgNjYuNzA5bC4wMDMgNDIuNDA0IDUwLjc5MSA2Ljk4My0uMDQtNDkuMDU3em01Ni44Mi42OGwuMDk0IDQ5LjQ2NSA2Ny4zNzYgOS41MDkuMDE2LTU4Ljg2M3pNMS42MSAxOS4yOTdsLjA0NyA0Mi4zODMgNTAuNzkxLS4yODktLjAyMy00OS4wMTZ6Ij48L3BhdGg+PC9zdmc+&color=dfe4ea)](https://github.com/wellwelwel/poku/actions/workflows/ci_coverage-windows.yml?query=branch%3Amain)

package.json

@@ -39,7 +39,9 @@
     "test:bun:parallel": "bun src/bin/index.ts --bun -p test/unit test/integration test/e2e",
     "test:deno:sequential": "tsx src/bin/index.ts --deno --deno-allow=all --deno-cjs ci/test/unit ci/test/integration ci/test/e2e",
     "test:deno:parallel": "tsx src/bin/index.ts --deno --deno-allow=all --deno-cjs -p ci/test/unit ci/test/integration ci/test/e2e",
+    "pretest:c8": "tsx tools/build/c8-file.ts",
     "test:c8": "c8 --experimental-monocart tsx test/c8.test.ts",
+    "posttest:c8": "rm -rf ./.nycrc.json",
     "test:ci": "tsx test/ci.test.ts",
     "test:ci:node": "FILTER='node-' npm run test:ci",
     "test:ci:bun": "FILTER='bun-' npm run test:ci",
@@ -49,7 +51,7 @@
     "clear": "rm -rf lib ci coverage .temp test-src test-tests",
     "prebuild": "npm run clear",
     "build": "tsc && tsc -p tsconfig.test.json",
-    "postbuild": "tsx tools/compatibility/node.ts && cp fixtures/server/package.json ci/fixtures/server/package.json && rm -f ./lib/@types/*.js ./lib/bin/*.ts && npm run build:deno && chmod +x lib/bin/index.js",
+    "postbuild": "tsx tools/compatibility/node.ts && tsx tools/compatibility/comments.ts && cp fixtures/server/package.json ci/fixtures/server/package.json && rm -f ./lib/@types/*.js ./lib/bin/*.ts && npm run build:deno && chmod +x lib/bin/index.js",
     "build:deno": "tsc -p tsconfig.mjs.json",
     "postbuild:deno": "tsx tools/build/check-deno-polyfill.ts",
     "lint": "npx @biomejs/biome lint && prettier --check .",
@@ -62,6 +64,7 @@
     "@biomejs/biome": "1.8.3",
     "@types/node": "^20.14.12",
     "c8": "^10.1.2",
+    "jsonc.min": "^1.0.0",
     "monocart-coverage-reports": "^2.9.3",
     "packages-update": "^2.0.0",
     "prettier": "^3.3.3",

src/modules/essentials/poku.ts

@@ -9,12 +9,12 @@ import { isQuiet } from '../../parsers/output.js';
 import { fileResults, finalResults } from '../../configs/files.js';
 import { indentation } from '../../configs/indentation.js';
 
-/* c8 ignore next 3 */
+/* c8 ignore next 3 */ // Process-based
 export const onSigint = () => {
   process.stdout.write('\u001B[?25h');
 };
 
-/* c8 ignore next */
+/* c8 ignore next */ // Process-based
 process.once('SIGINT', onSigint);
 
 export async function poku(

src/modules/helpers/exit.ts

@@ -37,11 +37,13 @@ export const exit = (code: Code, quiet?: boolean) => {
   process.exit(code === 0 ? 0 : 1);
 };
 
+/* c8 ignore next 4 */ // Unknown external error
 process.on('unhandledRejection', (reason) => {
   console.error('unhandledRejection', reason);
   process.exit(1);
 });
 
+/* c8 ignore next 4 */ // Unknown external error
 process.on('uncaughtException', (err) => {
   console.error('uncaughtException', err);
   process.exit(1);

src/modules/helpers/list-files.ts

@@ -57,7 +57,6 @@ export const getAllFiles = async (
       const fullPath = join(dirPath, file);
       const stat = await fsStat(fullPath);
 
-      /* c8 ignore next 6 */
       if (
         fullPath.indexOf('node_modules') !== -1 ||
         fullPath.indexOf('.git') === 0

src/modules/helpers/wait-for.ts

@@ -21,7 +21,6 @@ const checkPort = (port: number, host: string): Promise<boolean> =>
 
 /** Wait until the defined milliseconds. */
 export const sleep = (milliseconds: number): Promise<void> => {
-  /* c8 ignore next 3 */
   if (!Number.isInteger(milliseconds)) {
     throw new Error('Milliseconds must be an integer.');
   }
@@ -39,7 +38,6 @@ export const waitForExpectedResult = async (
   const interval = options?.interval || 100;
   const timeout = options?.timeout || 60000;
 
-  /* c8 ignore start */
   if (typeof callback !== 'function') {
     throw new Error('Callback must be a function.');
   }
@@ -55,7 +53,6 @@ export const waitForExpectedResult = async (
   if (!Number.isInteger(delay)) {
     throw new Error('Delay must be an integer.');
   }
-  /* c8 ignore stop */
 
   await sleep(delay);
 

src/parsers/assert.ts

@@ -20,7 +20,7 @@ export const parseResultType = (type?: unknown): string => {
       return Array.from(value).map(recurse);
     }
 
-    /* c8 ignore start */
+    /* c8 ignore start */ // Platform version
     if (value instanceof Map) {
       return recurse(
         !nodeVersion || nodeVersion >= 12

src/services/assert.ts

@@ -106,7 +106,7 @@ export const processAssert = async (
       exit(1);
     }
 
-    // Non-assertion errors
+    /* c8 ignore next */ // Unknown external error
     throw error;
   }
 };
@@ -383,7 +383,7 @@ export const createAssert = (nodeAssert: typeof assert) => {
     regExp: RegExp,
     message?: ProcessAssertionOptions['message']
   ): void => {
-    /* c8 ignore next 3 */
+    /* c8 ignore next 3 */ // Platform version
     if (typeof nodeVersion === 'number' && nodeVersion < 12) {
       throw new Error('match is available from Node.js 12 or higher');
     }
@@ -401,7 +401,7 @@ export const createAssert = (nodeAssert: typeof assert) => {
     regExp: RegExp,
     message?: ProcessAssertionOptions['message']
   ): void => {
-    /* c8 ignore next 3 */
+    /* c8 ignore next 3 */ // Platform version
     if (typeof nodeVersion === 'number' && nodeVersion < 12) {
       throw new Error('doesNotMatch is available from Node.js 12 or higher');
     }

src/services/container.ts

@@ -169,7 +169,7 @@ export class DockerCompose {
     this.envFile = envFile;
     this.projectName = projectName;
     this.detach = detach;
-    this.cwd = cwd ? sanitizePath(cwd) : undefined;
+    this.cwd = cwd ? sanitizePath(cwd) /* c8 ignore next */ : undefined;
     this.verbose = verbose;
   }
 

src/services/run-test-file.ts

@@ -20,7 +20,7 @@ export const runTestFile = async (
   const runtime = runtimeOptions.shift()!;
   const runtimeArguments = [
     ...runtimeOptions,
-    /* c8 ignore next 5 */
+    /* c8 ignore next 5 */ // Varies Platform
     configs?.deno?.cjs === true ||
     (Array.isArray(configs?.deno?.cjs) &&
       configs.deno.cjs.some((ext) => filePath.includes(ext)))
@@ -95,7 +95,7 @@ export const runTestFile = async (
       resolve(result);
     });
 
-    /* c8 ignore start */
+    /* c8 ignore next 10 */ // Unknown external error
     child.on('error', (err) => {
       end = hrtime(start);
 
@@ -106,6 +106,5 @@ export const runTestFile = async (
 
       resolve(false);
     });
-    /* c8 ignore stop */
   });
 };

src/services/watch.ts

@@ -25,11 +25,6 @@ export class Watcher {
       this.callback(filePath, eventType);
     });
 
-    /* c8 ignore next 3 */
-    watcher.on('error', () => {
-      return;
-    });
-
     this.fileWatchers.set(filePath, watcher);
   }
 
@@ -65,16 +60,10 @@ export class Watcher {
           if (stats.isDirectory()) {
             await this.watchDirectory(fullPath);
           }
-          /* c8 ignore next */
         } catch {}
       }
     });
 
-    /* c8 ignore next 3 */
-    watcher.on('error', () => {
-      return;
-    });
-
     this.dirWatchers.set(dir, watcher);
 
     const entries = await readdir(dir, { withFileTypes: true });
@@ -99,7 +88,6 @@ export class Watcher {
       } else {
         this.watchFile(this.rootDir);
       }
-      /* c8 ignore next */
     } catch {}
   }