@lithent/hmr-parser 0.1.0

package/dist/markerParse.d.ts

@@ -0,0 +1,2 @@
+import { MarkerTransformOptions, HmrTransformResult } from './types';
+export declare const transformWithMarker: (options: MarkerTransformOptions) => HmrTransformResult;

package/dist/noMarkerParse.d.ts

@@ -0,0 +1,2 @@
+import { BaseTransformOptions, HmrTransformResult } from './types';
+export declare const transformWithoutMarker: (options: BaseTransformOptions) => HmrTransformResult;

package/dist/shared.d.ts

@@ -0,0 +1,4 @@
+import { MarkerTransformOptions, BaseTransformOptions, MarkerAnalysisResult, BaseAnalysisResult } from './types';
+export declare const analyzeMarker: (options: MarkerTransformOptions) => MarkerAnalysisResult;
+export declare const analyzeNoMarker: (options: BaseTransformOptions) => BaseAnalysisResult;
+export declare const shouldSkipTransform: (code: string) => boolean;

package/dist/strings.d.ts

@@ -0,0 +1 @@
+export declare const createHmrBootstrapBlock: (targetExports: string[], componentNames: string[]) => string;

package/dist/tests/mark.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/nomark.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/transform/componentRegister.d.ts

@@ -0,0 +1,3 @@
+import { default as MagicString } from 'magic-string';
+import { MountInfo } from '../utils/ast/componentCollector';
+export declare const stitchComponentRegistration: (ms: MagicString, mounts: MountInfo[], code: string, importInsertionPos: number) => void;

package/dist/transform/renderGuard.d.ts

@@ -0,0 +1,3 @@
+import { default as MagicString } from 'magic-string';
+import { File } from '@babel/types';
+export declare const wrapRenderCalls: (ms: MagicString, ast: File, code: string) => boolean;

package/dist/types.d.ts

@@ -0,0 +1,28 @@
+import { default as MagicString } from 'magic-string';
+import { 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/dist/utils/ast/componentCollector.d.ts

@@ -0,0 +1,8 @@
+import { File } from '@babel/types';
+export type MountInfo = {
+    insertPos: number;
+    propsExpression: string;
+    componentName: string | null;
+    declarationEnd: number;
+};
+export declare const collectComponentMounts: (ast: File, code: string) => MountInfo[];

package/package.json

@@ -0,0 +1,52 @@
+{
+  "type": "module",
+  "name": "@lithent/hmr-parser",
+  "version": "0.1.0",
+  "description": "Lithent HMR parser utilities for build tools",
+  "packageManager": "pnpm@9.12.3",
+  "main": "./dist/lithentHmrParser.umd.js",
+  "module": "./dist/lithentHmrParser.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/lithentHmrParser.mjs",
+      "require": "./dist/lithentHmrParser.umd.js"
+    }
+  },
+  "scripts": {
+    "build": "vite build",
+    "watch": "vite build --watch",
+    "test": "vitest run --reporter verbose",
+    "test:dev": "vitest"
+  },
+  "author": "superlucky84",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/superlucky84/lithent.git"
+  },
+  "homepage": "https://github.com/superlucky84/lithent",
+  "license": "MIT",
+  "keywords": ["lithent", "hmr", "parser"],
+  "dependencies": {
+    "@babel/parser": "^7.26.2",
+    "@babel/types": "^7.26.0",
+    "magic-string": "^0.30.11"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "devDependencies": {
+    "lithent": "workspace:*",
+    "@types/babel__traverse": "^7.20.6",
+    "vite": "^5.4.8",
+    "vite-plugin-checker": "^0.8.0",
+    "vite-plugin-dts": "^4.2.1",
+    "vitest": "^2.1.5"
+  },
+  "volta": {
+    "node": "20.3.0",
+    "pnpm": "9.12.3"
+  }
+}

package/src/helper/calculator.ts

