zyzz 0.0.21 → 0.0.22

package/src/metro/Graph.ts

@@ -1,80 +1,265 @@
-/** Reads a closed local source graph for native authoring without evaluating modules. @module */
+/** Reads resolved source and packed native authoring without evaluating modules. @module */
+import type * as Ast from '@oxc-project/types'
+import type * as Compiler from '../compiler/Graph.js'
 import * as Fs from 'node:fs'
 import * as Path from 'node:path'
 import * as Snapshot from '../node/internal/Snapshot.js'
-import type * as Graph from '../compiler/Graph.js'
 
-/** Collects relative source imports; package and asset imports remain owned by Metro. */
+/** Serializable source snapshot delivered to a Metro transformer worker. */
+export type Input = Pick<
+  Compiler.compile.Options,
+  'contracts' | 'imports' | 'modules'
+> & {
+  /** Files and sidecars whose edits invalidate this consumer. */
+  readonly files: readonly string[]
+  /** Portable compiler identity for the requesting module. */
+  readonly moduleId: string
+}
+
+/** Collects authoring through Metro resolutions, retaining packed contracts and watched inputs. */
 export function read(
   filename: string,
   source: string,
   platform: string,
   root: string,
   snapshot = Snapshot.create(),
-) {
+  resolve?: Resolver,
+): read.ReturnType {
+  const contracts: Record<string, string> = Object.create(null)
   const files = new Set<string>()
-  const modules: Record<string, string> = Object.create(null)
   const imports: Record<string, Record<string, string | null>> = Object.create(
     null,
   )
+  const modules: Record<string, string> = Object.create(null)
+
   function identity(filename: string) {
-    const relative = Path.relative(root, filename).split(Path.sep).join('/')
-    if (relative.startsWith('../'))
-      throw new Error(
-        `Native authoring must be inside Metro's project root: ${filename}`,
+    const parts = Path.relative(root, filename).split(Path.sep)
+    let parents = 0
+    while (parts[0] === '..') {
+      parents++
+      parts.shift()
+    }
+    return `${parents ? `external/${parents}` : 'project'}/${parts.map(encodeURIComponent).join('/')}`
+  }
+
+  function local(filename: string): boolean {
+    const relative = Path.relative(root, filename)
+    return (
+      relative !== '..' &&
+      !relative.startsWith(`..${Path.sep}`) &&
+      !Path.isAbsolute(relative) &&
+      !relative.split(Path.sep).includes('node_modules')
+    )
+  }
+
+  function manifest(filename: string): string | undefined {
+    let directory = Path.dirname(filename)
+    while (true) {
+      const file = Path.join(directory, 'package.json')
+      files.add(file)
+      if (Fs.existsSync(file)) return file
+
+      const parent = Path.dirname(directory)
+      if (parent === directory) return undefined
+      directory = parent
+    }
+  }
+
+  function target(
+    filename: string,
+    specifier: string,
+    isESMImport = true,
+  ): string | undefined {
+    if (resolve) {
+      const next = resolve(filename, specifier, isESMImport)
+      if (next && !specifier.startsWith('.')) manifest(next)
+      return next
+    }
+    if (!specifier.startsWith('.')) return undefined
+    const base = Path.resolve(Path.dirname(filename), specifier)
+    const stem = base.replace(/\.[cm]?jsx?$/, '')
+    const candidates = [
+      ...['.ts', '.tsx', '.js', '.jsx'].flatMap((extension) => [
+        `${stem}.${platform}${extension}`,
+        `${stem}.native${extension}`,
+        `${stem}${extension}`,
+      ]),
+      base,
+      ...['.ts', '.tsx', '.js', '.jsx'].map((extension) =>
+        Path.join(base, `index${extension}`),
+      ),
+    ]
+    for (const candidate of candidates) files.add(candidate)
+    return candidates.find(
+      (path) => Fs.existsSync(path) && Fs.statSync(path).isFile(),
+    )
+  }
+
+  function specifier(node: Ast.Program['body'][number]): string | undefined {
+    if (
+      (node.type !== 'ImportDeclaration' &&
+        node.type !== 'ExportAllDeclaration' &&
+        node.type !== 'ExportNamedDeclaration') ||
+      !node.source ||
+      ('importKind' in node && node.importKind === 'type') ||
+      ('exportKind' in node && node.exportKind === 'type') ||
+      ('specifiers' in node &&
+        node.specifiers.length > 0 &&
+        node.specifiers.every(
+          (specifier) =>
+            ('importKind' in specifier && specifier.importKind === 'type') ||
+            ('exportKind' in specifier && specifier.exportKind === 'type'),
+        ))
+    )
+      return undefined
+
+    return node.source.value
+  }
+
+  function requires(node: unknown, names: Map<string, boolean>): void {
+    if (!node || typeof node !== 'object') return
+    if (Array.isArray(node)) {
+      for (const child of node) requires(child, names)
+      return
+    }
+
+    const entry = node as Ast.Node
+    if (
+      entry.type === 'CallExpression' &&
+      entry.callee.type === 'Identifier' &&
+      entry.callee.name === 'require' &&
+      entry.arguments.length === 1
+    ) {
+      const argument = entry.arguments[0]!
+      if (argument.type === 'Literal' && typeof argument.value === 'string')
+        names.set(argument.value, false)
+    }
+
+    for (const child of Object.values(node)) requires(child, names)
+  }
+
+  const authored = new Set<string>()
+  function authoring(filename: string, seen = new Set<string>()): boolean {
+    files.add(filename)
+    files.add(`${filename}.zyzz.json`)
+    if (Fs.existsSync(`${filename}.zyzz.json`)) return true
+    if (authored.has(filename)) return true
+    if (seen.has(filename)) return false
+    seen.add(filename)
+    const source = snapshot.readSync(filename)
+    const file = manifest(filename)
+    if (file && !/['"]zyzz(?:\/default)?['"]/.test(source)) {
+      const data = JSON.parse(snapshot.readSync(file)) as Record<
+        string,
+        unknown
+      >
+      if (
+        ![
+          'dependencies',
+          'devDependencies',
+          'optionalDependencies',
+          'peerDependencies',
+        ].some((key) => {
+          const dependencies = data[key]
+          return (
+            dependencies &&
+            typeof dependencies === 'object' &&
+            Object.hasOwn(dependencies, 'zyzz')
+          )
+        })
       )
-    return relative
+        return false
+    }
+
+    for (const node of snapshot.parse({ moduleId: identity(filename), source })
+      .program.body) {
+      const name = specifier(node)
+      if (name === 'zyzz' || name === 'zyzz/default') {
+        authored.add(filename)
+        return true
+      }
+      if (!name || name.startsWith('zyzz/')) continue
+      const next = target(filename, name)
+      if (next && /\.[cm]?[jt]sx?$/.test(next) && authoring(next, seen)) {
+        authored.add(filename)
+        return true
+      }
+    }
+    return false
   }
-  function visit(filename: string, source: string) {
+  const visited = new Set<string>()
+  function visit(filename: string, source: string, packed = false) {
     files.add(filename)
     const id = identity(filename)
-    if (Object.hasOwn(modules, id)) return
-    modules[id] = source
+    if (visited.has(id)) return
+    visited.add(id)
+    if (!packed) modules[id] = source
     const resolved: Record<string, string | null> = Object.create(null)
     imports[id] = resolved
-    for (const statement of snapshot.parse({ moduleId: id, source }).program
-      .body) {
+    const program = snapshot.parse({ moduleId: id, source }).program
+    const names = new Map<string, boolean>()
+    for (const statement of program.body) {
+      const name = specifier(statement)
+      if (name) names.set(name, true)
+    }
+    if (packed) requires(program, names)
+
+    for (const [name, isESMImport] of names) {
+      resolved[name] = null
       if (
-        !('source' in statement) ||
-        !statement.source ||
-        typeof statement.source !== 'object' ||
-        !('value' in statement.source) ||
-        typeof statement.source.value !== 'string'
+        name === 'zyzz' ||
+        name.startsWith('zyzz/') ||
+        ['react', 'react-native'].includes(name)
       )
         continue
-      const specifier = statement.source.value
-      resolved[specifier] = null
-      if (!specifier.startsWith('.')) continue
-      const base = Path.resolve(Path.dirname(filename), specifier)
-      const stem = base.replace(/\.[cm]?jsx?$/, '')
-      const candidates = [
-        ...['.ts', '.tsx', '.js', '.jsx'].flatMap((extension) => [
-          `${stem}.${platform}${extension}`,
-          `${stem}.native${extension}`,
-          `${stem}${extension}`,
-        ]),
-        base,
-        ...['.ts', '.tsx', '.js', '.jsx'].map((extension) =>
-          Path.join(base, `index${extension}`),
-        ),
-      ]
-      for (const candidate of candidates) files.add(candidate)
-      const target = candidates.find(
-        (path) => Fs.existsSync(path) && Fs.statSync(path).isFile(),
-      )
-      if (!target || !/\.[cm]?[jt]sx?$/.test(target)) continue
-      resolved[specifier] = identity(target)
-      visit(target, snapshot.readSync(target))
+      const next = target(filename, name, isESMImport)
+      if (!next || !/\.[cm]?[jt]sx?$/.test(next)) continue
+      const packed = `${next}.zyzz.json`
+      files.add(packed)
+      if (Fs.existsSync(packed)) {
+        files.add(next)
+        contracts[identity(next)] = snapshot.readSync(packed)
+        resolved[name] = identity(next)
+        visit(next, snapshot.readSync(next), true)
+        continue
+      }
+      if (!name.startsWith('.') && !local(next) && !authoring(next)) continue
+      resolved[name] = identity(next)
+      visit(next, snapshot.readSync(next))
     }
   }
+  if (!local(filename) && !authoring(filename))
+    return { files: [...files], input: undefined }
+
   visit(filename, source)
+
+  const watched = [...files]
   return {
-    moduleId: identity(filename),
-    modules,
-    imports,
-    files: [...files],
-  } satisfies Pick<Graph.compile.Options, 'modules' | 'imports'> & {
-    moduleId: string
-    files: readonly string[]
+    files: watched,
+    input: {
+      contracts,
+      files: watched,
+      imports,
+      moduleId: identity(filename),
+      modules,
+    },
   }
 }
+
+/** Source classification and all paths that can change its result. */
+export declare namespace read {
+  /** Candidate files remain watchable even when the module currently needs no compilation. */
+  type ReturnType = {
+    /** Sources, manifests, and sidecar candidates that affect classification. */
+    readonly files: readonly string[]
+    /** Compiler input when the module belongs to the authoring graph. */
+    readonly input: Input | undefined
+  }
+}
+
+/** Source resolution supplied by Metro's live dependency graph. */
+export type Resolver = (
+  filename: string,
+  specifier: string,
+  isESMImport: boolean,
+) => string | undefined

package/src/metro/Watch.ts

@@ -1,24 +1,57 @@
 /** Keeps Metro's transform cache and delta graph aligned with imported authoring. @module */
+import * as AsyncHooks from 'node:async_hooks'
 import * as Crypto from 'node:crypto'
 import * as Fs from 'node:fs'
 import * as Path from 'node:path'
+import * as Snapshot from '../node/internal/Snapshot.js'
 import type { EventEmitter } from 'node:events'
 import * as Graph from './Graph.js'
 
 type Options = {
-  readonly platform?: string
   readonly customTransformOptions?: Readonly<Record<string, unknown>>
+  readonly platform?: string
 }
 type Bundler = {
-  getDependencyGraph(): Promise<{ getWatcher(): EventEmitter }>
+  getDependencyGraph(): Promise<{
+    getWatcher(): EventEmitter
+    resolveDependency(
+      filename: string,
+      dependency: {
+        data: {
+          asyncType: null
+          isESMImport: boolean
+          key: string
+          locs: readonly never[]
+        }
+        name: string
+      },
+      platform: string,
+      options: { customResolverOptions: Readonly<Record<string, unknown>> },
+    ): { type: string; filePath?: string }
+  }>
   transformFile(
     filename: string,
     options: Options,
     buffer?: Buffer,
   ): Promise<unknown>
 }
+type ResolverOptions = {
+  readonly customResolverOptions: Readonly<Record<string, unknown>>
+}
+type IncrementalBundler = {
+  buildGraphForEntries: Build
+  getBundler(): Bundler
+  getDependencies: Build
+  updateGraph(revision: { graph: object }, reset: boolean): Promise<unknown>
+}
+type Build = (
+  entries: readonly string[],
+  transform: unknown,
+  resolver: ResolverOptions,
+  options?: unknown,
+) => Promise<object>
 /** Metro server methods used by its own serializers and development middleware. */
-export type Server = { getBundler(): { getBundler(): Bundler } }
+export type Server = { getBundler(): IncrementalBundler }
 type Changes = {
   rootDir: string
   changes: {
@@ -30,24 +63,74 @@ type Changes = {
 
 /** Includes imported source contents in transform keys and invalidates their consumers on edits. */
 export async function attach(server: Server, root: string) {
-  const bundler = server.getBundler().getBundler()
-  const graph = await bundler.getDependencyGraph()
+  const incremental = server.getBundler()
+  const bundler = incremental.getBundler()
+  const requests = new AsyncHooks.AsyncLocalStorage<ResolverOptions>()
+  const selections = new WeakMap<object, ResolverOptions>()
+  for (const name of ['buildGraphForEntries', 'getDependencies'] as const) {
+    const build = incremental[name].bind(incremental)
+    incremental[name] = (entries, transform, resolver, options) =>
+      requests.run(resolver, async () => {
+        const graph = await build(entries, transform, resolver, options)
+        selections.set(graph, resolver)
+        return graph
+      })
+  }
+  const update = incremental.updateGraph.bind(incremental)
+  incremental.updateGraph = (revision, reset) =>
+    requests.run(
+      selections.get(revision.graph) ?? { customResolverOptions: {} },
+      () => update(revision, reset),
+    )
+
+  const ready = bundler.getDependencyGraph()
   const dependencies = new Map<string, Map<string, Set<string>>>()
+  const snapshot = Snapshot.create()
   const transform = bundler.transformFile.bind(bundler)
-  bundler.transformFile = (filename, options, buffer) => {
+  bundler.transformFile = async (filename, options, buffer) => {
     if (
       (options.platform !== 'ios' && options.platform !== 'android') ||
       !/\.[cm]?[jt]sx?$/.test(filename) ||
-      Path.relative(root, filename).startsWith(`..${Path.sep}`) ||
-      filename.split(Path.sep).includes('node_modules')
+      filename.startsWith(
+        `${Path.resolve(import.meta.dirname, '..')}${Path.sep}`,
+      )
     )
       return transform(filename, options, buffer)
     const source = buffer?.toString('utf8') ?? Fs.readFileSync(filename, 'utf8')
-    const input = Graph.read(filename, source, options.platform, root)
+    const graph = await ready
+    const read = Graph.read(
+      filename,
+      source,
+      options.platform,
+      root,
+      snapshot,
+      (filename, specifier, isESMImport) => {
+        const resolved = graph.resolveDependency(
+          filename,
+          {
+            data: {
+              asyncType: null,
+              isESMImport,
+              key: specifier,
+              locs: [],
+            },
+            name: specifier,
+          },
+          options.platform!,
+          requests.getStore() ?? { customResolverOptions: {} },
+        )
+        return resolved.type === 'sourceFile' ? resolved.filePath : undefined
+      },
+    )
     const platforms =
       dependencies.get(filename) ?? new Map<string, Set<string>>()
-    platforms.set(options.platform, new Set(input.files))
+    platforms.set(
+      JSON.stringify([options.platform, requests.getStore()]),
+      new Set(read.files),
+    )
     dependencies.set(filename, platforms)
+    const input = read.input
+    if (!input) return transform(filename, options, buffer)
     const hash = Crypto.hash('sha256', JSON.stringify(input))
     return transform(
       filename,
@@ -56,11 +139,13 @@ export async function attach(server: Server, root: string) {
         customTransformOptions: {
           ...options.customTransformOptions,
           zyzzGraph: hash,
+          zyzzSources: input,
         },
       },
       buffer,
     )
   }
+  const graph = await ready
   graph.getWatcher().prependListener('change', (event: Changes) => {
     const entries = [
       ...event.changes.addedFiles,

package/src/metro/index.ts

@@ -6,12 +6,23 @@ import * as Module from 'node:module'
 import * as Path from 'node:path'
 import * as Watch from './Watch.js'
 
+type Context = {
+  readonly resolveRequest: Resolve
+}
+type Resolve = (
+  context: Context,
+  name: string,
+  platform: string | null,
+) => unknown
+
 /** Minimum Metro configuration consumed by the adapter. */
 export type Config = {
-  /** Existing development middleware settings. */
-  readonly server?: object | undefined
   /** Application root used for the adapter cache. */
   readonly projectRoot?: string | undefined
+  /** Existing package, alias, and platform resolution settings. */
+  readonly resolver?: object | undefined
+  /** Existing development middleware settings. */
+  readonly server?: object | undefined
   /** Existing transformer configuration, including Expo's Babel transformer. */
   readonly transformer?:
     | {
@@ -29,7 +40,13 @@ export function zyzz<const config extends Config>(
   config: config,
   options: Omit<
     NativeOptions,
-    'platform' | 'target' | 'moduleId' | 'modules' | 'imports' | 'colorScheme'
+    | 'platform'
+    | 'target'
+    | 'moduleId'
+    | 'modules'
+    | 'imports'
+    | 'contracts'
+    | 'colorScheme'
   > = {},
 ): zyzz.ReturnType<config> {
   if (Object.hasOwn(options, 'colorScheme'))
@@ -62,8 +79,42 @@ export function zyzz<const config extends Config>(
       | ((middleware: Middleware, server: Watch.Server) => Middleware)
       | undefined)
   type Middleware = (...args: unknown[]) => unknown
+  const resolve =
+    config.resolver &&
+    (Reflect.get(config.resolver, 'resolveRequest') as Resolve | undefined)
+
   return {
     ...config,
+    resolver: {
+      ...config.resolver,
+      resolveRequest(context: Context, name: string, platform: string | null) {
+        const next = resolve ?? context.resolveRequest
+        try {
+          return next(context, name, platform)
+        } catch (error) {
+          if (
+            (platform !== 'ios' && platform !== 'android') ||
+            !name.startsWith('.') ||
+            !name.endsWith('.js') ||
+            !(error instanceof Error && 'candidates' in error)
+          )
+            throw error
+
+          // NodeNext imports name emitted JavaScript; source packages retain TypeScript files.
+          const source = next(context, name.slice(0, -3), platform)
+          if (
+            source &&
+            typeof source === 'object' &&
+            'filePath' in source &&
+            typeof source.filePath === 'string' &&
+            /\.tsx?$/.test(source.filePath)
+          )
+            return source
+
+          throw error
+        }
+      },
+    },
     server: {
       ...config.server,
       enhanceMiddleware(middleware: Middleware, server: Watch.Server) {
@@ -89,7 +140,14 @@ export function zyzz<const config extends Config>(
 /** Configuration returned by the Metro adapter. */
 export declare namespace zyzz {
   /** Preserves caller configuration fields and the existing transformer options. */
-  type ReturnType<config extends Config> = Omit<config, 'transformer'> & {
+  type ReturnType<config extends Config> = Omit<
+    config,
+    'resolver' | 'transformer'
+  > & {
+    /** Existing resolver options with the chained native source resolver. */
+    resolver: Omit<NonNullable<config['resolver']>, 'resolveRequest'> & {
+      resolveRequest: Resolve
+    }
     /** Existing transformer configuration with the native compilation entrypoint. */
     transformer: Omit<
       NonNullable<config['transformer']>,

package/src/metro/transformer.ts

@@ -13,7 +13,12 @@ import { type NativeOptions, zyzz } from '../babel/index.js'
 /** Babel transformer inputs passed through without removing upstream fields. */
 type Input = {
   readonly filename: string
-  readonly options: { readonly platform?: string | undefined }
+  readonly options: {
+    readonly platform?: string | undefined
+    readonly customTransformOptions?:
+      | { readonly zyzzSources?: Graph.Input | undefined }
+      | undefined
+  }
   readonly plugins?: readonly Babel.PluginItem[] | undefined
   readonly src: string
 }
@@ -28,7 +33,13 @@ export function create(
   upstreamPath: string,
   options: Omit<
     NativeOptions,
-    'platform' | 'target' | 'moduleId' | 'modules' | 'imports' | 'colorScheme'
+    | 'platform'
+    | 'target'
+    | 'moduleId'
+    | 'modules'
+    | 'imports'
+    | 'contracts'
+    | 'colorScheme'
   > & { readonly root: string },
 ) {
   const compilers = new Map<string, ReturnType<typeof Compiler.create>>()
@@ -78,18 +89,17 @@ export function create(
       if (
         (platform !== 'ios' && platform !== 'android') ||
         !/\.[cm]?[jt]sx?$/.test(input.filename) ||
-        input.filename.split(/[\\/]/).includes('node_modules') ||
-        Path.relative(options.root, filename).startsWith(`..${Path.sep}`)
+        filename.startsWith(
+          `${Path.resolve(import.meta.dirname, '..')}${Path.sep}`,
+        )
       )
         return upstream.transform(input)
 
-      const graph = Graph.read(
-        filename,
-        input.src,
-        platform,
-        options.root,
-        snapshot,
-      )
+      const graph =
+        input.options.customTransformOptions?.zyzzSources ??
+        Graph.read(filename, input.src, platform, options.root, snapshot).input
+      if (!graph) return upstream.transform(input)
+
       const key = `${platform}:${filename}`
       let compiler = compilers.get(key)
       if (!compiler) {