@servicetitan/startup 36.4.0 → 37.0.0

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

@@ -0,0 +1,32 @@
+import { createExtensionRegExp } from '../create-extension-regexp';
+
+describe(createExtensionRegExp.name, () => {
+    let extensions: string[];
+
+    beforeEach(() => (extensions = ['png', 'gif']));
+
+    const subject = () => createExtensionRegExp(extensions);
+
+    test('regex matches all extensions', () => {
+        const regex = subject();
+        expect(extensions.every(extension => regex.test(`foo.${extension}`))).toBe(true);
+    });
+
+    test('regex does not match other extensions', () => {
+        expect(subject().test('foo.js')).toBe(false);
+    });
+
+    test('regex is case-insensitive', () => {
+        const regex = subject();
+        expect(extensions.every(extension => regex.test(`foo.${extension}`.toUpperCase()))).toBe(
+            true
+        );
+    });
+
+    test('regex only matches extension at end of string', () => {
+        const regex = subject();
+        expect(extensions.some(extension => regex.test(`${extension}/foo.js`.toUpperCase()))).toBe(
+            false
+        );
+    });
+});

package/src/core/__tests__/resolve-output-path.test.ts

@@ -0,0 +1,45 @@
+import path from 'path';
+import { getBundleType } from '../get-bundle-type';
+import { resolveOutputPath } from '../resolve-output-path';
+import { resolveOutputRoot } from '../resolve-output-root';
+import { BuildContext } from '../types';
+
+jest.mock('../get-bundle-type');
+
+describe(`[startup] ${resolveOutputPath.name}`, () => {
+    let context: BuildContext;
+    let outputPath: string | undefined;
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+        jest.mocked(getBundleType).mockReturnValue(undefined);
+        context = { build: {}, package: { destination: 'dist' } } as BuildContext;
+        outputPath = undefined;
+    });
+
+    const subject = () => resolveOutputPath(context, outputPath);
+
+    function itReturnsResolvedRoot() {
+        test('returns resolved root', () => {
+            expect(subject()).toBe(resolveOutputRoot(context, outputPath));
+        });
+    }
+
+    itReturnsResolvedRoot();
+
+    describe('with an outputPath', () => {
+        beforeEach(() => (outputPath = '/output/dir'));
+
+        itReturnsResolvedRoot();
+    });
+
+    describe('when getBundleType returns a subdir', () => {
+        const subdir = 'full';
+
+        beforeEach(() => jest.mocked(getBundleType).mockReturnValue(subdir));
+
+        test('appends the subdir to the output root', () => {
+            expect(subject()).toBe(path.join(resolveOutputRoot(context, outputPath), subdir));
+        });
+    });
+});

package/src/core/__tests__/resolve-output-root.test.ts

@@ -0,0 +1,37 @@
+import path from 'path';
+import { resolveOutputRoot } from '../resolve-output-root';
+import { BuildContext } from '../types';
+
+describe(`[startup] ${resolveOutputRoot.name}`, () => {
+    let context: BuildContext;
+    let outputPath: string | undefined;
+
+    beforeEach(() => {
+        context = { build: {}, package: { destination: 'dist' } } as BuildContext;
+        outputPath = undefined;
+    });
+
+    const subject = () => resolveOutputRoot(context, outputPath);
+
+    function itReturnsDefaultRoot() {
+        test('returns default output root', () => {
+            expect(subject()).toBe(path.join(process.cwd(), context.package.destination, 'bundle'));
+        });
+    }
+
+    itReturnsDefaultRoot();
+
+    describe('with an outputPath', () => {
+        beforeEach(() => (outputPath = '/foo'));
+
+        test('returns the outputPath', () => {
+            expect(subject()).toBe(outputPath);
+        });
+
+        describe('when the package is an MFE', () => {
+            beforeEach(() => (context.package.isWebComponent = true));
+
+            itReturnsDefaultRoot();
+        });
+    });
+});

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