@@ -0,0 +1,169 @@
+import type {
+  File,
+  ImportDeclaration,
+  ExpressionStatement,
+} from '@babel/types';
+
+export const collectExportNames = (ast: File): string[] => {
+  const names = new Set<string>();
+
+  for (const node of ast.program.body) {
+    if (node.type === 'ExportDefaultDeclaration') {
+      names.add('default');
+    }
+
+    if (node.type === 'ExportNamedDeclaration') {
+      const { declaration, specifiers } = node;
+
+      if (declaration) {
+        if (declaration.type === 'FunctionDeclaration' && declaration.id) {
+          names.add(declaration.id.name);
+        } else if (
+          declaration.type === 'VariableDeclaration' &&
+          declaration.declarations.length
+        ) {
+          for (const declarator of declaration.declarations) {
+            if (declarator.id.type === 'Identifier') {
+              names.add(declarator.id.name);
+            }
+          }
+        } else if (declaration.type === 'ClassDeclaration' && declaration.id) {
+          names.add(declaration.id.name);
+        }
+      }
+
+      if (specifiers?.length) {
+        specifiers.forEach(specifier => {
+          if (
+            specifier.type === 'ExportSpecifier' &&
+            specifier.exported.type === 'Identifier'
+          ) {
+            names.add(specifier.exported.name);
+          }
+        });
+      }
+    }
+  }
+
+  return Array.from(names);
+};
+
+export const detectLithentUsage = (ast: File): boolean => {
+  const watchedNames = new Set(['render', 'mount', 'createApp', 'createRoot']);
+
+  for (const node of ast.program.body) {
+    if (node.type !== 'ImportDeclaration') continue;
+    const source = node.source.value;
+    if (typeof source !== 'string') continue;
+
+    if (source === 'lithent') {
+      const hasWatched = node.specifiers.some(specifier => {
+        if (
+          specifier.type === 'ImportSpecifier' &&
+          specifier.imported.type === 'Identifier'
+        ) {
+          const importedName = specifier.imported.name;
+          return watchedNames.has(importedName);
+        }
+        return false;
+      });
+
+      if (hasWatched) return true;
+    }
+
+    if (source.startsWith('lithent/')) {
+      if ((node as ImportDeclaration).importKind === 'type') {
+        continue;
+      }
+      return true;
+    }
+  }
+
+  return false;
+};
+
+export const collectHeaderInsert = (
+  ast: File,
+  sourceCode: string,
+  boundaryImportSpecifier: string,
+  tagFunctionImportSpecifier: string
+) => {
+  const importsToPrepend: string[] = [];
+  let hasBoundaryImport = false;
+  let hasTagImport = false;
+  let lastImportEnd = 0;
+  let directiveEnd = 0;
+  let firstImportStart: number | null = null;
+
+  for (const node of ast.program.body) {
+    if (node.type === 'ImportDeclaration') {
+      lastImportEnd = node.end ?? lastImportEnd;
+      if (firstImportStart == null) {
+        firstImportStart = node.start ?? null;
+      }
+
+      if (node.source.value === boundaryImportSpecifier) {
+        hasBoundaryImport = true;
+      }
+
+      if (node.source.value === tagFunctionImportSpecifier) {
+        const hasTag = node.specifiers.some(specifier => {
+          return (
+            specifier.type === 'ImportSpecifier' &&
+            specifier.imported.type === 'Identifier' &&
+            specifier.imported.name === 'TagFunction'
+          );
+        });
+
+        if (hasTag) {
+          hasTagImport = true;
+        }
+      }
+
+      continue;
+    }
+
+    if (
+      node.type === 'ExpressionStatement' &&
+      node.expression.type === 'StringLiteral'
+    ) {
+      const expressionStatement = node as ExpressionStatement & {
+        directive?: string;
+      };
+      if (typeof expressionStatement.directive === 'string') {
+        directiveEnd = expressionStatement.end ?? directiveEnd;
+        continue;
+      }
+    }
+
+    break;
+  }
+
+  if (!hasBoundaryImport) {
+    importsToPrepend.push(
+      `import { createBoundary } from '${boundaryImportSpecifier}';`
+    );
+  }
+
+  if (!hasTagImport) {
+    importsToPrepend.push(
+      `import type { TagFunction } from '${tagFunctionImportSpecifier}';`
+    );
+  }
+
+  const importInsertionPos = firstImportStart ?? directiveEnd ?? 0;
+  const blockInsertionPos = lastImportEnd || directiveEnd || 0;
+
+  let snippet = '';
+  if (importsToPrepend.length) {
+    const precedingChar =
+      importInsertionPos > 0 ? sourceCode[importInsertionPos - 1] : undefined;
+    const needsLeadingNewline =
+      importInsertionPos > 0 && precedingChar !== '\n';
+    snippet += needsLeadingNewline ? '\n' : '';
+    snippet += importsToPrepend.join('\n');
+    snippet += '\n';
+  }
+
+  return { importInsertionPos, blockInsertionPos, headerSnippet: snippet };
+};

package/src/index.ts

