@harness-fe/webpack 3.0.0

package/src/index.ts

@@ -0,0 +1,29 @@
+/**
+ * @harness-fe/webpack — native webpack plugin for Harness-FE.
+ *
+ * Usage:
+ *   const { harnessFE } = require('@harness-fe/webpack')
+ *   // or
+ *   import { harnessFE } from '@harness-fe/webpack'
+ *
+ *   module.exports = { plugins: [harnessFE()] }
+ *
+ * Unlike previous versions (which were thin re-exports of
+ * @harness-fe/unplugin/webpack), this package implements a native webpack
+ * plugin that is compatible with thread-loader. See plugin.ts for the why.
+ */
+
+export { harnessFE, HarnessFEWebpackPlugin } from './plugin.js';
+export type { HarnessFEOptions } from '@harness-fe/unplugin';
+
+// Re-export transform utilities for direct usage (preserves the previous
+// public surface of @harness-fe/webpack@2.x).
+export {
+    transformJsx,
+    type ComponentMap,
+    type ComponentLocation,
+    type TransformResult,
+} from '@harness-fe/unplugin';
+
+import { harnessFE } from './plugin.js';
+export default harnessFE;

package/src/loader-options-serializable.test.ts

@@ -0,0 +1,106 @@
+/**
+ * The whole reason this package exists: loader options MUST be JSON-
+ * serializable, otherwise thread-loader crashes when dispatching jobs to
+ * its worker pool (`WorkerPool.writeJson` → JSON.stringify → circular
+ * structure on `Compiler.root`).
+ *
+ * This test pins that invariant.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { harnessFE, HarnessFEWebpackPlugin } from './plugin.js';
+
+describe('HarnessFEWebpackPlugin', () => {
+    let warnSpy: ReturnType<typeof vi.spyOn>;
+    beforeEach(() => {
+        // EntryPlugin tries to tap an unstubbed hook in our minimal mock and
+        // hits our catch-and-warn path. That's fine functionally but noisy.
+        warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    });
+    afterEach(() => {
+        warnSpy.mockRestore();
+    });
+
+    function buildMockCompiler() {
+        const rules: any[] = [];
+        const hookCalls: Record<string, number> = {};
+        const tapStub = (_name: string) => {
+            hookCalls[_name] = (hookCalls[_name] ?? 0) + 1;
+        };
+        const compiler = {
+            options: {
+                context: '/fake/project/root',
+                mode: 'development',
+                module: { rules },
+            },
+            context: '/fake/project/root',
+            hooks: {
+                afterEnvironment: { tap: tapStub.bind(null, 'afterEnvironment') },
+                shutdown: { tap: tapStub.bind(null, 'shutdown') },
+                compilation: { tap: tapStub.bind(null, 'compilation') },
+                done: { tap: tapStub.bind(null, 'done') },
+            },
+        };
+        return { compiler, rules, hookCalls };
+    }
+
+    it('registers a pre-rule whose loader options are JSON-serializable', () => {
+        const { compiler, rules } = buildMockCompiler();
+        // Force disabled=true to keep the test focused on rule injection
+        // (we don't want to actually open a websocket or inject runtime here).
+        const plugin = new HarnessFEWebpackPlugin({ projectId: 'test' });
+
+        // disabled bails out before rule injection — call apply with enabled
+        // but avoid the side-effecty hooks by stubbing webpack module loading.
+        // Easiest: enable, accept that hooks tap (they're stubbed above).
+        plugin.apply(compiler);
+
+        expect(rules.length).toBe(1);
+        const rule = rules[0];
+        expect(rule.enforce).toBe('pre');
+        expect(rule.test).toBeInstanceOf(RegExp);
+        expect(rule.use).toHaveLength(1);
+
+        const use = rule.use[0];
+        expect(use.loader).toMatch(/loader\.js$/);
+
+        // The critical assertion: options must round-trip through JSON
+        // without throwing on circular structure.
+        expect(() => JSON.stringify(use.options)).not.toThrow();
+
+        const parsed = JSON.parse(JSON.stringify(use.options));
+        expect(parsed.pluginId).toBeDefined();
+        expect(parsed.projectRoot).toBe('/fake/project/root');
+        expect(parsed.vueOptions).toEqual({ safeMode: true, dryRun: false });
+        expect(parsed.disabled).toBe(false);
+    });
+
+    it('matches the right file extensions including vue-loader virtual sub-modules', () => {
+        const { compiler, rules } = buildMockCompiler();
+        new HarnessFEWebpackPlugin().apply(compiler);
+        const re: RegExp = rules[0].test;
+
+        expect(re.test('/a/App.vue')).toBe(true);
+        expect(re.test('/a/App.vue?vue&type=template')).toBe(true);
+        expect(re.test('/a/App.vue?vue&type=script&lang=ts')).toBe(true);
+        expect(re.test('/a/Foo.tsx')).toBe(true);
+        expect(re.test('/a/Foo.jsx')).toBe(true);
+        expect(re.test('/a/Foo.ts')).toBe(false);
+        expect(re.test('/a/Foo.js')).toBe(false);
+        expect(re.test('/a/styles.css')).toBe(false);
+    });
+
+    it('skips rule injection when disabled', () => {
+        const { compiler, rules } = buildMockCompiler();
+        new HarnessFEWebpackPlugin({ disabled: true }).apply(compiler);
+        expect(rules).toHaveLength(0);
+    });
+
+    it('factory and class produce equivalent shapes', () => {
+        const { compiler: c1, rules: r1 } = buildMockCompiler();
+        const { compiler: c2, rules: r2 } = buildMockCompiler();
+        harnessFE({ projectId: 'a' }).apply(c1);
+        new HarnessFEWebpackPlugin({ projectId: 'a' }).apply(c2);
+        expect(r1[0].test.source).toBe(r2[0].test.source);
+        expect(r1[0].enforce).toBe(r2[0].enforce);
+    });
+});

package/src/loader.ts

@@ -0,0 +1,93 @@
+/**
+ * Webpack loader entrypoint for @harness-fe/webpack.
+ *
+ * IMPORTANT: This file is loaded by webpack's loader runner (potentially
+ * inside a thread-loader worker process). The options object passed to this
+ * loader MUST be pure JSON-serializable data — no plugin instance, no
+ * compiler reference, no closures. The reason this package exists at all is
+ * that unplugin's webpack adapter passes the plugin instance in options,
+ * which closes over `compiler.root` and breaks thread-loader's JSON.stringify.
+ *
+ * The loader collects component locations into a per-call temporary
+ * componentMap, then writes them to `module.buildMeta.harnessCollected`.
+ * The main-process plugin reads buildMeta via `compilation.succeedModule`
+ * and merges the entries into the real shared componentMap.
+ */
+
+import type { ComponentMap, ComponentLocation } from '@harness-fe/unplugin';
+import { runTransform } from './transform-runner.js';
+
+export interface HarnessLoaderOptions {
+    pluginId: string;
+    projectRoot: string;
+    vueOptions: {
+        safeMode: boolean;
+        dryRun: boolean;
+    };
+    disabled: boolean;
+}
+
+interface CollectedLocation {
+    name: string;
+    location: ComponentLocation;
+}
+
+interface LoaderContext {
+    async: () => (err: Error | null, content?: string, map?: object) => void;
+    getOptions: () => HarnessLoaderOptions;
+    resourcePath: string;
+    resourceQuery: string;
+    _module?: { buildMeta?: Record<string, unknown> };
+}
+
+export default function harnessLoader(this: LoaderContext, source: string): void {
+    const callback = this.async();
+    const opts = this.getOptions();
+
+    if (opts.disabled) {
+        callback(null, source);
+        return;
+    }
+
+    // Fresh map per call — caller-side accumulation lives in main-process
+    // shared-state, fed via module.buildMeta.
+    const localMap: ComponentMap = new Map();
+
+    let out;
+    try {
+        out = runTransform(
+            source,
+            this.resourcePath,
+            this.resourceQuery,
+            opts.projectRoot,
+            { safeMode: opts.vueOptions.safeMode, dryRun: opts.vueOptions.dryRun },
+            localMap,
+        );
+    } catch (err) {
+        // Never break the host build because of a transform bug.
+        callback(null, source);
+        return;
+    }
+
+    // Forward collected locations to main process via buildMeta.
+    if (localMap.size > 0 && this._module) {
+        const collected: CollectedLocation[] = [];
+        for (const [name, locs] of localMap.entries()) {
+            for (const location of locs) {
+                collected.push({ name, location });
+            }
+        }
+        const buildMeta = (this._module.buildMeta ??= {});
+        const existing = (buildMeta.harnessCollected as CollectedLocation[] | undefined) ?? [];
+        buildMeta.harnessCollected = existing.concat(collected);
+    }
+
+    if (!out) {
+        callback(null, source);
+        return;
+    }
+
+    callback(null, out.code, out.map);
+}
+
+export const raw = false;

