feat: new sparo lib

apps/sparo-lib/.eslintrc.js

@@ -0,0 +1,19 @@
+// This is a workaround for https://github.com/eslint/eslint/issues/3458
+require('@rushstack/heft-node-rig/profiles/default/includes/eslint/patch/modern-module-resolution');
+// This is a workaround for https://github.com/microsoft/rushstack/issues/3021
+require('@rushstack/heft-node-rig/profiles/default/includes/eslint/patch/custom-config-package-names');
+
+module.exports = {
+  extends: [
+    '@rushstack/heft-node-rig/profiles/default/includes/eslint/profile/node-trusted-tool',
+    '@rushstack/heft-node-rig/profiles/default/includes/eslint/mixins/friendly-locals'
+  ],
+  parserOptions: { tsconfigRootDir: __dirname },
+
+  overrides: [
+    {
+      files: ['*.ts', '*.tsx'],
+      rules: {}
+    }
+  ]
+};

apps/sparo-lib/.npmignore

@@ -0,0 +1,32 @@
+# THIS IS A STANDARD TEMPLATE FOR .npmignore FILES IN THIS REPO.
+
+# Ignore all files by default, to avoid accidentally publishing unintended files.
+*
+
+# Use negative patterns to bring back the specific things we want to publish.
+!/bin/**
+!/lib/**
+!/lib-*/**
+!/dist/**
+!ThirdPartyNotice.txt
+
+# Ignore certain patterns that should not get published.
+/dist/*.stats.*
+/lib/**/test/
+/lib-*/**/test/
+*.test.js
+
+# NOTE: These don't need to be specified, because NPM includes them automatically.
+#
+# package.json
+# README (and its variants)
+# CHANGELOG (and its variants)
+# LICENSE / LICENCE
+
+#--------------------------------------------
+# DO NOT MODIFY THE TEMPLATE ABOVE THIS LINE
+#--------------------------------------------
+
+# (Add your project-specific overrides here)
+!/assets/**
+/lib-*/**

apps/sparo-lib/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) TikTok Pte. Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

apps/sparo-lib/README.md

@@ -0,0 +1,6 @@
+## sparo-lib
+
+This is a companion package for the Sparo tool.
+
+The **sparo-lib** version number is always exactly equal
+to the **sparo** version number that it depends on.

apps/sparo-lib/config/api-extractor.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+
+  "mainEntryPointFilePath": "<projectFolder>/lib/index.d.ts",
+
+  "apiReport": {
+    "enabled": true,
+    "reportFolder": "../../../common/reviews/api"
+  },
+
+  "docModel": {
+    "enabled": true,
+    "apiJsonFilePath": "../../../common/temp/api/<unscopedPackageName>.api.json"
+  },
+
+  "dtsRollup": {
+    "enabled": true
+  }
+}

apps/sparo-lib/config/jest.config.json

@@ -0,0 +1,3 @@
+{
+  "extends": "@rushstack/heft-node-rig/profiles/default/config/jest.config.json"
+}

apps/sparo-lib/config/rig.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",
+
+  "rigPackageName": "@rushstack/heft-node-rig"
+}

apps/sparo-lib/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "sparo-lib",
+  "version": "0.0.0",
+  "description": "A library for writing scripts that interact with the Sparo",
+  "license": "MIT",
+  "main": "lib/index.js",
+  "typings": "dist/sparo-lib.d.ts",
+  "scripts": {
+    "_phase:build": "heft run --only build -- --clean",
+    "_phase:test": "heft run --only test -- --clean",
+    "test": "heft test --clean",
+    "build": "heft build --clean"
+  },
+  "dependencies": {
+    "@rushstack/node-core-library": "~3.64.2",
+    "git-repo-info": "~2.1.1",
+    "inversify": "~6.0.2",
+    "reflect-metadata": "~0.2.1",
+    "winston": "~3.11.0",
+    "yargs": "~17.7.2"
+  },
+  "devDependencies": {
+    "@rushstack/heft": "0.64.3",
+    "@rushstack/heft-node-rig": "2.4.5",
+    "@types/heft-jest": "1.0.6",
+    "@types/node": "20.11.16",
+    "@types/yargs": "17.0.32",
+    "eslint": "8.56.0",
+    "typescript": "~5.3.3"
+  }
+}

