@servicetitan/startup 30.3.0 → 31.0.0

package/src/cli/commands/review/review.ts

@@ -0,0 +1,247 @@
+import chalk from 'chalk';
+import { execSync } from 'child_process';
+import terminalLink from 'terminal-link';
+import {
+    findPackages,
+    getReviewConfiguration,
+    log,
+    logErrors,
+    readJsonSafe,
+    toArray,
+} from '../../../utils';
+import { Command } from '../types';
+
+import {
+    ErrorSeverity,
+    FixCategory,
+    Level,
+    Package,
+    PackageError,
+    PackageRule,
+    Project,
+    RuleConfiguration,
+} from './types';
+import {
+    collateDependencies,
+    ErrorSummary,
+    formatLocation,
+    indent,
+    pluralize,
+    summarize,
+} from './utils';
+import { rules } from './rules';
+
+const collator = new Intl.Collator();
+
+interface Args {
+    fix?: boolean;
+    rule?: string | string[];
+}
+
+export class Review implements Command {
+    private readonly severityToLabel: Record<ErrorSeverity, string> = {
+        [ErrorSeverity.warning]: chalk.yellow('warning'),
+        [ErrorSeverity.error]: chalk.red('error'),
+    };
+
+    private readonly levelToSeverity: Partial<Record<Level, ErrorSeverity>> = {
+        warn: ErrorSeverity.warning,
+        error: ErrorSeverity.error,
+    };
+
+    constructor(private readonly args: Args) {}
+
+    description() {
+        return 'check project for configuration errors';
+    }
+
+    @logErrors
+    async execute() {
+        const errors = this.args.fix ? this.fixErrors() : this.findErrors();
+        const summary = this.reportErrors(errors);
+        return summary.error > 0 ? Promise.reject() : Promise.resolve();
+    }
+
+    private createProject(): Project {
+        const root = readJsonSafe('package.json');
+        if (!root?.workspaces) {
+            throw new Error('this command must be run from the workspace root directory');
+        }
+
+        const packageLock = readJsonSafe<Project['packageLock']>('package-lock.json');
+        if (!packageLock?.packages) {
+            throw new Error('this command must be run with valid package-lock.json');
+        }
+
+        root.location = '.'; // identifies the root package.json for rules that care
+        packageLock.location = './package-lock.json';
+
+        const config = getReviewConfiguration();
+        const packages: Package[] = [root, ...findPackages()];
+        const dependencies = sortByKey(collateDependencies(packages));
+        this.debug('review:packages', packages);
+        this.debug('review:dependencies', dependencies);
+
+        return { config, dependencies, packageLock, packages };
+    }
+
+    private debug(namespace: string, data: any) {
+        /* istanbul ignore next: debug only */
+        log.debug(namespace, () => data && JSON.stringify(data, null, 2));
+    }
+
+    private findErrors(project?: Project) {
+        const errors = this.runRules(project ?? this.createProject());
+        this.debug('review:errors', errors);
+        return errors;
+    }
+
+    private fixErrors() {
+        const rulesById = rules.reduce<Record<string, PackageRule>>((result, rule) => {
+            result[rule.id] = rule;
+            return result;
+        }, {});
+
+        let project = this.createProject();
+        let errors = this.findErrors(project);
+        let totalFixed = 0;
+
+        for (const category of [FixCategory.isolated, FixCategory.normal, FixCategory.lockFile]) {
+            const fixable = errors.filter(({ fixable }) => fixable === category);
+            if (fixable.length === 0) {
+                continue;
+            }
+
+            fixable.forEach(error => {
+                const rule = rulesById[error.id];
+                if (rule.fix) {
+                    log.text(`Fixing ${this.formatError({ ...error, details: '', location: '' })}`);
+                    rule.fix(error, project);
+                    totalFixed += 1;
+                }
+            });
+
+            execSync('npx startup install --fix --quiet', { stdio: 'inherit' });
+            project = this.createProject();
+            errors = this.findErrors(project);
+        }
+
+        if (totalFixed > 0) {
+            let summary = `Fixed ${pluralize(totalFixed, 'problem')}`;
+            if (errors.length) {
+                summary = `${summary}, ${pluralize(errors.length, 'problem remains', 'problems remain')}:\n`;
+            }
+            log.info(summary);
+        }
+
+        return errors;
+    }
+
+    private formatError(error: PackageError) {
+        const { location, message, severity = ErrorSeverity.error } = error;
+
+        const label = indent(this.severityToLabel[severity], location ? 1 : 0);
+        const details = error.details ? `\n${indent(error.details, location ? 2 : 1)}` : '';
+        const link = this.getLink(error);
+
+        return `${label} ${message} ${link}${details}`;
+    }
+
+    private reportErrors(errors: PackageError[]) {
+        let prevLocation: string | undefined;
+
+        errors.forEach((error, index) => {
+            const { location } = error;
+            if (index > 0 && (!location || location !== prevLocation)) {
+                log.text('');
+            }
+            if (location && location !== prevLocation) {
+                log.text(chalk.underline(formatLocation(location)));
+                prevLocation = location;
+            }
+            log.text(this.formatError(error));
+        });
+
+        const summary = summarize(errors);
+        this.reportSummary(summary);
+        return summary;
+    }
+
+    private reportSummary({ error, warning, fixable }: ErrorSummary) {
+        if (error + warning === 0) {
+            return log.success('0 problems');
+        }
+
+        log.text('');
+
+        const severity = error ? 'error' : 'warning';
+        log[severity](
+            `${pluralize(error + warning, 'problem')} (${pluralize(error, 'error')}, ${pluralize(warning, 'warning')})`
+        );
+
+        if (fixable.error + fixable.warning > 0) {
+            log[severity](
+                `${pluralize(fixable.error, 'error')} and ${pluralize(fixable.warning, 'warning')} potentially fixable with --fix option`
+            );
+        }
+    }
+
+    private runRules(project: Project): PackageError[] {
+        const selected = this.getSelectedRules();
+        return rules
+            .filter(({ id }) => !selected || selected.has(id))
+            .flatMap(rule => this.runRule(rule, project))
+            .filter(error => !!error)
+            .sort(compareError);
+    }
+
+    private runRule(rule: PackageRule, project: Project) {
+        const level = this.getLevel(project.config.rules?.[rule.id]);
+        if (level === 'off') {
+            return;
+        }
+
+        return this.transform(rule.run(project), level);
+    }
+
+    private transform(errors?: PackageError | PackageError[], level?: 'error' | 'warn') {
+        const severity = level && this.levelToSeverity[level];
+        return errors && severity ? toArray(errors).map(error => ({ ...error, severity })) : errors;
+    }
+
+    private getLevel(config?: RuleConfiguration) {
+        if (typeof config === 'string') {
+            return config;
+        }
+        if (Array.isArray(config) && typeof config[0] === 'string') {
+            return config[0];
+        }
+    }
+
+    private getLink({ id }: PackageError) {
+        const url = `https://docs.st.dev/docs/frontend/uikit/startup/review#${id}`;
+        return chalk.dim(terminalLink(id, url));
+    }
+
+    private getSelectedRules() {
+        const rule = this.args.rule;
+        if (typeof rule === 'string' && rule) {
+            return new Set([rule]);
+        }
+        if (Array.isArray(rule)) {
+            return new Set(rule.filter(id => !!id));
+        }
+        return undefined;
+    }
+}
+
+function compareError(
+    { location: locationA = '', severity: severityA = ErrorSeverity.error }: PackageError,
+    { location: locationB = '', severity: severityB = ErrorSeverity.error }: PackageError
+) {
+    return locationA === locationB ? severityA - severityB : collator.compare(locationA, locationB);
+}
+
+function sortByKey<T>(obj: Record<string, T>): Record<string, T> {
+    return Object.fromEntries(Object.entries(obj).sort(([a], [b]) => collator.compare(a, b)));
+}

