@servicetitan/startup 36.3.1 → 37.0.0

package/src/core/__tests__/sort-shared-css.test.ts

@@ -0,0 +1,39 @@
+import { sortSharedCss } from '../sort-shared-css';
+
+describe(`[startup] ${sortSharedCss.name}`, () => {
+    let cssFiles: string[];
+
+    beforeEach(() => {
+        cssFiles = ['foo.bundle.css', 'bar.bundle.css'];
+    });
+
+    const subject = () => sortSharedCss(cssFiles);
+
+    function itReturnsInput() {
+        test('returns input', () => {
+            expect(subject()).toBe(cssFiles);
+        });
+    }
+
+    itReturnsInput();
+
+    describe('when input contains design-system CSS', () => {
+        let otherCssFiles: string[];
+        const designSystemBundle = 'design-system.bundle.css';
+
+        beforeEach(() => {
+            otherCssFiles = [...cssFiles];
+            cssFiles = [...otherCssFiles, designSystemBundle];
+        });
+
+        test('moves design system to front', () => {
+            expect(subject()).toEqual([designSystemBundle, ...otherCssFiles]);
+        });
+
+        describe('when design-system CSS is already first', () => {
+            beforeEach(() => (cssFiles = [designSystemBundle, ...otherCssFiles]));
+
+            itReturnsInput();
+        });
+    });
+});

package/src/core/bundle-report.ts