apps/sparo-lib/src/api/Sparo.ts

@@ -0,0 +1,37 @@
+import { SparoCommandLine } from '../cli/SparoCommandLine';
+import { SparoCICommandLine } from '../cli/SparoCICommandLine';
+import type { ICollectTelemetryFunction } from '../services/TelemetryService';
+
+/**
+ * Options to pass to the sparo "launch" functions.
+ *
+ * @public
+ */
+export interface ILaunchOptions {
+  /**
+   * A callback function to tell Sparo how to handle telemetry
+   * @internal
+   *
+   * @remarks
+   * This is a temporary implementation for customizing telemetry reporting.
+   * Later, the API will be redesigned to meet more generic requirements.
+   */
+  collectTelemetryAsync?: ICollectTelemetryFunction;
+}
+
+/**
+ * General operations for Sparo engine.
+ *
+ * @public
+ */
+export class Sparo {
+  private constructor() {}
+
+  public static async launchSparoAsync(launchOptions: ILaunchOptions): Promise<void> {
+    await SparoCommandLine.launchAsync(launchOptions);
+  }
+
+  public static async launchSparoCIAsync(launchOptions: ILaunchOptions): Promise<void> {
+    await SparoCICommandLine.launchAsync(launchOptions);
+  }
+}

apps/sparo/src/api/SparoCI.ts → apps/sparo-lib/src/cli/SparoCICommandLine.ts

@@ -1,18 +1,29 @@
 import 'reflect-metadata';
 import { getFromContainer, registerClass } from '../di/container';
 import { CommandService } from '../services/CommandService';
-import { CI_COMMAND_LIST } from '../commands/cmd-list';
-import { ICommand } from '../commands/base';
+import { CI_COMMAND_LIST } from './commands/cmd-list';
+import { ICommand } from './commands/base';
 import { ArgvService } from '../services/ArgvService';
-import { CIHelpCommand } from '../commands/ci-help';
+import { CIHelpCommand } from './commands/ci-help';
+import { GitVersionCompatibility } from '../logic/GitVersionCompatibility';
+import { TelemetryService } from '../services/TelemetryService';
+import { getCommandName } from './commands/util';
+import type { ILaunchOptions } from '../api/Sparo';
 
-class SparoCI {
+export class SparoCICommandLine {
   private _commandsMap: Set<string> = new Set<string>();
 
   private constructor() {}
 
-  public static async launchAsync(): Promise<void> {
-    const sparoCI: SparoCI = new SparoCI();
+  public static async launchAsync(launchOptions: ILaunchOptions): Promise<void> {
+    await GitVersionCompatibility.ensureGitVersionAsync();
+
+    if (launchOptions.collectTelemetryAsync) {
+      const telemetryService: TelemetryService = await getFromContainer(TelemetryService);
+      telemetryService.setCollectTelemetryFunction(launchOptions.collectTelemetryAsync);
+    }
+
+    const sparoCI: SparoCICommandLine = new SparoCICommandLine();
     await sparoCI.prepareCommandAsync();
     await sparoCI.runAsync();
   }
@@ -25,7 +36,7 @@ class SparoCI {
         registerClass(cmd);
         const cmdInstance: ICommand<{}> = await getFromContainer(cmd);
         commandsService.register(cmdInstance);
-        this._commandsMap.add(cmdInstance.cmd);
+        this._commandsMap.add(getCommandName(cmdInstance.cmd));
       })
     );
   }
@@ -45,5 +56,3 @@ class SparoCI {
     return this._commandsMap.has(commandName);
   }
 }
-
-export { SparoCI };