@@ -0,0 +1,33 @@
+import { transformWithMarker } from './markerParse';
+import { transformWithoutMarker } from './noMarkerParse';
+import { analyzeMarker, analyzeNoMarker, shouldSkipTransform } from './shared';
+import type {
+  MarkerTransformOptions,
+  BaseTransformOptions,
+  HmrTransformResult,
+} from './types';
+
+export const transformWithHmr = (
+  options: MarkerTransformOptions
+): HmrTransformResult => {
+  const markerResult = transformWithMarker(options);
+  if (markerResult.transformed) {
+    return markerResult;
+  }
+
+  const baseOptions: BaseTransformOptions = {
+    code: options.code,
+    boundaryImportSpecifier: options.boundaryImportSpecifier,
+    tagFunctionImportSpecifier: options.tagFunctionImportSpecifier,
+  };
+
+  return transformWithoutMarker(baseOptions);
+};
+
+export { analyzeMarker, analyzeNoMarker, shouldSkipTransform };
+export { transformWithMarker, transformWithoutMarker };
+export type {
+  MarkerTransformOptions,
+  BaseTransformOptions,
+  HmrTransformResult,
+} from './types';

package/src/markerParse.ts

@@ -0,0 +1,61 @@
+import MagicString from 'magic-string';
+import { createHmrBootstrapBlock } from './strings';
+import type { MarkerTransformOptions, HmrTransformResult } from './types';
+import { analyzeMarker } from './shared';
+import { stitchComponentRegistration } from './transform/componentRegister';
+import { wrapRenderCalls } from './transform/renderGuard';
+import { collectComponentMounts } from './utils/ast/componentCollector';
+
+export const transformWithMarker = (
+  options: MarkerTransformOptions
+): HmrTransformResult => {
+  const analysis = analyzeMarker(options);
+  const {
+    match,
+    targetExports,
+    shouldTransform,
+    importInsertionPos,
+    headerSnippet,
+  } = analysis;
+
+  if (!shouldTransform || !match) {
+    return { transformed: false, code: options.code, map: null };
+  }
+
+  const mounts = collectComponentMounts(analysis.ast, options.code);
+  const componentNames = Array.from(
+    new Set(
+      mounts
+        .map(mount => mount.componentName)
+        .filter((name): name is string => !!name)
+    )
+  );
+
+  const ms = new MagicString(options.code);
+  wrapRenderCalls(ms, analysis.ast, options.code);
+  const transformBlock = createHmrBootstrapBlock(
+    targetExports,
+    componentNames
+  ).trimStart();
+
+  if (headerSnippet) {
+    ms.appendLeft(importInsertionPos, headerSnippet);
+  }
+
+  const precedingChar =
+    match.index > 0 ? options.code[match.index - 1] : undefined;
+  const needsLeadingNewline = match.index > 0 && precedingChar !== '\n';
+  const followingChar = options.code[match.index + match[0].length] ?? null;
+  const trailingNewline = followingChar === '\n' ? '\n' : '\n\n';
+  const blockSnippet = `${needsLeadingNewline ? '\n' : ''}${transformBlock}${trailingNewline}`;
+
+  ms.overwrite(match.index, match.index + match[0].length, blockSnippet);
+
+  stitchComponentRegistration(ms, mounts, options.code, importInsertionPos);
+
+  return {
+    transformed: true,
+    code: ms.toString(),
+    map: ms.generateMap({ hires: true }),
+  };
+};

package/src/noMarkerParse.ts

