From ad463908871731b1a92f29ea36fdc91631407169 Mon Sep 17 00:00:00 2001
From: Eric Doughty-Papassideris <edoughtypapassideris@linagora.com>
Date: Tue, 26 Mar 2024 12:06:22 +0100
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20CLI:=20better=20dev=20documentat?=
 =?UTF-8?q?ion=20and=20argument=20description=20(#438)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .gitignore                                    | 13 ++++++++++
 tdrive/backend/node/README.md                 | 10 --------
 .../src/cli/cmds/search_cmds/index_all.ts     | 24 ++++++++++++++++++-
 3 files changed, 36 insertions(+), 11 deletions(-)
 create mode 100644 .gitignore

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 00000000..9358044f
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,13 @@
+
+# Devenv
+.devenv*
+devenv.local.nix
+
+# direnv
+.direnv
+
+# pre-commit
+.pre-commit-config.yaml
+
+docker-data
+node_modules
\ No newline at end of file
diff --git a/tdrive/backend/node/README.md b/tdrive/backend/node/README.md
index c084b8c5..e44429cf 100644
--- a/tdrive/backend/node/README.md
+++ b/tdrive/backend/node/README.md
@@ -68,16 +68,6 @@ choices (or we're using it wrong).
 eval "$(bin/twake-cli completion)"
 ```
 
-#### Bash completion
-
-It's a bit awkward to do real completion from a configuration since this isn't really a node module we recommend to install globally.
-This should setup a shell if you're in the right path however. It's yarg's auto generated completion though; so eg: it mixes up commands and
-choices (or we're using it wrong).
-
-```sh
-eval "$(bin/twake-cli completion)"
-```
-
 ### Component Framework
 
 The backend is developed using a software component approach in order to compose and adapt the platform based on needs and constraints.
diff --git a/tdrive/backend/node/src/cli/cmds/search_cmds/index_all.ts b/tdrive/backend/node/src/cli/cmds/search_cmds/index_all.ts
index a8bec93a..b508b997 100644
--- a/tdrive/backend/node/src/cli/cmds/search_cmds/index_all.ts
+++ b/tdrive/backend/node/src/cli/cmds/search_cmds/index_all.ts
@@ -22,6 +22,7 @@ type Options = {
   repairEntities: boolean;
 };
 
+const repairEntitiesArgumentDetails = [];
 const waitTimeoutMS = (ms: number) => ms > 0 && new Promise(r => setTimeout(r, ms));
 const defaultPageSize = "100";
 
@@ -41,6 +42,9 @@ async function iterateOverRepoPages<Entity>(
   } while (page.page_token);
 }
 
+/** This is an abstract base class for re-index cli commands; it stores runtime options
+ *  into fields; runs repair first if request and re-indexes generically from the database
+ *  to search services. */
 abstract class ReindexerCLICommand<Entity> {
   protected readonly database: DatabaseServiceAPI;
   protected readonly search: SearchServiceAPI;
@@ -80,6 +84,9 @@ abstract class ReindexerCLICommand<Entity> {
     this.options.spinner.info(`${this.table} > ${info}`);
   }
 
+  /** Override in sub-classes to translate a page from database to search entities.
+   * This is called by `reindexFromDBToSearch` so if that is overriden; this won't be called.
+   */
   protected async repairEntities(): Promise<void> {
     this.statusWarn(`repairEntities > No repair action for ${this.table}`);
   }
@@ -88,6 +95,11 @@ abstract class ReindexerCLICommand<Entity> {
     return entities;
   }
 
+  /** Override in a sub-class to completely replace the re-indexing logic.
+   * - Iterates over pages of the entity from the database repository
+   *     - calls `mapEntitiesToReIndexFromDBToSearch` to convert each page to a search entity
+   *     - and upserts the result into the search repository
+   */
   protected async reindexFromDBToSearch(): Promise<void> {
     const repository = await this.dbRepository();
     this.statusStart("Start indexing...");
@@ -105,6 +117,8 @@ abstract class ReindexerCLICommand<Entity> {
     await waitTimeoutMS(giveFlushAChanceDurationMS);
     this.statusSucceed("Done!");
   }
+
+  /** Run both operations: repair if requested and re-index */
   public async run(): Promise<void> {
     if (this.options.repairEntities) await this.repairEntities();
     await this.reindexFromDBToSearch();
@@ -149,6 +163,9 @@ RepositoryNameToCTOR.set(
   "users",
   (platform, options) => new UserReindexerCLICommand(platform, options),
 );
+repairEntitiesArgumentDetails.push(
+  "users: Rebuild cache.companies and save to database if changed",
+);
 
 class DocumentsReindexerCLICommand extends ReindexerCLICommand<DriveFile> {
   constructor(platform: TdrivePlatform, options: Options) {
@@ -159,6 +176,9 @@ RepositoryNameToCTOR.set(
   "documents",
   (platform, options) => new DocumentsReindexerCLICommand(platform, options),
 );
+repairEntitiesArgumentDetails.push(
+  "documents: Download and re-extract keywords before re-indexing",
+);
 
 const reindexingArgumentGroupTitle = "Re-indexing options";
 const repositoryArgumentName = "repository";
@@ -176,7 +196,9 @@ const command: yargs.CommandModule<unknown, unknown> = {
     repairEntities: {
       default: false,
       type: "boolean",
-      description: "Repair entities too when possible",
+      description: ["Repair entities too when possible", ...repairEntitiesArgumentDetails].join(
+        "\n- ",
+      ),
       group: reindexingArgumentGroupTitle,
     },
   },