@harness-fe/unplugin 3.0.0

package/src/resolveProjectId.ts

@@ -0,0 +1,48 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+
+const HARNESS_ID_FILE = '.harness-id';
+
+/**
+ * Resolves the project ID for a given project root directory.
+ *
+ * Priority:
+ * 1. `userConfig` — if provided, return immediately without touching `.harness-id`
+ * 2. Read `{root}/.harness-id` — if readable, return trimmed content
+ * 3. Generate UUID v4, write to `{root}/.harness-id` (UTF-8, no BOM, no trailing whitespace), return it
+ */
+export async function resolveProjectId(root: string, userConfig?: string): Promise<string> {
+  // Priority 1: explicit user config value
+  if (userConfig !== undefined && userConfig !== '') {
+    return userConfig;
+  }
+
+  const idFilePath = join(root, HARNESS_ID_FILE);
+
+  // Priority 2: read existing .harness-id file
+  try {
+    const content = await readFile(idFilePath, 'utf-8');
+    const trimmed = content.trim();
+    if (trimmed.length > 0) {
+      return trimmed;
+    }
+  } catch (err) {
+    // ENOENT or other read error — fall through to generate a new UUID
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code !== 'ENOENT') {
+      // Log unexpected errors but still proceed to generate a new ID
+      console.warn(`[harness] Could not read ${idFilePath}: ${(err as Error).message}`);
+    }
+  }
+
+  // Priority 3: generate UUID v4, write to .harness-id, return it
+  const newId = randomUUID();
+  try {
+    await writeFile(idFilePath, newId, { encoding: 'utf-8' });
+  } catch (err) {
+    console.warn(`[harness] Could not write ${idFilePath}: ${(err as Error).message}`);
+  }
+
+  return newId;
+}

package/src/rollup.ts

@@ -0,0 +1,12 @@
+/**
+ * Rollup-specific export.
+ *
+ * Usage:
+ *   import { harnessFE } from '@harness-fe/unplugin/rollup'
+ */
+
+import { unplugin } from './core.js';
+export type { HarnessFEOptions } from './core.js';
+
+export const harnessFE = unplugin.rollup;
+export default harnessFE;

package/src/rspack.ts

@@ -0,0 +1,12 @@
+/**
+ * Rspack-specific export.
+ *
+ * Usage:
+ *   import { harnessFE } from '@harness-fe/unplugin/rspack'
+ */
+
+import { unplugin } from './core.js';
+export type { HarnessFEOptions } from './core.js';
+
+export const harnessFE = unplugin.rspack;
+export default harnessFE;

package/src/transform.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest';
+import { transformJsx } from './transform.js';
+
+describe('transformJsx', () => {
+    it('tags JSX inside a function component with data-morphix-comp + data-morphix-loc', () => {
+        const src = `
+export function SubmitButton() {
+    return <button>Submit</button>;
+}
+`;
+        const map = new Map();
+        const out = transformJsx(src, 'src/Submit.tsx', map);
+        expect(out).not.toBeNull();
+        expect(out!.code).toContain('data-morphix-comp="SubmitButton"');
+        expect(out!.code).toMatch(/data-morphix-loc="src\/Submit\.tsx:\d+:\d+"/);
+        expect(map.get('SubmitButton')).toBeDefined();
+        expect(map.get('SubmitButton')!.length).toBeGreaterThan(0);
+    });
+
+    it('tags arrow-function component assigned to PascalCase variable', () => {
+        const src = `
+const Card = () => <div>hello</div>;
+`;
+        const map = new Map();
+        const out = transformJsx(src, 'src/Card.tsx', map);
+        expect(out!.code).toContain('data-morphix-comp="Card"');
+        expect(map.get('Card')).toBeDefined();
+    });
+
+    it('only adds data-morphix-loc on JSX outside any component (e.g. helper)', () => {
+        const src = `
+function helper() {
+    return <span>x</span>;
+}
+`;
+        const map = new Map();
+        const out = transformJsx(src, 'src/h.tsx', map);
+        // JSX is tagged with loc but not with comp (helper is lowercase).
+        expect(out!.code).toContain('data-morphix-loc=');
+        expect(out!.code).not.toContain('data-morphix-comp=');
+        expect(map.size).toBe(0);
+    });
+
+    it('returns null for files without JSX', () => {
+        const src = `export const x = 1;\n`;
+        const map = new Map();
+        const out = transformJsx(src, 'src/a.tsx', map);
+        expect(out).toBeNull();
+    });
+
+    it('preserves existing data-morphix-comp if author already wrote one', () => {
+        const src = `
+export function Foo() {
+    return <button data-morphix-comp="OverrideName">x</button>;
+}
+`;
+        const map = new Map();
+        const out = transformJsx(src, 'src/Foo.tsx', map);
+        // Did not add a duplicate.
+        const matches = out!.code.match(/data-morphix-comp/g) ?? [];
+        expect(matches).toHaveLength(1);
+        expect(out!.code).toContain('data-morphix-comp="OverrideName"');
+        // Both the enclosing component and the hand-written tag land in the map.
+        expect(map.get('Foo')).toBeDefined();
+        expect(map.get('OverrideName')).toBeDefined();
+        expect(map.get('OverrideName')![0].file).toBe('src/Foo.tsx');
+    });
+
+    it('collects hand-written data-morphix-comp tags inside an enclosing component', () => {
+        const src = `
+export function App() {
+    return (
+        <main>
+            <button data-morphix-comp="IncrementBtn">+</button>
+            <input data-morphix-comp="EchoInput" />
+            <p data-morphix-comp="EchoDisplay">x</p>
+        </main>
+    );
+}
+`;
+        const map = new Map();
+        const out = transformJsx(src, 'src/App.tsx', map);
+        expect(out).not.toBeNull();
+        expect(map.get('App')).toBeDefined();
+        expect(map.get('IncrementBtn')).toBeDefined();
+        expect(map.get('EchoInput')).toBeDefined();
+        expect(map.get('EchoDisplay')).toBeDefined();
+    });
+});