apps/sparo/src/api/Sparo.ts → apps/sparo-lib/src/cli/SparoCommandLine.ts

@@ -3,17 +3,28 @@ import { getFromContainer, registerClass } from '../di/container';
 import { GitService } from '../services/GitService';
 import { CommandService } from '../services/CommandService';
 import { ArgvService } from '../services/ArgvService';
-import { COMMAND_LIST } from '../commands/cmd-list';
-import { HelpCommand } from '../commands/help';
-import { ICommand } from '../commands/base';
+import { COMMAND_LIST } from './commands/cmd-list';
+import { HelpCommand } from './commands/help';
+import { ICommand } from './commands/base';
+import { GitVersionCompatibility } from '../logic/GitVersionCompatibility';
+import { TelemetryService } from '../services/TelemetryService';
+import { getCommandName } from './commands/util';
+import type { ILaunchOptions } from '../api/Sparo';
 
-class Sparo {
+export class SparoCommandLine {
   private _commandsMap: Set<string> = new Set<string>();
 
   private constructor() {}
 
-  public static async launchAsync(): Promise<void> {
-    const sparo: Sparo = new Sparo();
+  public static async launchAsync(launchOptions: ILaunchOptions): Promise<void> {
+    await GitVersionCompatibility.ensureGitVersionAsync();
+
+    if (launchOptions.collectTelemetryAsync) {
+      const telemetryService: TelemetryService = await getFromContainer(TelemetryService);
+      telemetryService.setCollectTelemetryFunction(launchOptions.collectTelemetryAsync);
+    }
+
+    const sparo: SparoCommandLine = new SparoCommandLine();
     await sparo.prepareCommandAsync();
     await sparo.runAsync();
   }
@@ -26,7 +37,7 @@ class Sparo {
         registerClass(cmd);
         const cmdInstance: ICommand<{}> = await getFromContainer(cmd);
         commandsService.register(cmdInstance);
-        this._commandsMap.add(cmdInstance.cmd);
+        this._commandsMap.add(getCommandName(cmdInstance.cmd));
       })
     );
   }
@@ -54,5 +65,3 @@ class Sparo {
     return this._commandsMap.has(commandName);
   }
 }
-
-export { Sparo };

apps/sparo/src/commands/auto-config.ts → apps/sparo-lib/src/cli/commands/auto-config.ts

@@ -1,9 +1,9 @@
 import { Argv } from 'yargs';
-import { Command } from '../decorator';
+import { Command } from '../../decorator';
 import { inject } from 'inversify';
-import { GitService } from '../services/GitService';
+import { GitService } from '../../services/GitService';
 import type { ArgumentsCamelCase } from 'yargs';
-import type { LogService } from '../services/LogService';
+import type { LogService } from '../../services/LogService';
 import type { ICommand } from './base';
 import type { GitRepoInfo } from 'git-repo-info';
 

apps/sparo/src/commands/base.ts → apps/sparo-lib/src/cli/commands/base.ts

@@ -1,5 +1,5 @@
 import type { Argv, ArgumentsCamelCase } from 'yargs';
