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.
This commit is contained in:
DeryFerd
2026-11-15 22:44:38 +07:00
parent 98e01cc47b
commit c8601ac49d
3 changed files with 111 additions and 4 deletions
+9 -1
View File
@@ -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:
+47 -3
View File
@@ -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.
+55
View File
@@ -0,0 +1,55 @@
import { describe, expect, it } from "vitest";
import { blaRollupPlugin, blaVitePlugin } from "../src/bundler/index.js";
function captureWarnings<T>(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);
});
});