package/src/plugin.ts

@@ -0,0 +1,272 @@
+/**
+ * @harness-fe/webpack — native webpack plugin.
+ *
+ * Why native (vs the unplugin adapter):
+ *   unplugin's webpack adapter passes the plugin instance through a loader's
+ *   `options` field. The plugin instance closes over `compiler` (via the
+ *   `webpack(compiler)` hook), and `compiler.root` self-references the
+ *   compiler — JSON.stringify chokes on the cycle. thread-loader serializes
+ *   downstream loader options when dispatching to its worker pool, so any
+ *   project that puts thread-loader anywhere ahead of harness in the
+ *   resolved loader chain (e.g. a `.ts` rule that vue-loader inlines for
+ *   `<script lang="ts">` SFC blocks) breaks the entire build.
+ *
+ * This native plugin:
+ *   - Registers a separate `enforce: 'pre'` rule pointing at an independent
+ *     loader file (loader.ts) whose options are pure JSON-serializable data.
+ *   - Keeps all stateful work (WebSocket to MCP, log capture, runtime
+ *     injection, error forwarding, HTML injection) in the main process via
+ *     compiler hooks.
+ *   - Aggregates componentMap entries from worker processes via
+ *     `module.buildMeta.harnessCollected`.
+ */
+
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve as resolvePath } from 'node:path';
+import {
+    createMcpClient,
+    createBuildIdentity,
+    installNodeLogCapture,
+    appendTokenQuery,
+    type ComponentLocation,
+    type HarnessFEOptions,
+    type McpClient,
+    type McpClientContext,
+} from '@harness-fe/unplugin';
+import { DEFAULT_WS_PORT } from '@harness-fe/protocol';
+import { getOrCreateComponentMap } from './shared-state.js';
+import type { HarnessLoaderOptions } from './loader.js';
+
+const require = createRequire(import.meta.url);
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+function newPluginId(): string {
+    const g = globalThis as { crypto?: { randomUUID?: () => string } };
+    if (g.crypto?.randomUUID) return g.crypto.randomUUID();
+    return `harness-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+}
+
+interface CollectedLocation {
+    name: string;
+    location: ComponentLocation;
+}
+
+export class HarnessFEWebpackPlugin {
+    private readonly pluginId = newPluginId();
+    private readonly options: HarnessFEOptions;
+    private projectRoot: string = process.cwd();
+    private projectId: string;
+    private readonly mcpUrl: string;
+    private readonly token: string | undefined;
+    private mcpClient?: McpClient;
+    private logCleanup?: () => void;
+    private identity = createBuildIdentity({
+        userBuildId: undefined,
+        userDisplayName: undefined,
+    });
+
+    constructor(options: HarnessFEOptions = {}) {
+        this.options = options;
+        this.projectId = options.projectId ?? 'unknown-project';
+        const baseUrl =
+            options.mcpUrl ??
+            process.env.HARNESS_FE_URL ??
+            `ws://127.0.0.1:${DEFAULT_WS_PORT}`;
+        this.token = options.token ?? process.env.HARNESS_FE_TOKEN;
+        this.mcpUrl = appendTokenQuery(baseUrl, this.token);
+        this.identity = createBuildIdentity({
+            userBuildId: options.buildId,
+            userDisplayName: options.displayName,
+        });
+    }
+
+    apply(compiler: any): void {
+        if (this.options.disabled) return;
+
+        this.projectRoot = compiler.options?.context ?? process.cwd();
+
+        // Resolve loader path. require.resolve gives an absolute path that
+        // webpack can hand to loader-runner regardless of host project's
+        // module resolution config.
+        const loaderPath = resolvePath(__dirname, 'loader.js');
+
+        const loaderOptions: HarnessLoaderOptions = {
+            pluginId: this.pluginId,
+            projectRoot: this.projectRoot,
+            vueOptions: {
+                safeMode: this.options.safeMode !== false,
+                dryRun: process.env.HARNESS_FE_DRY_RUN === '1',
+            },
+            disabled: false,
+        };
+
+        // Register the transform loader as a pre-rule.
+        compiler.options.module ??= { rules: [] };
+        compiler.options.module.rules ??= [];
+        compiler.options.module.rules.unshift({
+            test: /\.([jt]sx|vue)($|\?)/,
+            exclude: /[\\/]node_modules[\\/]/,
+            enforce: 'pre',
+            use: [
+                {
+                    loader: loaderPath,
+                    options: loaderOptions,
+                    ident: `harness-fe-${this.pluginId}`,
+                },
+            ],
+        });
+
+        // Skip the rest in production builds — runtime injection and MCP
+        // connection are dev-only conveniences.
+        if (compiler.options?.mode === 'production') return;
+
+        this.installRuntimeEntry(compiler);
+        this.installMcpHooks(compiler);
+        this.installComponentMapAggregator(compiler);
+        this.installHtmlInjection(compiler);
+        this.installErrorForwarding(compiler);
+    }
+
+    private installRuntimeEntry(compiler: any): void {
+        try {
+            const webpackPkg = require('webpack');
+            const { EntryPlugin } = webpackPkg;
+            const runtimeEntry = require.resolve('@harness-fe/runtime');
+            new EntryPlugin(compiler.context ?? this.projectRoot, runtimeEntry, {
+                name: undefined,
+            }).apply(compiler);
+        } catch (err) {
+            console.warn(
+                '[harness-fe] failed to register runtime entry via webpack.EntryPlugin:',
+                err,
+            );
+        }
+    }
+
+    private installMcpHooks(compiler: any): void {
+        const ctx: McpClientContext = {
+            get projectId() {
+                return self.projectId;
+            },
+            get mcpUrl() {
+                return self.mcpUrl;
+            },
+            get token() {
+                return self.token;
+            },
+            peerRole: 'webpack-plugin',
+            get parentProjectId() {
+                return self.options.parentProjectId;
+            },
+            get projectRoot() {
+                return self.projectRoot;
+            },
+            get componentMap() {
+                return getOrCreateComponentMap(self.pluginId);
+            },
+            getBuildId: () => this.identity.getBuildId(this.projectRoot),
+            getDisplayName: () => this.identity.getDisplayName(this.projectRoot),
+        };
+        const self = this;
+
+        compiler.hooks.afterEnvironment.tap('harness-fe', () => {
+            const client = createMcpClient(ctx);
+            this.mcpClient = client;
+            client.connect();
+            this.logCleanup = installNodeLogCapture((name, payload) => client.emitEvent(name, payload));
+        });
+
+        compiler.hooks.shutdown?.tap('harness-fe', () => {
+            this.logCleanup?.();
+            this.logCleanup = undefined;
+            this.mcpClient?.disconnect();
+            this.mcpClient = undefined;
+        });
+    }
+
+    private installComponentMapAggregator(compiler: any): void {
+        const pluginId = this.pluginId;
+        compiler.hooks.compilation.tap('harness-fe', (compilation: any) => {
+            compilation.hooks.succeedModule.tap('harness-fe', (module: any) => {
+                const collected = module.buildMeta?.harnessCollected as
+                    | CollectedLocation[]
+                    | undefined;
+                if (!collected?.length) return;
+                const map = getOrCreateComponentMap(pluginId);
+                for (const { name, location } of collected) {
+                    const existing = map.get(name) ?? [];
+                    existing.push(location);
+                    map.set(name, existing);
+                }
+            });
+        });
+    }
+
+    private installHtmlInjection(compiler: any): void {
+        compiler.hooks.compilation.tap('harness-fe', (compilation: any) => {
+            // Prefer html-webpack-plugin hooks when available.
+            try {
+                const HtmlPlugin = require('html-webpack-plugin');
+                const hooks = HtmlPlugin.getHooks(compilation);
+                hooks.beforeEmit.tapAsync('harness-fe', (data: any, cb: any) => {
+                    data.html = this.injectConfigScript(data.html);
+                    cb(null, data);
+                });
+            } catch {
+                // Fallback: rewrite html assets directly.
+                const { Compilation, sources } = require('webpack');
+                compilation.hooks.processAssets.tap(
+                    {
+                        name: 'harness-fe',
+                        stage: Compilation.PROCESS_ASSETS_STAGE_OPTIMIZE_INLINE,
+                    },
+                    (assets: Record<string, any>) => {
+                        for (const [name, source] of Object.entries(assets)) {
+                            if (!name.endsWith('.html')) continue;
+                            const html = source.source();
+                            if (typeof html !== 'string') continue;
+                            compilation.updateAsset(
+                                name,
+                                new sources.RawSource(this.injectConfigScript(html)),
+                            );
+                        }
+                    },
+                );
+            }
+        });
+    }
+
+    private installErrorForwarding(compiler: any): void {
+        compiler.hooks.done.tap('harness-fe', (stats: any) => {
+            if (!this.mcpClient || !stats.hasErrors()) return;
+            const errors = stats.compilation?.errors ?? [];
+            for (const err of errors) {
+                this.mcpClient.emitEvent('error', {
+                    message: err.message ?? String(err),
+                    file: err.module?.resource ?? undefined,
+                });
+            }
+        });
+    }
+
+    private injectConfigScript(html: string): string {
+        const injection = `<!-- @harness-fe injected (dev only) -->
+<script>
+window.__HARNESS_FE__ = ${JSON.stringify({
+            projectId: this.projectId,
+            mcpUrl: this.mcpUrl,
+            buildId: this.identity.getBuildId(this.projectRoot),
+            parentProjectId: this.options.parentProjectId,
+            displayName: this.identity.getDisplayName(this.projectRoot),
+        })};
+</script>`;
+        return html.replace(/<\/head>/i, `${injection}\n</head>`);
+    }
+}
+
+/** Factory matching the previous unplugin-based call shape. */
+export function harnessFE(options: HarnessFEOptions = {}): HarnessFEWebpackPlugin {
+    return new HarnessFEWebpackPlugin(options);
+}