-import type { LogService } from '../services/LogService';
+import type { LogService } from '../../services/LogService';
 
 export interface ICommand<O extends {}> {
   /**

apps/sparo/src/commands/ci-clone.ts → apps/sparo-lib/src/cli/commands/ci-clone.ts

@@ -1,10 +1,10 @@
 import { inject } from 'inversify';
-import { Command } from '../decorator';
-import { GitSparseCheckoutService } from '../services/GitSparseCheckoutService';
-import { GitCloneService, ICloneOptions } from '../services/GitCloneService';
+import { Command } from '../../decorator';
+import { GitSparseCheckoutService } from '../../services/GitSparseCheckoutService';
+import { GitCloneService, ICloneOptions } from '../../services/GitCloneService';
 import type { Argv, ArgumentsCamelCase } from 'yargs';
 import type { ICommand } from './base';
-import type { LogService } from '../services/LogService';
+import type { LogService } from '../../services/LogService';
 
 export interface ICloneCommandOptions {
   full?: boolean;

apps/sparo/src/commands/ci-help.ts → apps/sparo-lib/src/cli/commands/ci-help.ts

@@ -1,4 +1,4 @@
-import { Command } from '../decorator';
+import { Command } from '../../decorator';
 import type { Argv } from 'yargs';
 import type { ICommand } from './base';
 

apps/sparo/src/commands/ci-sparse.ts → apps/sparo-lib/src/cli/commands/ci-sparse.ts

@@ -1,8 +1,8 @@
 import { inject } from 'inversify';
 import type { Argv, ArgumentsCamelCase } from 'yargs';
 import { ICommand } from './base';
-import { Command } from '../decorator';
-import { GitSparseCheckoutService } from '../services/GitSparseCheckoutService';
+import { Command } from '../../decorator';
+import { GitSparseCheckoutService } from '../../services/GitSparseCheckoutService';
 
 export interface ICISparseCommandOptions {
   to?: string[];

apps/sparo/src/commands/clone.ts → apps/sparo-lib/src/cli/commands/clone.ts

@@ -1,11 +1,11 @@
 import { inject } from 'inversify';
-import { Command } from '../decorator';
+import { Command } from '../../decorator';
 import { executeSelfCmd } from './util';
-import { GitSparseCheckoutService } from '../services/GitSparseCheckoutService';
-import { GitCloneService, ICloneOptions } from '../services/GitCloneService';
+import { GitSparseCheckoutService } from '../../services/GitSparseCheckoutService';
+import { GitCloneService, ICloneOptions } from '../../services/GitCloneService';
 import type { Argv, ArgumentsCamelCase } from 'yargs';
 import type { ICommand } from './base';
-import type { LogService } from '../services/LogService';
+import type { LogService } from '../../services/LogService';
 
 export interface ICloneCommandOptions {
   full?: boolean;

apps/sparo/src/commands/cmd-list.ts → apps/sparo-lib/src/cli/commands/cmd-list.ts

@@ -1,4 +1,4 @@
-import { Constructable } from '../di/types';
+import { Constructable } from '../../di/types';
 import { CloneCommand } from './clone';
 import { HelpCommand } from './help';
 import { SparseCommand } from './sparse';

apps/sparo/src/commands/fetch.ts → apps/sparo-lib/src/cli/commands/fetch.ts

@@ -1,11 +1,11 @@
 import { inject } from 'inversify';
-import { Command } from '../decorator';
-import { GitService } from '../services/GitService';
+import { Command } from '../../decorator';
+import { GitService } from '../../services/GitService';
 
 import type { Argv, ArgumentsCamelCase } from 'yargs';
 import type { GitRepoInfo } from 'git-repo-info';
 import type { ICommand } from './base';
-import type { LogService } from '../services/LogService';
+import type { LogService } from '../../services/LogService';
 
 export interface IFetchCommandOptions {
   all?: boolean;

apps/sparo/src/commands/help.ts → apps/sparo-lib/src/cli/commands/help.ts

@@ -1,4 +1,4 @@
-import { Command } from '../decorator';
+import { Command } from '../../decorator';
 import { Argv } from 'yargs';
 import type { ICommand } from './base';
 

apps/sparo/src/commands/purge.ts → apps/sparo-lib/src/cli/commands/purge.ts

@@ -2,9 +2,9 @@ import { inject } from 'inversify';
 import { type ArgumentsCamelCase } from 'yargs';
 
 import { ICommand } from './base';
-import { Command } from '../decorator';
-import { GitSparseCheckoutService } from '../services/GitSparseCheckoutService';
-import { LocalState } from '../logic/LocalState';
+import { Command } from '../../decorator';
+import { GitSparseCheckoutService } from '../../services/GitSparseCheckoutService';
+import { LocalState } from '../../logic/LocalState';
 
 export interface ISparseCommandOptions {
   profile: string[];