@yahoo/uds-create-loader 1.13.0 → 1.14.0

package/src/loader.ts

@@ -0,0 +1,209 @@
+import { parse } from '@babel/parser';
+import _traverse from '@babel/traverse';
+import type { LoaderDefinitionFunction } from 'webpack';
+import {
+  getLoaderProjection,
+  type LoaderOptions,
+  loadUdsConfig,
+} from './loader/artifacts';
+
+// Handle CJS/ESM interop for the babel CJS-shipped modules.
+// biome-ignore lint/suspicious/noExplicitAny: untyped babel CJS/ESM interop
+const traverse = (_traverse as any).default ?? _traverse;
+
+/**
+ * The UDS loader's only build-time job: rewrite alias-prefixed local
+ * imports of registered UDS components from `@/uds/components/<seg>`
+ * (the authoring file) to `'#uds/components/<seg>'` (the codegen-
+ * emitted per-source-file module at `.uds/components/<seg>.tsx`).
+ *
+ * The authoring file is read only by codegen — production renders the
+ * downleveled FC. Per-file targets keep Next.js Fast Refresh surgical:
+ * editing one authoring source only invalidates that one downleveled
+ * module.
+ *
+ * No JSX-site work: composite / variant / bool / style-prop resolution
+ * and motion wiring are owned by the codegen-emitted FC. The loader
+ * only changes import sources.
+ */
+const transformLoader: LoaderDefinitionFunction = function (source) {
+  const loaderContext =
+    (this as
+      | {
+          getOptions?: () => unknown;
+          addDependency?: (dep: string) => void;
+          resourcePath?: string;
+        }
+      | undefined) ?? undefined;
+  if (!loaderContext?.getOptions) return source;
+
+  const options = loaderContext.getOptions() as LoaderOptions;
+  const { dataPath, isDev, skipWatchDependencies } = options;
+  const resourcePath = loaderContext.resourcePath ?? '';
+
+  // Skip .uds/ generated files — they are codegen output and must
+  // not be re-transformed.
+  if (resourcePath.includes('.uds/')) {
+    return source;
+  }
+
+  // Tell webpack to watch generated uds artifacts for changes.
+  // Skipped when the host app has its own reload mechanism (Studio
+  // WebSocket) to avoid full-page reloads on artifact regeneration.
+  if (!skipWatchDependencies) {
+    loaderContext.addDependency?.(dataPath);
+  }
+
+  // Config is required — without it we don't know which JSX tags
+  // belong to UDS. Returning early keeps non-UDS files untouched.
+  const config = loadUdsConfig(dataPath, isDev);
+  if (!config) return source;
+  const projection = getLoaderProjection(config);
+
+  // Cheap pre-filter: only parse files that look like they import or
+  // reference a UDS component. Avoids babel overhead on the bulk of
+  // application files.
+  let hasComponentReference = false;
+  for (const name of projection.componentNames) {
+    if (source.includes(name)) {
+      hasComponentReference = true;
+      break;
+    }
+  }
+  if (!hasComponentReference) {
+    return source;
+  }
+
+  // Determine parser plugins from file extension.
+  const isTS = resourcePath?.endsWith('.ts') || resourcePath?.endsWith('.tsx');
+  const isJSX =
+    resourcePath?.endsWith('.tsx') || resourcePath?.endsWith('.jsx');
+  const parserPlugins: Array<'jsx' | 'typescript'> = [];
+  if (isJSX || !isTS) parserPlugins.push('jsx');
+  if (isTS) parserPlugins.push('typescript');
+
+  let ast: ReturnType<typeof parse>;
+  try {
+    ast = parse(source, {
+      sourceType: 'module',
+      plugins: parserPlugins,
+    });
+  } catch {
+    return source;
+  }
+
+  // Collected source-literal rewrites, keyed by character offset.
+  // We splice these into the original `source` string rather than
+  // regenerating the file: the loader's only job is to swap import
+  // source strings, and re-printing the whole file through
+  // @babel/generator (esp. with `retainLines`) can mangle dense JSX
+  // into invalid output. Surgical splicing keeps every byte outside
+  // the rewritten literals identical, so the loader can never turn a
+  // valid file into a broken one.
+  const edits: Array<{ start: number; end: number; value: string }> = [];
+
+  traverse(ast, {
+    // -----------------------------------------------------------------------
+    // Import rewrite: alias-prefixed local imports of registered UDS
+    // components → `#uds/components/<seg>` (the per-source-file
+    // codegen-emitted module).
+    // -----------------------------------------------------------------------
+    // biome-ignore lint/suspicious/noExplicitAny: untyped babel traverse visitor
+    ImportDeclaration(nodePath: any) {
+      const importSource: string | undefined = nodePath.node.source?.value;
+      if (!importSource) return;
+
+      // Only rewrite alias-prefixed local imports (e.g.
+      // `@/uds/components/<name>`, `~/uds/components/<name>`).
+      // Relative imports (`./text`, `../box`) belong to the authoring
+      // chain where each `defineComponent(...)` may reference its
+      // siblings (`defineComponent(Text).config(...)`) — rewriting those
+      // would break codegen's read of the configs.
+      const isAliasedLocalImport =
+        !importSource.startsWith('.') && !importSource.startsWith('/');
+      if (!isAliasedLocalImport) return;
+
+      // First-pass match: any specifier name matches a registered
+      // component. The common case — `import { Box } from
+      // '@/uds/components/box'`.
+      let shouldRewriteSource = false;
+      for (const specifier of nodePath.node.specifiers) {
+        if (specifier.type !== 'ImportSpecifier') continue;
+        const importedName: string | undefined =
+          specifier.imported?.type === 'Identifier'
+            ? specifier.imported.name
+            : undefined;
+        if (!importedName) continue;
+
+        if (projection.componentNames.has(importedName)) {
+          shouldRewriteSource = true;
+        }
+      }
+
+      // Second-pass match: the import path points at the authoring
+      // file of a registered component (e.g. `@/uds/components/sidebar`)
+      // but the visible specifiers are co-located helpers like
+      // `SidebarProvider` / `useSidebar`. If we let this resolve to the
+      // source file, the helper sets up a different `SidebarContext`
+      // than the codegen-emitted `Sidebar` reads — provider and consumer
+      // end up with different context identities and `useSidebar()`
+      // throws. Funnel every export from that file through the codegen
+      // module so helper AND component share the same module.
+      //
+      // Constrain to `*/uds/components/<name>` paths so unrelated
+      // imports whose tail happens to match a registered name
+      // (`next/image` → `Image`) don't get rewritten.
+      const segmentMatch = importSource.match(/\/uds\/components\/([^/]+)$/);
+      if (!shouldRewriteSource && segmentMatch) {
+        const tail = segmentMatch[1];
+        const pascal = tail
+          .split('-')
+          .filter(Boolean)
+          .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
+          .join('');
+        if (projection.componentNames.has(pascal)) {
+          shouldRewriteSource = true;
+        }
+      }
+
+      if (shouldRewriteSource && segmentMatch) {
+        // Per-file rewrite: keep the trailing `<seg>` so each import
+        // resolves to its own downleveled module at
+        // `.uds/components/<seg>.tsx`. Splice over the literal's
+        // character range (quotes included) using the original quote
+        // char so the rest of the file is untouched.
+        const sourceNode = nodePath.node.source;
+        if (
+          typeof sourceNode.start !== 'number' ||
+          typeof sourceNode.end !== 'number'
+        ) {
+          return;
+        }
+
+        const quote = source[sourceNode.start] ?? "'";
+        edits.push({
+          start: sourceNode.start,
+          end: sourceNode.end,
+          value: `${quote}#uds/components/${segmentMatch[1]}${quote}`,
+        });
+      }
+    },
+  });
+
+  if (edits.length === 0) return source;
+
+  // Apply edits from the end of the file backwards so earlier offsets
+  // stay valid as we splice.
+  edits.sort((a, b) => b.start - a.start);
+
+  let output = source;
+  for (const edit of edits) {
+    output = output.slice(0, edit.start) + edit.value + output.slice(edit.end);
+  }
+
+  return output;
+};
+
+// webpack loader-runner treats ESM loaders as valid when `normal` is exported.
+export const normal = transformLoader;
+export default transformLoader;

