feat(cli): support for multiple paths in any position (#562)

* docs(website): add History and Stability components

* feat(cli): support for multiple paths in any position

* docs: improve history

* ci: add tests

* chore: improve perf

src/bin/index.ts

@@ -3,12 +3,7 @@
 import type { Configs } from '../@types/poku.js';
 import process from 'node:process';
 import { escapeRegExp } from '../modules/helpers/list-files.js';
-import {
-  getArg,
-  getLastParam,
-  hasArg,
-  argToArray,
-} from '../parsers/get-arg.js';
+import { getArg, getPaths, hasArg, argToArray } from '../parsers/get-arg.js';
 import { fileResults } from '../configs/files.js';
 import { platformIsValid } from '../parsers/get-runtime.js';
 import { format } from '../services/format.js';
@@ -30,14 +25,12 @@ import { getConfigs } from '../parsers/options.js';
       return includeArg.split(',');
     }
 
-    const lastParam = getLastParam();
-    if (lastParam !== undefined) {
-      return lastParam.split(',');
-    }
-
-    return defaultConfigs?.include
-      ? Array.prototype.concat(defaultConfigs?.include)
-      : ['.'];
+    return (
+      getPaths() ??
+      (defaultConfigs?.include
+        ? Array.prototype.concat(defaultConfigs?.include)
+        : ['.'])
+    );
   })();
   const platform = getArg('platform');
   const filter = getArg('filter') ?? defaultConfigs?.filter;

src/parsers/get-arg.ts

@@ -4,19 +4,6 @@ import { argv } from 'node:process';
 const [, , ...processArgs] = argv;
 const regexQuotes = /''|""/;
 