@@ -2,9 +2,11 @@ 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';
@@ -22,7 +24,7 @@ describe(`${checkResource.name}`, () => {
 
     const subject = () => checkResource(context)({ resource, importer });
 
-    function itReturns(value: boolean) {
+    function itReturns(value: 'throw' | 'empty' | false) {
         test(`returns ${JSON.stringify(value)}`, () => expect(subject()).toBe(value));
     }
 
@@ -31,7 +33,19 @@ describe(`${checkResource.name}`, () => {
     describe('when resource is optional peer dependency', () => {
         beforeEach(() => (peerDependenciesMeta = { optional: true }));
 
-        itReturns(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] = '*'));
@@ -43,16 +57,16 @@ describe(`${checkResource.name}`, () => {
     describe('when resource is managed react-dom client dependency', () => {
         beforeEach(() => jest.mocked(isManagedReactDomClientDependency).mockReturnValue(true));
 
-        describe('when resource is present', () => {
-            beforeEach(() => (resource = 'fs'));
+        describe('when resource is resolvable', () => {
+            beforeEach(() => jest.mocked(isResolvable).mockReturnValue(true));
 
             itReturns(false);
         });
 
-        describe('when resource is not present', () => {
-            beforeEach(() => (resource = 'foo'));
+        describe('when resource is not resolvable', () => {
+            beforeEach(() => jest.mocked(isResolvable).mockReturnValue(false));
 
-            itReturns(true);
+            itReturns('empty');
         });
     });
 });

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

@@ -4,17 +4,16 @@ import { getPeerDependencyMeta } from '../get-peer-dependency-meta';
 jest.mock('../get-package-json');
 
 describe(`[startup] ${getPeerDependencyMeta.name}`, () => {
-    const meta = { optional: true };
     let importer: string;
     let resource: string;
+    let packageJson: ReturnType<typeof getPackageJson>;
 
     beforeEach(() => {
         jest.clearAllMocks();
         importer = 'node_modules/pkg/dist';
         resource = '@scope/a';
-        jest.mocked(getPackageJson).mockImplementation(() => ({
-            peerDependenciesMeta: { [resource]: meta },
-        }));
+        packageJson = undefined;
+        jest.mocked(getPackageJson).mockImplementation(() => packageJson);
     });
 
     const subject = () => getPeerDependencyMeta({ resource, importer });
@@ -25,9 +24,7 @@ describe(`[startup] ${getPeerDependencyMeta.name}`, () => {
         });
     }
 
-    test('returns peerDependenciesMeta for resource', () => {
-        expect(subject()).toEqual(meta);
-    });
+    itReturnsUndefined();
 
     describe('when resource is not a package name', () => {
         beforeEach(() => (resource = './local'));
@@ -35,17 +32,77 @@ describe(`[startup] ${getPeerDependencyMeta.name}`, () => {
         itReturnsUndefined();
     });
 
-    describe('when peerDependenciesMeta omits resource', () => {
+    describe('when package.json has no entry for resource', () => {
+        beforeEach(() => (packageJson = {}));
+
+        itReturnsUndefined();
+    });
+
+    describe('when peerDependenciesMeta includes resource', () => {
         beforeEach(() => {
-            jest.mocked(getPackageJson).mockReturnValue({ peerDependenciesMeta: {} });
+            packageJson = { peerDependenciesMeta: { [resource]: { optional: true } } };
         });
 
-        itReturnsUndefined();
+        test('returns entry', () => {
+            expect(subject()).toEqual(packageJson!.peerDependenciesMeta[resource]);
+        });
     });
 
-    describe('when package.json is not found', () => {
-        beforeEach(() => jest.mocked(getPackageJson).mockReturnValue(undefined));
+    describe('when cli.peerDependenciesMeta includes resource', () => {
+        beforeEach(() => {
+            packageJson = {
+                peerDependenciesMeta: { [resource]: { optional: true } },
+                cli: { peerDependenciesMeta: { [resource]: { fallback: 'empty' } } },
+            };
+        });
 
-        itReturnsUndefined();
+        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-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

@@ -2,28 +2,29 @@ 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 type { CheckerArgs } from './types';
+import { isResolvable } from './is-resolvable';
+import type { CheckerArgs, IgnoreMode } from './types';
 
 export function checkResource(context: BuildContext) {
-    return function ({ resource, importer }: CheckerArgs): boolean {
-        if (
-            !context.package.dependencies[resource] &&
-            getPeerDependencyMeta({ resource, importer })?.optional
-        ) {
-            log.debug('check-resource', `${JSON.stringify({ resource, importer })} => true`);
-            return true;
+    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 })) {
-            try {
-                require.resolve(resource);
-            } catch {
-                return true;
-            }
+        if (
+            isManagedReactDomClientDependency({ resource, importer }) &&
+            !isResolvable({ resource, importer })
+        ) {
+            return 'empty';
         }
         return false;
     };

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

@@ -1,15 +1,78 @@
+import memoize from 'lodash.memoize';
 import { getPackageJson } from './get-package-json';
-import type { CheckerArgs } from './types';
+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 {
-    return /^[@a-z]/.test(resource)
-        ? getPackageJson(importer)?.peerDependenciesMeta?.[resource]
-        : 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

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

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

@@ -1,3 +1,5 @@
+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/create-build-context.ts

@@ -2,6 +2,7 @@ import { getPackageManager } from '@servicetitan/install';
 import yargs, { Arguments } from 'yargs';
 import { hideBin } from 'yargs/helpers';
 import {
+    getExposeProcessEnv,
     getFolders,
     getPackageData,
     isExposeSharedDependencies,
@@ -18,7 +19,6 @@ export interface BuildContextOptions {
     light?: boolean;
     headless?: boolean;
     emitExposedDependencies?: BuildIdentity['emitExposedDependencies'];
-    outputBasePath?: string;
     codeCoverage?: boolean;
     buildStat?: boolean;
 }
@@ -43,6 +43,7 @@ export function createBuildContext(options: BuildContextOptions): BuildContext {
             isWebComponent: isWebComponent(),
             isLegacyRoot: isLegacyRoot(),
             isExposeSharedDependencies: isExposeSharedDependencies(),
+            exposeProcessEnv: getExposeProcessEnv(),
             packageManager: getPackageManager(),
         },
         build: {
@@ -51,7 +52,6 @@ export function createBuildContext(options: BuildContextOptions): BuildContext {
             light: options.light,
             headless: options.headless,
             emitExposedDependencies: options.emitExposedDependencies,
-            outputBasePath: options.outputBasePath,
         },
         options: {
             codeCoverage: options.codeCoverage ?? !!args['code-coverage'],

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/get-process-env.ts

@@ -0,0 +1,17 @@
+import { BuildContext } from './types';
+
+/*
+ * Maps each configured variable name to a `process.env.NAME` key holding its JSON-encoded
+ * build-time value. An unset variable maps to `undefined`. Returns undefined when none are
+ * configured.
+ */
+export function getProcessEnv(context: BuildContext): Record<string, string> | undefined {
+    const names = context.package.exposeProcessEnv;
+    if (!names?.length) {
+        return;
+    }
+
+    return Object.fromEntries(
+        names.map(name => [`process.env.${name}`, JSON.stringify(process.env[name]) ?? 'undefined'])
+    );
+}

package/src/core/index.ts

@@ -1,16 +1,23 @@
+export * from './bundle-report';
 export * from './check-resource';
+export * from './chunk-patterns';
 export * from './constants';
 export * from './create-build-context';
+export * from './create-extension-regexp';
 export * from './defines';
 export * from './externals';
 export * from './get-build-name';
 export * from './get-bundle-type';
 export * from './get-cdn-path';
 export * from './get-exposed-dependencies';
-export * from './get-output-path';
+export * from './get-process-env';
 export * from './get-shared-entry-points';
 export * from './get-version';
 export * from './metadata';
+export * from './moment-locales';
+export * from './resolve-output-path';
+export * from './resolve-output-root';
+export * from './sort-shared-css';
 export * from './stringify-config';
 export type * from './types';
 export * from './virtual-modules';