package/src/next.ts

@@ -0,0 +1,118 @@
+import path from 'node:path';
+import type { NextConfig } from 'next';
+
+export interface WithUdsOptions {
+  /** Output directory for generated files (default: '.uds') */
+  outputDir?: string;
+  /** Skip addDependency calls to prevent webpack from watching .uds/ artifacts.
+   *  Use this when the app has its own reload mechanism (e.g., Studio WebSocket). */
+  skipWatchDependencies?: boolean;
+}
+
+function resolveLoaderPath(): string {
+  return require.resolve('@yahoo/uds-create-loader/loader');
+}
+
+type NextConfigFn = (
+  phase: string,
+  ctx: { defaultConfig: NextConfig },
+) => NextConfig | Promise<NextConfig>;
+
+function applyUds(
+  nextConfig: NextConfig,
+  options?: WithUdsOptions,
+): NextConfig {
+  const outputDir = options?.outputDir ?? '.uds';
+  const skipWatch = options?.skipWatchDependencies ?? false;
+  const dataPath = path.resolve(process.cwd(), outputDir, 'config.json');
+  const loaderPath = resolveLoaderPath();
+  const turbopack = nextConfig.turbopack ?? {};
+  const existingRules = turbopack.rules ?? {};
+
+  const udsLoader = {
+    loader: loaderPath,
+    options: {
+      dataPath,
+      isDev: true,
+      skipWatchDependencies: skipWatch,
+    },
+  };
+
+  // Build turbopack rules that coexist with other plugins (e.g., Workflow
+  // DevKit). Other plugins may attach a `condition` to their rule entries
+  // which would incorrectly gate the UDS loader too. To avoid this, we
+  // keep existing rules intact and add the UDS loader as a separate
+  // unconditional rule under a distinct key (`**/*.ext`).
+  const udsRules: typeof existingRules = {};
+  for (const ext of ['tsx', 'ts', 'js'] as const) {
+    const key = `*.${ext}`;
+    const udsKey = `**/*.${ext}`;
+    // If another plugin already owns *.ext, use **/*.ext for UDS
+    if (existingRules[key]) {
+      udsRules[udsKey] = { loaders: [udsLoader] };
+    } else {
+      udsRules[key] = { loaders: [udsLoader] };
+    }
+  }
+
+  return {
+    ...nextConfig,
+    turbopack: {
+      ...turbopack,
+      rules: {
+        ...existingRules,
+        ...udsRules,
+      },
+    },
+    webpack(config, webpackOptions) {
+      config.module?.rules?.push({
+        test: /\.(tsx|ts|js)$/,
+        use: [
+          {
+            loader: loaderPath,
+            options: {
+              dataPath,
+              isDev: webpackOptions.dev,
+              skipWatchDependencies: skipWatch,
+            },
+          },
+        ],
+      });
+
+      if (skipWatch) {
+        const existing = config.watchOptions?.ignored;
+        config.watchOptions = {
+          ...config.watchOptions,
+          ignored: [
+            ...(Array.isArray(existing)
+              ? existing
+              : existing
+                ? [existing]
+                : []),
+            '**/.uds/**',
+            '**/uds.config.ts',
+          ],
+        };
+      }
+
+      if (typeof nextConfig.webpack === 'function') {
+        return nextConfig.webpack(config, webpackOptions);
+      }
+
+      return config;
+    },
+  };
+}
+
+export function withUds(
+  nextConfigOrFn: NextConfig | NextConfigFn,
+  options?: WithUdsOptions,
+): NextConfig | NextConfigFn {
+  if (typeof nextConfigOrFn === 'function') {
+    return async (phase, ctx) => {
+      const resolved = await nextConfigOrFn(phase, ctx);
+      return applyUds(resolved, options);
+    };
+  }
+  return applyUds(nextConfigOrFn, options);
+}

