@lithent/hmr-parser 0.1.0

package/src/strings.ts

@@ -0,0 +1,176 @@
+export const createHmrBootstrapBlock = (
+  targetExports: string[],
+  componentNames: string[]
+) => {
+  const normalizedTargets = new Set(
+    componentNames.length ? componentNames : targetExports
+  );
+
+  const serializedTargets = JSON.stringify(Array.from(normalizedTargets));
+
+  return `
+const __lithentModuleId = new URL(import.meta.url).pathname;
+const __lithentBoundaryStoreKey = \`__lithent_hmr_boundary__\${__lithentModuleId}\`;
+const __lithentDisposeStoreKey = \`__lithent_hmr_dispose__\${__lithentModuleId}\`;
+const __lithentGlobalStore =
+  typeof globalThis === 'object'
+    ? (globalThis as Record<string, unknown>)
+    : undefined;
+
+const __lithentEnsureHotData = (): Record<string, unknown> | undefined => {
+  const hot =
+    (import.meta.hot as
+      | {
+          data?: Record<string, unknown>;
+          __lithentData?: Record<string, unknown>;
+        }
+      | undefined) ?? undefined;
+  if (!hot) return undefined;
+
+  const existing = hot.data;
+  if (existing && typeof existing === 'object') {
+    return existing;
+  }
+
+  try {
+    const target: Record<string, unknown> = {};
+    hot.data = target;
+    return target;
+  } catch {
+    hot.__lithentData = hot.__lithentData || {};
+    return hot.__lithentData;
+  }
+};
+
+const __lithentHotData = __lithentEnsureHotData();
+type __LithentBoundaryController = ReturnType<typeof createBoundary>;
+
+const counterBoundary: __LithentBoundaryController =
+  (__lithentHotData?.counterBoundary as __LithentBoundaryController | undefined) ||
+  (__lithentGlobalStore?.[__lithentBoundaryStoreKey] as __LithentBoundaryController | undefined) ||
+  createBoundary(__lithentModuleId);
+
+if (__lithentHotData) {
+  __lithentHotData.counterBoundary = counterBoundary;
+}
+
+if (__lithentGlobalStore) {
+  __lithentGlobalStore[__lithentBoundaryStoreKey] = counterBoundary;
+}
+
+let disposeApp =
+  (__lithentHotData?.disposeApp as (() => void) | undefined) ||
+  (__lithentGlobalStore?.[__lithentDisposeStoreKey] as (() => void) | undefined);
+
+const __lithentRenderOnce = <T,>(factory: () => T) => {
+  if (disposeApp) {
+    return disposeApp as unknown as T;
+  }
+
+  const result = factory();
+
+  if (typeof result === 'function') {
+    disposeApp = result as unknown as () => void;
+
+    if (__lithentHotData) {
+      __lithentHotData.disposeApp = disposeApp;
+    }
+
+    if (__lithentGlobalStore && disposeApp) {
+      __lithentGlobalStore[__lithentDisposeStoreKey] = disposeApp;
+    }
+  }
+
+  return result;
+};
+
+const __lithentModuleHotStore =
+  __lithentHotData
+    ? ((__lithentHotData.components =
+        (__lithentHotData.components as Record<
+          string,
+          TagFunction | undefined
+        > | undefined) ?? {}) as Record<string, TagFunction | undefined>)
+    : undefined;
+
+const __lithentHmrTargets = ${serializedTargets};
+
+const __lithentSetupHmrHooks = () => {
+  if (!import.meta.hot) {
+    return;
+  }
+
+  import.meta.hot.accept(mod => {
+    let applied = false;
+    const nextModule = (mod ?? {}) as Record<string, unknown>;
+    const missing: string[] = [];
+    const knownNames = new Set([
+      ...${JSON.stringify(Array.from(new Set(componentNames)))},
+      ...__lithentHmrTargets,
+    ]);
+
+    for (const name of knownNames) {
+      const nextCtor =
+        name === 'default'
+          ? (nextModule.default as TagFunction | undefined)
+          : (nextModule[name] as TagFunction | undefined) ||
+            (__lithentModuleHotStore?.[name] as TagFunction | undefined);
+
+      if (!nextCtor) {
+        missing.push(name);
+        continue;
+      }
+
+      if (counterBoundary.update(nextCtor)) {
+        applied = true;
+      }
+    }
+
+    if (!applied) {
+      if (missing.length && __lithentModuleHotStore) {
+        queueMicrotask(() => {
+          let retried = false;
+          for (const name of missing) {
+            const retryCtor = __lithentModuleHotStore?.[name] as
+              | TagFunction
+              | undefined;
+            if (retryCtor && counterBoundary.update(retryCtor)) {
+              retried = true;
+            }
+          }
+          if (!retried) {
+            console.warn(
+              '[Lithent HMR] 변경된 경계를 적용하지 못해 전체 리프레시합니다.'
+            );
+            import.meta.hot?.invalidate?.();
+          }
+        });
+        return;
+      }
+      console.warn(
+        '[Lithent HMR] 변경된 경계를 적용하지 못해 전체 리프레시합니다.'
+      );
+      import.meta.hot?.invalidate?.();
+    }
+  });
+
+  import.meta.hot.dispose(data => {
+    data.counterBoundary = counterBoundary;
+
+    if (disposeApp) {
+      data.disposeApp = disposeApp;
+    }
+
+    if (__lithentGlobalStore) {
+      __lithentGlobalStore[__lithentBoundaryStoreKey] = counterBoundary;
+
+      if (disposeApp) {
+        __lithentGlobalStore[__lithentDisposeStoreKey] = disposeApp;
+      }
+    }
+  });
+};
+
+__lithentSetupHmrHooks();
+`;
+};