package/src/cli/commands/review/rules/__mocks__/index.ts

@@ -0,0 +1,3 @@
+export * from './mock-config';
+export * from './mock-packages';
+export * from './mock-project';

package/src/cli/commands/review/rules/__mocks__/mock-config.ts

@@ -0,0 +1,14 @@
+import { toArray } from '../../../../../utils';
+import { ReviewConfiguration } from '../../types';
+
+export function mockConfig({
+    id,
+    level = 'error',
+    exclude = [],
+}: {
+    id: string;
+    level?: 'error' | 'warn';
+    exclude: string | string[];
+}): ReviewConfiguration {
+    return { rules: { [id]: exclude ? [level, { exclude: toArray(exclude) }] : [level] } };
+}

package/src/cli/commands/review/rules/__mocks__/mock-packages.ts

@@ -0,0 +1,41 @@
+import path from 'path';
+import { Dependencies, Package } from '../../types';
+
+/**
+ * Generates an array of mock Package objects based on a dependencies map.
+ *
+ * Each dependency entry can specify multiple versions, and each version can be used by multiple package names.
+ * The resulting packages will have their dependencies set accordingly.
+ *
+ * @param {Dependencies} dependencies - An object mapping dependency names to version maps,
+ *   where each version maps to an array of package names that depend on that version.
+ *
+ * @returns {Package[]} An array of Package objects with the specified dependencies.
+ *
+ * @example
+ * const deps = {
+ *   lodash: { '4.17.21': ['foo', 'bar'], '4.17.20': ['baz'] }
+ * };
+ * const pkgs = mockPackages(deps);
+ * // pkgs will include packages 'foo', 'bar', and 'baz' with appropriate lodash dependencies.
+ */
+export function mockPackages(dependencies: Dependencies): Package[] {
+    const packages = Object.entries(dependencies).reduce<Record<string, Package>>(
+        (result, [dependency, versions]) => {
+            Object.entries(versions).forEach(([version, names]) => {
+                names.forEach(name => {
+                    result[name] ??= {
+                        name,
+                        location: path.join('packages', name),
+                        dependencies: {},
+                    };
+                    result[name].dependencies![dependency] = version;
+                });
+            });
+            return result;
+        },
+        {}
+    );
+
+    return Object.values(packages);
+}

