@upstart.gg/vite-plugins 0.0.37

package/src/vite-plugin-upstart-attrs.ts

@@ -0,0 +1,708 @@
+import { createUnplugin } from "unplugin";
+import { parseSync } from "oxc-parser";
+import { walk } from "zimmerframe";
+import MagicString from "magic-string";
+import path from "path";
+import type {
+  Program,
+  Node,
+  JSXElement,
+  JSXOpeningElement,
+  JSXAttribute,
+  Expression,
+  MemberExpression,
+  CallExpression,
+} from "estree-jsx";
+
+interface Options {
+  enabled: boolean;
+  emitRegistry?: boolean;
+}
+
+type NodeWithRange = Node & { start: number; end: number };
+
+function hasRange(node: any): node is NodeWithRange {
+  return node && typeof node.start === "number" && typeof node.end === "number";
+}
+
+// Fast, stable hash function (djb2 variant)
+// Produces a short hex string that's stable across rebuilds
+function hashContent(content: string): string {
+  let hash = 5381;
+  for (let i = 0; i < content.length; i++) {
+    hash = ((hash << 5) + hash) ^ content.charCodeAt(i);
+  }
+  // Convert to unsigned 32-bit and then to hex
+  return (hash >>> 0).toString(16);
+}
+
+interface LoopContext {
+  itemName: string;
+  indexName: string | null;
+  arrayExpr: string;
+}
+
+
+interface I18nKeyInfo {
+  /** The resolved key with namespace, e.g. "dashboard:features.title" */
+  fullKey: string;
+  /** Just the translation key, e.g. "features.title" */
+  key: string;
+  /** The namespace, e.g. "dashboard" */
+  namespace: string;
+}
+
+// Registry entry for editable elements (text and className)
+export interface EditableEntry {
+  file: string;
+  type: "text" | "className";
+  startOffset: number;
+  endOffset: number;
+  originalContent: string;
+  context: { parentTag: string };
+}
+
+// Module-level registry (collected across all files during build)
+const editableRegistry = new Map<string, EditableEntry>();
+
+// Generate stable ID for editable elements
+// Replace the counter-based ID generation with position-based
+function generateId(filePath: string, node: NodeWithRange): string {
+  // Use file path + start position for a stable, deterministic ID
+  return `${filePath}:${node.start}`;
+}
+
+// Export for testing - get a copy of the current registry
+export function getRegistry(): Record<string, EditableEntry> {
+  return Object.fromEntries(editableRegistry);
+}
+
+// Export for testing - clear registry and counters
+export function clearRegistry(): void {
+  editableRegistry.clear();
+}
+
+interface TransformState {
+  filePath: string;
+  code: string;
+  s: MagicString;
+  loopStack: LoopContext[];
+}
+
+export const upstartEditor = createUnplugin<Options>((options) => {
+  if (!options.enabled) {
+    return { name: "upstart-editor-disabled" };
+  }
+
+  const emitRegistry = options.emitRegistry ?? true;
+  let root = process.cwd();
+
+  return {
+    name: "upstart-editor",
+    enforce: "pre",
+
+    vite: {
+      configResolved(config) {
+        root = config.root;
+      },
+      generateBundle() {
+        if (!emitRegistry || editableRegistry.size === 0) {
+          return;
+        }
+
+        const registry = {
+          version: 1,
+          generatedAt: new Date().toISOString(),
+          elements: Object.fromEntries(editableRegistry),
+        };
+
+        this.emitFile({
+          type: "asset",
+          fileName: "upstart-registry.json",
+          source: JSON.stringify(registry, null, 2),
+        });
+
+        // Clear for next build
+        editableRegistry.clear();
+      },
+    },
+
+    transformInclude(id) {
+      return /\.(tsx|jsx)$/.test(id) && !id.includes("node_modules");
+    },
+
+    transform(code, id) {
+      // Fast path: skip files without JSX
+      if (!code.includes("<")) {
+        return null;
+      }
+
+      try {
+        const relativePath = path.relative(root, id);
+        const result = transformWithOxc(code, relativePath);
+
+        if (!result) {
+          return null;
+        }
+
+        return {
+          code: result.code,
+          map: result.map,
+        };
+      } catch (error) {
+        console.error(`Error transforming ${id}:`, error);
+        return null;
+      }
+    },
+  };
+});
+
+export function transformWithOxc(code: string, filePath: string) {
+  // Parse with oxc (super fast!)
+  const ast = parseSync(filePath, code, {
+    sourceType: "module",
+  });
+
+  if (!ast.program) {
+    return null;
+  }
+
+  const s = new MagicString(code);
+  const state: TransformState = {
+    filePath,
+    code,
+    s,
+    loopStack: [],
+  };
+
+  let modified = false;
+
+  // Use zimmerframe to walk and transform the AST
+  walk(ast.program as Program, state, {
+    _(node: Node, { state, next }: { state: TransformState; next: () => void }) {
+      // ENFORCE: Throw error if useTranslation is used for translations (destructuring `t`)
+      if (node.type === "VariableDeclaration") {
+        checkForbiddenUseTranslation(node, state.filePath);
+      }
+
+      // Handle .map() calls to track loops (must be before JSXElement)
+      if (node.type === "CallExpression") {
+        const loopInfo = detectMapCall(node as CallExpression, state.code);
+
+        if (loopInfo) {
+          // Push loop context
+          state.loopStack.push(loopInfo);
+
+          // Continue walking into the callback
+          next();
+
+          // Pop loop context after traversing
+          state.loopStack.pop();
+          return;
+        }
+      }
+
+      // Handle JSX elements
+      if (node.type === "JSXElement") {
+        const jsxNode = node as JSXElement;
+        const opening = jsxNode.openingElement;
+        const tagName = getJSXElementName(opening);
+        const insertPos = getAttributeInsertPosition(opening, state.code);
+
+        // Track attributes to inject
+        const attributes: string[] = [];
+
+        // Compute stable hash from the element's source code (includes all children)
+        // This hash changes if ANY part of the element or its children change
+        if (hasRange(jsxNode)) {
+          const elementSource = state.code.slice(jsxNode.start, jsxNode.end);
+          const hash = hashContent(elementSource);
+          attributes.push(`data-upstart-hash="${hash}"`);
+        }
+
+        // Check for text leaf elements (any element with only static text)
+        if (isTextLeafElement(jsxNode)) {
+          attributes.push('data-upstart-editable-text="true"');
+
+          // Find the actual JSXText node to track its location
+          const textChild = jsxNode.children.find((c) => c.type === "JSXText" && (c as any).value?.trim());
+
+          if (textChild && hasRange(textChild)) {
+            const id = generateId(state.filePath, textChild);
+            const textValue = (textChild as any).value as string;
+
+            // Calculate trimmed offsets (exclude leading/trailing whitespace)
+            const trimmedStart = textChild.start + (textValue.length - textValue.trimStart().length);
+            const trimmedEnd = textChild.end - (textValue.length - textValue.trimEnd().length);
+
+            editableRegistry.set(id, {
+              file: state.filePath,
+              type: "text",
+              startOffset: trimmedStart,
+              endOffset: trimmedEnd,
+              originalContent: textValue.trim(),
+              context: { parentTag: tagName || "unknown" },
+            });
+
+            attributes.push(`data-upstart-id="${id}"`);
+          }
+        }
+
+        // Check if this element IS a <Trans> component - add i18n tracking attributes
+        const transInfo = detectTransComponent(jsxNode, state.code);
+        if (transInfo) {
+          attributes.push('data-upstart-editable-text="true"');
+          attributes.push(`data-i18n-key="${escapeProp(transInfo.fullKey)}"`);
+        }
+
+        // Track className attribute if it's a string literal
+        const classNameAttr = opening.attributes.find(
+          (attr): attr is JSXAttribute =>
+            attr.type === "JSXAttribute" &&
+            attr.name.type === "JSXIdentifier" &&
+            attr.name.name === "className" &&
+            attr.value?.type === "Literal" &&
+            typeof (attr.value as any).value === "string",
+        );
+
+        if (classNameAttr && classNameAttr.value && hasRange(classNameAttr.value)) {
+          const id = generateId(state.filePath, classNameAttr.value);
+          const classValue = (classNameAttr.value as any).value as string;
+
+          // +1 and -1 to exclude the quotes
+          editableRegistry.set(id, {
+            file: state.filePath,
+            type: "className",
+            startOffset: classNameAttr.value.start + 1,
+            endOffset: classNameAttr.value.end - 1,
+            originalContent: classValue,
+            context: { parentTag: tagName || "unknown" },
+          });
+
+          attributes.push(`data-upstart-classname-id="${id}"`);
+        }
+
+        // Process PascalCase components for additional tracking
+        if (tagName && /^[A-Z]/.test(tagName)) {
+          // File and component tracking
+          attributes.push(`data-upstart-file="${escapeProp(state.filePath)}"`);
+          attributes.push(`data-upstart-component="${escapeProp(tagName)}"`);
+
+          // Loop context tracking
+          if (state.loopStack.length > 0) {
+            const loop = state.loopStack[state.loopStack.length - 1];
+            attributes.push(`data-upstart-loop-item="${escapeProp(loop.itemName)}"`);
+            if (loop.indexName) {
+              attributes.push(`data-upstart-loop-index={${loop.indexName.toLowerCase()}}`);
+            }
+            attributes.push(`data-upstart-loop-array="${escapeProp(loop.arrayExpr)}"`);
+          }
+
+          // Analyze each prop for data bindings
+          for (const attr of opening.attributes) {
+            if (attr.type !== "JSXAttribute" || attr.name.type !== "JSXIdentifier") {
+              continue;
+            }
+
+            const propName = attr.name.name;
+            const binding = analyzeBinding(attr.value, state.code);
+
+            if (binding) {
+              attributes.push(`data-upstart-prop-${propName.toLowerCase()}="${escapeProp(binding.path)}"`);
+
+              if (binding.datasource) {
+                attributes.push(
+                  `data-upstart-datasource-${propName.toLowerCase()}="${escapeProp(binding.datasource)}"`,
+                );
+              }
+
+              if (binding.recordId) {
+                attributes.push(`data-upstart-record-id-${propName.toLowerCase()}={${binding.recordId}}`);
+              }
+
+              // Track conditional expressions
+              if (binding.isConditional) {
+                attributes.push(`data-upstart-conditional-${propName.toLowerCase()}="true"`);
+              }
+            }
+          }
+        }
+
+        // Inject attributes if any
+        if (insertPos !== -1 && attributes.length > 0) {
+          const attrString = " " + attributes.join(" ");
+          state.s.appendLeft(insertPos, attrString);
+          modified = true;
+        }
+      }
+
+      next();
+    },
+  });
+
+  if (!modified) {
+    return null;
+  }
+
+  return {
+    code: s.toString(),
+    map: s.generateMap({ hires: true }),
+  };
+}
+
+// Helper: Get JSX element name
+function getJSXElementName(opening: JSXOpeningElement): string | null {
+  if (opening.name.type === "JSXIdentifier") {
+    return opening.name.name;
+  }
+
+  // Handle JSXMemberExpression like <Foo.Bar>
+  if (opening.name.type === "JSXMemberExpression") {
+    let current = opening.name;
+    while (current.property) {
+      if (current.property.type === "JSXIdentifier") {
+        return current.property.name;
+      }
+      if (current.type === "JSXMemberExpression") {
+        current = current.property as any;
+      } else {
+        break;
+      }
+    }
+  }
+
+  return null;
+}
+
+// Helper: Find where to insert attributes in JSX opening tag
+function getAttributeInsertPosition(opening: JSXOpeningElement, code: string): number {
+  // If there are existing attributes, insert before the first one
+  if (opening.attributes.length > 0) {
+    const firstAttr = opening.attributes[0];
+    if (hasRange(firstAttr)) {
+      return firstAttr.start;
+    }
+  }
+
+  // Otherwise, insert after the tag name
+  if (opening.name.type === "JSXIdentifier" && hasRange(opening.name)) {
+    return opening.name.end;
+  }
+
+  if (opening.name.type === "JSXMemberExpression" && hasRange(opening.name)) {
+    return opening.name.end;
+  }
+
+  return -1;
+}
+
+// Helper: Analyze a prop value to extract data binding
+function analyzeBinding(
+  value: JSXAttribute["value"],
+  code: string,
+): {
+  path: string;
+  datasource?: string;
+  recordId?: string;
+  isConditional?: boolean;
+} | null {
+  if (!value) {
+    return null;
+  }
+
+  if (value.type === "JSXExpressionContainer") {
+    const expr = value.expression;
+
+    if (expr.type === "JSXEmptyExpression") {
+      return null;
+    }
+
+    return analyzeExpression(expr, code);
+  }
+
+  return null;
+}
+
+// Helper: Analyze any expression to extract binding info
+function analyzeExpression(
+  expr: Expression,
+  code: string,
+): {
+  path: string;
+  datasource?: string;
+  recordId?: string;
+  isConditional?: boolean;
+} | null {
+  // Handle member expressions: user.name, product.price, etc.
+  if (expr.type === "MemberExpression") {
+    const path = exprToString(expr, code);
+    const datasource = extractDatasource(expr);
+    const recordId = extractRecordId(expr);
+
+    return { path, datasource, recordId };
+  }
+
+  // Handle identifiers: userName, price, etc.
+  if (expr.type === "Identifier") {
+    return { path: expr.name };
+  }
+
+  // Handle conditional expressions: condition ? value1 : value2
+  if (expr.type === "ConditionalExpression") {
+    // Try to extract from the consequent
+    const consequent = analyzeExpression(expr.consequent, code);
+    if (consequent) {
+      return {
+        ...consequent,
+        isConditional: true,
+        path: exprToString(expr, code),
+      };
+    }
+  }
+
+  // Handle logical expressions: value1 && value2, value1 || value2
+  if (expr.type === "LogicalExpression") {
+    const right = analyzeExpression(expr.right, code);
+    if (right) {
+      return {
+        ...right,
+        isConditional: true,
+        path: exprToString(expr, code),
+      };
+    }
+  }
+
+  // For other complex expressions, just return the path
+  const exprWithRange = expr as any;
+  if (exprWithRange.start !== undefined && exprWithRange.end !== undefined) {
+    return {
+      path: code.slice(exprWithRange.start, exprWithRange.end),
+    };
+  }
+
+  return null;
+}
+
+// Helper: Convert expression AST to string
+function exprToString(expr: Expression, code: string): string {
+  // Use the source range to get the actual code
+  const exprWithRange = expr as any;
+  if (exprWithRange.start !== undefined && exprWithRange.end !== undefined) {
+    return code.slice(exprWithRange.start, exprWithRange.end);
+  }
+
+  // Fallback: reconstruct from AST
+  if (expr.type === "Identifier") {
+    return expr.name;
+  }
+
+  if (expr.type === "MemberExpression") {
+    const obj = exprToString(expr.object as Expression, code);
+    const prop =
+      expr.property.type === "Identifier" && !expr.computed
+        ? expr.property.name
+        : exprToString(expr.property as Expression, code);
+    return expr.computed ? `${obj}[${prop}]` : `${obj}.${prop}`;
+  }
+
+  if (expr.type === "ConditionalExpression") {
+    const test = exprToString(expr.test, code);
+    const consequent = exprToString(expr.consequent, code);
+    const alternate = exprToString(expr.alternate, code);
+    return `${test} ? ${consequent} : ${alternate}`;
+  }
+
+  if (expr.type === "LogicalExpression") {
+    const left = exprToString(expr.left, code);
+    const right = exprToString(expr.right, code);
+    return `${left} ${expr.operator} ${right}`;
+  }
+
+  return "";
+}
+
+// Helper: Extract datasource name from member expression
+function extractDatasource(expr: MemberExpression): string | undefined {
+  let current: Expression = expr.object as Expression;
+
+  // Traverse to the root object
+  while (current.type === "MemberExpression") {
+    current = current.object as Expression;
+  }
+
+  if (current.type === "Identifier") {
+    return current.name;
+  }
+
+  return undefined;
+}
+
+// Helper: Extract record ID reference
+function extractRecordId(expr: MemberExpression): string | undefined {
+  const obj = expr.object;
+
+  if (obj.type === "Identifier") {
+    // Assume the ID field is `${object}.id`
+    return `${obj.name}.id`;
+  }
+
+  if (obj.type === "MemberExpression") {
+    // For nested objects like user.profile.id
+    const datasource = extractDatasource(obj);
+    if (datasource) {
+      return `${datasource}.id`;
+    }
+  }
+
+  return undefined;
+}
+
+// Helper: Detect .map() calls and extract loop context
+function detectMapCall(node: CallExpression, code: string): LoopContext | null {
+  // Check if this is a .map() call
+  if (
+    node.callee.type !== "MemberExpression" ||
+    node.callee.property.type !== "Identifier" ||
+    node.callee.property.name !== "map"
+  ) {
+    return null;
+  }
+
+  const callback = node.arguments[0];
+
+  if (!callback) {
+    return null;
+  }
+
+  // Check if callback is an arrow function or function expression
+  if (callback.type !== "ArrowFunctionExpression" && callback.type !== "FunctionExpression") {
+    return null;
+  }
+
+  const params = callback.params;
+  const itemParam = params[0];
+  const indexParam = params[1];
+
+  if (!itemParam) {
+    return null;
+  }
+
+  // Extract parameter names
+  const itemName = itemParam.type === "Identifier" ? itemParam.name : "item";
+  const indexName = indexParam?.type === "Identifier" ? indexParam.name : null;
+
+  // Get the array expression
+  const arrayExpr = exprToString(node.callee.object as Expression, code);
+
+  return {
+    itemName,
+    indexName,
+    arrayExpr,
+  };
+}
+
+// Helper: Escape prop values for JSX attributes
+function escapeProp(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+// Helper: ENFORCE forbidden useTranslation usage - throw error if `t` is destructured
+// Only `{ i18n }` is allowed (for language switching), not `{ t }` (use <Trans> instead)
+function checkForbiddenUseTranslation(node: Node, filePath: string): void {
+  if (node.type !== "VariableDeclaration") return;
+
+  const decl = node as any;
+  for (const declarator of decl.declarations) {
+    if (
+      declarator.id?.type !== "ObjectPattern" ||
+      !declarator.init ||
+      declarator.init.type !== "CallExpression"
+    ) {
+      continue;
+    }
+
+    const callExpr = declarator.init;
+    if (callExpr.callee?.type !== "Identifier" || callExpr.callee.name !== "useTranslation") {
+      continue;
+    }
+
+    // Check if `t` is being destructured (forbidden)
+    for (const prop of declarator.id.properties) {
+      if (prop.type !== "Property") continue;
+
+      if (prop.key?.type === "Identifier" && prop.key.name === "t") {
+        throw new Error(
+          `[${filePath}] useTranslation hook is forbidden for translations. ` +
+            `Use <Trans i18nKey="..." /> component instead. ` +
+            `Only { i18n } destructuring is allowed (for language switching).`,
+        );
+      }
+    }
+  }
+}
+
+// Helper: Detect <Trans i18nKey="..." /> component and extract i18n key info
+function detectTransComponent(jsxElement: JSXElement, code: string): I18nKeyInfo | null {
+  const opening = jsxElement.openingElement;
+  const tagName = getJSXElementName(opening);
+
+  if (tagName !== "Trans") return null;
+
+  let i18nKey: string | null = null;
+  let namespace = "translation";
+
+  for (const attr of opening.attributes) {
+    if (attr.type !== "JSXAttribute" || attr.name.type !== "JSXIdentifier") continue;
+
+    const attrName = attr.name.name;
+
+    // Extract i18nKey prop value
+    if (attrName === "i18nKey" && attr.value?.type === "Literal") {
+      i18nKey = (attr.value as any).value as string;
+    }
+
+    // Extract ns prop value (optional namespace override)
+    if (attrName === "ns" && attr.value?.type === "Literal") {
+      namespace = (attr.value as any).value as string;
+    }
+  }
+
+  if (!i18nKey) return null;
+
+  return {
+    fullKey: `${namespace}:${i18nKey}`,
+    key: i18nKey,
+    namespace,
+  };
+}
+
+// Helper: Check if element is a "leaf" with only static text (no nested elements or expressions)
+function isTextLeafElement(jsxElement: JSXElement): boolean {
+  let hasText = false;
+
+  for (const child of jsxElement.children) {
+    if (child.type === "JSXText") {
+      const textValue = (child as any).value;
+      if (textValue?.trim()) {
+        hasText = true;
+      }
+    } else if (
+      child.type === "JSXElement" ||
+      child.type === "JSXFragment" ||
+      child.type === "JSXExpressionContainer" ||
+      child.type === "JSXSpreadChild"
+    ) {
+      // Has non-text children, not a leaf element
+      return false;
+    }
+  }
+
+  return hasText;
+}
+
+export default upstartEditor.vite;