feat(cli): enforce flags validation (#699)

* feat(cli): enforce flags validation

* chore: improve general performance

* chore: better organize flags list

* ci: add tests

* docs: add docs

* ci: remove debug

biome.jsonc

@@ -25,7 +25,7 @@
           "level": "error",
           "options": {
             // TODO: better estimate complexity
-            "maxAllowedComplexity": 60
+            "maxAllowedComplexity": 45
           }
         }
       },
@@ -107,6 +107,16 @@
           }
         }
       }
+    },
+    {
+      "include": ["src/bin/index.ts"],
+      "linter": {
+        "rules": {
+          "complexity": {
+            "noExcessiveCognitiveComplexity": "off"
+          }
+        }
+      }
     }
   ]
 }

src/bin/enforce.ts

@@ -0,0 +1,57 @@
+import { argv, exit } from 'node:process';
+import { Write } from '../services/write.js';
+import { format } from '../services/format.js';
+
+export const checkFlags = () => {
+  const allowedFlags = new Set([
+    '--bun',
+    '--concurrency',
+    '--config',
+    '--debug',
+    '--deno',
+    '--denoAllow',
+    '--denoCjs',
+    '--denoDeny',
+    '--enforce',
+    '--envFile',
+    '--exclude',
+    '--failFast',
+    '--filter',
+    '--killPid',
+    '--killPort',
+    '--killRange',
+    '--node',
+    '--parallel',
+    '--platform',
+    '--quiet',
+    '--watch',
+    '--watchInterval',
+    '-c',
+    '-d',
+    '-p',
+    '-q',
+    '-w',
+    '-x',
+  ]);
+
+  const args = argv.slice(2);
+  const unrecognizedFlags: string[] = [];
+
+  for (const arg of args) {
+    const flagName = arg.split('=')[0];
+
+    if (!allowedFlags.has(flagName) && flagName.startsWith('-')) {
+      unrecognizedFlags.push(flagName);
+    }
+  }
+
+  if (unrecognizedFlags.length > 0) {
+    Write.hr();
+    Write.log(
+      `${format('Unrecognized flags:').bold()}\n\n${unrecognizedFlags.map((flag) => format(flag).fail()).join('\n')}`
+    );
+    Write.hr();
+
+    exit(1);
+  }
+};

src/bin/index.ts

@@ -20,6 +20,7 @@ import { getConfigs } from '../parsers/options.js';
     return;
   }
 
+  const enforce = hasArg('enforce') || hasArg('x', '-');
   const configFile = getArg('config') || getArg('c', '-');
   const defaultConfigs = await getConfigs(configFile);
   const dirs: string[] = (() => {
@@ -109,6 +110,12 @@ import { getConfigs } from '../parsers/options.js';
     return;
   }
 
+  if (enforce) {
+    const { checkFlags } = require('./enforce.js');
+
+    checkFlags();
+  }
+
   const tasks: Promise<unknown>[] = [];
 
   /* c8 ignore start */ // Process-based

test/e2e/cli-ensure-flags.test.ts

@@ -0,0 +1,48 @@
+import { describe } from '../../src/modules/helpers/describe.js';
+import { it } from '../../src/modules/helpers/it/core.js';
+import { assert } from '../../src/modules/essentials/assert.js';
+import { inspectPoku, isBuild } from '../__utils__/capture-cli.test.js';
+import { getRuntime } from '../../src/parsers/get-runtime.js';
+import { skip } from '../../src/modules/helpers/skip.js';
+
+const runtime = getRuntime();
+
+if (isBuild || runtime === 'deno') {
+  skip();
+}
+
+describe('Enforce Option', async () => {
+  await it('--enforce', async () => {
+    const output = await inspectPoku('--enforce -P --paralell', {
+      cwd: 'test/__fixtures__/e2e/no-tests',
+    });
+
+    assert.strictEqual(output.exitCode, 1, 'Exit Code needs to be 1');
+    assert(/Unrecognized flags/.test(output.stdout), 'Has unrecognized flags');
+    assert(/-P/.test(output.stdout), 'Short flag: wrong case for valid option');
+    assert(/--paralell/.test(output.stdout), 'Invalid option');
+  });
+
+  await it('-x', async () => {
+    const output = await inspectPoku('-x -P --paralell', {
+      cwd: 'test/__fixtures__/e2e/no-tests',
+    });
+
+    assert.strictEqual(output.exitCode, 1, 'Exit Code needs to be 1');
+    assert(/Unrecognized flags/.test(output.stdout), 'Has unrecognized flags');
+    assert(/-P/.test(output.stdout), 'Short flag: wrong case for valid option');
+    assert(/--paralell/.test(output.stdout), 'Invalid option');
+  });
+
+  await it('No ensure', async () => {
+    const output = await inspectPoku('-P --paralell', {
+      cwd: 'test/__fixtures__/e2e/no-tests',
+    });
+
+    assert.strictEqual(output.exitCode, 0, 'Exit Code needs to be 0');
+    assert(
+      !/Unrecognized flags/.test(output.stdout),
+      "Doesn't recognized wrong flags"
+    );
+  });
+});

website/docs/documentation/poku/options/enforce.mdx

@@ -0,0 +1,41 @@
+---
+sidebar_position: 10
+---
+
+import { History } from '@site/src/components/History';
+import { Stability } from '@site/src/components/Stability';
+
+# `enforce`
+
+Ensures that the execution is valid and safe before proceeding with the tests.
+
+<Stability level={1.1} />
+
+<History
+  records={[
+    {
+      version: '2.5.0',
+      changes: [
+        <>
+          <strong>CLI:</strong> Add <code>enforce</code> option.
+        </>,
+      ],
+    },
+  ]}
+/>
+
+- [x] Forces an error if any _CLI_ flags are invalid.
+- [ ] Forces an error if no file is found _(soon)_.
+- [ ] Forces an error if the environment has multiple platforms and the `--platform` option isn't explicit _(soon)_.
+
+## CLI
+
+```bash
+npx poku --enforce ./test
+```
+
+- Short flag: `-x`.
+
+:::info
+This feature will be included in the configuration file when the development stage is stable.
+:::