package/src/cli/commands/review/rules/__mocks__/mock-project.ts

@@ -0,0 +1,11 @@
+import { Project } from '../../types';
+
+export function mockProject(project: Partial<Project>): Project {
+    return {
+        config: {},
+        dependencies: {},
+        packageLock: { packages: {}, location: './package-lock.json' },
+        packages: [],
+        ...project,
+    };
+}

package/src/cli/commands/review/rules/__tests__/no-typescript-entry-point.test.ts

@@ -0,0 +1,166 @@
+import { execSync } from 'child_process';
+import path from 'path';
+import { getFolders } from '../../../../../utils';
+import { FixCategory, Package, ReviewConfiguration } from '../../types';
+import { mockConfig, mockProject } from '../__mocks__';
+
+import { NoTypescriptEntryPoint } from '../no-typescript-entry-point';
+
+jest.mock('child_process', () => ({ execSync: jest.fn() }));
+jest.mock('../../../../../utils', () => ({
+    ...jest.requireActual('../../../../../utils'),
+    getFolders: jest.fn(),
+}));
+
+describe(`[startup] Review ${NoTypescriptEntryPoint.name}`, () => {
+    const id = 'no-typescript-entry-point';
+    const rule = new NoTypescriptEntryPoint();
+    let config: ReviewConfiguration;
+    let pkg: Package;
+    let packages: Package[];
+
+    beforeEach(() => {
+        config = {};
+        pkg = { name: 'lib', location: path.normalize('packages/lib'), main: 'index.js' };
+        packages = [pkg];
+        jest.clearAllMocks();
+        jest.mocked(getFolders).mockImplementation(() => ({ source: 'src', destination: 'dist' }));
+    });
+
+    const subject = () => rule.run(mockProject({ config, packages }));
+
+    function itReturnsError(message: () => string) {
+        test('returns error', () => {
+            expect(subject()).toEqual([
+                expect.objectContaining({
+                    id,
+                    message: message(),
+                    location: pkg.location,
+                    fixable: FixCategory.normal,
+                }),
+            ]);
+        });
+    }
+
+    function itReturnsNothing() {
+        test('returns nothing', () => {
+            expect(subject()).toEqual([]);
+        });
+    }
+
+    function itFixesErrorWith(command: () => string) {
+        test('fixes error', () => {
+            rule.fix(subject()[0]);
+
+            expect(execSync).toHaveBeenCalledWith(command());
+        });
+    }
+
+    itReturnsNothing();
+
+    describe('when main is a .ts file', () => {
+        beforeEach(() => (pkg.main = 'src/index.ts'));
+
+        itReturnsError(() => `"main" is Typescript: ${pkg.main}`);
+
+        itFixesErrorWith(() => `npm pkg set "main"="dist/index.js" -w ${pkg.location}`);
+
+        describe('when config excludes package', () => {
+            beforeEach(() => (config = mockConfig({ id, exclude: pkg.name })));
+
+            itReturnsNothing();
+        });
+    });
+
+    describe('when module is a .ts file', () => {
+        beforeEach(() => (pkg.module = './src/foo.ts'));
+
+        itReturnsError(() => `"module" is Typescript: ${pkg.module as string}`);
+
+        itFixesErrorWith(() => `npm pkg set "module"="./dist/foo.js" -w ${pkg.location}`);
+    });
+
+    describe('when exports is a .ts file', () => {
+        beforeEach(() => (pkg.exports = './src/foo.ts'));
+
+        itReturnsError(() => `"exports" is Typescript: ${pkg.exports as string}`);
+
+        itFixesErrorWith(() => `npm pkg set "exports"="./dist/foo.js" -w ${pkg.location}`);
+    });
+
+    describe('when exports is a .d.ts file', () => {
+        beforeEach(() => (pkg.exports = './dist/index.d.ts'));
+
+        itReturnsNothing();
+    });
+
+    describe('when exports is an object with .ts file', () => {
+        beforeEach(() => (pkg.exports = { import: './foo.ts', require: './foo.js' }));
+
+        itReturnsError(() => `"exports[import]" is Typescript: ${(pkg.exports as any).import}`);
+
+        itFixesErrorWith(() => `npm pkg set "exports[import]"="./foo.js" -w ${pkg.location}`);
+    });
+
+    describe('when exports is a nested object with .ts file', () => {
+        beforeEach(() => {
+            pkg.exports = { '.': { import: './src/import/foo.ts', require: './foo.js' } };
+        });
+
+        itReturnsError(
+            () => `"exports[.][import]" is Typescript: ${(pkg.exports as any)['.'].import}`
+        );
+
+        itFixesErrorWith(
+            () => `npm pkg set "exports[.][import]"="./dist/import/foo.js" -w ${pkg.location}`
+        );
+    });
+
+    describe('when both main and exports are .ts files', () => {
+        const exports = { import: './foo.ts', require: './foo.js' };
+
+        beforeEach(() => Object.assign(pkg, { main: 'main.ts', exports }));
+
+        test('returns multiple errors', () => {
+            expect(subject()).toEqual([
+                expect.objectContaining({
+                    message: `"main" is Typescript: ${pkg.main}`,
+                    location: pkg.location,
+                }),
+                expect.objectContaining({
+                    message: `"exports[import]" is Typescript: ${exports.import}`,
+                    location: pkg.location,
+                }),
+            ]);
+        });
+    });
+
+    describe('when multiple packages contain Typescript entry points', () => {
+        beforeEach(() => {
+            packages = [
+                { ...pkg, name: 'lib1' }, // ok
+                { ...pkg, name: 'lib2', main: 'main.ts' }, // error
+                { ...pkg, name: 'lib3', exports: 'foo.ts' }, // error
+            ];
+        });
+
+        test('returns errors for each package', () => {
+            expect(subject()).toEqual([
+                expect.objectContaining({
+                    message: `"main" is Typescript: ${packages[1].main}`,
+                    location: packages[1].location,
+                }),
+                expect.objectContaining({
+                    message: `"exports" is Typescript: ${packages[2].exports as string}`,
+                    location: packages[2].location,
+                }),
+            ]);
+        });
+    });
+
+    test('ignores invalid error', () => {
+        rule.fix({} as any);
+
+        expect(execSync).not.toHaveBeenCalled();
+    });
+});

