From c8601ac49d8baf1b14d9a364543fad93d7c91eb9 Mon Sep 17 00:00:00 2001 From: DeryFerd Date: Sun, 15 Nov 2026 22:44:38 +0700 Subject: [PATCH] feat(bundler): report chunks that shipped unshielded at build end With failBuildOnError false (the default) a chunk whose transform throws is passed through untouched, and the only evidence was a console.warn per chunk that is easy to lose in a large build log. A partial shield is exactly the kind of implicit claim the rest of BLA refuses to leave unsaid. Rollup/Vite and esbuild now print one summary from their build-end hook, and the webpack plugin prints it at the end of the asset stage, listing every chunk that shipped unprotected. Default behaviour for successful builds is unchanged (no summary, same pass-through for bad chunks). Also corrects the documented Vite option name (`honeySourceMap`, not `enableHoneySourceMaps`) in the same guide. --- docs/bundler-and-ci-integration.md | 10 +++++- src/bundler/index.ts | 50 +++++++++++++++++++++++++-- tests/bundler-skip-summary.test.ts | 55 ++++++++++++++++++++++++++++++ 3 files changed, 111 insertions(+), 4 deletions(-) create mode 100644 tests/bundler-skip-summary.test.ts diff --git a/docs/bundler-and-ci-integration.md b/docs/bundler-and-ci-integration.md index d164336..d8d04dd 100644 --- a/docs/bundler-and-ci-integration.md +++ b/docs/bundler-and-ci-integration.md @@ -10,12 +10,20 @@ export default defineConfig({ plugins: [ blaVitePlugin({ intensity: "bankrupt", - enableHoneySourceMaps: true, + honeySourceMap: true, }), ], }); ``` +Chunk-level protection is never silently partial. When a chunk fails to parse or transform and `failBuildOnError` is `false` (the default), that chunk ships **unshielded**, and the plugin prints one build-end summary listing every affected chunk: + +```text +[bla-shield] rollup/vite: 2 chunk(s) shipped UNPROTECTED (transform failed, failBuildOnError is false): a.js, b.js. Fix the parse/transform errors or set failBuildOnError: true. +``` + +Set `failBuildOnError: true` to fail the build at the first bad chunk instead. The Rollup/Vite and esbuild plugins print the summary from their build-end hook; the Webpack plugin prints it at the end of the asset stage. + ## 2. GitHub Actions Post-Build Hardening Add a single step after `npm run build` in your release workflow: diff --git a/src/bundler/index.ts b/src/bundler/index.ts index d778c8e..a606d83 100644 --- a/src/bundler/index.ts +++ b/src/bundler/index.ts @@ -76,6 +76,7 @@ function shieldOrPassThrough( ctx: { readonly fileName: string; readonly failBuildOnError: boolean; + readonly onSkip?: (fileName: string) => void; }, ): string | null { try { @@ -86,10 +87,34 @@ function shieldOrPassThrough( console.warn( `[bla-shield] skipped protection for ${ctx.fileName}: ${message}`, ); + ctx.onSkip?.(ctx.fileName); return null; } } +/** + * Collects the chunks that shipped unshielded so a build can end with one + * honest summary. A per-chunk `console.warn` alone is easy to lose in a large + * build log, and a partial shield is exactly the kind of claim the rest of BLA + * refuses to leave implicit. + */ +function createSkipTracker(pluginName: string) { + const skipped: string[] = []; + return { + note(fileName: string): void { + skipped.push(fileName); + }, + summary(): string | null { + if (skipped.length === 0) return null; + return ( + `[bla-shield] ${pluginName}: ${skipped.length} chunk(s) shipped UNPROTECTED ` + + `(transform failed, failBuildOnError is false): ${skipped.join(", ")}. ` + + "Fix the parse/transform errors or set failBuildOnError: true." + ); + }, + }; +} + /** * Vite & Rollup plugin (`blaVitePlugin` / `blaRollupPlugin`) that automatically * injects BLA's three-stage adversarial shield into generated JS chunks during `renderChunk`. @@ -109,9 +134,14 @@ export function blaRollupPlugin(options: BlaBundlerPluginOptions = {}) { const include = options.include ?? /\.(?:m?js|cjs)$/i; const emitMap = options.honeySourceMap ?? true; const failBuildOnError = options.failBuildOnError ?? false; + const skips = createSkipTracker("rollup/vite"); return { name: "bla-shield-rollup-plugin", + buildEnd() { + const summary = skips.summary(); + if (summary !== null) console.warn(summary); + }, renderChunk( code: string, chunk: { fileName: string; isEntry?: boolean }, @@ -135,7 +165,7 @@ export function blaRollupPlugin(options: BlaBundlerPluginOptions = {}) { sourceType, loader, }), - { fileName: chunk.fileName, failBuildOnError }, + { fileName: chunk.fileName, failBuildOnError, onSkip: (f) => skips.note(f) }, ); if (shieldedCode === null) { return null; // Rollup treats null as "no change": chunk passes through. @@ -235,6 +265,7 @@ export class BlaWebpackPlugin { const include = this.options.include ?? /\.(?:m?js|cjs)$/i; const emitMap = this.options.honeySourceMap ?? true; const failBuildOnError = this.options.failBuildOnError ?? false; + const skips = createSkipTracker("webpack"); compiler.hooks.compilation.tap("BlaWebpackPlugin", (compilation) => { compilation.hooks.processAssets.tap( @@ -260,7 +291,7 @@ export class BlaWebpackPlugin { sourceType, loader, }), - { fileName: assetName, failBuildOnError }, + { fileName: assetName, failBuildOnError, onSkip: (f) => skips.note(f) }, ); if (shieldedCode === null) { continue; // Webpack leaves the already-emitted asset untouched. @@ -278,6 +309,10 @@ export class BlaWebpackPlugin { compilation.emitAsset(`${assetName}.map`, createWebpackRawSource(honeyMap.jsonString)); } } + // Same honest build-end summary the Rollup plugin prints; webpack only + // exposes the asset stage to a structural plugin type. + const summary = skips.summary(); + if (summary !== null) console.warn(summary); }, ); }); @@ -302,7 +337,16 @@ export function blaEsbuildPlugin(options: BlaBundlerPluginOptions = {}) { path: string; }) => Promise<{ contents: string; loader: JsLoaderType } | null>, ) => void; + onEnd?: (cb: () => void) => void; }) { + const skips = createSkipTracker("esbuild"); + // Real esbuild always provides onEnd; tolerate structural test doubles. + if (typeof build.onEnd === "function") { + build.onEnd(() => { + const summary = skips.summary(); + if (summary !== null) console.warn(summary); + }); + } build.onLoad({ filter: include }, async (args) => { if (args.path.includes("node_modules")) return null; const fs = await import("node:fs/promises"); @@ -325,7 +369,7 @@ export function blaEsbuildPlugin(options: BlaBundlerPluginOptions = {}) { loader, sourceType, }), - { fileName: args.path, failBuildOnError }, + { fileName: args.path, failBuildOnError, onSkip: (f) => skips.note(f) }, ); if (shieldedCode === null) { return null; // esbuild falls back to reading the file as-is. diff --git a/tests/bundler-skip-summary.test.ts b/tests/bundler-skip-summary.test.ts new file mode 100644 index 0000000..4699d1d --- /dev/null +++ b/tests/bundler-skip-summary.test.ts @@ -0,0 +1,55 @@ +import { describe, expect, it } from "vitest"; +import { blaRollupPlugin, blaVitePlugin } from "../src/bundler/index.js"; + +function captureWarnings(fn: () => T): { result: T; warnings: string[] } { + const warnings: string[] = []; + const original = console.warn; + console.warn = (...args: unknown[]) => { + warnings.push(args.map(String).join(" ")); + }; + try { + return { result: fn(), warnings }; + } finally { + console.warn = original; + } +} + +describe("bundler skip summary", () => { + it("summarises unshielded chunks at build end", () => { + const plugin = blaRollupPlugin({ seed: "summary" }); + const { warnings } = captureWarnings(() => { + plugin.renderChunk("function ( {", { fileName: "broken-a.js" }, { format: "es" }); + plugin.renderChunk("function ( {", { fileName: "broken-b.js" }, { format: "es" }); + plugin.buildEnd(); + return null; + }); + + const summary = warnings.find((w) => w.includes("UNPROTECTED")); + expect(summary).toBeDefined(); + expect(summary).toContain("2 chunk(s)"); + expect(summary).toContain("broken-a.js"); + expect(summary).toContain("broken-b.js"); + }); + + it("stays quiet when every chunk was shielded", () => { + const plugin = blaRollupPlugin({ seed: "quiet", honeySourceMap: false }); + const { warnings } = captureWarnings(() => { + plugin.renderChunk("export const a = 1;\n", { fileName: "ok.js" }, { format: "es" }); + plugin.buildEnd(); + return null; + }); + + expect(warnings.some((w) => w.includes("UNPROTECTED"))).toBe(false); + }); + + it("exposes the same summary on the Vite alias", () => { + const plugin = blaVitePlugin({ seed: "vite-summary" }); + const { warnings } = captureWarnings(() => { + plugin.renderChunk("function ( {", { fileName: "broken-vite.js" }, { format: "es" }); + plugin.buildEnd(); + return null; + }); + + expect(warnings.some((w) => w.includes("broken-vite.js"))).toBe(true); + }); +}); \ No newline at end of file