diff --git a/.changepacks/changepack_log_best_effort_warnings.json b/.changepacks/changepack_log_best_effort_warnings.json new file mode 100644 index 000000000..4be7978cb --- /dev/null +++ b/.changepacks/changepack_log_best_effort_warnings.json @@ -0,0 +1 @@ +{"changes":{"packages/plugin-utils/package.json":"Patch","packages/vite-plugin/package.json":"Patch","packages/webpack-plugin/package.json":"Patch","packages/rsbuild-plugin/package.json":"Patch","packages/bun-plugin/package.json":"Patch"},"note":"When an optional setup step fails and the build goes on without it (Vite, webpack and Bun file numbering, the webpack and Rsbuild import graphs, the webpack stylesheet warm-up), print one warning naming the step, the cause and what the build loses instead of continuing silently. A project without a src directory stays quiet. No new build errors.","date":"2026-11-15T00:00:00.000Z"} diff --git a/packages/bun-plugin/src/__tests__/plugin.test.ts b/packages/bun-plugin/src/__tests__/plugin.test.ts index 6e2ea54a2..f42acc136 100644 --- a/packages/bun-plugin/src/__tests__/plugin.test.ts +++ b/packages/bun-plugin/src/__tests__/plugin.test.ts @@ -223,6 +223,33 @@ describe('registered Bun hooks', () => { expect(loads.length).toBe(2) }) + it('warns when runtime file numbering fails, and stays quiet without src', async () => { + const collect = spyOn(pluginUtils, 'collectNumberedFiles') + const warn = spyOn(console, 'warn').mockImplementation(() => {}) + try { + collect.mockImplementation(() => { + throw new Error('scan boom') + }) + await register({ engine: 'wasm' }) + expect(warn).toHaveBeenCalledWith( + '[devup-ui] Bun file numbering failed: scan boom. Stylesheet file numbers follow the order Bun loads files in, so they can differ between runs of the same source.', + ) + + warn.mockClear() + collect.mockImplementation(() => { + throw Object.assign(new Error('ENOENT'), { + code: 'ENOENT', + path: nodePath.resolve('src'), + }) + }) + await register({ engine: 'wasm' }) + expect(warn).not.toHaveBeenCalled() + } finally { + warn.mockRestore() + collect.mockRestore() + } + }) + it('leaves invalid JavaScript to the native loader after scanning fails', async () => { const path = join(root, 'malformed.ts') const source = 'import {' diff --git a/packages/bun-plugin/src/plugin.ts b/packages/bun-plugin/src/plugin.ts index 284772623..3abafeeec 100644 --- a/packages/bun-plugin/src/plugin.ts +++ b/packages/bun-plugin/src/plugin.ts @@ -12,6 +12,7 @@ import { type CustomShorthands, type DevupCompiler, type DevupEngine, + isMissingDirectory, isProjectJsx, loadCompiler, loadDevupConfig, @@ -19,6 +20,7 @@ import { normalizeShorthands, readJsxImportSource, seedFileNumbers, + setupWarning, tailwindCssFiles, withTailwindCss, } from '@devup-ui/plugin-utils' @@ -236,6 +238,14 @@ function DevupUI(options: DevupUIBunPluginOptions = {}) { ) } catch (error) { if (!(error instanceof Error)) throw error + if (!isMissingDirectory(error, resolve('src'))) + console.warn( + setupWarning( + 'Bun file numbering', + error, + 'Stylesheet file numbers follow the order Bun loads files in, so they can differ between runs of the same source.', + ), + ) } } diff --git a/packages/plugin-utils/src/__tests__/shared.test.ts b/packages/plugin-utils/src/__tests__/shared.test.ts index dd119cfd8..a95cffad7 100644 --- a/packages/plugin-utils/src/__tests__/shared.test.ts +++ b/packages/plugin-utils/src/__tests__/shared.test.ts @@ -6,8 +6,47 @@ import { DEFAULT_THEME_INTERFACE_NAMES, type DevupUIBasePluginOptions, getFileNumByFilename, + isMissingDirectory, + setupWarning, } from '../shared' +describe('isMissingDirectory', () => { + const missing = (path?: unknown, code = 'ENOENT') => + Object.assign(new Error('missing'), { code, path }) + + it('recognizes the directory itself not existing', () => { + expect(isMissingDirectory(missing('/project/src/'), '/project/src')).toBe( + true, + ) + }) + + it('rejects another path, another code and other thrown values', () => { + expect( + isMissingDirectory(missing('/project/src/a.ts'), '/project/src'), + ).toBe(false) + expect( + isMissingDirectory(missing('/project/src', 'EACCES'), '/project/src'), + ).toBe(false) + expect(isMissingDirectory(missing(), '/project/src')).toBe(false) + expect(isMissingDirectory(new Error('boom'), '/project/src')).toBe(false) + expect(isMissingDirectory('ENOENT', '/project/src')).toBe(false) + }) +}) + +describe('setupWarning', () => { + it('names the step, the cause and what the build loses', () => { + expect( + setupWarning('Vite file numbering', new Error('EACCES'), 'Numbers vary.'), + ).toBe('[devup-ui] Vite file numbering failed: EACCES. Numbers vary.') + }) + + it('reads a thrown value that is not an Error', () => { + expect(setupWarning('Step', 'gone', 'Impact.')).toBe( + '[devup-ui] Step failed: gone. Impact.', + ) + }) +}) + describe('getFileNumByFilename', () => { it('should return null for devup-ui.css', () => { expect(getFileNumByFilename('devup-ui.css')).toBeNull() diff --git a/packages/plugin-utils/src/index.ts b/packages/plugin-utils/src/index.ts index bfc7b1e1b..74abb94b0 100644 --- a/packages/plugin-utils/src/index.ts +++ b/packages/plugin-utils/src/index.ts @@ -56,6 +56,8 @@ export { type DevupThemeInterfaceNames, type DevupUIBasePluginOptions, getFileNumByFilename, + isMissingDirectory, + setupWarning, } from './shared' export { createSharedSlotReservation, diff --git a/packages/plugin-utils/src/shared.ts b/packages/plugin-utils/src/shared.ts index 20b7aac0e..d43551524 100644 --- a/packages/plugin-utils/src/shared.ts +++ b/packages/plugin-utils/src/shared.ts @@ -1,3 +1,5 @@ +import { resolve } from 'node:path' + import type { DevupEngine } from './compiler-types' import type { CustomShorthands, ImportAliases } from './types' @@ -108,3 +110,31 @@ export interface DevupUIBasePluginOptions { /** Build-time aliases that expand one style prop into multiple CSS properties. */ shorthands?: CustomShorthands } + +/** + * The warning a plugin prints when an optional setup step fails and the build + * goes on without it: the step, the root cause and what the build loses. + */ +export function setupWarning( + step: string, + error: unknown, + impact: string, +): string { + const cause = error instanceof Error ? error.message : String(error) + return `[devup-ui] ${step} failed: ${cause}. ${impact}` +} + +/** + * Whether `error` reports that `dir` itself does not exist. A project without + * that source root has nothing there to scan, so the step loses nothing. + */ +export function isMissingDirectory(error: unknown, dir: string): boolean { + return ( + error instanceof Error && + 'code' in error && + error.code === 'ENOENT' && + 'path' in error && + typeof error.path === 'string' && + resolve(error.path) === resolve(dir) + ) +} diff --git a/packages/rsbuild-plugin/src/plugin.ts b/packages/rsbuild-plugin/src/plugin.ts index 91dae66c8..c0d259cea 100644 --- a/packages/rsbuild-plugin/src/plugin.ts +++ b/packages/rsbuild-plugin/src/plugin.ts @@ -17,12 +17,14 @@ import { type DevupUIBasePluginOptions, getFileNumByFilename, type ImportAliases, + isMissingDirectory, loadCompiler, loadDevupConfig, mergeImportAliases, normalizeShorthands, planAtomHoist, readJsxImportSource, + setupWarning, tailwindCssFiles, withTailwindCss, } from '@devup-ui/plugin-utils' @@ -265,8 +267,16 @@ export const DevupUI = ({ '[devup-ui] fewer than 2 routes were detected; atom hoisting is a no-op (single-entry/SPA).', ) } - } catch { + } catch (error) { // Best-effort; on failure atom hoisting stays off (identity). + if (!isMissingDirectory(error, resolve(process.cwd(), 'src'))) + console.warn( + setupWarning( + 'Rsbuild import graph', + error, + 'Atom hoisting is off, so atoms several routes share are not moved into the shared stylesheet.', + ), + ) } } diff --git a/packages/vite-plugin/src/__tests__/plugin.test.ts b/packages/vite-plugin/src/__tests__/plugin.test.ts index cbc3643da..6ab18774e 100644 --- a/packages/vite-plugin/src/__tests__/plugin.test.ts +++ b/packages/vite-plugin/src/__tests__/plugin.test.ts @@ -627,15 +627,23 @@ describe('devupUIVitePlugin', () => { expect(seedFileMapSpy).not.toHaveBeenCalled() }) - it('keeps building when the scan fails', async () => { + it('keeps building when the scan fails, and says what numbering loses', async () => { onlyDirs('src') collectSpy.mockImplementation(() => { throw new Error('scan boom') }) + const warn = spyOn(console, 'warn').mockImplementation(() => {}) - await createPlugin({}).configResolved({ root: '/p' }) + try { + await createPlugin({}).configResolved({ root: '/p' }) - expect(seedFileMapSpy).not.toHaveBeenCalled() + expect(seedFileMapSpy).not.toHaveBeenCalled() + expect(warn).toHaveBeenCalledWith( + '[devup-ui] Vite file numbering failed: scan boom. Stylesheet file numbers follow the order Vite transforms files in, so they can differ between builds of the same source.', + ) + } finally { + warn.mockRestore() + } }) describe('source collection before seeding', () => { diff --git a/packages/vite-plugin/src/plugin.ts b/packages/vite-plugin/src/plugin.ts index f9ce736fc..568dfe22c 100644 --- a/packages/vite-plugin/src/plugin.ts +++ b/packages/vite-plugin/src/plugin.ts @@ -23,6 +23,7 @@ import { normalizeShorthands, readJsxImportSource, seedFileNumbers, + setupWarning, tailwindCssFiles, withTailwindCss, } from '@devup-ui/plugin-utils' @@ -529,8 +530,15 @@ export function DevupUI({ importAliases, }), ) - } catch { + } catch (error) { // Best-effort; on failure numbering falls back to arrival order. + console.warn( + setupWarning( + 'Vite file numbering', + error, + 'Stylesheet file numbers follow the order Vite transforms files in, so they can differ between builds of the same source.', + ), + ) } reservation.configure(config) if (extractionSession === session) session.ready = true diff --git a/packages/webpack-plugin/src/__tests__/plugin.test.ts b/packages/webpack-plugin/src/__tests__/plugin.test.ts index f22c489e3..407e17207 100644 --- a/packages/webpack-plugin/src/__tests__/plugin.test.ts +++ b/packages/webpack-plugin/src/__tests__/plugin.test.ts @@ -402,9 +402,17 @@ describe('devupUIWebpackPlugin', () => { collectSpy.mockImplementation(() => { throw new Error('scan boom') }) - new DevupUIWebpackPlugin({ engine: 'wasm', debug: true }).apply( - asCompiler(createCompiler()), - ) + const warn = spyOn(console, 'warn').mockImplementation(() => {}) + try { + new DevupUIWebpackPlugin({ engine: 'wasm', debug: true }).apply( + asCompiler(createCompiler()), + ) + expect(warn).toHaveBeenCalledWith( + '[devup-ui] webpack file numbering failed: scan boom. Stylesheet file numbers follow the order webpack compiles files in, so they can differ between builds of the same source.', + ) + } finally { + warn.mockRestore() + } } finally { collectSpy.mockRestore() seedSpy.mockRestore() @@ -1288,9 +1296,52 @@ describe('devupUIWebpackPlugin', () => { throw new Error('boom') }) const plugin = new DevupUIWebpackPlugin({ engine: 'wasm', atomHoist: 2 }) - // apply must still complete without throwing - plugin.apply(asCompiler(createCompiler())) - expect(setAtomHoistSpy).not.toHaveBeenCalled() + const warn = spyOn(console, 'warn').mockImplementation(() => {}) + try { + // apply must still complete without throwing + plugin.apply(asCompiler(createCompiler())) + expect(setAtomHoistSpy).not.toHaveBeenCalled() + expect(warn).toHaveBeenCalledWith( + '[devup-ui] webpack import graph failed: boom. Classes are not merged across files only one module imports, and atom hoisting is off.', + ) + } finally { + warn.mockRestore() + } + }) + + it('warns without atom hoisting when a pre-pass outside atom mode fails', () => { + buildCanonicalMapSpy.mockImplementation(() => { + throw new Error('boom') + }) + const warn = spyOn(console, 'warn').mockImplementation(() => {}) + try { + new DevupUIWebpackPlugin({ engine: 'wasm', atomHoist: 0 }).apply( + asCompiler(createCompiler()), + ) + expect(warn).toHaveBeenCalledWith( + '[devup-ui] webpack import graph failed: boom. Classes are not merged across files only one module imports.', + ) + } finally { + warn.mockRestore() + } + }) + + it('stays quiet when the project has no src directory to scan', () => { + buildCanonicalMapSpy.mockImplementation(() => { + throw Object.assign(new Error('ENOENT'), { + code: 'ENOENT', + path: resolve(process.cwd(), 'src'), + }) + }) + const warn = spyOn(console, 'warn').mockImplementation(() => {}) + try { + new DevupUIWebpackPlugin({ engine: 'wasm', atomHoist: 2 }).apply( + asCompiler(createCompiler()), + ) + expect(warn).not.toHaveBeenCalled() + } finally { + warn.mockRestore() + } }) it('configures atom hoisting BEFORE registering loader rules', () => { diff --git a/packages/webpack-plugin/src/plugin.ts b/packages/webpack-plugin/src/plugin.ts index 2c5bd2ed0..f5b10a19d 100644 --- a/packages/webpack-plugin/src/plugin.ts +++ b/packages/webpack-plugin/src/plugin.ts @@ -19,6 +19,7 @@ import { extractedNeedles, getFileNumByFilename, type ImportAliases, + isMissingDirectory, loadCompiler, loadDevupConfigSync, mergeImportAliases, @@ -26,6 +27,7 @@ import { planAtomHoist, readJsxImportSource, seedFileNumbers, + setupWarning, tailwindCssFiles, type WasmImportAliases, withTailwindCss, @@ -225,6 +227,13 @@ export class DevupUIWebpackPlugin { if (this.options.productionPrewarmFiles !== undefined) throw error // Best-effort warm-up; on failure the css-loader still serves whatever // atoms were extracted, matching pre-fix behavior. + console.warn( + setupWarning( + 'webpack stylesheet warm-up', + error, + 'A stylesheet webpack builds before every file it holds is extracted can miss their styles.', + ), + ) } } @@ -335,6 +344,16 @@ export class DevupUIWebpackPlugin { throw error // Best-effort; on failure canonical() is the identity (no merge) and atom // hoisting stays off. + if (!isMissingDirectory(error, resolve(process.cwd(), 'src'))) + console.warn( + setupWarning( + 'webpack import graph', + error, + atomMode + ? 'Classes are not merged across files only one module imports, and atom hoisting is off.' + : 'Classes are not merged across files only one module imports.', + ), + ) } // Number every file the build can extract in path order, so class @@ -361,6 +380,13 @@ export class DevupUIWebpackPlugin { ) throw error // Best-effort; numbering falls back to arrival order. + console.warn( + setupWarning( + 'webpack file numbering', + error, + 'Stylesheet file numbers follow the order webpack compiles files in, so they can differ between builds of the same source.', + ), + ) } // Pre-warm the extractor so the css-loader serves COMPLETE CSS. //