@servicetitan/startup 36.4.0 → 37.0.1

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

@@ -1,29 +1,30 @@
 import { log } from '../../utils';
-import { BuildContext } from '../types';
+import type { PackageContext } 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;
+export function checkResource(context: { package: Pick<PackageContext, 'dependencies'> }) {
+    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';

package/src/core/moment-locales.ts

@@ -0,0 +1,6 @@
+/*
+ * The moment locales the build supports. Under webpack, MomentLocalesPlugin narrows moment's
+ * built-in locales down to this set; under Vite, Rolldown bundles no locales, so the Vite plugin
+ * statically imports these to add them back. Shared so both bundlers agree on the set.
+ */
+export const MOMENT_LOCALES = ['en-au', 'en-ca', 'en-gb'];

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

@@ -0,0 +1,10 @@
+import path from 'path';
+import { getBundleType } from './get-bundle-type';
+import { resolveOutputRoot } from './resolve-output-root';
+import { BuildContext } from './types';
+
+export function resolveOutputPath(context: BuildContext, outputPath: string | undefined): string {
+    const root = resolveOutputRoot(context, outputPath);
+    const subdir = getBundleType(context);
+    return subdir ? path.join(root, subdir) : root;
+}

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

@@ -0,0 +1,8 @@
+import path from 'path';
+import { BuildContext } from './types';
+
+export function resolveOutputRoot(context: BuildContext, outputPath: string | undefined): string {
+    const { destination, isWebComponent } = context.package;
+    const defaultOutputPath = path.join(process.cwd(), destination, 'bundle');
+    return isWebComponent ? defaultOutputPath : (outputPath ?? defaultOutputPath);
+}

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

@@ -0,0 +1,7 @@
+export function sortSharedCss(cssFiles: string[]): string[] {
+    // Put design-system CSS first to give anvil2 CSS higher precedence
+    const offset = cssFiles.findIndex(name => name.startsWith('design-system'));
+    return offset > 0
+        ? [cssFiles[offset], ...cssFiles.filter((_, index) => index !== offset)]
+        : cssFiles;
+}

package/src/core/types.ts

@@ -16,6 +16,7 @@ export interface PackageContext {
     isWebComponent: boolean;
     isLegacyRoot: boolean;
     isExposeSharedDependencies: boolean;
+    exposeProcessEnv?: string[];
     packageManager: ReturnType<typeof getPackageManager>;
 }
 
@@ -25,7 +26,6 @@ export interface BuildIdentity {
     light?: boolean;
     headless?: boolean;
     emitExposedDependencies?: boolean;
-    outputBasePath?: string;
 }
 
 export interface BuildOptions {

package/src/cypress/config/__tests__/vite-config.test.ts

@@ -0,0 +1,72 @@
+import type { InlineConfig } from 'vite';
+import { createCssConfig } from '../../../vite/config/create-css-config';
+import { istanbulPlugin, svgrPlugin } from '../../../vite/plugins';
+import { viteConfig } from '../vite-config';
+
+jest.mock('vite', () => ({
+    mergeConfig: (base: object, overrides: object) => ({ ...base, ...overrides }),
+}));
+jest.mock('../../../vite/config/create-css-config');
+jest.mock('../../../vite/plugins');
+
+describe(`[startup/cypress-config] ${viteConfig.name}`, () => {
+    const cssConfig: any = { modules: { localsConvention: 'camelCaseOnly' } };
+    const svgr: any = { name: 'svgr' };
+    const istanbul: any = { name: 'istanbul' };
+
+    let overrides: InlineConfig | undefined;
+
+    const subject = () => viteConfig(overrides);
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+        jest.mocked(createCssConfig).mockReturnValue(cssConfig);
+        jest.mocked(svgrPlugin).mockReturnValue(svgr);
+        jest.mocked(istanbulPlugin).mockReturnValue(istanbul);
+        overrides = undefined;
+    });
+
+    test('builds the CSS config for development', () => {
+        subject();
+
+        expect(createCssConfig).toHaveBeenCalledWith(false);
+    });
+
+    test('wires the shared CSS config', () => {
+        expect(subject().css).toBe(cssConfig);
+    });
+
+    test('includes the SVG plugin', () => {
+        expect(subject().plugins).toContain(svgr);
+    });
+
+    test('enables code coverage', () => {
+        subject();
+
+        expect(istanbulPlugin).toHaveBeenCalledWith(
+            expect.objectContaining({ options: { codeCoverage: true } })
+        );
+    });
+
+    test('includes the coverage plugin', () => {
+        expect(subject().plugins).toContain(istanbul);
+    });
+
+    test('dedupes React', () => {
+        expect(subject().resolve?.dedupe).toEqual(['react', 'react-dom']);
+    });
+
+    test('pre-bundles React', () => {
+        expect(subject().optimizeDeps?.include).toContain('react/jsx-runtime');
+    });
+
+    describe('with overrides', () => {
+        beforeEach(() => {
+            overrides = { clearScreen: false };
+        });
+
+        test('merges overrides into the config', () => {
+            expect(subject().clearScreen).toBe(false);
+        });
+    });
+});

package/src/cypress/config/index.ts

@@ -1 +1,2 @@
+export * from './vite-config';
 export * from './webpack-config';

package/src/cypress/config/vite-config.ts

@@ -0,0 +1,37 @@
+import { type InlineConfig, mergeConfig } from 'vite';
+import { createCssConfig } from '../../vite/config/create-css-config';
+import { istanbulPlugin, svgrPlugin } from '../../vite/plugins';
+import type { ViteBuildContext } from '../../vite/types';
+
+/*
+ * Dedupe and pre-bundle React so component tests load a single React instance.
+ * Mirrors how viteFinal handles Storybook, where automatic discovery can miss
+ * React in monorepos.
+ */
+const REACT_DEDUPE = ['react', 'react-dom'];
+const REACT_OPTIMIZE = [...REACT_DEDUPE, 'react/jsx-runtime'];
+
+export function viteConfig(overrides?: InlineConfig): InlineConfig {
+    const context = getContext();
+
+    const config: InlineConfig = {
+        css: createCssConfig(false),
+        resolve: { dedupe: REACT_DEDUPE },
+        optimizeDeps: { include: REACT_OPTIMIZE },
+        plugins: [svgrPlugin(context), istanbulPlugin(context)],
+    };
+
+    return mergeConfig(config, overrides ?? {});
+}
+
+function getContext(): ViteBuildContext {
+    /*
+     * svgrPlugin reads bundlerConfig.pluginOverrides and istanbulPlugin reads
+     * options.codeCoverage, so a minimal context reuses both. Component tests
+     * always instrument for coverage, matching the webpack Cypress config.
+     */
+    return {
+        options: { codeCoverage: true },
+        bundlerConfig: { pluginOverrides: {} },
+    } as ViteBuildContext;
+}