feat(assert): human readability assert (#14)

* feat(assert): human readability `assert`

* chore: improve description

.github/codeql/codeql-config.yml

@@ -0,0 +1,5 @@
+name: 'CodeQL Config'
+
+paths:
+  - src/
+  - lib/

.github/workflows/codeql.yml

@@ -57,6 +57,7 @@ jobs:
 
           # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
           # queries: security-extended,security-and-quality
+          config-file: ./.github/codeql/codeql-config.yml
 
       # Autobuild attempts to build any compiled languages (C/C++, C#, Go, Java, or Swift).
       # If this step fails, then you should remove it and run the build manually (see below)

README.md

@@ -62,6 +62,20 @@ A flexible and easy-to-use **Test Runner** for [Node.js][node-version-url], [Bun
 
 ---
 
+**Poku** also includes the `assert` method, keeping everything as it is, but providing human readability:
+
+```ts
+import { assert } from 'poku'; // Node and Bun
+import { assert } from 'npm:poku'; // Deno
+
+assert(true);
+assert.deepStrictEqual(1, '1', 'My optional custom message');
+```
+
+> <img src=".github/assets/readme/assert.png" width="468" />
+
+---
+
 ## Install
 
 ### **Node.js**
@@ -462,6 +476,39 @@ npx poku --exclude='some-file-or-dir|other-file-or-dir' ./test
 
 ---
 
+### Assert
+
+> _Since **1.3.0**_
+>
+> [**Node.js**][node-version-url], [**Bun**][bun-version-url] and [**Deno**][deno-version-url] compatible.
+
+**Poku** includes the `assert` method, keeping everything as it is, but providing human readability.
+
+**Available methods:**
+
+- `assert(value[, message])`
+- `assert.deepEqual(actual, expected[, message])`
+- `assert.deepStrictEqual(actual, expected[, message])`
+- `assert.doesNotMatch(string, regexp[, message])`
+- `assert.doesNotReject(asyncFn[, error][, message])`
+- `assert.doesNotThrow(fn[, error][, message])`
+- `assert.equal(actual, expected[, message])`
+- `assert.fail([message])`
+- `assert.ifError(value)`
+- `assert.match(string, regexp[, message])`
+- `assert.notDeepEqual(actual, expected[, message])`
+- `assert.notDeepStrictEqual(actual, expected[, message])`
+- `assert.notEqual(actual, expected[, message])`
+- `assert.notStrictEqual(actual, expected[, message])`
+- `assert.ok(value[, message])`
+- `assert.rejects(asyncFn[, error][, message])`
+- `assert.strictEqual(actual, expected[, message])`
+- `assert.throws(fn[, error][, message])`
+
+You can follow the [**assert documentation**](https://nodejs.org/api/assert.html) from **Node.js**'s documentation.
+
+---
+
 ### `listFiles(targetDir: string, configs?: ListFilesConfigs)`
 
 > _Since **1.2.0**_

package.json

@@ -30,6 +30,8 @@
     "🐷",
     "test",
     "runner",
+    "assert",
+    "assertion",
     "testing",
     "run",
     "isolate",
@@ -42,12 +44,6 @@
     "unit",
     "integration",
     "typescript",
-    "tsx",
-    "filter",
-    "exclude",
-    "list",
-    "files",
-    "list-files",
     "queue",
     "queuing",
     "nodejs",
@@ -56,8 +52,21 @@
     "deno",
     "cli",
     "cli-app",
-    "easy",
-    "expect"
+    "expect",
+    "mocha",
+    "jest",
+    "ava",
+    "tap",
+    "tape",
+    "karma",
+    "filter",
+    "exclude",
+    "list",
+    "files",
+    "list-files",
+    "tsx",
+    "fast",
+    "easy"
   ],
   "author": "https://github.com/wellwelwel",
   "bugs": {

src/helpers/format.ts

@@ -5,6 +5,7 @@ export const format = {
     const totalDigits = String(total).length;
     return padStart(String(current), totalDigits, pad);
   },
+  dim: (value: string) => `\x1b[2m${value}\x1b[0m`,
   bold: (value: string) => `\x1b[1m${value}\x1b[0m`,
   underline: (value: string) => `\x1b[4m${value}\x1b[0m`,
   info: (value: string) => `\x1b[36m${value}\x1b[0m`,

src/helpers/hr.ts

@@ -3,7 +3,7 @@ import process from 'node:process';
 
 export const hr = () => {
   const columns = process.stdout.columns;
-  const line = '_'.repeat(columns - 10 || 0);
+  const line = '_'.repeat(columns - 10 || 30);
 
   console.log(`\x1b[2m${line}\x1b[0m${EOL}`);
 };

src/helpers/parseAsssetion.ts

@@ -0,0 +1,97 @@
+import process from 'node:process';
+import assert from 'node:assert';
+import { EOL } from 'node:os';
+import { format } from './format.js';
+import { hr } from './hr.js';
+
+export type ParseAssertionOptions = {
+  message?: string | Error;
+  defaultMessage?: string;
+  actual?: string;
+  expected?: string;
+  throw?: boolean;
+  hideDiff?: boolean;
+};
+
+const findFile = (error: Error) => {
+  const stackLines = error.stack?.split(EOL) || [];
+
+  let file = '';
+
+  const basePath = 'poku/lib/';
+
+  for (const line of stackLines) {
+    if (!line.includes(basePath)) {
+      const match = line.match(/at\s(\/.+|file:\/\/\/.+)/i);
+      if (match && match[1]) {
+        file = match[1];
+        break;
+      }
+    }
+  }
+
+  return file;
+};
+
+export const parseAssertion = (
+  cb: () => void,
+  options: ParseAssertionOptions
+) => {
+  try {
+    cb();
+  } catch (error) {
+    if (error instanceof assert.AssertionError) {
+      const { code, actual, expected, operator } = error;
+      const file = findFile(error);
+
+      hr();
+
+      if (typeof options.message === 'string')
+        console.log(format.bold(options.message), EOL);
+      else if (options.message instanceof Error)
+        console.log(format.bold(options.message.message), EOL);
+      else if (typeof options.defaultMessage === 'string')
+        console.log(options.defaultMessage, EOL);
+
+      console.log(format.dim('Code:    '), format.bold(format.fail(code)));
+      file && console.log(format.dim('File:    '), file);
+      console.log(format.dim('Operator:'), operator);
+
+      hr();
+
+      if (!options?.hideDiff) {
+        console.log(format.dim(`${options?.actual || 'Actual'}:`));
+        console.log(
+          format.bold(
+            typeof actual === 'function' || actual instanceof RegExp
+              ? String(actual)
+              : format.fail(JSON.stringify(actual))
+          )
+        );
+
+        console.log(
+          `${EOL}${format.dim(`${options?.expected || 'Expected'}:`)}`
+        );
+        console.log(
+          format.bold(
+            typeof expected === 'function' || expected instanceof RegExp
+              ? String(expected)
+              : format.success(JSON.stringify(expected))
+          )
+        );
+
+        hr();
+      }
+
+      if (options.throw) {
+        console.log(error);
+        hr();
+      }
+
+      process.exit(1);
+    }
+
+    // Non-assertion errors
+    throw error;
+  }
+};

src/index.ts

@@ -1,5 +1,6 @@
 export { poku } from './modules/poku.js';
 export { exit } from './modules/exit.js';
+export { assert } from './modules/assert.js';
 export { publicListFiles as listFiles } from './modules/list-files.js';
 export type { Code } from './@types/code.ts';
 export type { Configs } from './@types/poku.ts';