feat: introduce custom reporters (poku, dot, compact, focus, …

…`verbose`, and `classic`) (#921)

* feat: initialize custom reporters

* chore: adjust runtime for Windows

* chore: adjust runtime for WSL

* chore: remove debug

* refactor: improve runtime identification

* chore: check for Deno version

* refactor: use global runtime

* ci: enable CI for `reporter` branch

* ci: remove canary from matrix

* debug: disable coverage check

* ci: check lint for all push events

* refactor: improve plugin param names

* chore: adjust params

* chore: add file events

* refactor: resume logic

* ci: improve c8 comments

* debug: restore canary versions from matrix

* chore: create reporters

* ci: revert c8 comments

* ci: add e2e tests

* chore: improve coverage

* ci: add test to `--listFiles` command

* ci: remove debug

* chore: improve verbose reporter

* chore: support for config files

* refactor: use number for durations

* refactor: use number for durations

* perf: remove file map from global memory

* ci: improve CI timeout

* chore(website): remove deprecated Sass usage

* docs: add `reporter` documentation

.github/workflows/bot_deps-docs-update.yml

@@ -18,6 +18,7 @@ env:
 jobs:
   update-deps:
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     if: github.event.repository.fork == false
     name: Update
     steps:

.github/workflows/bot_deps-update.yml

@@ -17,6 +17,7 @@ env:
 jobs:
   update-deps:
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     if: github.event.repository.fork == false
     name: Update
     steps:

.github/workflows/bot_stale.yml

@@ -8,6 +8,7 @@ on:
 jobs:
   stale:
     runs-on: ubuntu-latest
+    timeout-minutes: 5
     name: Issues and PRs
     steps:
       - uses: actions/stale@v9

.github/workflows/ci_codeql.yml

@@ -27,7 +27,7 @@ jobs:
     #   - https://gh.io/using-larger-runners
     # Consider using larger runners for possible analysis time improvements.
     runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
-    timeout-minutes: ${{ (matrix.language == 'swift' && 120) || 360 }}
+    timeout-minutes: 15
     permissions:
       actions: read
       contents: read

.github/workflows/ci_coverage-linux.yml

@@ -10,7 +10,7 @@ on:
 jobs:
   linux:
     runs-on: ubuntu-latest
-    timeout-minutes: 5
+    timeout-minutes: 10
     strategy:
       fail-fast: false
     name: Linux

.github/workflows/ci_coverage-osx.yml

@@ -10,7 +10,7 @@ on:
 jobs:
   osx:
     runs-on: macos-latest
-    timeout-minutes: 5
+    timeout-minutes: 10
     strategy:
       fail-fast: false
     name: macOS

.github/workflows/ci_lint.yml

@@ -2,8 +2,6 @@ name: '👔 CI — Lint'
 
 on:
   push:
-    branches:
-      - 'main'
   pull_request:
   workflow_dispatch:
 

.nycrc/darwin.jsonc

@@ -7,15 +7,17 @@
 {
   "exclude": [
     "src/@types", // Typings exports only
+    "src/globals.d.ts", // 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 (this test isn't skipped locally)
     "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 (npm, yarn, bun, deno, pnpm, etc.)
     "src/parsers/get-runtime.ts", // Varies of platform (Node.js, Bun, and Deno)
+    "src/parsers/runtime-version.ts", // Varies of platform (Node.js, Bun, and Deno)
     "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 (this test isn't skipped locally)
     "src/services/pid.ts", // 100% Process-based
-    "src/bin" // TODO: Remove after expose `inpectCLI` and `watchCLI` methods
+    "src/bin/watch.ts" // Blocked by TSX
   ]
 }

.nycrc/linux.jsonc

@@ -7,15 +7,17 @@
 {
   "exclude": [
     "src/@types", // Typings exports only
+    "src/globals.d.ts", // Typings exports only
     "src/polyfills", // They involve compatibility between older versions of platforms or assist in cross-platform compatibility
     "src/modules/helpers/container.ts", // Unexpectedly, GitHub Actions started refusing a simple connection (`node:http`), not directly related to the container test (this test isn't skipped locally)
     "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/parsers/runtime-version.ts", // Varies of platform (Node.js, Bun, and Deno)
     "src/services/container.ts", // Unexpectedly, GitHub Actions started refusing a simple connection (`node:http`), not directly related to the container test (this test isn't skipped locally)
     "src/services/pid.ts", // 100% Process-based
-    "src/bin" // TODO: Remove after expose `inpectCLI` and `watchCLI` methods
+    "src/bin/watch.ts" // Blocked by TSX
   ]
 }

.nycrc/win32.jsonc

@@ -7,15 +7,17 @@
 {
   "exclude": [
     "src/@types", // Typings exports only
+    "src/globals.d.ts", // 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/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/parsers/runtime-version.ts", // Varies of platform (Node.js, Bun, and Deno)
     "src/services/pid.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/bin" // TODO: Remove after expose `inpectCLI` and `watchCLI` methods
+    "src/bin/watch.ts" // Blocked by TSX
   ]
 }

biome.jsonc

@@ -77,7 +77,7 @@
     }
   },
   "javascript": {
-    "globals": ["BufferEncoding"]
+    "globals": ["BufferEncoding", "Bun", "Deno"]
   },
   "overrides": [
     {

package.json

@@ -4,7 +4,6 @@
   "description": "🐷 Poku makes testing easy for Node.js, Bun, Deno, and you at the same time.",
   "main": "./lib/modules/index.js",
   "license": "MIT",
-  "type": "commonjs",
   "bin": {
     "poku": "./lib/bin/index.js"
   },

src/@types/list-files.ts

@@ -12,8 +12,3 @@ export type Configs = {
    */
   exclude?: RegExp | RegExp[];
 };
-
-export type FileResults = {
-  success: Map<string, string>;
-  fail: Map<string, string>;
-};

src/@types/poku.ts

@@ -1,4 +1,10 @@
+import type { AssertionError } from 'node:assert';
+import type { results } from '../configs/poku.js';
 import type { Configs as ListFilesConfigs } from './list-files.js';
+import type { ProcessAssertionOptions } from './assert.js';
+import type { DescribeOptions } from './describe.js';
+
+type CustomString = string & NonNullable<unknown>;
 
 export type DenoOptions = {
   allow?: string[];
@@ -8,6 +14,15 @@ export type DenoOptions = {
 
 export type Runtime = 'node' | 'bun' | 'deno';
 
+export type Reporter =
+  | 'poku'
+  | 'focus'
+  | 'dot'
+  | 'verbose'
+  | 'compact'
+  | 'classic'
+  | CustomString;
+
 export type Configs = {
   /**
    * By setting `true`, **Poku** won't exit the process and will return the exit code (`0` or `1`).
@@ -47,6 +62,10 @@ export type Configs = {
    * @default (availableParallelism() || cpus().lenght) - 1
    */
   concurrency?: number;
+  /**
+   * @default "poku"
+   */
+  reporter?: Reporter;
   /**
    * You can use this option to run a **callback** or a **file** before each test file on your suite.
    *
@@ -78,9 +97,11 @@ export type Configs = {
   deno?: DenoOptions;
 } & ListFilesConfigs;
 
-export type FinalResults = {
-  time: string;
+export type Timespan = {
   started: Date;
+  finished: Date;
+  /** Calculation from `process.hrtime()`. */
+  duration: number;
 };
 
 export type States = {
@@ -113,3 +134,42 @@ export type ConfigJSONFile = {
   cliConfigs;
 
 export type ConfigFile = Omit<Configs, 'noExit'> & cliConfigs;
+
+type Results = {
+  code: number;
+  timespan: Timespan;
+  results: typeof results;
+};
+
+type Path = {
+  absolute: string;
+  relative: string;
+};
+
+export type ReporterPlugin = (configs?: Configs) => {
+  onRunStart: () => void;
+  onDescribeAsTitle: (title: string, options: DescribeOptions) => void;
+  onDescribeStart: (options: { title?: string }) => void;
+  onDescribeEnd: (options: { title?: string; duration: number }) => void;
+  onItStart: (options: { title?: string }) => void;
+  onItEnd: (options: { title?: string; duration: number }) => void;
+  onAssertionSuccess: (options: { message: string }) => void;
+  onAssertionFailure: (options: {
+    assertOptions: ProcessAssertionOptions;
+    error: AssertionError;
+  }) => void;
+  onSkipFile: (options: { message: string }) => void;
+  onSkipModifier: (options: { message: string }) => void;
+  onTodoModifier: (options: { message: string }) => void;
+  onFileStart: (options: { path: Path }) => void;
+  onFileResult: (options: {
+    status: boolean;
+    path: Path;
+    duration: number;
+    output?: string;
+  }) => void;
+  onRunResult: (options: Results) => void;
+  onExit: (options: Results) => void;
+};
+
+export type ReporterEvents = Partial<ReturnType<ReporterPlugin>>;

src/bin/help.ts

@@ -26,6 +26,10 @@ const summary: [string, string][] = [
   ['--killPort', 'Terminate the specified ports.'],
   ['--killRange', 'Terminate the specified port ranges.'],
   ['--listFiles', 'Display all the files returned in the terminal.'],
+  [
+    '--reporter, -r',
+    'Specify the reporter: poku, dot, compact, focus, verbose, classic.',
+  ],
   ['--only', 'Enable selective execution of tests.'],
   ['--quiet, -q', 'Run tests with no logs.'],
   ['--sequential', 'Run tests files sequentially.'],
@@ -73,7 +77,7 @@ ${sortedSummary
 `;
 
 const footer = `
-${b('Documentation:')} ${u('https://poku.io')}
+${b('Documentation:')} ${u('https://poku.io/docs')}
 
 ${bullet} ${b('Poku')} is made with ${b('love')} and ${b('care')} in every detail.
 ${bullet} Give him a ${b('star')} to show your support 🌟

src/bin/index.ts

@@ -1,7 +1,7 @@
 #! /usr/bin/env node
 import { escapeRegExp } from '../modules/helpers/list-files.js';
 import { getArg, getPaths, hasArg, argToArray } from '../parsers/get-arg.js';
-import { states } from '../configs/files.js';
+import { states } from '../configs/poku.js';
 import { format } from '../services/format.js';
 import { kill } from '../modules/helpers/kill.js';
 import { envFile } from '../modules/helpers/env.js';
@@ -11,6 +11,7 @@ import { getConfigs } from '../parsers/options.js';
 import { GLOBAL, VERSION } from '../configs/poku.js';
 
 (async () => {
+  /* c8 ignore next 4 */ // Version is tested during build process: "../../tools/build/version.ts"
   if (hasArg('version') || hasArg('v', '-')) {
     log(VERSION);
     return;
@@ -37,6 +38,11 @@ import { GLOBAL, VERSION } from '../configs/poku.js';
   const killPort = getArg('killPort');
   const killRange = getArg('killRange');
   const killPID = getArg('killPid');
+  const reporter =
+    getArg('reporter') ??
+    getArg('r', '-') ??
+    GLOBAL.configsFromFile.reporter ??
+    'poku';
   /* c8 ignore start */ // Deno
   const denoAllow = argToArray('denoAllow') ?? configsFromFile?.deno?.allow;
   const denoDeny = argToArray('denoDeny') ?? configsFromFile?.deno?.deny;
@@ -112,6 +118,7 @@ import { GLOBAL, VERSION } from '../configs/poku.js';
       cjs: denoCJS,
     },
     noExit: watchMode,
+    reporter,
     beforeEach:
       'beforeEach' in configsFromFile ? configsFromFile.beforeEach : undefined,
     afterEach:
@@ -160,15 +167,19 @@ import { GLOBAL, VERSION } from '../configs/poku.js';
   if (debug || configsFromFile?.debug) {
     hr();
     log(`${format(' Debug Enabled ').bg('brightBlue')}\n`);
-    log(`${format('…').info().italic()} ${format('Paths').bold()}`);
-    console.table(dirs);
-    log('\n');
     log(`${format('…').info().italic()} ${format('Options').bold()}`);
-    console.dir(GLOBAL.configs, { depth: null, colors: true });
+    console.dir(GLOBAL.configs, {
+      depth: Number.POSITIVE_INFINITY,
+      colors: true,
+    });
+    log(
+      `\n${format('💡')} To list all test files, run: ${format('poku --listFiles').bold()}`
+    );
   }
 
   await Promise.all(tasks);
   await poku(dirs);
 
+  /* c8 ignore next 1 */ // Blocked by TSX
   if (watchMode) await require('./watch.js').startWatch(dirs);
 })();

src/bin/watch.ts

@@ -5,13 +5,14 @@ import { log, hr } from '../services/write.js';
 import process from 'node:process';
 import { format } from '../services/format.js';
 import { getArg } from '../parsers/get-arg.js';
-import { fileResults } from '../configs/files.js';
 import { availableParallelism } from '../polyfills/os.js';
 import { GLOBAL } from '../configs/poku.js';
+import { errors } from '../services/reporters/poku.js';
 
 export const startWatch = async (dirs: string[]) => {
   let isRunning = false;
 
+  const { configs } = GLOBAL;
   const watchers: Set<Watcher> = new Set();
   const executing = new Set<string>();
   const interval = Number(getArg('watchInterval')) || 1500;
@@ -21,8 +22,7 @@ export const startWatch = async (dirs: string[]) => {
   };
 
   const resultsClear = () => {
-    fileResults.success.clear();
-    fileResults.fail.clear();
+    errors.length = 0;
   };
 
   const listenStdin = async (input: Buffer | string) => {
@@ -44,8 +44,8 @@ export const startWatch = async (dirs: string[]) => {
   const mappedTests = await mapTests(
     '.',
     dirs,
-    GLOBAL.configs.filter,
-    GLOBAL.configs.exclude
+    configs.filter,
+    configs.exclude
   );
 
   for (const mappedTest of Array.from(mappedTests.keys())) {
@@ -62,9 +62,9 @@ export const startWatch = async (dirs: string[]) => {
         if (!tests) return;
 
         await poku(Array.from(tests), {
-          ...GLOBAL.configs,
+          ...configs,
           concurrency:
-            GLOBAL.configs.concurrency ??
+            configs.concurrency ??
             Math.max(Math.floor(availableParallelism() / 2), 1),
         });
 

src/builders/reporter.ts

@@ -0,0 +1,9 @@
+import type { ReporterEvents, ReporterPlugin } from '../@types/poku.js';
+import { poku } from '../services/reporters/poku.js';
+
+export const createReporter = (events: ReporterEvents): ReporterPlugin => {
+  return () => ({
+    ...poku,
+    ...events,
+  });
+};