@@ -0,0 +1,33 @@
+import { getBundleType } from './get-bundle-type';
+import { BuildContext } from './types';
+
+/*
+ * Base name (no extension) and title for the bundle-size report, shared by the webpack and Vite
+ * builds so both bundlers label their reports identically. The timestamp keeps successive reports
+ * for the same package distinct.
+ */
+export function bundleReportFileName(context: BuildContext): string {
+    const type = getBundleType(context);
+    const qualifier = type ? `-${type}` : '';
+    return `${context.package.name}${qualifier}-bundle-${Date.now()}`;
+}
+
+export function bundleReportTitle(context: BuildContext): string {
+    const unscopedName = context.package.name.replace(/^@[^/]+\//, '');
+    const type = getBundleType(context);
+    const qualifier = type ? ` (${type})` : '';
+    return `${unscopedName}${qualifier} ${formatDate(new Date())}`;
+}
+
+function formatDate(date: Date): string {
+    const yyyy = date.getFullYear();
+    const mm = zeroPad(date.getMonth() + 1);
+    const dd = zeroPad(date.getDate());
+    const HH = zeroPad(date.getHours());
+    const MM = zeroPad(date.getMinutes());
+    return `${yyyy}-${mm}-${dd} ${HH}:${MM}`;
+}
+
+function zeroPad(value: number) {
+    return value.toString().padStart(2, '0');
+}

package/src/core/check-resource/__tests__/check-resource.test.ts

@@ -0,0 +1,72 @@
+import { BuildContext } from '../../types';
+import { checkResource } from '../check-resource';
+import { getPeerDependencyMeta } from '../get-peer-dependency-meta';
+import { isManagedReactDomClientDependency } from '../is-managed-react-dom-client-dependency';
+import { isResolvable } from '../is-resolvable';
+
+jest.mock('../is-managed-react-dom-client-dependency');
+jest.mock('../get-peer-dependency-meta');
+jest.mock('../is-resolvable');
+
+describe(`${checkResource.name}`, () => {
+    const importer = 'node_modules/web-components/dist';
+    let context: BuildContext;
+    let resource: string;
+    let peerDependenciesMeta: ReturnType<typeof getPeerDependencyMeta>;
+
+    beforeEach(() => {
+        jest.resetAllMocks();
+        jest.mocked(getPeerDependencyMeta).mockImplementation(() => peerDependenciesMeta);
+        peerDependenciesMeta = undefined;
+        resource = '@servicetitan/foo';
+        context = { package: { dependencies: {} } } as BuildContext;
+    });
+
+    const subject = () => checkResource(context)({ resource, importer });
+
+    function itReturns(value: 'throw' | 'empty' | false) {
+        test(`returns ${JSON.stringify(value)}`, () => expect(subject()).toBe(value));
+    }
+
+    itReturns(false);
+
+    describe('when resource is optional peer dependency', () => {
+        beforeEach(() => (peerDependenciesMeta = { optional: true }));
+
+        itReturns('throw');
+
+        describe('when peer fallback is "empty"', () => {
+            beforeEach(() => (peerDependenciesMeta!.fallback = 'empty'));
+
+            itReturns('empty');
+        });
+
+        describe('when resource is resolvable', () => {
+            beforeEach(() => jest.mocked(isResolvable).mockReturnValue(true));
+
+            itReturns(false);
+        });
+
+        describe('when resource is package dependency', () => {
+            beforeEach(() => (context.package.dependencies[resource] = '*'));
+
+            itReturns(false);
+        });
+    });
+
+    describe('when resource is managed react-dom client dependency', () => {
+        beforeEach(() => jest.mocked(isManagedReactDomClientDependency).mockReturnValue(true));
+
+        describe('when resource is resolvable', () => {
+            beforeEach(() => jest.mocked(isResolvable).mockReturnValue(true));
+
+            itReturns(false);
+        });
+
+        describe('when resource is not resolvable', () => {
+            beforeEach(() => jest.mocked(isResolvable).mockReturnValue(false));
+
+            itReturns('empty');
+        });
+    });
+});

package/src/{webpack/configs/plugins/ignore-plugin → core/check-resource}/__tests__/get-package-json.test.ts

@@ -8,6 +8,7 @@ describe(`[startup] ${getPackageJson.name}`, () => {
     let context: string;
 
     beforeEach(() => {
+        getPackageJson.cache.clear?.();
         context = 'node_modules/foo/dist';
         vol.fromNestedJSON({
             // eslint-disable-next-line @typescript-eslint/naming-convention
@@ -39,7 +40,7 @@ describe(`[startup] ${getPackageJson.name}`, () => {
 
     describe('when context is not in node_modules', () => {
         beforeEach(() => {
-            context = 'foo/dist';
+            context = '/foo/dist';
             vol.fromNestedJSON({
                 foo: { 'package.json': JSON.stringify(packageJson) },
             });

package/src/core/check-resource/__tests__/get-peer-dependency-meta.test.ts

@@ -0,0 +1,108 @@
+import { getPackageJson } from '../get-package-json';
+import { getPeerDependencyMeta } from '../get-peer-dependency-meta';
+
+jest.mock('../get-package-json');
+
+describe(`[startup] ${getPeerDependencyMeta.name}`, () => {
+    let importer: string;
+    let resource: string;
+    let packageJson: ReturnType<typeof getPackageJson>;
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+        importer = 'node_modules/pkg/dist';
+        resource = '@scope/a';
+        packageJson = undefined;
+        jest.mocked(getPackageJson).mockImplementation(() => packageJson);
+    });
+
+    const subject = () => getPeerDependencyMeta({ resource, importer });
+
+    function itReturnsUndefined() {
+        test('returns undefined', () => {
+            expect(subject()).toBeUndefined();
+        });
+    }
+
+    itReturnsUndefined();
+
+    describe('when resource is not a package name', () => {
+        beforeEach(() => (resource = './local'));
+
+        itReturnsUndefined();
+    });
+
+    describe('when package.json has no entry for resource', () => {
+        beforeEach(() => (packageJson = {}));
+
+        itReturnsUndefined();
+    });
+
+    describe('when peerDependenciesMeta includes resource', () => {
+        beforeEach(() => {
+            packageJson = { peerDependenciesMeta: { [resource]: { optional: true } } };
+        });
+
+        test('returns entry', () => {
+            expect(subject()).toEqual(packageJson!.peerDependenciesMeta[resource]);
+        });
+    });
+
+    describe('when cli.peerDependenciesMeta includes resource', () => {
+        beforeEach(() => {
+            packageJson = {
+                peerDependenciesMeta: { [resource]: { optional: true } },
+                cli: { peerDependenciesMeta: { [resource]: { fallback: 'empty' } } },
+            };
+        });
+
+        function itThrowsError(matcher: RegExp) {
+            test('throws', () => {
+                expect(subject).toThrow(matcher);
+            });
+        }
+
+        test('returns merged entry', () => {
+            expect(subject()).toEqual({
+                ...packageJson!.peerDependenciesMeta[resource],
+                ...packageJson!.cli.peerDependenciesMeta[resource],
+            });
+        });
+
+        describe('when peerDependenciesMeta.optional is missing', () => {
+            beforeEach(() => delete packageJson!.peerDependenciesMeta);
+
+            itThrowsError(/requires peerDependenciesMeta.*optional/);
+        });
+
+        describe('when entry is not an object', () => {
+            beforeEach(() => (packageJson!.cli.peerDependenciesMeta[resource] = ''));
+
+            itThrowsError(/must be an object/);
+        });
+
+        describe('when the malformed entry is for a different resource', () => {
+            beforeEach(() => {
+                packageJson!.cli.peerDependenciesMeta.foo = '';
+            });
+
+            itThrowsError(/must be an object/);
+        });
+
+        describe('when entry has an unexpected key', () => {
+            beforeEach(() => {
+                packageJson!.cli.peerDependenciesMeta[resource].optional = true;
+            });
+
+            itThrowsError(/unexpected key\(s\) \[optional\]/);
+        });
+
+        describe('when entry has invalid fallback', () => {
+            beforeEach(() => {
+                packageJson!.cli.peerDependenciesMeta[resource].fallback = 'foo';
+            });
+
+            itThrowsError(/must be one of \[throw, empty\]/);
+        });
+    });
+});

package/src/core/check-resource/__tests__/is-managed-react-dom-client-dependency.test.ts

@@ -0,0 +1,35 @@
+import { isManagedReactDomClientDependency } from '../is-managed-react-dom-client-dependency';
+
+describe(`[startup] ${isManagedReactDomClientDependency.name}`, () => {
+    const subject = (...args: Parameters<typeof isManagedReactDomClientDependency>) =>
+        isManagedReactDomClientDependency(...args);
+
+    describe.each([
+        {
+            resource: 'react-dom/client',
+            importers: [
+                '@servicetitan/web-components',
+                'uikit/packages/web-components/dist',
+                '@servicetitan/ko-bridge',
+                'uikit/packages/ko-bridge/dist',
+            ],
+        },
+    ])('with dependency "$resource"', ({ resource, importers }) => {
+        importers.forEach(importer => {
+            test(`with importer ${importer}, returns true`, () => {
+                expect(subject({ importer, resource })).toBe(true);
+            });
+        });
+    });
+
+    describe.each([
+        { resource: 'react-dom', importers: ['@servicetitan/web-components'] },
+        { resource: 'react-dom/client', importers: ['@servicetitan/foo'] },
+    ])('with dependency "$resource"', ({ resource, importers }) => {
+        importers.forEach(importer => {
+            test(`with importer ${importer}, returns false`, () => {
+                expect(subject({ importer, resource })).toBe(false);
+            });
+        });
+    });
+});

package/src/core/check-resource/__tests__/is-resolvable.test.ts

@@ -0,0 +1,20 @@
+import { isResolvable } from '../is-resolvable';
+
+describe('isResolvable', () => {
+    const importer = __filename;
+    let resource: string;
+
+    const subject = () => isResolvable({ resource, importer });
+
+    describe('when the resource resolves', () => {
+        beforeEach(() => (resource = 'lodash.memoize'));
+
+        test('returns true', () => expect(subject()).toBe(true));
+    });
+
+    describe('when the resource does not resolve', () => {
+        beforeEach(() => (resource = '@servicetitan/does-not-exist'));
+
+        test('returns false', () => expect(subject()).toBe(false));
+    });
+});

package/src/core/check-resource/check-resource.ts

@@ -0,0 +1,31 @@
+import { log } from '../../utils';
+import { BuildContext } from '../types';
+import { getPeerDependencyMeta } from './get-peer-dependency-meta';
+import { isManagedReactDomClientDependency } from './is-managed-react-dom-client-dependency';
+import { isResolvable } from './is-resolvable';
+import type { CheckerArgs, IgnoreMode } from './types';
+
+export function checkResource(context: BuildContext) {
+    return function ({ resource, importer }: CheckerArgs): IgnoreMode | false {
+        if (!context.package.dependencies[resource]) {
+            const meta = getPeerDependencyMeta({ resource, importer });
+            if (meta?.optional && !isResolvable({ resource, importer })) {
+                const mode = meta.fallback ?? 'throw';
+                log.debug('check-resource', `${JSON.stringify({ resource, importer })} => ${mode}`);
+                return mode;
+            }
+        }
+
+        /**
+         * react-dom/client isn't an explicit dependency, so the peerDependenciesMeta
+         * path above can't catch it.
+         */
+        if (
+            isManagedReactDomClientDependency({ resource, importer }) &&
+            !isResolvable({ resource, importer })
+        ) {
+            return 'empty';
+        }
+        return false;
+    };
+}

package/src/core/check-resource/get-package-json.ts

@@ -0,0 +1,33 @@
+import fs from 'fs';
+import memoize from 'lodash.memoize';
+import path from 'path';
+import { log, readJson } from '../../utils';
+
+const containsExternalPackages = /[\\/](node_modules|\.yalc|ignore-plugin-test)([\\/]|$)/;
+const isNodeModules = /(node_modules|\.yalc)/;
+
+/**
+ * Find the nearest package.json for a file path by walking up the directory tree.
+ * Only searches paths inside node_modules or .yalc because the ignore plugin only
+ * needs to suppress missing optional peer dependencies from third-party packages.
+ * ignore-plugin-test is for local integration tests.
+ *
+ * Memoized to avoid re-walking parent directories on every import resolution.
+ */
+export const getPackageJson = memoize(function getPackageJson(context: string) {
+    const fullPath = path.resolve(context);
+    if (!containsExternalPackages.test(fullPath)) {
+        return;
+    }
+
+    for (let dir = path.dirname(fullPath); dir !== path.dirname(dir); dir = path.dirname(dir)) {
+        if (isNodeModules.test(path.basename(dir))) {
+            break;
+        }
+        const packageJsonFile = path.join(dir, 'package.json');
+        if (fs.existsSync(packageJsonFile)) {
+            log.debug('get-package-json', `${context} => ${packageJsonFile}`);
+            return readJson<Record<string, any>>(packageJsonFile);
+        }
+    }
+});

package/src/core/check-resource/get-peer-dependency-meta.ts

@@ -0,0 +1,78 @@
+import memoize from 'lodash.memoize';
+import { getPackageJson } from './get-package-json';
+import type { CheckerArgs, IgnoreMode } from './types';
+
+interface PeerDependencyMeta {
+    optional?: boolean;
+    fallback?: IgnoreMode;
+}
+
+const ALLOWED_KEYS: readonly string[] = ['fallback'];
+const ALLOWED_FALLBACKS: readonly IgnoreMode[] = ['throw', 'empty'];
+
+/**
+ * Merged view of npm's `peerDependenciesMeta[resource]` (which carries
+ * `optional`) and our extension `cli.peerDependenciesMeta[resource]`. Returns
+ * undefined when no entry is declared for the resource.
+ *
+ * Validates the `cli.peerDependenciesMeta` map so a malformed entry (for
+ * example, `optional: true` written there by mistake, thinking it's npm's
+ * field) fails loudly.
+ */
+export function getPeerDependencyMeta({
+    resource,
+    importer,
+}: CheckerArgs): PeerDependencyMeta | undefined {
+    if (!/^[@a-z]/.test(resource)) {
+        return;
+    }
+
+    const pkg = getPackageJson(importer);
+    if (!pkg) {
+        return;
+    }
+
+    const cliMap = pkg.cli?.peerDependenciesMeta;
+    if (cliMap && typeof cliMap === 'object') {
+        validate(cliMap);
+    }
+
+    const npmEntry = pkg.peerDependenciesMeta?.[resource];
+    const cliEntry = cliMap?.[resource];
+    if (!npmEntry && !cliEntry) {
+        return;
+    }
+    if (cliEntry?.fallback && !npmEntry?.optional) {
+        throw new Error(
+            `cli.peerDependenciesMeta["${resource}"].fallback requires peerDependenciesMeta["${resource}"].optional = true`
+        );
+    }
+    return { ...npmEntry, ...cliEntry };
+}
+
+/*
+ * cli.peerDependenciesMeta mirrors npm's peerDependenciesMeta shape. If a
+ * developer mistakenly puts npm fields (for example, `optional: true`) there
+ * thinking it's npm's config, this check causes it to fail loudly.
+ *
+ * Memoized by reference so each importer's map is validated once per build.
+ */
+const validate = memoize(function validate(meta: Record<string, unknown>) {
+    for (const [resource, entry] of Object.entries(meta)) {
+        if (entry === null || typeof entry !== 'object') {
+            throw new Error(`cli.peerDependenciesMeta["${resource}"] must be an object`);
+        }
+        const unknown = Object.keys(entry).filter(k => !ALLOWED_KEYS.includes(k));
+        if (unknown.length) {
+            throw new Error(
+                `cli.peerDependenciesMeta["${resource}"] has unexpected key(s) [${unknown.join(', ')}]; allowed: [${ALLOWED_KEYS.join(', ')}]`
+            );
+        }
+        const { fallback } = entry as { fallback?: unknown };
+        if (fallback !== undefined && !ALLOWED_FALLBACKS.includes(fallback as IgnoreMode)) {
+            throw new Error(
+                `cli.peerDependenciesMeta["${resource}"].fallback must be one of [${ALLOWED_FALLBACKS.join(', ')}], got ${JSON.stringify(fallback)}`
+            );
+        }
+    }
+});

package/src/core/check-resource/index.ts

@@ -0,0 +1,2 @@
+export { checkResource } from './check-resource';
+export type { CheckerArgs, IgnoreMode } from './types';

package/src/core/check-resource/is-managed-react-dom-client-dependency.ts

@@ -0,0 +1,13 @@
+import type { CheckerArgs } from './types';
+
+/**
+ * Matches both published paths (@servicetitan/ko-bridge, @servicetitan/web-components) and
+ * in-repo paths (packages/ko-bridge, packages/web-components) so the check works whether the
+ * importer is installed from npm/yalc or resolved locally during a uikit-internal build.
+ */
+export function isManagedReactDomClientDependency({ importer, resource }: CheckerArgs) {
+    return (
+        resource === 'react-dom/client' &&
+        /(@servicetitan|packages)\/(ko-bridge|web-components)/.test(importer)
+    );
+}

package/src/core/check-resource/is-resolvable.ts

@@ -0,0 +1,19 @@
+import memoize from 'lodash.memoize';
+import path from 'path';
+import type { CheckerArgs } from './types';
+
+/**
+ * Whether a module resolves from the importer's location. Memoized so each unique
+ * (package, importer directory) pair is resolved once.
+ */
+export const isResolvable = memoize(
+    function isResolvable({ resource, importer }: CheckerArgs): boolean {
+        try {
+            require.resolve(resource, { paths: [path.dirname(importer)] });
+            return true;
+        } catch {
+            return false;
+        }
+    },
+    ({ resource, importer }) => `${resource}\0${path.dirname(importer)}`
+);

package/src/core/check-resource/types.ts

@@ -0,0 +1,6 @@
+export type IgnoreMode = 'throw' | 'empty';
+
+export interface CheckerArgs {
+    resource: string;
+    importer: string;
+}

package/src/core/chunk-patterns.ts

@@ -0,0 +1,30 @@
+/*
+ * Canonical module-path patterns for each code-splitting chunk, shared by the Vite
+ * and webpack configs. Using [\\/]? at the start matches both Vite module IDs (which
+ * begin with "node_modules/...") and webpack module paths (which begin with an
+ * absolute path separator before "node_modules/...").
+ */
+
+const VENDOR_CORE_PACKAGES = [
+    'axios',
+    'classnames',
+    'formstate',
+    'inversify',
+    'mobx',
+    'mobx-react',
+    'mobx-utils',
+    'react',
+    'react-dom',
+    'react-router',
+    'react-router-dom',
+    'reflect-metadata',
+];
+
+export const CHUNK_PATTERNS = {
+    'servicetitan': /[\\/]?node_modules[\\/]@servicetitan[\\/]/,
+    'kendo': /[\\/]?node_modules[\\/](@progress|@telerik)[\\/]/,
+    'vendor-core': new RegExp(
+        `[\\\\/]?node_modules[\\\\/](${VENDOR_CORE_PACKAGES.join('|')})[\\\\/]`
+    ),
+    'vendor': /[\\/]?node_modules[\\/]/,
+};

package/src/core/constants.ts

@@ -0,0 +1,16 @@
+export const bundleConstants = {
+    cssModules: {
+        classnameTemplate: {
+            production: '[local]__[hash:base64:5]',
+            development: '[path][name]__[local]',
+        },
+        localsConvention: 'camelCaseOnly',
+    },
+    less: {
+        math: 'always',
+    },
+    mode: {
+        production: 'production',
+        development: 'development',
+    },
+} as const;

package/src/core/create-build-context.ts

@@ -0,0 +1,61 @@
+import { getPackageManager } from '@servicetitan/install';
+import yargs, { Arguments } from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import {
+    getExposeProcessEnv,
+    getFolders,
+    getPackageData,
+    isExposeSharedDependencies,
+    isLegacyRoot,
+    isWebComponent,
+    loadSharedDependencies,
+} from '../utils';
+import { BuildContext, BuildIdentity } from './types';
+export type { BuildContext } from './types';
+
+export interface BuildContextOptions {
+    name: string;
+    isProduction: boolean;
+    light?: boolean;
+    headless?: boolean;
+    emitExposedDependencies?: BuildIdentity['emitExposedDependencies'];
+    codeCoverage?: boolean;
+    buildStat?: boolean;
+}
+
+export function createBuildContext(options: BuildContextOptions): BuildContext {
+    const args = yargs(hideBin(process.argv)).argv as Arguments;
+    const { source, destination } = getFolders();
+    const packageData = getPackageData();
+    const sharedDependencies = loadSharedDependencies(
+        packageData.dependencies,
+        packageData.sharedDependencies
+    );
+
+    return {
+        package: {
+            name: packageData.name,
+            version: packageData.version,
+            destination,
+            source,
+            dependencies: packageData.dependencies,
+            sharedDependencies,
+            isWebComponent: isWebComponent(),
+            isLegacyRoot: isLegacyRoot(),
+            isExposeSharedDependencies: isExposeSharedDependencies(),
+            exposeProcessEnv: getExposeProcessEnv(),
+            packageManager: getPackageManager(),
+        },
+        build: {
+            name: options.name,
+            isProduction: options.isProduction,
+            light: options.light,
+            headless: options.headless,
+            emitExposedDependencies: options.emitExposedDependencies,
+        },
+        options: {
+            codeCoverage: options.codeCoverage ?? !!args['code-coverage'],
+            buildStat: options.buildStat,
+        },
+    };
+}

package/src/core/create-extension-regexp.ts

@@ -0,0 +1,7 @@
+export const FONT_EXTENSIONS = ['woff', 'woff2', 'eot', 'ttf', 'otf'];
+export const IMAGE_EXTENSIONS = ['png', 'jpg', 'jpeg', 'gif'];
+export const SVG_EXTENSIONS = ['svg'];
+
+export function createExtensionRegExp(extensions: string[]): RegExp {
+    return new RegExp(`\\.(${extensions.join('|')})$`, 'i');
+}

package/src/core/defines/define-exposed-dependencies.ts

@@ -0,0 +1,25 @@
+import { getExposedDependencies } from '../get-exposed-dependencies';
+import { BuildContext } from '../types';
+
+export function defineExposedDependencies(context: BuildContext) {
+    const { isExposeSharedDependencies, sharedDependencies, dependencies, packageManager } =
+        context.package;
+    const { emitExposedDependencies } = context.build;
+
+    if (!isExposeSharedDependencies || emitExposedDependencies) {
+        return;
+    }
+
+    const workspacePackage = packageManager.getWorkspacePackage();
+    const exposedDependencies = getExposedDependencies(
+        sharedDependencies,
+        dependency =>
+            packageManager.getResolvedVersion({ workspacePackage, dependency }) ??
+            dependencies?.[dependency]
+    );
+
+    return {
+        // eslint-disable-next-line @typescript-eslint/naming-convention
+        EXPOSED_DEPENDENCIES: JSON.stringify(exposedDependencies),
+    };
+}