package/src/tests/mark.test.ts

@@ -0,0 +1,162 @@
+import { transformWithMarker } from '../markerParse';
+
+const createDefaultMarkerRegex = () =>
+  new RegExp(
+    '/\\*\\s*lithent:hmr-boundary(?:\\s+([A-Za-z0-9_,\\s]+))?\\s*\\*/'
+  );
+
+const markerSourceDefault = `
+'use client';
+import { render, mount } from 'lithent';
+
+/* lithent:hmr-boundary default */
+
+const App = mount((renew, props: { title: string }) => {
+  return () => <div>{props.title}</div>;
+});
+
+const Secondary = mount((renew, props: { subtitle: string }) => {
+  return () => <p>{props.subtitle}</p>;
+});
+
+export default App;
+`;
+
+const markerSourceNamed = `
+"use client";
+import type { TagFunction } from 'lithent';
+import { createBoundary } from 'lithent/devHelper';
+import { render, mount } from 'lithent';
+
+/* lithent:hmr-boundary Counter, Another */
+
+export const Counter = mount((renew, props) => {
+  return () => <span>{props.value}</span>;
+});
+
+export const Another = mount((renew, props) => {
+  return () => <span>{props.value}</span>;
+});
+`;
+
+const defaultResult = transformWithMarker({
+  code: markerSourceDefault,
+  markerRegex: createDefaultMarkerRegex(),
+  boundaryImportSpecifier: 'lithent/devHelper',
+  tagFunctionImportSpecifier: 'lithent',
+});
+
+const namedResult = transformWithMarker({
+  code: markerSourceNamed,
+  markerRegex: createDefaultMarkerRegex(),
+  boundaryImportSpecifier: 'lithent/devHelper',
+  tagFunctionImportSpecifier: 'lithent',
+});
+
+console.log('[marker] transformed default:', defaultResult.transformed);
+console.log('[marker] transformed named:', namedResult.transformed);
+console.log('[marker] code default:', defaultResult.code);
+console.log('[marker] code named:', namedResult.code);
+
+if (!import.meta.vitest) {
+  const defaultPre = document?.getElementById('marker-default');
+  if (defaultPre) {
+    defaultPre.textContent = defaultResult.transformed
+      ? defaultResult.code
+      : 'transform skipped';
+  }
+
+  const namedPre = document?.getElementById('marker-named');
+  if (namedPre) {
+    namedPre.textContent = namedResult.transformed
+      ? namedResult.code
+      : 'transform skipped';
+  }
+}
+
+if (import.meta.vitest) {
+  const { describe, it, expect } = import.meta.vitest;
+
+  describe('transformWithMarker', () => {
+    it('replaces marker comment with HMR bootstrap and injects helpers', () => {
+      expect(defaultResult.transformed).toBe(true);
+      expect(defaultResult.code).not.toMatch(/lithent:hmr-boundary/);
+      expect(defaultResult.code).toContain(
+        "import { createBoundary } from 'lithent/devHelper';"
+      );
+      expect(defaultResult.code).toContain(
+        "import type { TagFunction } from 'lithent';"
+      );
+      expect(defaultResult.code).toContain('import.meta.hot as');
+      expect(defaultResult.code).toContain(
+        "import { mountCallback, getComponentKey } from 'lithent';"
+      );
+      expect(defaultResult.code).toContain(
+        'const __lithentModuleId = new URL(import.meta.url).pathname;'
+      );
+      expect(defaultResult.code).toContain(
+        'const __lithentHmrTargets = ["App","Secondary"];'
+      );
+      expect(defaultResult.code).toContain('const knownNames = new Set([');
+      expect(defaultResult.code).toContain('...["App","Secondary"]');
+      expect(defaultResult.code).toContain('...__lithentHmrTargets');
+      expect(defaultResult.code).toContain(
+        'const __lithentHotComponent_App = App as unknown as TagFunction;'
+      );
+      expect(defaultResult.code).toContain(
+        '__lithentModuleHotStore["App"] = __lithentHotComponent_App;'
+      );
+      expect(defaultResult.code).toContain(
+        'const __lithentHotComponent_Secondary = Secondary as unknown as TagFunction;'
+      );
+      expect(defaultResult.code).toContain(
+        '__lithentModuleHotStore["Secondary"] = __lithentHotComponent_Secondary;'
+      );
+      expect(defaultResult.code).toContain('const __lithentRenderOnce = <');
+      const registerMatches =
+        defaultResult.code.match(/counterBoundary\.register\(compKey\)/g) ?? [];
+      const unregisterMatches =
+        defaultResult.code.match(
+          /mountCallback\(\(\) => \(\) => unregister\(\)\)/g
+        ) ?? [];
+      expect(registerMatches).toHaveLength(2);
+      expect(unregisterMatches).toHaveLength(2);
+    });
+
+    it('respects explicit export names declared in the marker', () => {
+      expect(namedResult.transformed).toBe(true);
+      expect(
+        namedResult.code.match(
+          /import { createBoundary } from 'lithent\/devHelper';/g
+        )
+      ).toHaveLength(1);
+      expect(namedResult.code).toContain(
+        'const __lithentHmrTargets = ["Counter","Another"];'
+      );
+      expect(namedResult.code).toContain('import.meta.hot as');
+      expect(namedResult.code).toContain('const knownNames = new Set([');
+      expect(namedResult.code).toContain('...["Counter","Another"]');
+      expect(namedResult.code).toContain('...__lithentHmrTargets');
+      expect(namedResult.code).toContain(
+        'const __lithentHotComponent_Counter = Counter as unknown as TagFunction;'
+      );
+      expect(namedResult.code).toContain(
+        '__lithentModuleHotStore["Counter"] = __lithentHotComponent_Counter;'
+      );
+      expect(namedResult.code).toContain(
+        'const __lithentHotComponent_Another = Another as unknown as TagFunction;'
+      );
+      expect(namedResult.code).toContain(
+        '__lithentModuleHotStore["Another"] = __lithentHotComponent_Another;'
+      );
+      const namedRegisters =
+        namedResult.code.match(/counterBoundary\.register\(compKey\)/g) ?? [];
+      const namedUnregisters =
+        namedResult.code.match(
+          /mountCallback\(\(\) => \(\) => unregister\(\)\)/g
+        ) ?? [];
+      expect(namedRegisters).toHaveLength(2);
+      expect(namedUnregisters).toHaveLength(2);
+    });
+  });
+}

