feat: add --list-files command line option (#645)

* feat: add `--list-files` flag

* docs: add `--list-files` usage and examples

* docs: add history

src/bin/index.ts

@@ -74,6 +74,37 @@ import { getConfigs } from '../parsers/options.js';
     states.isSinglePath = true;
   }
 
+  if (hasArg('list-files')) {
+    const { listFiles } = require('../modules/helpers/list-files.js');
+
+    let total = 0;
+
+    Write.hr();
+
+    for (const dir of dirs) {
+      const files: string[] = await listFiles(dir, {
+        filter:
+          typeof filter === 'string'
+            ? new RegExp(escapeRegExp(filter))
+            : filter,
+        exclude:
+          typeof exclude === 'string'
+            ? new RegExp(escapeRegExp(exclude))
+            : exclude,
+      });
+
+      total += files.length;
+
+      Write.log(files.map((file) => `${format('-').dim()} ${file}`).join('\n'));
+    }
+
+    Write.hr();
+    Write.log(`Total test files: ${format(String(total)).bold()}`);
+    Write.hr();
+
+    return;
+  }
+
   const tasks: Promise<unknown>[] = [];
 
   /* c8 ignore start */ // Process-based

website/docs/documentation/helpers/list-files.mdx

@@ -1,6 +1,54 @@
+import { History } from '@site/src/components/History';
+
 # 🗄️ List Files
 
-Returns all files in a directory, independent of their depth.
+Returns all files in a directory (independent of their depth) or the file itself.
+
+<History
+  records={[
+    {
+      version: '2.4.0',
+      changes: [<>Support for CLI usage.</>],
+    },
+  ]}
+/>
+
+## CLI
+
+Displays all the files returned in the terminal, without running the tests.
+
+```sh
+npx poku --list-files
+```
+
+```sh
+npx poku ./test --list-files
+```
+
+```sh
+npx poku ./packages/**/test --list-files
+```
+
+```sh
+npx poku ./test/unit ./test/e2e --list-files
+```
+
+- You can use the `--filter` and `--exclude` flags and include multiple paths.
+
+:::note
+
+The files returned by `--list-files` don't reflect the paths displayed by `--debug`:
+
+- **`--debug`:** the paths to be searched for.
+- **`--list-files`:** the paths found.
+
+:::
+
+:::tip
+If you pass flags apart from `--filter` and `--exclude`, they will be ignored.
+:::
+
+## API
 
 > `listFiles(targetDir: string, configs?: ListFilesConfigs)`