package/src/cli/commands/review/rules/__tests__/require-explicit-side-effects.test.ts

@@ -0,0 +1,113 @@
+import { ErrorSeverity, Package, ReviewConfiguration } from '../../types';
+import { mockConfig, mockProject } from '../__mocks__';
+
+import { RequireExplicitSideEffects } from '../require-explicit-side-effects';
+
+describe(`[startup] Review ${RequireExplicitSideEffects.name}`, () => {
+    const id = 'require-explicit-side-effects';
+    const rule = new RequireExplicitSideEffects();
+    const basePackage: Package = {
+        name: 'lib',
+        main: 'index.js',
+        cli: { webpack: false },
+        location: 'packages/lib',
+    };
+    let config: ReviewConfiguration;
+    let packages: Package[];
+
+    beforeEach(() => {
+        config = {};
+        packages = [basePackage];
+    });
+
+    const subject = () => rule.run(mockProject({ config, packages }));
+
+    function itReturnsError() {
+        test('returns warning', () => {
+            expect(subject()).toEqual([
+                {
+                    id,
+                    message: `package "${packages[0].name}" omits sideEffects property`,
+                    severity: ErrorSeverity.warning,
+                    location: packages[0].location,
+                },
+            ]);
+        });
+    }
+
+    function itReturnsNothing() {
+        test('returns nothing', () => {
+            expect(subject()).toEqual([]);
+        });
+    }
+
+    describe('when sideEffects is omitted', () => {
+        beforeEach(() => (packages = [{ ...basePackage, sideEffects: undefined }]));
+
+        itReturnsError();
+
+        describe('when config excludes package', () => {
+            beforeEach(() => (config = mockConfig({ id, exclude: packages[0].name })));
+
+            itReturnsNothing();
+        });
+    });
+
+    describe('when sideEffects is true', () => {
+        beforeEach(() => (packages = [{ ...basePackage, sideEffects: true }]));
+
+        itReturnsNothing();
+    });
+
+    describe('when sideEffects is false', () => {
+        beforeEach(() => (packages = [{ ...basePackage, sideEffects: false }]));
+
+        itReturnsNothing();
+    });
+
+    describe('when sideEffects is an array', () => {
+        beforeEach(() => (packages = [{ ...basePackage, sideEffects: ['*.css'] }]));
+
+        itReturnsNothing();
+    });
+
+    describe('when package is an application', () => {
+        beforeEach(() => (packages = [{ ...basePackage, cli: undefined }]));
+
+        itReturnsNothing();
+    });
+
+    describe('when package omits "main" entry points', () => {
+        beforeEach(() => (packages = [{ ...basePackage, main: undefined }]));
+
+        itReturnsNothing();
+
+        describe('when package has "exports"', () => {
+            beforeEach(() => (packages[0].exports = 'index.js'));
+
+            itReturnsError();
+        });
+    });
+
+    describe('when multiple packages omit sideEffects', () => {
+        beforeEach(() => {
+            packages = [
+                basePackage, // error
+                { ...basePackage, name: 'lib2', sideEffects: false }, // ok
+                { ...basePackage, name: 'lib3', cli: { webpack: undefined } }, // ok
+                { ...basePackage, name: 'lib4', main: undefined, exports: 'index.js' }, // error
+            ];
+        });
+
+        test('returns multiple warnings', () => {
+            expect(subject()).toEqual([
+                expect.objectContaining({
+                    message: `package "${packages[0].name}" omits sideEffects property`,
+                }),
+                expect.objectContaining({
+                    message: `package "${packages[3].name}" omits sideEffects property`,
+                }),
+            ]);
+        });
+    });
+});