package/src/tests/nomark.test.tsx

@@ -0,0 +1,100 @@
+import { transformWithoutMarker } from '../noMarkerParse';
+
+const source = `
+'use client';
+import { render, mount } from 'lithent';
+
+const Demo = mount((_renew, props: { message: string }) => {
+  return () => ({ type: 'div', props: {}, children: [props.message] } as any);
+});
+
+const Another = mount((_renew, props: { id: number }) => {
+  return () => ({ type: 'span', props: {}, children: [String(props.id)] } as any);
+});
+
+const root = document.getElementById('app');
+if (root) {
+  render(Demo({ message: 'hello' }), root as any);
+  render(Another({ id: 1 }), root as any);
+}
+`;
+
+const result = transformWithoutMarker({
+  code: source,
+  boundaryImportSpecifier: 'lithent/devHelper',
+  tagFunctionImportSpecifier: 'lithent',
+});
+
+console.log('[no-marker] transformed:', result.transformed);
+console.log('[no-marker] code:', result.code);
+
+if (!import.meta.vitest) {
+  const pre = document?.getElementById('output');
+  if (pre) {
+    pre.textContent = result.transformed ? result.code : 'transform skipped';
+  }
+}
+
+if (import.meta.vitest) {
+  const { describe, it, expect } = import.meta.vitest;
+
+  describe('transformWithoutMarker (integration)', () => {
+    it('should mark transform as successful and inject HMR bootstrap + boundary registration', () => {
+      const expectedSnippet =
+        'const __lithentModuleId = new URL(import.meta.url).pathname;';
+
+      expect(result.transformed).toBe(true);
+      expect(result.code.includes(expectedSnippet)).toBe(true);
+      expect(
+        result.code.includes(
+          "import { createBoundary } from 'lithent/devHelper'"
+        )
+      ).toBe(true);
+      expect(
+        result.code.includes(
+          "import { mountCallback, getComponentKey } from 'lithent'"
+        )
+      ).toBe(true);
+      expect(result.code.includes('const compKey = getComponentKey();')).toBe(
+        true
+      );
+      expect(
+        result.code.includes('const __lithentHmrTargets = ["Demo","Another"];')
+      ).toBe(true);
+      expect(result.code.includes('const knownNames = new Set([')).toBe(true);
+      expect(result.code.includes('...["Demo","Another"]')).toBe(true);
+      expect(result.code.includes('...__lithentHmrTargets')).toBe(true);
+      expect(
+        result.code.includes(
+          'const __lithentHotComponent_Demo = Demo as unknown as TagFunction;'
+        )
+      ).toBe(true);
+      expect(
+        result.code.includes(
+          '__lithentModuleHotStore["Demo"] = __lithentHotComponent_Demo;'
+        )
+      ).toBe(true);
+      expect(
+        result.code.includes(
+          'const __lithentHotComponent_Another = Another as unknown as TagFunction;'
+        )
+      ).toBe(true);
+      expect(
+        result.code.includes(
+          '__lithentModuleHotStore["Another"] = __lithentHotComponent_Another;'
+        )
+      ).toBe(true);
+      expect(result.code.includes('const __lithentRenderOnce = <')).toBe(true);
+      expect(/__lithentRenderOnce\(\(\) =>\s*render\(/.test(result.code)).toBe(
+        true
+      );
+      const registerMatches =
+        result.code.match(/counterBoundary\.register\(compKey\)/g) ?? [];
+      const unregisterMatches =
+        result.code.match(/mountCallback\(\(\) => \(\) => unregister\(\)\)/g) ??
+        [];
+      expect(registerMatches).toHaveLength(2);
+      expect(unregisterMatches).toHaveLength(2);
+    });
+  });
+}

package/src/transform/componentRegister.ts

@@ -0,0 +1,50 @@
+import MagicString from 'magic-string';
+import type { MountInfo } from '../utils/ast/componentCollector';
+
+export const stitchComponentRegistration = (
+  ms: MagicString,
+  mounts: MountInfo[],
+  code: string,
+  importInsertionPos: number
+) => {
+  if (!mounts.length) return;
+
+  const needsMountCallback = !/import\s+{[^}]*mountCallback/.test(code);
+  const needsGetComponentKey = !/import\s+{[^}]*getComponentKey/.test(code);
+
+  if (needsMountCallback || needsGetComponentKey) {
+    const pieces: string[] = [];
+    if (needsMountCallback) {
+      pieces.push('mountCallback');
+    }
+    if (needsGetComponentKey) {
+      pieces.push('getComponentKey');
+    }
+
+    const joined = pieces.join(', ');
+    ms.appendLeft(importInsertionPos, `import { ${joined} } from 'lithent';\n`);
+  }
+
+  for (const mount of mounts) {
+    const { insertPos, componentName, declarationEnd } = mount;
+    const unregisterBlock = `
+    const compKey = getComponentKey();
+    const unregister = compKey ? counterBoundary.register(compKey) : null;
+    if (unregister) {
+      mountCallback(() => () => unregister());
+    }
+`;
+    ms.appendLeft(insertPos, unregisterBlock);
+
+    if (componentName) {
+      const hotStoreVar = `__lithentHotComponent_${componentName}`;
+      const storeSnippet = `
+const ${hotStoreVar} = ${componentName} as unknown as TagFunction;
+if (__lithentModuleHotStore) {
+  __lithentModuleHotStore["${componentName}"] = ${hotStoreVar};
+}
+`;
+      ms.appendRight(declarationEnd, storeSnippet);
+    }
+  }
+};

package/src/transform/renderGuard.ts

@@ -0,0 +1,59 @@
+import MagicString from 'magic-string';
+import type { File, Node, CallExpression } from '@babel/types';
+import { VISITOR_KEYS } from '@babel/types';
+
+const collectRenderCalls = (ast: Node, calls: CallExpression[]): void => {
+  const visit = (node: Node | null | undefined) => {
+    if (!node) return;
+
+    if (
+      node.type === 'CallExpression' &&
+      node.callee.type === 'Identifier' &&
+      node.callee.name === 'render'
+    ) {
+      calls.push(node as CallExpression);
+    }
+
+    const keys = VISITOR_KEYS[node.type] ?? [];
+    for (const key of keys) {
+      const value = (node as any)[key];
+      if (Array.isArray(value)) {
+        for (const child of value) {
+          if (child && typeof child.type === 'string') {
+            visit(child as Node);
+          }
+        }
+      } else if (value && typeof value.type === 'string') {
+        visit(value as Node);
+      }
+    }
+  };
+
+  visit(ast);
+};
+
+export const wrapRenderCalls = (
+  ms: MagicString,
+  ast: File,
+  code: string
+): boolean => {
+  const calls: CallExpression[] = [];
+  collectRenderCalls(ast, calls);
+
+  if (!calls.length) return false;
+
+  const sorted = calls
+    .map(node => ({
+      start: node.start ?? 0,
+      end: node.end ?? 0,
+    }))
+    .filter(({ start, end }) => start >= 0 && end > start)
+    .sort((a, b) => b.start - a.start);
+
+  for (const { start, end } of sorted) {
+    const original = code.slice(start, end);
+    ms.overwrite(start, end, `__lithentRenderOnce(() => ${original})`);
+  }
+
+  return true;
+};

package/src/types.ts

@@ -0,0 +1,33 @@
+import type MagicString from 'magic-string';
+import type { File } from '@babel/types';
+
+export interface BaseTransformOptions {
+  code: string;
+  boundaryImportSpecifier: string;
+  tagFunctionImportSpecifier: string;
+}
+
+export interface MarkerTransformOptions extends BaseTransformOptions {
+  markerRegex: RegExp;
+}
+
+export interface BaseAnalysisResult {
+  targetExports: string[];
+  shouldTransform: boolean;
+  importInsertionPos: number;
+  blockInsertionPos: number;
+  headerSnippet: string;
+  ast: File;
+}
+
+export interface MarkerAnalysisResult extends BaseAnalysisResult {
+  match: RegExpExecArray | null;
+}
+
+export interface HmrTransformOptions extends MarkerTransformOptions {}
+
+export interface HmrTransformResult {
+  transformed: boolean;
+  code: string;
+  map: ReturnType<MagicString['generateMap']> | null;
+}

package/src/utils/ast/componentCollector.ts

@@ -0,0 +1,119 @@
+import type {
+  File,
+  Node,
+  CallExpression,
+  Identifier,
+  ObjectPattern,
+  ArrayPattern,
+} from '@babel/types';
+
+export type MountInfo = {
+  insertPos: number;
+  propsExpression: string;
+  componentName: string | null;
+  declarationEnd: number;
+};
+
+const isMountCall = (node: Node): node is CallExpression =>
+  node.type === 'CallExpression' &&
+  node.callee.type === 'Identifier' &&
+  node.callee.name === 'mount';
+
+const sliceWithoutType = (
+  code: string,
+  node: Node & { typeAnnotation?: Node | null }
+): string => {
+  const start = node.start ?? 0;
+  const end = node.typeAnnotation?.start ?? node.end ?? 0;
+  return code.slice(start, end);
+};
+
+const extractPropsExpression = (
+  propsParam: Identifier | ObjectPattern | ArrayPattern | undefined,
+  code: string
+): string => {
+  if (!propsParam) {
+    return 'props';
+  }
+
+  switch (propsParam.type) {
+    case 'Identifier':
+      return propsParam.name;
+    case 'ObjectPattern':
+    case 'ArrayPattern':
+      return sliceWithoutType(code, propsParam);
+    default:
+      return 'props';
+  }
+};
+
+export const collectComponentMounts = (
+  ast: File,
+  code: string
+): MountInfo[] => {
+  const results: MountInfo[] = [];
+
+  const inspectDeclaration = (node: any) => {
+    if (node.type !== 'VariableDeclaration' || node.declarations.length !== 1) {
+      return;
+    }
+
+    const declaration = node.declarations[0];
+    if (
+      !declaration.init ||
+      !isMountCall(declaration.init) ||
+      declaration.init.arguments.length === 0
+    ) {
+      return;
+    }
+
+    const firstArg = declaration.init.arguments[0];
+    if (
+      firstArg.type !== 'ArrowFunctionExpression' ||
+      firstArg.body.type !== 'BlockStatement'
+    ) {
+      return;
+    }
+
+    const block = firstArg.body;
+    const propsParam = firstArg.params[1] as
+      | Identifier
+      | ObjectPattern
+      | ArrayPattern
+      | undefined;
+    const propsExpression = extractPropsExpression(propsParam, code);
+    const insertPos =
+      block.body.length > 0
+        ? (block.body[0].start ?? block.start ?? 0)
+        : (block.start ?? 0);
+    const componentName =
+      declaration.id && declaration.id.type === 'Identifier'
+        ? declaration.id.name
+        : null;
+    const declarationEnd = node.end ?? block.end ?? insertPos;
+
+    results.push({
+      insertPos,
+      propsExpression,
+      componentName,
+      declarationEnd,
+    });
+  };
+
+  for (const statement of ast.program.body) {
+    if (statement.type === 'VariableDeclaration') {
+      inspectDeclaration(statement);
+      continue;
+    }
+
+    if (
+      statement.type === 'ExportNamedDeclaration' &&
+      statement.declaration &&
+      statement.declaration.type === 'VariableDeclaration'
+    ) {
+      inspectDeclaration(statement.declaration);
+    }
+  }
+
+  return results;
+};