package/src/shared-state.test.ts

@@ -0,0 +1,32 @@
+import { describe, it, expect } from 'vitest';
+import { getOrCreateComponentMap, clearComponentMap } from './shared-state.js';
+
+describe('shared-state', () => {
+    it('returns the same map for the same pluginId across calls', () => {
+        const a = getOrCreateComponentMap('plugin-1');
+        const b = getOrCreateComponentMap('plugin-1');
+        expect(a).toBe(b);
+        a.set('Foo', [{ file: 'x.tsx', line: 1, col: 0 }]);
+        expect(b.get('Foo')?.length).toBe(1);
+        clearComponentMap('plugin-1');
+    });
+
+    it('isolates maps between different plugin ids', () => {
+        const a = getOrCreateComponentMap('plugin-A');
+        const b = getOrCreateComponentMap('plugin-B');
+        expect(a).not.toBe(b);
+        a.set('Foo', [{ file: 'a.tsx', line: 1, col: 0 }]);
+        expect(b.has('Foo')).toBe(false);
+        clearComponentMap('plugin-A');
+        clearComponentMap('plugin-B');
+    });
+
+    it('clearComponentMap forgets the entry', () => {
+        const a = getOrCreateComponentMap('plugin-X');
+        a.set('Foo', [{ file: 'x.tsx', line: 1, col: 0 }]);
+        clearComponentMap('plugin-X');
+        const b = getOrCreateComponentMap('plugin-X');
+        expect(b.has('Foo')).toBe(false);
+        clearComponentMap('plugin-X');
+    });
+});

