poc: preserve comments in esbuild

Author: shakyShane

injected/scripts/utils/build.js

@@ -3,6 +3,7 @@ import { readFileSync } from 'fs';
 import { cwd } from '../../../scripts/script-utils.js';
 import { join } from 'path';
 import * as esbuild from 'esbuild';
+import { commentPlugin } from './comment-plugin.js';
 const ROOT = join(cwd(import.meta.url), '..', '..');
 const DEBUG = false;
 
@@ -38,6 +39,7 @@ export async function bundle(params) {
         format: 'iife',
         bundle: true,
         metafile: true,
+        legalComments: 'inline',
         globalName: name,
         loader: {
             '.css': 'text',
@@ -48,7 +50,7 @@ export async function bundle(params) {
             'import.meta.injectName': JSON.stringify(platform),
             'import.meta.trackerLookup': trackerLookup,
         },
-        plugins: [loadFeaturesPlugin],
+        plugins: [loadFeaturesPlugin, commentPlugin({ pathMatch: 'seedrandom/lib/alea', regex: /^\/\/ Copyright \(C\)/ })],
         banner: {
             js: prefixMessage,
         },

injected/scripts/utils/comment-plugin.js

@@ -0,0 +1,79 @@
+import { join } from 'path';
+import { promises } from 'node:fs';
+
+/**
+ * @param {object} params
+ * @param {string} params.pathMatch
+ * @param {RegExp} params.regex
+ * @returns {import("esbuild").Plugin}
+ */
+export function commentPlugin({ pathMatch, regex }) {
+    const PLUGIN_ID = 'comment-override';
+
+    /** @type {import("esbuild").Plugin} */
+    const plugin = {
+        name: PLUGIN_ID,
+        setup(build) {
+            // watch every import/require and mark matches for processing
+            build.onResolve({ filter: /.*/ }, (args) => {
+                const path = join(args.resolveDir, args.path);
+                if (!path.includes(pathMatch)) return undefined;
+
+                // mark this file for processing
+                return {
+                    path: args.path,
+                    namespace: PLUGIN_ID,
+                    pluginData: {
+                        fullPath: join(args.resolveDir, args.path + '.js'),
+                    },
+                };
+            });
+
+            // this will only run for files matched above
+            build.onLoad({ filter: /.*/, namespace: PLUGIN_ID }, async (args) => {
+                const text = await promises.readFile(args.pluginData.fullPath, 'utf8');
+                return {
+                    contents: convertToLegalComments(text.toString(), regex),
+                    loader: 'js',
+                };
+            });
+        },
+    };
+    return plugin;
+}
+
+/**
+ * Detect the start of a particular comment and change the
+ * lines to have the prefix `//!`
+ *
+ * When a line is detect
+ *
+ * @param {string} source
+ * @param {RegExp} regex
+ */
+export function convertToLegalComments(source, regex) {
+    const lines = [];
+
+    let insideCommentBlock = false;
+
+    for (const line of source.split('\n')) {
+        if (insideCommentBlock) {
+            if (!line.match(/^\/\//)) {
+                insideCommentBlock = false;
+            }
+        } else {
+            if (line.match(regex)) {
+                insideCommentBlock = true;
+            }
+        }
+
+        // chose line treatment
+        if (insideCommentBlock) {
+            lines.push('//!' + line.slice(2));
+        } else {
+            lines.push(line);
+        }
+    }
+
+    return lines.join('\n');
+}

injected/unit-test/comment-plugin.js

@@ -0,0 +1,48 @@
+import { convertToLegalComments } from '../scripts/utils/comment-plugin.js';
+
+describe('convertToLegalComments', () => {
+    it('should convert matching comments to legal comments', () => {
+        const source = '// Copyright\n// All rights reserved\n// 2024';
+        const regex = /\/\/\s*Copyright/;
+        const expected = '//! Copyright\n//! All rights reserved\n//! 2024';
+
+        expect(convertToLegalComments(source, regex)).toBe(expected);
+    });
+
+    it("should not convert comments that don't match the regex", () => {
+        const source = '// Regular comment\n// Another comment';
+        const regex = /\/\/\s*License/;
+
+        expect(convertToLegalComments(source, regex)).toBe(source);
+    });
+
+    it('should stop converting when encountering non-comment line', () => {
+        const source = '// Copyright\n// All rights reserved\ncode line\n// Regular comment';
+        const regex = /\/\/\s*Copyright/;
+        const expected = '//! Copyright\n//! All rights reserved\ncode line\n// Regular comment';
+
+        expect(convertToLegalComments(source, regex)).toBe(expected);
+    });
+
+    it('should handle empty string input', () => {
+        const regex = /\/\/\s*Copyright/;
+
+        expect(convertToLegalComments('', regex)).toBe('');
+    });
+
+    it('should handle multiple comment blocks', () => {
+        const source = '// Copyright\n// Notice\ncode\n// Copyright\n// Notice';
+        const regex = /\/\/\s*Copyright/;
+        const expected = '//! Copyright\n//! Notice\ncode\n//! Copyright\n//! Notice';
+
+        expect(convertToLegalComments(source, regex)).toBe(expected);
+    });
+
+    it('should preserve leading spaces in comments', () => {
+        const source = '//    Copyright\n//   All rights reserved';
+        const regex = /\/\/\s*Copyright/;
+        const expected = '//!    Copyright\n//!   All rights reserved';
+
+        expect(convertToLegalComments(source, regex)).toBe(expected);
+    });
+});

injected/unit-test/verify-artifacts.js

@@ -23,6 +23,7 @@ const checks = {
         tests: [
             { kind: 'maxFileSize', value: CSS_OUTPUT_SIZE },
             { kind: 'containsString', text: '$TRACKER_LOOKUP$', includes: true },
+            { kind: 'containsString', text: 'Copyright (C) 2010 by Johannes Baagøe <[email protected]>', includes: true },
         ],
     },
     firefox: {
@@ -34,7 +35,7 @@ const checks = {
     },
     integration: {
         file: join(BUILD, 'integration/contentScope.js'),
-        tests: [{ kind: 'containsString', text: 'trackerLookup: ', includes: true }],
+        tests: [{ kind: 'containsString', text: 'init_define_import_meta_trackerLookup = ', includes: true }],
     },
     windows: {
         file: join(BUILD, 'windows/contentScope.js'),