@@ -0,0 +1,70 @@
+import MagicString from 'magic-string';
+import { createHmrBootstrapBlock } from './strings';
+import type { BaseTransformOptions, HmrTransformResult } from './types';
+import { analyzeNoMarker } from './shared';
+import { stitchComponentRegistration } from './transform/componentRegister';
+import { wrapRenderCalls } from './transform/renderGuard';
+import { collectComponentMounts } from './utils/ast/componentCollector';
+
+export const transformWithoutMarker = (
+  options: BaseTransformOptions
+): HmrTransformResult => {
+  const analysis = analyzeNoMarker(options);
+  const {
+    targetExports,
+    shouldTransform,
+    importInsertionPos,
+    blockInsertionPos,
+    headerSnippet,
+    ast,
+  } = analysis;
+
+  if (!shouldTransform) {
+    return { transformed: false, code: options.code, map: null };
+  }
+
+  const mounts = collectComponentMounts(ast, options.code);
+  const componentNames = Array.from(
+    new Set(
+      mounts
+        .map(mount => mount.componentName)
+        .filter((name): name is string => !!name)
+    )
+  );
+
+  const ms = new MagicString(options.code);
+  wrapRenderCalls(ms, ast, options.code);
+  const transformBlock = createHmrBootstrapBlock(
+    targetExports,
+    componentNames
+  ).trimStart();
+
+  const blockPrecedingChar =
+    blockInsertionPos > 0 ? options.code[blockInsertionPos - 1] : undefined;
+  const needsLeadingNewlineForBlock =
+    blockInsertionPos > 0 && blockPrecedingChar !== '\n';
+  const blockSnippet = `${needsLeadingNewlineForBlock ? '\n' : ''}${transformBlock}\n\n`;
+
+  if (!headerSnippet && !blockSnippet.trim().length) {
+    return { transformed: false, code: options.code, map: null };
+  }
+
+  if (headerSnippet) {
+    if (blockInsertionPos === importInsertionPos) {
+      ms.appendLeft(importInsertionPos, `${headerSnippet}${blockSnippet}`);
+    } else {
+      ms.appendLeft(importInsertionPos, headerSnippet);
+      ms.appendLeft(blockInsertionPos, blockSnippet);
+    }
+  } else {
+    ms.appendLeft(blockInsertionPos, blockSnippet);
+  }
+
+  stitchComponentRegistration(ms, mounts, options.code, importInsertionPos);
+
+  return {
+    transformed: true,
+    code: ms.toString(),
+    map: ms.generateMap({ hires: true }),
+  };
+};

package/src/shared.ts

@@ -0,0 +1,109 @@
+import { parse } from '@babel/parser';
+import type { File } from '@babel/types';
+import type {
+  MarkerTransformOptions,
+  BaseTransformOptions,
+  MarkerAnalysisResult,
+  BaseAnalysisResult,
+} from './types';
+import {
+  collectExportNames,
+  detectLithentUsage,
+  collectHeaderInsert,
+} from './helper/calculator';
+
+const analyzeBase = (
+  code: string,
+  boundaryImportSpecifier: string,
+  tagFunctionImportSpecifier: string
+) => {
+  const ast = parse(code, {
+    sourceType: 'module',
+    plugins: ['typescript', 'jsx'],
+    ranges: true,
+  }) as File;
+
+  const inferredExports = collectExportNames(ast);
+  const targetExports =
+    inferredExports.length > 0 ? inferredExports : ['default'];
+  const { importInsertionPos, blockInsertionPos, headerSnippet } =
+    collectHeaderInsert(
+      ast,
+      code,
+      boundaryImportSpecifier,
+      tagFunctionImportSpecifier
+    );
+
+  return {
+    ast,
+    targetExports,
+    importInsertionPos,
+    blockInsertionPos,
+    headerSnippet,
+  } as const;
+};
+
+export const analyzeMarker = (
+  options: MarkerTransformOptions
+): MarkerAnalysisResult => {
+  const {
+    code,
+    markerRegex,
+    boundaryImportSpecifier,
+    tagFunctionImportSpecifier,
+  } = options;
+
+  const {
+    ast,
+    targetExports,
+    importInsertionPos,
+    blockInsertionPos,
+    headerSnippet,
+  } = analyzeBase(code, boundaryImportSpecifier, tagFunctionImportSpecifier);
+
+  const match = markerRegex.exec(code);
+  const rawNames = match?.[1]
+    ? match[1]
+        .split(',')
+        .map(token => token.trim())
+        .filter(Boolean)
+    : [];
+
+  const finalTargets = rawNames.length ? rawNames : targetExports;
+
+  return {
+    targetExports: finalTargets,
+    shouldTransform: !!match || detectLithentUsage(ast),
+    importInsertionPos,
+    blockInsertionPos,
+    headerSnippet,
+    ast,
+    match: match ?? null,
+  };
+};
+
+export const analyzeNoMarker = (
+  options: BaseTransformOptions
+): BaseAnalysisResult => {
+  const { code, boundaryImportSpecifier, tagFunctionImportSpecifier } = options;
+
+  const {
+    ast,
+    targetExports,
+    importInsertionPos,
+    blockInsertionPos,
+    headerSnippet,
+  } = analyzeBase(code, boundaryImportSpecifier, tagFunctionImportSpecifier);
+
+  return {
+    targetExports,
+    shouldTransform: detectLithentUsage(ast),
+    importInsertionPos,
+    blockInsertionPos,
+    headerSnippet,
+    ast,
+  };
+};
+
+export const shouldSkipTransform = (code: string): boolean =>
+  code.includes('__lithentModuleId');