package/src/cli/commands/review/rules/__tests__/require-npmrc.test.ts

@@ -0,0 +1,71 @@
+import { execSync } from 'child_process';
+import { ErrorSeverity, FixCategory } from '../../types';
+
+import { RequireNpmrc } from '../require-npmrc';
+
+jest.mock('child_process', () => ({ execSync: jest.fn() }));
+
+describe(`[startup] Review ${RequireNpmrc.name}`, () => {
+    const rule = new RequireNpmrc();
+    let npmConfig: Record<string, any>;
+
+    beforeEach(() => (npmConfig = {}));
+
+    const subject = () => {
+        jest.mocked(execSync).mockImplementation(() => JSON.stringify(npmConfig));
+        return rule.run();
+    };
+
+    function itReturnsWarning() {
+        test('returns warning', () => {
+            expect(subject()).toEqual({
+                id: expect.any(String),
+                message: 'project does not contain .npmrc with legacy-peer-deps=true',
+                severity: ErrorSeverity.warning,
+                fixable: FixCategory.isolated,
+            });
+        });
+    }
+
+    function itReturnsNothing() {
+        test('returns nothing', () => {
+            expect(subject()).toBeUndefined();
+        });
+    }
+
+    test('fetches npm settings', () => {
+        subject();
+
+        expect(execSync).toHaveBeenCalledWith(`npm config list --json`, { encoding: 'utf8' });
+    });
+
+    describe('when legacy-peer-deps is missing', () => {
+        beforeEach(() => (npmConfig = {}));
+
+        itReturnsWarning();
+    });
+
+    describe('when legacy-peer-deps is true', () => {
+        beforeEach(() => (npmConfig = { 'legacy-peer-deps': true }));
+
+        itReturnsNothing();
+    });
+
+    describe('when legacy-peer-deps is false', () => {
+        beforeEach(() => (npmConfig = { 'legacy-peer-deps': false }));
+
+        itReturnsWarning();
+    });
+
+    describe('fix', () => {
+        const subject = () => rule.fix();
+
+        test('sets npm project legacy-peer-deps=true', () => {
+            subject();
+
+            expect(execSync).toHaveBeenCalledWith(
+                'npm config set --location=project legacy-peer-deps=true'
+            );
+        });
+    });
+});