package/src/shared-state.ts

@@ -0,0 +1,30 @@
+/**
+ * Module-level componentMap registry keyed by plugin instance id.
+ *
+ * Used by the main webpack process to accumulate component locations forwarded
+ * from worker processes via `module.buildMeta.harnessCollected`. The MCP
+ * client (also main-process only) reads from this map to answer
+ * `project.where_is` / `project.module_graph` queries.
+ *
+ * thread-loader workers fork separate Node processes, so they get their own
+ * empty `maps` instance — but the loader in workers doesn't persist anything
+ * here. It writes collected locations to `module.buildMeta` and the main
+ * process aggregates them via the `succeedModule` hook.
+ */
+
+import type { ComponentMap } from '@harness-fe/unplugin';
+
+const maps = new Map<string, ComponentMap>();
+
+export function getOrCreateComponentMap(pluginId: string): ComponentMap {
+    let m = maps.get(pluginId);
+    if (!m) {
+        m = new Map();
+        maps.set(pluginId, m);
+    }
+    return m;
+}
+
+export function clearComponentMap(pluginId: string): void {
+    maps.delete(pluginId);
+}

package/src/transform-runner.test.ts

@@ -0,0 +1,70 @@
+/**
+ * runTransform dispatcher tests — verifies the right transform function is
+ * picked for each id variant (.vue, .vue?type=template, .vue?type=script,
+ * .tsx, .jsx) and that componentMap is populated for the cases that own
+ * component name resolution.
+ */
+import { describe, it, expect } from 'vitest';
+import type { ComponentMap } from '@harness-fe/unplugin';
+import { runTransform } from './transform-runner.js';
+
+const VUE_OPTIONS = { safeMode: true, dryRun: false } as const;
+
+describe('runTransform', () => {
+    it('transforms a .tsx file and populates componentMap', () => {
+        const map: ComponentMap = new Map();
+        const src = `
+            export function App() {
+                return <div className="root"><span>hi</span></div>;
+            }
+        `;
+        const out = runTransform(src, '/project/App.tsx', '', '/project', VUE_OPTIONS, map);
+        expect(out).not.toBeNull();
+        expect(out!.code).toContain('data-morphix-loc=');
+        expect(out!.code).toContain('data-morphix-comp="App"');
+        const locs = map.get('App');
+        expect(locs && locs.length).toBeGreaterThan(0);
+    });
+
+    it('returns null for non-template .vue sub-modules (script/style)', () => {
+        const map: ComponentMap = new Map();
+        const out = runTransform(
+            'export default {}',
+            '/project/App.vue',
+            '?vue&type=script&lang=ts',
+            '/project',
+            VUE_OPTIONS,
+            map,
+        );
+        expect(out).toBeNull();
+        expect(map.size).toBe(0);
+    });
+
+    it('returns null for a non-JSX .tsx file (transformJsx returns null when nothing tagged)', () => {
+        const map: ComponentMap = new Map();
+        const out = runTransform(
+            'export const x: number = 1;',
+            '/project/util.tsx',
+            '',
+            '/project',
+            VUE_OPTIONS,
+            map,
+        );
+        expect(out).toBeNull();
+    });
+
+    it('returns null when transform encounters malformed source (errorRecovery falls back to no tags)', () => {
+        const map: ComponentMap = new Map();
+        const out = runTransform(
+            'this is not valid javascript at all <<<>>>',
+            '/project/broken.tsx',
+            '',
+            '/project',
+            VUE_OPTIONS,
+            map,
+        );
+        // Either returns null (no JSX found) or returns a result with no
+        // taggedCount — both are acceptable, neither should throw.
+        expect(out === null || typeof out.code === 'string').toBe(true);
+    });
+});