package/src/transform.ts

@@ -0,0 +1,188 @@
+/**
+ * JSX transform: parse a .tsx / .jsx file and inject:
+ *   - `data-morphix-loc="<relPath>:<line>:<col>"` on every JSX opening element
+ *   - `data-morphix-comp="<ComponentName>"` on JSX opening elements that are
+ *     enclosed (transitively) by a top-level component definition. The
+ *     component name comes from the nearest enclosing function/class/variable
+ *     declaration whose name starts with an uppercase letter (PascalCase).
+ *
+ * Output is the original source with the attribute strings spliced in via
+ * MagicString — keeps source maps intact and avoids re-generating the file.
+ *
+ * Side effect: every successfully scanned file contributes entries to the
+ * supplied `componentMap`: name → list of locations (file:line:col).
+ */
+
+import { parse } from '@babel/parser';
+import traverseDefault from '@babel/traverse';
+import type { NodePath } from '@babel/traverse';
+import * as t from '@babel/types';
+import MagicString from 'magic-string';
+
+// @babel/traverse exposes its default as `default` only when published as ESM
+// in older versions; later versions also expose a named export. Pick whichever
+// is callable.
+const traverse: typeof traverseDefault =
+    typeof traverseDefault === 'function'
+        ? traverseDefault
+        : ((traverseDefault as unknown as { default: typeof traverseDefault }).default ?? traverseDefault);
+
+export interface ComponentLocation {
+    file: string;
+    line: number;
+    col: number;
+}
+
+export type ComponentMap = Map<string, ComponentLocation[]>;
+
+export interface TransformResult {
+    code: string;
+    map?: object;
+    /** Number of JSX elements that got attributes. */
+    taggedCount: number;
+}
+
+const ATTR_COMP = 'data-morphix-comp';
+const ATTR_LOC = 'data-morphix-loc';
+
+const PASCAL_CASE = /^[A-Z][A-Za-z0-9]*$/;
+
+export function transformJsx(
+    source: string,
+    relPath: string,
+    componentMap: ComponentMap,
+): TransformResult | null {
+    let ast;
+    try {
+        ast = parse(source, {
+            sourceType: 'module',
+            plugins: ['jsx', 'typescript'],
+            errorRecovery: true,
+        });
+    } catch {
+        return null;
+    }
+
+    const magic = new MagicString(source);
+    let taggedCount = 0;
+
+    traverse(ast, {
+        JSXOpeningElement(path: NodePath<t.JSXOpeningElement>) {
+            const node = path.node;
+            const start = node.start;
+            if (start == null) return;
+            // Position attribute insertion right after the tag name token.
+            const name = node.name;
+            const nameEnd = name.end;
+            if (nameEnd == null) return;
+
+            const loc = node.loc?.start;
+            if (!loc) return;
+            const locValue = `${relPath}:${loc.line}:${loc.column}`;
+            const enclosingName = findEnclosingComponentName(path);
+            const explicitName = getStringAttribute(node, ATTR_COMP);
+
+            const attrs: string[] = [];
+            if (!hasAttribute(node, ATTR_LOC)) {
+                attrs.push(`${ATTR_LOC}="${escapeAttr(locValue)}"`);
+            }
+            if (!hasAttribute(node, ATTR_COMP) && enclosingName) {
+                attrs.push(`${ATTR_COMP}="${escapeAttr(enclosingName)}"`);
+            }
+
+            // Register every name that ends up on this element into the map —
+            // both enclosing component (so e.g. App resolves) and any
+            // hand-written tag (so IncrementBtn / EchoInput resolve too).
+            const names = new Set<string>();
+            if (enclosingName) names.add(enclosingName);
+            if (explicitName) names.add(explicitName);
+            for (const name of names) {
+                const entries = componentMap.get(name) ?? [];
+                entries.push({ file: relPath, line: loc.line, col: loc.column });
+                componentMap.set(name, entries);
+            }
+
+            if (!attrs.length) return;
+            // Insert: <Foo ATTRS … >
+            magic.appendLeft(nameEnd, ' ' + attrs.join(' '));
+            taggedCount++;
+        },
+    });
+
+    if (taggedCount === 0) return null;
+
+    return {
+        code: magic.toString(),
+        map: magic.generateMap({ hires: true, source: relPath, includeContent: true }),
+        taggedCount,
+    };
+}
+
+function getStringAttribute(node: t.JSXOpeningElement, name: string): string | undefined {
+    for (const attr of node.attributes) {
+        if (
+            attr.type === 'JSXAttribute' &&
+            attr.name.type === 'JSXIdentifier' &&
+            attr.name.name === name &&
+            attr.value &&
+            attr.value.type === 'StringLiteral'
+        ) {
+            return attr.value.value;
+        }
+    }
+    return undefined;
+}
+
+function hasAttribute(node: t.JSXOpeningElement, name: string): boolean {
+    for (const attr of node.attributes) {
+        if (
+            attr.type === 'JSXAttribute' &&
+            attr.name.type === 'JSXIdentifier' &&
+            attr.name.name === name
+        ) {
+            return true;
+        }
+    }
+    return false;
+}
+
+function findEnclosingComponentName(path: NodePath<t.JSXOpeningElement>): string | undefined {
+    let current: NodePath | null = path.parentPath;
+    while (current) {
+        const node = current.node;
+        // function Foo() { return <jsx/> }
+        if (t.isFunctionDeclaration(node) && node.id && PASCAL_CASE.test(node.id.name)) {
+            return node.id.name;
+        }
+        // const Foo = (...) => <jsx/>
+        // const Foo = function (...) { return <jsx/> }
+        if (
+            (t.isArrowFunctionExpression(node) || t.isFunctionExpression(node)) &&
+            current.parentPath &&
+            t.isVariableDeclarator(current.parentPath.node) &&
+            t.isIdentifier(current.parentPath.node.id) &&
+            PASCAL_CASE.test(current.parentPath.node.id.name)
+        ) {
+            return current.parentPath.node.id.name;
+        }
+        // class Foo extends Component { render() { return <jsx/> } }
+        if (t.isClassDeclaration(node) && node.id && PASCAL_CASE.test(node.id.name)) {
+            return node.id.name;
+        }
+        // export default function Foo() ...
+        if (
+            t.isExportDefaultDeclaration(node) &&
+            t.isFunctionDeclaration(node.declaration) &&
+            node.declaration.id &&
+            PASCAL_CASE.test(node.declaration.id.name)
+        ) {
+            return node.declaration.id.name;
+        }
+        current = current.parentPath;
+    }
+    return undefined;
+}
+
+function escapeAttr(value: string): string {
+    return value.replace(/"/g, '&quot;');
+}

package/src/vite.ts

@@ -0,0 +1,13 @@
+/**
+ * Vite-specific export.
+ *
+ * Usage:
+ *   import { harnessFE } from '@harness-fe/unplugin/vite'
+ *   export default defineConfig({ plugins: [harnessFE()] })
+ */
+
+import { unplugin } from './core.js';
+export type { HarnessFEOptions } from './core.js';
+
+export const harnessFE = unplugin.vite;
+export default harnessFE;