@yahoo/uds-create-loader 1.13.0 → 1.14.0

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@yahoo/uds-create-loader",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "type": "module",
   "private": false,
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "exports": {
     ".": {
@@ -37,7 +38,7 @@
     "test:update": "bun test src/ --update-snapshots"
   },
   "dependencies": {
-    "@yahoo/uds-create-config": "1.13.0",
+    "@yahoo/uds-create-config": "1.14.0",
     "@babel/parser": "^7.29.0",
     "@babel/traverse": "^7.29.0",
     "@babel/types": "^7.29.0",

package/src/index.ts

@@ -0,0 +1,12 @@
+export { default as transformLoader } from './loader';
+export type {
+  LoaderTransformOutputSpecs,
+  LoaderTransformResult,
+  RunLoaderTransformOptions,
+} from './transform-runner';
+export {
+  getLoaderTransformOutputSpecs,
+  runLoaderTransform,
+} from './transform-runner';
+export type { UdsPluginOptions } from './unplugin';
+export { udsPlugin } from './unplugin';

package/src/inspect-transform.ts

@@ -0,0 +1,79 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import type { Config } from '@yahoo/uds-create-config';
+import { runLoaderTransform } from './transform-runner';
+
+function readFlag(flag: string): string | null {
+  const index = process.argv.indexOf(flag);
+  if (index === -1) return null;
+  const value = process.argv[index + 1];
+  if (!value || value.startsWith('-')) return null;
+  return value;
+}
+
+function printUsage(): never {
+  console.error(
+    [
+      'Usage:',
+      '  bun run src/inspect-transform.ts --file <path-to-tsx> --config <path-to-uds.config.ts>',
+      '',
+      'Example:',
+      '  bun run --filter @yahoo/uds-create-loader inspect:transform -- --file packages/components/src/accordion.tsx --config apps/docs/uds.config.ts',
+    ].join('\n'),
+  );
+  process.exit(1);
+}
+
+async function loadUdsConfig(configPath: string): Promise<unknown> {
+  const resolvedPath = path.resolve(configPath);
+  const configUrl = pathToFileURL(resolvedPath).href;
+  const module = (await import(configUrl)) as {
+    default?: unknown;
+    udsConfig?: unknown;
+  };
+
+  if (module.default !== undefined) {
+    return module.default;
+  }
+  if (module.udsConfig !== undefined) {
+    return module.udsConfig;
+  }
+
+  return module;
+}
+
+async function main() {
+  const sourcePath = readFlag('--file');
+  const configPath = readFlag('--config');
+  if (!sourcePath || !configPath) {
+    printUsage();
+  }
+
+  const sourceAbsolutePath = path.resolve(sourcePath);
+  if (!fs.existsSync(sourceAbsolutePath)) {
+    throw new Error(`Source file not found: ${sourceAbsolutePath}`);
+  }
+
+  const rawConfig = await loadUdsConfig(configPath);
+  const config = (rawConfig as Config).toJSON();
+
+  const source = fs.readFileSync(sourceAbsolutePath, 'utf8');
+  const result = runLoaderTransform(source, {
+    config,
+    resourcePath: sourceAbsolutePath,
+    isDev: false,
+  });
+
+  if ('error' in result) {
+    throw new Error(result.error);
+  }
+
+  process.stdout.write(result.output);
+}
+
+void main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`[inspect-transform] ${message}`);
+  process.exit(1);
+});

package/src/loader/artifacts.ts

