From 49f62919efab319a8aaeca1f240d64cf85c2e1b6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Weslley=20Ara=C3=BAjo?=
 <46850407+wellwelwel@users.noreply.github.com>
Date: Sat, 3 Aug 2024 17:03:04 -0300
Subject: [PATCH] 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                              | 31 ++++++++++++
 .../docs/documentation/helpers/list-files.mdx | 50 ++++++++++++++++++-
 2 files changed, 80 insertions(+), 1 deletion(-)

diff --git a/src/bin/index.ts b/src/bin/index.ts
index 91ddd8d3..b490216b 100644
--- a/src/bin/index.ts
+++ b/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
diff --git a/website/docs/documentation/helpers/list-files.mdx b/website/docs/documentation/helpers/list-files.mdx
index 5a8c7139..570a2987 100644
--- a/website/docs/documentation/helpers/list-files.mdx
+++ b/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)`