-/**
- * Gets the value of an argument.
- *
- * ---
- *
- * CLI arguments examples:
- *
- * ```sh
- * command --arg=some # 'some'
- * command --arg=""   # ''
- * command --arg      # undefined
- * ```
- */
 export const getArg = (
   arg: string,
   prefix = '--',
@@ -32,18 +19,6 @@ export const getArg = (
   return argValue.slice(argPattern.length).replace(regexQuotes, '');
 };
 
-/**
- * Checks if an argument exists.
- *
- * ---
- *
- * CLI arguments examples:
- *
- * ```sh
- * command --arg  # true
- * command        # false
- * ```
- */
 export const hasArg = (
   arg: string,
   prefix = '--',
@@ -54,29 +29,24 @@ export const hasArg = (
   return baseArgs.some((a) => a.startsWith(argPattern));
 };
 
-/**
- * Gets the last param/value.
- *
- * CLI arguments examples:
- *
- * ```sh
- * command --arg --arg2=some value  # 'value'
- * command value                    # 'value'
- * command                          # undefined
- * command --arg                    # undefined
- * ```
- */
-export const getLastParam = (
+export const getPaths = (
   prefix = '--',
   baseArgs = processArgs
-): string | undefined => {
-  const lastArg = baseArgs[baseArgs.length - 1];
+): string[] | undefined => {
+  let hasPaths = false;
+  const paths: string[] = [];
 
-  if (!lastArg || lastArg.startsWith(prefix)) {
-    return undefined;
+  for (const arg of baseArgs) {
+    if (!arg.startsWith(prefix)) {
+      hasPaths = true;
+      const parts = arg.split(',');
+      for (const part of parts) {
+        paths.push(part);
+      }
+    }
   }
 
-  return lastArg;
+  return hasPaths ? paths : undefined;
 };
 
 /* c8 ignore next */ // ?

test/unit/args.test.ts

@@ -4,8 +4,8 @@ import { assert } from '../../src/modules/essentials/assert.js';
 import {
   getArg,
   hasArg,
-  getLastParam,
   argToArray,
+  getPaths,
 } from '../../src/parsers/get-arg.js';
 
 describe('CLI Argument Handling Functions', async () => {
@@ -33,18 +33,6 @@ describe('CLI Argument Handling Functions', async () => {
     assert.strictEqual(result, false, 'Argument should not exist');
   });
 
-  await it('should get the last parameter', () => {
-    const args = ['value'];
-    const result = getLastParam('--', args);
-    assert.strictEqual(result, 'value', 'Last parameter should be "value"');
-  });
-
-  await it('should return undefined for last parameter if none provided', () => {
-    const args: string[] = [];
-    const result = getLastParam('--', args);
-    assert.strictEqual(result, undefined, 'Last parameter should be undefined');
-  });
-
   await it('should convert argument to array', () => {
     const args = ['--array=1,2,3'];
     const result = argToArray('array', '--', args);
@@ -70,4 +58,54 @@ describe('CLI Argument Handling Functions', async () => {
     const result = argToArray('array', '--', args);
     assert.strictEqual(result, undefined, 'Argument should be undefined');
   });
+
+  await it('should return paths without prefix arguments', () => {
+    const args = ['--arg=value', 'path1', 'path2'];
+    const result = getPaths('--', args);
+    assert.deepStrictEqual(
+      result,
+      ['path1', 'path2'],
+      'Should return ["path1", "path2"]'
+    );
+  });
+
+  await it('should split paths by comma', () => {
+    const args = ['path1,path2,path3'];
+    const result = getPaths('--', args);
+    assert.deepStrictEqual(
+      result,
+      ['path1', 'path2', 'path3'],
+      'Should split paths by comma'
+    );
+  });
+
+  await it('should return undefined if no paths provided', () => {
+    const args = ['--arg=value'];
+    const result = getPaths('--', args);
+    assert.strictEqual(
+      result,
+      undefined,
+      'Should return undefined if no paths'
+    );
+  });
+
+  await it('should handle mixed arguments with and without prefix', () => {
+    const args = ['--arg=value', 'path1', '--another=value', 'path2,path3'];
+    const result = getPaths('--', args);
+    assert.deepStrictEqual(
+      result,
+      ['path1', 'path2', 'path3'],
+      'Should return ["path1", "path2", "path3"]'
+    );
+  });
+
+  await it('should handle empty array', () => {
+    const args: string[] = [];
+    const result = getPaths('--', args);
+    assert.strictEqual(
+      result,
+      undefined,
+      'Should return undefined for empty array'
+    );
+  });
 });

website/docs/documentation/poku/config-files.mdx

@@ -2,16 +2,33 @@
 sidebar_position: 2
 ---
 
+import { History } from '@site/src/components/History';
+import { Stability } from '@site/src/components/Stability';
+
 # ⚙️ Config Files
 
 By default, **Poku** comes with the most common usage pre-set, but you can configure it as you want.
 
-:::danger
-Unreleased _(work in progress)_.
-:::
+<History
+  records={[
+    {
+      version: '2.1.0',
+      changes: [
+        <>
+          support for config files (<code>js</code> and <code>cjs</code>)
+        </>,
+        <>
+          support for config files (<code>json</code> and <code>jsonc</code>)
+        </>,
+      ],
+    },
+  ]}
+/>
 
 ## JavaScript
 
+<Stability level={2} message={'Recommended: supports functions and regex.'} />
+
 Create a `poku.js` (or `poku.cjs` when using `"type": "module"` in your _package.json_) in your project's root directory, for example:
 
 ```js
@@ -91,6 +108,10 @@ Create a `poku.json` (or `poku.jsonc`) in your project's root directory, for exa
 
 :::
 
+:::note
+Shares the same limitations as _CLI_ flags.
+:::
+
 <hr />
 
 ## Default Configuration Files

website/docs/documentation/poku/include-files.mdx

@@ -2,12 +2,33 @@
 sidebar_position: 1
 ---
 
+import { History } from '@site/src/components/History';
+import { Stability } from '@site/src/components/Stability';
+
 # 📦 Include Directories and Files
 
 By default, **Poku** searches for _`.test.`_ and `.spec.` files, but you can customize it using the [`filter`](/docs/documentation/poku/options/filter) option.
 
 ## CLI
 
+<History
+  records={[
+    {
+      version: '2.1.0',
+      changes: [
+        <>Support for multiple paths in any order.</>,
+        <>
+          Deprecate <code>--include</code> flag.
+        </>,
+        <>
+          Maintains retroactive support for multiple comma-separated paths to
+          avoid breaking changes.
+        </>,
+      ],
+    },
+  ]}
+/>
+
 ### Common usage
 
 ```bash
@@ -41,26 +62,19 @@ npx poku targetPath
 ```
 
 ```bash
-npx poku targetPathA,targetPathB
+npx poku targetPathA targetPathB
 ```
 
 <hr />
 
-### By using `--include` flag
-
-Using the `--include` flag, you can use it in any order:
-
-```bash
-npx poku --include='targetPath'
-```
+### `--include`
 
-```bash
-npx poku --include='targetPathA,targetPathB'
-```
-
-```bash
-npx poku --include='./'
-```
+<Stability
+  level={0}
+  message={
+    "It's now possible to pass multiple paths in any order since v2.1.0."
+  }
+/>
 
 <hr />