@@ -0,0 +1,113 @@
+import fs from 'node:fs';
+import type { SerializedConfig } from '@yahoo/uds-create-config';
+
+export interface LoaderOptions {
+  /** Path to `.uds/manifest.json`. The loader extracts `.config` at the
+   *  read boundary; the manifest's wrapper fields (`catalogMeta`,
+   *  `sourceMap`, …) exist for Studio/MCP and aren't read here. */
+  dataPath: string;
+  isDev: boolean;
+  /** 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;
+}
+
+/**
+ * Derived projection of one loaded config — built lazily on first use,
+ * cached by config object identity so subsequent transforms reuse the
+ * same set. Carries the registered-component-name set the loader uses
+ * for the pre-filter and the import-rewrite visitor's eligibility check.
+ */
+export interface LoaderProjection {
+  readonly componentNames: ReadonlySet<string>;
+}
+
+/**
+ * `.uds/config.json` IS the serialized config — no envelope. Parse and
+ * cache by file mtime so subsequent transforms reuse the same object.
+ */
+function createCachedJsonLoader(): (
+  filePath: string,
+  isDev: boolean,
+) => SerializedConfig | null {
+  let cached: SerializedConfig | null = null;
+  let cachedPath: string | null = null;
+  let cachedMtime = 0;
+
+  return (filePath: string, isDev: boolean): SerializedConfig | null => {
+    try {
+      const stat = fs.statSync(filePath);
+      const mtime = stat.mtimeMs;
+
+      if (
+        cached &&
+        cachedPath === filePath &&
+        (!isDev || cachedMtime === mtime)
+      ) {
+        return cached;
+      }
+
+      const content = fs.readFileSync(filePath, 'utf-8');
+      cached = JSON.parse(content) as SerializedConfig;
+      cachedPath = filePath;
+      cachedMtime = mtime;
+      return cached;
+    } catch {
+      return null;
+    }
+  };
+}
+
+function createCachedJsonLoaderWithSeed(): {
+  load: (filePath: string, isDev: boolean) => SerializedConfig | null;
+  seed: (filePath: string, config: SerializedConfig) => void;
+} {
+  const loader = createCachedJsonLoader();
+  let seededPath: string | null = null;
+  let seededData: SerializedConfig | null = null;
+
+  return {
+    load: (filePath: string, isDev: boolean): SerializedConfig | null => {
+      if (seededPath === filePath && seededData) {
+        return seededData;
+      }
+      return loader(filePath, isDev);
+    },
+    seed: (filePath: string, config: SerializedConfig) => {
+      seededPath = filePath;
+      seededData = config;
+    },
+  };
+}
+
+const configLoader = createCachedJsonLoaderWithSeed();
+
+export const loadUdsConfig = configLoader.load;
+export const seedUdsConfig = configLoader.seed;
+
+// ---------------------------------------------------------------------------
+// Derived projection
+// ---------------------------------------------------------------------------
+
+const projectionCache = new WeakMap<SerializedConfig, LoaderProjection>();
+
+/**
+ * Build (or return a cached) projection of the config for the loader's
+ * hot path. Keyed by config object identity. The cache survives across
+ * transforms within one process; reloading `.uds/manifest.json`
+ * produces a fresh object, which transparently invalidates the
+ * projection.
+ */
+export function getLoaderProjection(
+  config: SerializedConfig,
+): LoaderProjection {
+  const cached = projectionCache.get(config);
+  if (cached) return cached;
+
+  const components = (config.components ?? {}) as Record<string, unknown>;
+  const componentNames = new Set<string>(Object.keys(components));
+
+  const projection: LoaderProjection = { componentNames };
+  projectionCache.set(config, projection);
+  return projection;
+}

package/src/loader/babel-utils.ts

@@ -0,0 +1,39 @@
+import * as t from '@babel/types';
+
+/** JSX function names used by compiled JSX (React, etc.) */
+const COMPILED_JSX_NAMES = new Set([
+  'jsx',
+  'jsxs',
+  'jsxDEV',
+  '_jsx',
+  '_jsxs',
+  '_jsxDEV',
+]);
+
+/**
+ * Check whether a callee expression is a compiled JSX call.
+ *
+ * Matches:
+ * - Direct identifiers: `jsx(...)`, `_jsxs(...)`, `jsxDEV(...)`, etc.
+ * - Member expressions: `React.jsx(...)`, `_reactJsxRuntime.jsxs(...)`, etc.
+ */
+export function isCompiledJsxCallee(
+  node: t.Expression | t.V8IntrinsicIdentifier | null | undefined,
+): boolean {
+  if (!node) return false;
+
+  if (t.isIdentifier(node)) {
+    return COMPILED_JSX_NAMES.has(node.name);
+  }
+
+  if (t.isMemberExpression(node) || t.isOptionalMemberExpression(node)) {
+    if (!node.computed && t.isIdentifier(node.property)) {
+      return COMPILED_JSX_NAMES.has(node.property.name);
+    }
+    if (node.computed && t.isStringLiteral(node.property)) {
+      return COMPILED_JSX_NAMES.has(node.property.value);
+    }
+  }
+
+  return false;
+}

package/src/loader.test.ts

@@ -0,0 +1,254 @@
+/**
+ * Unit tests for the trimmed `transformLoader`.
+ *
+ * Fixtures use the public authoring API (`defineComponent`,
+ * `defineStyleProp`, `uds.register*`) and call `Config.toJSON()` so the
+ * loader sees exactly the serialized-config shape it would in production.
+ * Avoids coupling tests to internal serialized layer / marker shape —
+ * those shapes can evolve without touching this file.
+ */
+
+import { describe, expect, it } from 'bun:test';
+import path from 'node:path';
+import { parse } from '@babel/parser';
+import type { SerializedConfig } from '@yahoo/uds-create-config';
+import {
+  Config,
+  defineComponent,
+  defineStyleProp,
+} from '@yahoo/uds-create-config';
+import transformLoader from './loader';
+import { seedUdsConfig } from './loader/artifacts';
+
+const VIRTUAL_CONFIG_PATH = '/virtual/uds-config.json';
+
+function runLoader(
+  source: string,
+  config: SerializedConfig,
+  options?: { isDev?: boolean; resourcePath?: string },
+): string {
+  seedUdsConfig(VIRTUAL_CONFIG_PATH, config);
+
+  const context = {
+    getOptions: () => ({
+      dataPath: VIRTUAL_CONFIG_PATH,
+      isDev: options?.isDev ?? false,
+    }),
+    addDependency: () => {},
+    resourcePath: options?.resourcePath ?? path.join(process.cwd(), 'demo.tsx'),
+  };
+
+  return (
+    transformLoader as unknown as (this: unknown, code: string) => string
+  ).call(context, source);
+}
+
+// ---------------------------------------------------------------------------
+// Shared config factories — authoring-API based
+// ---------------------------------------------------------------------------
+
+const bg = defineStyleProp({
+  cssProperty: 'background-color',
+  classPrefix: 'bg',
+  values: [],
+});
+
+const padding = defineStyleProp({
+  cssProperty: 'padding',
+  classPrefix: 'p',
+  values: [],
+});
+
+/** Single-layer primitive `<Box>` with two style-prop bindings. Lowerable. */
+function makeBoxConfig(): SerializedConfig {
+  const Box = defineComponent('div').config(({ styleProp }) => ({
+    props: {
+      bg: styleProp('bg'),
+      padding: styleProp('padding'),
+    },
+  }));
+  const config = new Config()
+    .registerStyleProps({ bg, padding })
+    .registerComponents({ Box });
+  return config.toJSON();
+}
+
+/** Empty config — no registered components. */
+function makeEmptyConfig(): SerializedConfig {
+  return new Config().toJSON();
+}
+
+describe('loader — new-API import rewrite', () => {
+  it('rewrites aliased `@/uds/components/<seg>` imports to `#uds/components/<seg>`', () => {
+    const config = makeBoxConfig();
+    const source = `
+import { Box } from '@/uds/components/box';
+
+export function Demo() {
+  return <Box bg="brand">hi</Box>;
+}
+`;
+    const output = runLoader(source, config);
+
+    expect(output).toMatch(/from\s+["']#uds\/components\/box["']/);
+    expect(output).not.toContain("from '@/uds/components/box'");
+  });
+
+  it('does not rewrite relative imports', () => {
+    const config = makeBoxConfig();
+    const source = `
+import { Box } from './box';
+
+export function Demo() {
+  return <Box bg="brand">hi</Box>;
+}
+`;
+    const output = runLoader(source, config);
+
+    expect(output).toMatch(/from\s+["']\.\/box["']/);
+    expect(output).not.toMatch(/from\s+["']#uds\/components/);
+  });
+
+  it('does not rewrite imports of unknown names', () => {
+    const config = makeBoxConfig();
+    const source = `
+import { Unrelated } from '@/uds/components/unrelated';
+
+export function Demo() {
+  return <Unrelated />;
+}
+`;
+    const output = runLoader(source, config);
+
+    expect(output).toMatch(/from\s+["']@\/uds\/components\/unrelated["']/);
+    expect(output).not.toMatch(/from\s+["']#uds\/components/);
+  });
+});
+
+describe('loader — JSX passes through unchanged', () => {
+  it('leaves JSX call sites alone while rewriting the import', () => {
+    const config = makeBoxConfig();
+    const source = `
+import { Box } from '@/uds/components/box';
+
+export function Demo() {
+  return <Box bg="brand" padding="md">hi</Box>;
+}
+`;
+    const output = runLoader(source, config);
+
+    expect(output).toMatch(/from\s+["']#uds\/components\/box["']/);
+    expect(output).toContain('<Box');
+    expect(output).toContain('bg="brand"');
+    expect(output).toContain('padding="md"');
+  });
+});
+
+describe('loader — non-import bytes are preserved verbatim', () => {
+  it('rewrites only the import literal and leaves every other byte identical', () => {
+    const config = makeBoxConfig();
+    const source = `
+import { Box } from '@/uds/components/box';
+
+export function Demo() {
+  return <Box bg="brand">hi</Box>;
+}
+`;
+    const output = runLoader(source, config);
+    const expected = source.replace(
+      "'@/uds/components/box'",
+      "'#uds/components/box'",
+    );
+
+    expect(output).toBe(expected);
+  });
+
+  // Regression: the loader used to re-print the whole file through
+  // @babel/generator with `retainLines`, which mangled dense JSX into
+  // invalid output (e.g. a stray `}` in JSX-text position). Splicing
+  // only the import literal must leave all JSX — including expression
+  // containers, fragments, and nested closing braces — untouched.
+  it('does not corrupt dense JSX with nested braces and fragments', () => {
+    const config = makeBoxConfig();
+    const source = `import { Box } from '@/uds/components/box';
+import { useState } from 'react';
+
+const items = ['a', 'b', 'c'];
+
+export function LayerTree() {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      {items.map((item) => (
+        <Box key={item} bg="brand" padding="md">
+          {item === 'a' ? <span>{\`first: \${item}\`}</span> : null}
+          {open && (
+            <Box>
+              {items
+                .filter((i) => i !== item)
+                .map((i) => (
+                  <span key={i}>{i}</span>
+                ))}
+            </Box>
+          )}
+        </Box>
+      ))}
+    </>
+  );
+}
+`;
+    const output = runLoader(source, config);
+    const expected = source.replace(
+      "'@/uds/components/box'",
+      "'#uds/components/box'",
+    );
+
+    expect(output).toBe(expected);
+    // The output must still parse as valid TSX.
+    expect(() =>
+      parse(output, { sourceType: 'module', plugins: ['jsx', 'typescript'] }),
+    ).not.toThrow();
+  });
+});
+
+describe('loader — bailout paths', () => {
+  it('returns source unchanged when the manifest has no components', () => {
+    const config = makeEmptyConfig();
+    const source = `
+import { Box } from '@/uds/components/box';
+
+export function Demo() {
+  return <Box>hi</Box>;
+}
+`;
+    const output = runLoader(source, config);
+    expect(output).toBe(source);
+  });
+
+  it('returns source unchanged for files inside `.uds/`', () => {
+    const config = makeBoxConfig();
+    const source = `
+import { Box } from '@/uds/components/box';
+
+export function Demo() {
+  return <Box bg="brand">hi</Box>;
+}
+`;
+    const output = runLoader(source, config, {
+      resourcePath: path.join(process.cwd(), '.uds/components/box.tsx'),
+    });
+
+    expect(output).toBe(source);
+  });
+
+  it('returns source unchanged when no manifest component is referenced', () => {
+    const config = makeBoxConfig();
+    const source = `
+export function Demo() {
+  return <div>just a div</div>;
+}
+`;
+    const output = runLoader(source, config);
+    expect(output).toBe(source);
+  });
+});