package/src/transform-runner.ts

@@ -0,0 +1,354 @@
+import path from 'node:path';
+import { gzipSync } from 'node:zlib';
+import { parse as parseBabel } from '@babel/parser';
+import * as t from '@babel/types';
+import { VISITOR_KEYS } from '@babel/types';
+import type { SerializedConfig } from '@yahoo/uds-create-config';
+import transformLoader from './loader';
+import { seedUdsConfig } from './loader/artifacts';
+import { isCompiledJsxCallee } from './loader/babel-utils';
+
+export interface LoaderTransformOutputSpecs {
+  outputGzipBytes: number;
+  classNameAssignments: number;
+  utilityClassTokens: number;
+  uniqueUtilityClassTokens: number;
+  runtimeStyleParserCalls: number;
+}
+
+interface LoaderTransformSuccess {
+  output: string;
+  specs: LoaderTransformOutputSpecs;
+}
+
+interface LoaderTransformFailure {
+  error: string;
+}
+
+export type LoaderTransformResult =
+  | LoaderTransformSuccess
+  | LoaderTransformFailure;
+
+export interface RunLoaderTransformOptions {
+  config: SerializedConfig;
+  resourcePath?: string;
+  isDev?: boolean;
+}
+
+function getClassTokens(value: string): string[] {
+  return value
+    .split(/\s+/)
+    .map((token) => token.trim())
+    .filter(Boolean);
+}
+
+function collectClassTokensFromNode(
+  node: t.Node | null | undefined,
+  tokens: string[],
+): void {
+  if (!node) {
+    return;
+  }
+
+  if (t.isStringLiteral(node)) {
+    tokens.push(...getClassTokens(node.value));
+    return;
+  }
+
+  if (t.isTemplateLiteral(node)) {
+    for (const quasi of node.quasis) {
+      tokens.push(
+        ...getClassTokens(quasi.value.cooked ?? quasi.value.raw ?? ''),
+      );
+    }
+    for (const expression of node.expressions) {
+      collectClassTokensFromNode(expression, tokens);
+    }
+    return;
+  }
+
+  if (t.isJSXExpressionContainer(node)) {
+    if (!t.isJSXEmptyExpression(node.expression)) {
+      collectClassTokensFromNode(node.expression, tokens);
+    }
+    return;
+  }
+
+  if (
+    t.isParenthesizedExpression(node) ||
+    t.isTSAsExpression(node) ||
+    t.isTSTypeAssertion(node) ||
+    t.isTSNonNullExpression(node)
+  ) {
+    collectClassTokensFromNode(node.expression, tokens);
+    return;
+  }
+
+  if (t.isUnaryExpression(node) || t.isUpdateExpression(node)) {
+    collectClassTokensFromNode(node.argument, tokens);
+    return;
+  }
+
+  if (
+    t.isBinaryExpression(node) ||
+    t.isLogicalExpression(node) ||
+    t.isAssignmentExpression(node)
+  ) {
+    collectClassTokensFromNode(node.left, tokens);
+    collectClassTokensFromNode(node.right, tokens);
+    return;
+  }
+
+  if (t.isConditionalExpression(node)) {
+    collectClassTokensFromNode(node.test, tokens);
+    collectClassTokensFromNode(node.consequent, tokens);
+    collectClassTokensFromNode(node.alternate, tokens);
+    return;
+  }
+
+  if (t.isSequenceExpression(node)) {
+    for (const expression of node.expressions) {
+      collectClassTokensFromNode(expression, tokens);
+    }
+    return;
+  }
+
+  if (t.isArrayExpression(node)) {
+    for (const element of node.elements) {
+      if (!element) {
+        continue;
+      }
+      if (t.isSpreadElement(element)) {
+        collectClassTokensFromNode(element.argument, tokens);
+        continue;
+      }
+      collectClassTokensFromNode(element, tokens);
+    }
+    return;
+  }
+
+  if (t.isObjectExpression(node)) {
+    for (const property of node.properties) {
+      if (t.isSpreadElement(property)) {
+        collectClassTokensFromNode(property.argument, tokens);
+        continue;
+      }
+      if (t.isObjectProperty(property)) {
+        collectClassTokensFromNode(property.value, tokens);
+      }
+    }
+    return;
+  }
+
+  if (t.isCallExpression(node) || t.isOptionalCallExpression(node)) {
+    collectClassTokensFromNode(node.callee, tokens);
+    for (const argument of node.arguments) {
+      if (t.isSpreadElement(argument)) {
+        collectClassTokensFromNode(argument.argument, tokens);
+        continue;
+      }
+      collectClassTokensFromNode(argument, tokens);
+    }
+    return;
+  }
+
+  if (t.isMemberExpression(node) || t.isOptionalMemberExpression(node)) {
+    collectClassTokensFromNode(node.object, tokens);
+    if (node.computed) {
+      collectClassTokensFromNode(node.property, tokens);
+    }
+    return;
+  }
+
+  if (t.isNewExpression(node)) {
+    collectClassTokensFromNode(node.callee, tokens);
+    for (const argument of node.arguments ?? []) {
+      if (t.isSpreadElement(argument)) {
+        collectClassTokensFromNode(argument.argument, tokens);
+        continue;
+      }
+      collectClassTokensFromNode(argument, tokens);
+    }
+  }
+}
+
+function isClassNameObjectProperty(node: t.ObjectProperty): boolean {
+  if (node.computed) {
+    return false;
+  }
+  return (
+    (t.isIdentifier(node.key) && node.key.name === 'className') ||
+    (t.isStringLiteral(node.key) && node.key.value === 'className')
+  );
+}
+
+function isBabelNode(value: unknown): value is t.Node {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'type' in (value as Record<string, unknown>)
+  );
+}
+
+function isClassNamePropOnCompiledJsxCall(
+  node: t.ObjectProperty,
+  parent: t.Node | null,
+  grandParent: t.Node | null,
+): boolean {
+  if (!isClassNameObjectProperty(node)) {
+    return false;
+  }
+  if (!parent || !t.isObjectExpression(parent)) {
+    return false;
+  }
+  if (!grandParent || !t.isCallExpression(grandParent)) {
+    return false;
+  }
+  if (!isCompiledJsxCallee(grandParent.callee)) {
+    return false;
+  }
+  return grandParent.arguments.some((argument) => argument === parent);
+}
+
+function getClassTokenStats(output: string): {
+  total: number;
+  unique: number;
+  assignments: number;
+} {
+  try {
+    const ast = parseBabel(output, {
+      sourceType: 'module',
+      plugins: ['jsx', 'typescript'],
+    });
+
+    const uniqueTokens = new Set<string>();
+    let total = 0;
+    let assignments = 0;
+
+    const addTokens = (node: t.Node | null | undefined) => {
+      const nextTokens: string[] = [];
+      collectClassTokensFromNode(node, nextTokens);
+      total += nextTokens.length;
+      for (const token of nextTokens) {
+        uniqueTokens.add(token);
+      }
+    };
+
+    const visit = (
+      node: t.Node | null | undefined,
+      parent: t.Node | null,
+      grandParent: t.Node | null,
+    ) => {
+      if (!node) {
+        return;
+      }
+
+      if (
+        t.isJSXAttribute(node) &&
+        t.isJSXIdentifier(node.name) &&
+        node.name.name === 'className'
+      ) {
+        assignments += 1;
+        addTokens(node.value);
+      } else if (t.isObjectProperty(node)) {
+        if (isClassNamePropOnCompiledJsxCall(node, parent, grandParent)) {
+          assignments += 1;
+          addTokens(node.value);
+        }
+      }
+
+      const visitorKeys = VISITOR_KEYS[node.type] ?? [];
+      const typedNode = node as unknown as Record<string, unknown>;
+      for (const key of visitorKeys) {
+        const childValue = typedNode[key];
+        if (Array.isArray(childValue)) {
+          for (const item of childValue) {
+            if (isBabelNode(item)) {
+              visit(item, node, parent);
+            }
+          }
+          continue;
+        }
+        if (isBabelNode(childValue)) {
+          visit(childValue, node, parent);
+        }
+      }
+    };
+
+    visit(ast.program, null, null);
+
+    return {
+      total,
+      unique: uniqueTokens.size,
+      assignments,
+    };
+  } catch {
+    const fallbackAssignments = (output.match(/className\s*[:=]/g) ?? [])
+      .length;
+    return {
+      total: 0,
+      unique: 0,
+      assignments: fallbackAssignments,
+    };
+  }
+}
+
+function getRuntimeStyleParserCallCount(output: string): number {
+  const patterns = [/extractStyleProps\s*\(/g, /getStyles\s*\(/g];
+  return patterns.reduce(
+    (count, pattern) => count + (output.match(pattern) ?? []).length,
+    0,
+  );
+}
+
+export function getLoaderTransformOutputSpecs(
+  output: string,
+): LoaderTransformOutputSpecs {
+  const classTokenStats = getClassTokenStats(output);
+  return {
+    outputGzipBytes: gzipSync(output).byteLength,
+    classNameAssignments: classTokenStats.assignments,
+    utilityClassTokens: classTokenStats.total,
+    uniqueUtilityClassTokens: classTokenStats.unique,
+    runtimeStyleParserCalls: getRuntimeStyleParserCallCount(output),
+  };
+}
+
+const VIRTUAL_CONFIG_PATH = '/virtual/uds-config.json';
+
+export function runLoaderTransform(
+  source: string,
+  options: RunLoaderTransformOptions,
+): LoaderTransformResult {
+  if (typeof source !== 'string') {
+    return { error: '`source` must be a string.' };
+  }
+
+  // Seed the loader's in-memory cache so it skips disk I/O
+  seedUdsConfig(VIRTUAL_CONFIG_PATH, options.config);
+
+  const context = {
+    getOptions: () => ({
+      dataPath: VIRTUAL_CONFIG_PATH,
+      isDev: options.isDev ?? false,
+    }),
+    addDependency: () => {},
+    resourcePath:
+      options.resourcePath ??
+      path.resolve(process.cwd(), 'playground-input.tsx'),
+  };
+
+  try {
+    const output = (
+      transformLoader as unknown as (this: unknown, code: string) => string
+    ).call(context, source);
+    return { output, specs: getLoaderTransformOutputSpecs(output) };
+  } catch (error) {
+    return {
+      error:
+        error instanceof Error
+          ? error.message
+          : 'Transform failed unexpectedly.',
+    };
+  }
+}