@servicetitan/startup 33.1.1 → 34.0.0

package/src/cli/commands/review/rules/require-compatible-launch-darkly-sdk.ts

@@ -56,7 +56,7 @@ export class RequireCompatibleLaunchDarklySdk implements PackageRule {
 
         [
             `npm pkg set dependencies["${JS_CLIENT_SDK}"]=${targetVersion}`,
-            'npx startup install --fix --quiet',
+            'npx @servicetitan/install --fix --quiet',
             `npm pkg delete dependencies["${JS_CLIENT_SDK}"]`,
         ].forEach(command => execSync(command, { stdio: 'inherit' }));
     }

package/src/cli/commands/review/rules/require-one-uikit-version.ts

@@ -16,6 +16,7 @@ const UIKIT_PACKAGES = [
     '@servicetitan/react-ioc',
     '@servicetitan/restrict-imports',
     '@servicetitan/startup',
+    '@servicetitan/startup-utils',
     '@servicetitan/stylelint-config',
     '@servicetitan/suppress-warnings',
     '@servicetitan/web-components',

package/src/cli/commands/review/rules/require-project-version-in-root-node-modules.ts

@@ -1,9 +1,9 @@
 import chalk from 'chalk';
+import { execSync } from 'child_process';
 import { satisfies } from 'semver';
+import { log } from '../../../../utils';
 import { FixCategory, PackageError, PackageRule, Project } from '../types';
 import { applyFilter, getKey, getMaxVersion } from '../utils';
-import { execSync } from 'child_process';
-import { log } from '../../../../utils';
 
 interface Mismatch {
     name: string;
@@ -67,7 +67,7 @@ export class RequireProjectVersionInRootNodeModules implements PackageRule {
 
         [
             ...entries.map(([name, version]) => `npm pkg set dependencies["${name}"]="${version}"`),
-            'npx startup install --fix --quiet',
+            'npx @servicetitan/install --fix --quiet',
             ...entries.map(([name]) => `npm pkg delete dependencies["${name}"]`),
         ].forEach(command => execSync(command, { stdio: 'inherit' }));
     }

package/src/cli/commands/review/rules/require-tsconfig-references.ts

@@ -0,0 +1,157 @@
+import { globSync } from 'glob';
+import fs from 'node:fs';
+import path from 'node:path';
+import { getTsConfig, prettifySync, readJsonSafe } from '../../../../utils';
+import { FixCategory, Package, PackageError, PackageRule, Project } from '../types';
+import { checkPackages } from '../utils';
+
+interface TsConfig {
+    references?: { path: string }[];
+}
+
+interface ErrorData {
+    tsconfigPath: string;
+    missingReference: string;
+    expectedPath: string;
+}
+
+export type RuleError = PackageError<ErrorData>;
+
+export class RequireTsconfigReferences implements PackageRule {
+    private packageNameToLocation!: Map<string, string>;
+    private locationToPackageName!: Map<string, string>;
+    private workspacePackageNames!: Set<string>;
+
+    get id() {
+        return 'require-tsconfig-references';
+    }
+
+    run(project: Project): RuleError[] {
+        this.packageNameToLocation = new Map(
+            project.packages.map(({ name, location }) => [name, location])
+        );
+        this.locationToPackageName = new Map(
+            project.packages.map(({ name, location }) => [path.resolve(location), name])
+        );
+        this.workspacePackageNames = new Set(project.packages.map(({ name }) => name));
+
+        return checkPackages(this, project, this.checkTsConfigReferences);
+    }
+
+    fix({ data }: RuleError) {
+        if (!data) {
+            return;
+        }
+
+        const { tsconfigPath, expectedPath } = data;
+        const tsconfig = readJsonSafe<TsConfig>(tsconfigPath);
+        if (!tsconfig) {
+            return;
+        }
+
+        const references = tsconfig.references ?? [];
+        references.push({ path: expectedPath });
+        tsconfig.references = references;
+
+        fs.writeFileSync(tsconfigPath, JSON.stringify(tsconfig) + '\n', 'utf-8');
+        prettifySync(tsconfigPath);
+    }
+
+    private getLocalDependencies(pkg: Package) {
+        const dependencies = {
+            ...pkg.dependencies,
+            ...pkg.devDependencies,
+            ...pkg.peerDependencies,
+        };
+
+        return Object.keys(dependencies).filter(dependency =>
+            this.workspacePackageNames.has(dependency)
+        );
+    }
+
+    private normalizeTsConfigPath(filePath: string): string {
+        return filePath.endsWith('.json') ? filePath : `${filePath}.json`;
+    }
+
+    private getTsConfigReferencedPackages(tsconfigPath: string) {
+        const config = readJsonSafe<TsConfig>(tsconfigPath);
+        if (!config?.references) {
+            return new Set<string>();
+        }
+
+        const tsconfigDir = path.dirname(tsconfigPath);
+        const referencedPackages = new Set<string>();
+
+        for (const reference of config.references) {
+            const normalizedPath = this.normalizeTsConfigPath(reference.path);
+            const resolvedRefPath = path.resolve(tsconfigDir, normalizedPath);
+            const refDir = path.dirname(resolvedRefPath);
+            const packageName = this.locationToPackageName.get(refDir);
+
+            if (packageName) {
+                referencedPackages.add(packageName);
+            }
+        }
+
+        return referencedPackages;
+    }
+
+    private getExpectedReferencePath(fromLocation: string, toLocation: string) {
+        const relativePath = path.relative(fromLocation, toLocation);
+        const tsconfigFile = getTsConfig(toLocation);
+        const tsconfigName = path.basename(tsconfigFile);
+
+        return path.join(relativePath, tsconfigName).replaceAll('\\', '/');
+    }
+
+    private collectTsConfigFiles(location: string): string[] {
+        const tsconfigFiles = globSync(['tsconfig.json', 'tsconfig.*.json'], {
+            absolute: false,
+            cwd: location,
+        });
+
+        return tsconfigFiles.map(tsconfigFile => path.join(location, tsconfigFile));
+    }
+
+    private findMissingDependencyReferences(
+        pkg: Package,
+        tsconfigPath: string,
+        localDependencies: string[]
+    ): RuleError[] {
+        const referencedPackages = this.getTsConfigReferencedPackages(tsconfigPath);
+
+        return localDependencies
+            .filter(dependency => !referencedPackages.has(dependency))
+            .map(dependency => {
+                const dependencyLocation = this.packageNameToLocation.get(dependency)!;
+
+                return {
+                    id: this.id,
+                    message: `missing reference for dependency: ${dependency}`,
+                    location: tsconfigPath,
+                    fixable: FixCategory.normal,
+                    data: {
+                        tsconfigPath,
+                        missingReference: dependency,
+                        expectedPath: this.getExpectedReferencePath(
+                            pkg.location,
+                            dependencyLocation
+                        ),
+                    },
+                };
+            });
+    }
+
+    private readonly checkTsConfigReferences = (pkg: Package) => {
+        if (pkg.location === '.') {
+            return [];
+        }
+
+        const tsconfigFiles = this.collectTsConfigFiles(pkg.location);
+        const localDependencies = this.getLocalDependencies(pkg);
+
+        return tsconfigFiles.flatMap(tsconfigPath =>
+            this.findMissingDependencyReferences(pkg, tsconfigPath, localDependencies)
+        );
+    };
+}

package/src/cli/commands/review/utils/__tests__/set-version.test.ts

@@ -1,7 +1,6 @@
 import { execSync } from 'child_process';
 import path from 'path';
 import { Package } from '../../types';
-
 import { setVersion } from '../set-version';
 
 jest.mock('child_process', () => ({ execSync: jest.fn() }));

package/src/cli/commands/run-task.test.ts

@@ -1,9 +1,11 @@
+import { log } from '../../utils';
 import { SwcCompilePackage } from '../tasks/swc-compile-package';
 import { TscCompile } from '../tasks/tsc-compile';
 import { TscCompilePackage } from '../tasks/tsc-compile-package';
-
 import { RunTask } from './run-task';
-import { log } from '../../utils';
+
+jest.mock('yargs', () => jest.fn());
+jest.mock('yargs/helpers', () => ({ hideBin: jest.fn() }));
 
 jest.mock('../../utils', () => ({
     ...jest.requireActual('../../utils'),
@@ -40,13 +42,23 @@ describe(`[startup] ${RunTask.name}`, () => {
         })
     );
 
+    describe('with empty args', () => {
+        beforeEach(() => (args = {}));
+
+        test('logs error for undefined task', async () => {
+            await subject();
+
+            expect(log.error).toHaveBeenCalledWith('Unknown task: "undefined"');
+        });
+    });
+
     describe('with unrecognized task', () => {
         beforeEach(() => (args = { _: ['foo'] })); // eslint-disable-line @typescript-eslint/naming-convention
 
         test('logs error', async () => {
             await subject();
 
-            expect(log.error).toHaveBeenCalledWith(`Unknown task: "${args._[0]}"`);
+            expect(log.error).toHaveBeenCalledWith(`Unknown task: "${args._?.[0]}"`);
         });
 
         test('lists supported tasks', async () => {

package/src/cli/commands/run-task.ts

@@ -1,16 +1,16 @@
 /* eslint-disable @typescript-eslint/naming-convention */
 import { log, logErrors } from '../../utils';
 import { SwcCompilePackage } from '../tasks/swc-compile-package';
-import { TscCompilePackage } from '../tasks/tsc-compile-package';
-import { TscCompile } from '../tasks/tsc-compile';
 import { Task } from '../tasks/task';
-import { Command, CommandArgs } from './types';
+import { TscCompile } from '../tasks/tsc-compile';
+import { TscCompilePackage } from '../tasks/tsc-compile-package';
+import { Command, CommandOptions } from './types';
 
-interface Args extends CommandArgs {
-    _: string[];
-    taskName?: string;
-    taskArgs?: string[];
-}
+const options = {
+    _: { description: '<taskName> [taskArgs...]', array: true, string: true },
+    taskName: { string: true, hidden: true },
+    taskArgs: { array: true, string: true, hidden: true },
+} satisfies CommandOptions;
 
 const tasks: Record<string, new (args: { [key: string]: unknown }) => Task> = {
     'tsc-compile-package': TscCompilePackage,
@@ -18,16 +18,14 @@ const tasks: Record<string, new (args: { [key: string]: unknown }) => Task> = {
     'tsc-compile': TscCompile,
 };
 
-export class RunTask extends Command<Args> {
-    static readonly options = {
-        _: { description: '<taskName> [taskArgs...]' },
-    };
+export class RunTask extends Command<typeof options> {
+    static readonly options = options;
 
     @logErrors
     async execute() {
-        const { _, taskName = this.args._[0], taskArgs = [], ...restOptions } = this.args;
+        const { _ = [], taskName = this.args._?.[0], taskArgs = [], ...restOptions } = this.args;
 
-        if (taskName in tasks) {
+        if (taskName && taskName in tasks) {
             await new tasks[taskName]({
                 _: [..._, ...taskArgs],
                 ...restOptions,

package/src/cli/commands/start.ts

@@ -1,24 +1,25 @@
 import { getPackages, log, logErrors, PackageType } from '../../utils';
 import {
     checkArgs,
-    lernaExec,
     compile,
-    typeCheck,
+    lernaExec,
     pipeStdout,
-    watchStdout,
     ProcessTree,
+    typeCheck,
+    watchStdout,
 } from '../utils';
-import { Command, CommandArgs } from './types';
-
-interface Args extends CommandArgs {
-    'config'?: string;
-    'code-coverage'?: boolean;
-    'ignore'?: string | string[];
-    'scope'?: string | string[];
-    'use-tsc'?: boolean;
-}
+import { Command, CommandOptions } from './types';
+
+const options = {
+    codeCoverage: { boolean: true, description: 'Instrument code for coverage analysis?' },
+    config: { string: true, hidden: true, description: 'Use specified configuration' },
+    ignore: { array: true, string: true, description: 'Packages to skip' },
+    scope: { array: true, string: true, description: 'Packages to run and watch' },
+    useTsc: { boolean: true, description: 'Use tsc to compile packages?' },
+} satisfies CommandOptions;
 
 enum StartProcesses {
+    Precompile,
     Compile,
     KendoUILicense,
     PreparePackage,
@@ -28,22 +29,16 @@ enum StartProcesses {
     BundlePackage,
 }
 
-export class Start extends Command<Args> {
+export class Start extends Command<typeof options> {
     static readonly description = 'Run project in development mode';
     static readonly greedy = true;
-    static readonly options = {
-        'config': { string: true, hidden: true, description: 'Use specified configuration' },
-        'code-coverage': { boolean: true, description: 'Instrument code for coverage analysis?' },
-        'ignore': { array: true, description: 'Packages to skip' },
-        'scope': { array: true, description: 'Packages to run and watch' },
-        'use-tsc': { boolean: true, description: 'Use tsc to compile packages?' },
-    };
+    static readonly options = options;
 
     @logErrors
     async execute() {
         checkArgs(this.args, { obsolete: ['--esbuild', '--experimental-bundlers'] });
 
-        const useTsc = this.args['use-tsc'];
+        const useTsc = this.args.useTsc;
 
         const packages = getPackages({
             scope: this.args.scope,
@@ -58,52 +53,73 @@ export class Start extends Command<Args> {
         const webpackScope = packages
             .filter(({ type }) => type === PackageType.Webpack)
             .map(({ name }) => name);
+        const precompileScope = packages
+            .filter(({ scripts }) => !!scripts?.precompile)
+            .map(({ name }) => name);
 
         const processTree = new ProcessTree<typeof StartProcesses>();
 
-        processTree.add(StartProcesses.Compile, () => {
-            const process = compile({
-                packages: scope,
-                watch: true,
-                useTsc,
+        processTree.add(StartProcesses.Precompile, () => {
+            if (precompileScope.length === 0) {
+                return Promise.resolve();
+            }
+            return lernaExec({
+                cmd: 'npm run precompile',
+                scope: precompileScope,
+                parallel: true,
+                stream: true,
             });
+        });
 
-            pipeStdout(process);
-
-            const onComplete = new Promise<void>(resolve => {
-                let counter = 0;
-                let timeout: NodeJS.Timeout;
-
-                if (!useTsc) {
-                    /*
-                     * Running the timer as a fallback
-                     * In case there are no files in the package swc will not print out completion indicator
-                     */
-                    timeout = setTimeout(() => {
-                        log.warning('Compilation timeout exceeded. Proceeding without waiting.');
-                        resolve();
-                        unwatch();
-                    }, 30000);
-                }
-
-                const unwatch = watchStdout(
-                    process,
-                    useTsc
-                        ? 'Initial tsc-compile-package task completed'
-                        : 'Initial swc-compile-package task completed',
-                    count => {
-                        counter += count;
+        processTree.add(
+            StartProcesses.Compile,
+            () => {
+                const process = compile({
+                    packages: scope,
+                    watch: true,
+                    useTsc,
+                });
 
-                        if (counter === scope.length) {
+                pipeStdout(process);
+
+                const onComplete = new Promise<void>(resolve => {
+                    let counter = 0;
+                    let timeout: NodeJS.Timeout;
+
+                    if (!useTsc) {
+                        /*
+                         * Running the timer as a fallback
+                         * In case there are no files in the package swc will not print out completion indicator
+                         */
+                        timeout = setTimeout(() => {
+                            log.warning(
+                                'Compilation timeout exceeded. Proceeding without waiting.'
+                            );
                             resolve();
-                            clearTimeout(timeout);
-                        }
+                            unwatch();
+                        }, 30000);
                     }
-                );
-            });
 
-            return { process, onComplete };
-        });
+                    const unwatch = watchStdout(
+                        process,
+                        useTsc
+                            ? 'Initial tsc-compile-package task completed'
+                            : 'Initial swc-compile-package task completed',
+                        count => {
+                            counter += count;
+
+                            if (counter === scope.length) {
+                                resolve();
+                                clearTimeout(timeout);
+                            }
+                        }
+                    );
+                });
+
+                return { process, onComplete };
+            },
+            { dependsOn: [StartProcesses.Precompile] }
+        );
         processTree.add(StartProcesses.PreparePackage, () =>
             lernaExec({
                 cmd: 'startup prepare-package',
@@ -158,7 +174,7 @@ export class Start extends Command<Args> {
                     '--': [
                         '--watch',
                         this.args.config ? `--config "${this.args.config}"` : undefined,
-                        this.args['code-coverage'] ? '--code-coverage' : undefined,
+                        this.args.codeCoverage ? '--code-coverage' : undefined,
                     ].filter(item => !!item) as string[],
                 });
             },

package/src/cli/commands/stylelint.ts

@@ -1,18 +1,16 @@
 /* eslint-disable @typescript-eslint/naming-convention */
 import { logErrors } from '../../utils';
 import { stylelint } from '../utils/stylelint';
-import { Command, CommandArgs } from './types';
+import { Command, CommandOptions } from './types';
 
-interface Args extends CommandArgs {
-    _: string[];
-    fix?: boolean;
-    paths?: string[];
-}
+const options = {
+    _: { description: '[paths...]', array: true, string: true },
+    fix: { boolean: true, hidden: true },
+    paths: { array: true, string: true, hidden: true },
+} satisfies CommandOptions;
 
-export class Stylelint extends Command<Args> {
-    static readonly options = {
-        _: { description: '[paths...]' },
-    };
+export class Stylelint extends Command<typeof options> {
+    static readonly options = options;
 
     @logErrors
     async execute() {
@@ -20,7 +18,7 @@ export class Stylelint extends Command<Args> {
     }
 
     private get paths() {
-        const { _, paths = [] } = this.args;
+        const { _ = [], paths = [] } = this.args;
         return [..._, ...paths];
     }
 }

package/src/cli/commands/test/runners/__tests__/jest.test.ts

@@ -1,7 +1,6 @@
 import { runCLI } from '@jest/core';
-
-import { Jest } from '../jest';
 import { getJestConfigCLI } from '../../../../../utils';
+import { Jest } from '../jest';
 
 jest.mock('@jest/core', () => ({ runCLI: jest.fn() }));
 jest.mock('../../../../../utils', () => ({

package/src/cli/commands/test/runners/vitest.ts

@@ -1,5 +1,5 @@
 import { configDefaults, coverageConfigDefaults, mergeConfig, ViteUserConfig } from 'vitest/config';
-import { startVitest, parseCLI, resolveConfig } from 'vitest/node';
+import { parseCLI, resolveConfig, startVitest } from 'vitest/node';
 import { getVitestConfiguration, log, omit } from '../../../../utils';
 import svgTransformer from '../../../../vitest/svg-transformer';
 

package/src/cli/commands/test/tests.ts

@@ -1,34 +1,32 @@
 /* eslint-disable @typescript-eslint/naming-convention */
 import { Config } from '@jest/types';
 import { getConfiguration, logErrors } from '../../../utils';
-import { Command } from '../types';
+import { Command, CommandOptions } from '../types';
 import { Jest, Vitest } from './runners';
 
-type Args = Config.Argv & {
-    runner?: 'jest' | 'vitest';
-    runnerArgs?: string[];
-};
+const options = {
+    _: { description: '[runnerArgs...]', array: true, string: true },
+    runner: {
+        choices: ['jest', 'vitest'] as const,
+        description: 'Test runner',
+        defaultDescription: 'jest',
+    },
+    runnerArgs: { array: true, string: true, hidden: true },
+} satisfies CommandOptions;
 
 /**
  * This class is named "Tests" instead of "Test" because the corresponding
  * "test.ts" would be interpreted as a test file.
  */
-export class Tests extends Command<Args> {
+export class Tests extends Command<typeof options, Config.Argv> {
     static readonly description = 'Run tests';
     static readonly greedy = true;
-    static readonly options = {
-        _: { description: '[runnerArgs...]' },
-        runner: {
-            choices: ['jest', 'vitest'],
-            description: 'Test runner',
-            defaultDescription: 'jest',
-        },
-    };
+    static readonly options = options;
 
     @logErrors
     async execute() {
         const {
-            _,
+            _ = [],
             runner = getConfiguration().testRunner ?? 'jest',
             runnerArgs = [],
             ...restOptions

package/src/cli/commands/types.ts

@@ -1,15 +1,61 @@
-import type { Options } from 'yargs';
+import type { InferredOptionTypes, Options } from 'yargs';
 
-export interface CommandArgs {
-    [key: string]: unknown;
-}
+export type CommandOptions = Record<string, Options>;
+
+/**
+ * Expands a type by resolving any type aliases and intersections into a single object type.
+ *
+ * This is useful for flattening complex type compositions so their properties are materialized,
+ * especially when working with mapped types and conditional types.
+ *
+ * @template T - The type to expand.
+ * @example
+ * type Input = { a: string } & { b: number };
+ * type Output = Expand<Input>; // { a: string; b: number }
+ */
+type Expand<T> = T extends infer O ? { [K in keyof O]: O[K] } : never;
+
+/**
+ * Transforms a type so that properties whose value type includes `undefined`
+ * become optional (`?:`), while properties that cannot be `undefined` remain required.
+ *
+ * @example
+ * type Input = { a: string; b: string | undefined; c?: number };
+ * type Output = UndefinedToOptional<Input>;
+ * // Results in: { a: string; b?: string | undefined; c?: number }
+ */
+type UndefinedToOptional<T> = {
+    [K in keyof T as undefined extends T[K] ? never : K]: T[K];
+} & {
+    [K in keyof T as undefined extends T[K] ? K : never]?: T[K];
+};
+
+/**
+ * Infers the command args type from a yargs options definition object.
+ * Makes properties optional unless demandOption is set to true.
+ *
+ * @example
+ * const options = {
+ *     watch: { boolean: true, description: '...' },
+ *     outputPath: { string: true, description: '...' },
+ *     config: { string: true, demandOption: true, description: '...' },
+ * } satisfies CommandOptions;
+ *
+ * type Args = InferArgs<typeof options>;
+ * // Results in: { watch?: boolean; outputPath?: string; config: string; }
+ */
+export type InferArgs<T extends CommandOptions, U = unknown> = Expand<
+    UndefinedToOptional<InferredOptionTypes<T>>
+> &
+    U;
 
-export abstract class Command<T extends CommandArgs = CommandArgs> {
+export abstract class Command<T extends CommandOptions = CommandOptions, U = unknown> {
+    static readonly allowRunFromGlobal?: boolean;
     static readonly description?: string;
     static readonly greedy?: boolean;
-    static readonly options?: { [key: string]: Options };
+    static readonly options?: CommandOptions;
 
-    constructor(protected readonly args: T) {}
+    constructor(protected readonly args: InferArgs<T, U>) {}
 
     abstract execute(): Promise<void>;
 }