zyzz 0.0.24 → 0.0.26

package/src/node/Host.ts

@@ -12,6 +12,8 @@ import { ResolverFactory } from 'oxc-resolver'
 import * as Graph from '../compiler/Graph.js'
 import * as AtRules from '../compiler/internal/AtRules.js'
 import * as Catalogs from '../compiler/internal/Catalogs.js'
+import * as ClassName from '../web/internal/ClassName.js'
+import * as Contracts from './internal/Contracts.js'
 import * as Relative from '../compiler/internal/Relative.js'
 import * as Scheme from '../internal/Scheme.js'
 import * as Snapshot from './internal/Snapshot.js'
@@ -135,6 +137,7 @@ export async function create(options: create.Options): Promise<Runtime> {
   const manifestPath = Path.join(outDir, '.zyzz.json')
 
   const compiler = Graph.create()
+  const packages = Contracts.create()
   const snapshot = Snapshot.create()
   const stylesheets = new WeakMap<Transform.compile.ReturnType, Stylesheet>()
   let closed = false
@@ -316,18 +319,16 @@ export async function create(options: create.Options): Promise<Runtime> {
     async function contract(file: string, required = false): Promise<boolean> {
       if (Object.hasOwn(contracts, file)) return true
 
-      observe(`${file}.zyzz.json`)
-      try {
-        contracts[file] = await snapshot.read(`${file}.zyzz.json`)
-      } catch (error) {
-        if (
-          !required &&
-          !previousContracts.has(file) &&
-          (error as NodeJS.ErrnoException).code === 'ENOENT'
-        )
-          return false
-        throw error
-      }
+      const source = await packages.read(file, {
+        read(path) {
+          observe(path)
+          return snapshot.read(path)
+        },
+        required: required || previousContracts.has(file),
+        resolve: async (specifier, importer) => resolve(specifier, importer),
+      })
+      if (source === undefined) return false
+      contracts[file] = source
 
       const metadata = (() => {
         try {
@@ -460,6 +461,7 @@ export async function create(options: create.Options): Promise<Runtime> {
     }
 
     const graph = compiler.compile({
+      [ClassName.complete]: true,
       [ThemeRules.shared]:
         options.modules === false && !native ? 'all' : undefined,
       [Syntax.cache]: snapshot.programs(modules),
@@ -470,13 +472,7 @@ export async function create(options: create.Options): Promise<Runtime> {
       imports,
     })
 
-    snapshot.retain(
-      new Set([
-        ...inputs,
-        ...Object.keys(contracts).map((file) => `${file}.zyzz.json`),
-      ]),
-      modules,
-    )
+    snapshot.retain(new Set([...inputs, ...observed]), modules)
 
     const artifactNames = [
       'zyzz.css',
@@ -675,10 +671,11 @@ export async function create(options: create.Options): Promise<Runtime> {
     // cascade over the rules of the modules it imports.
     if (shared || moduleStylesheets.size) {
       const parts = shared ? [shared] : []
+      const units = new Set<string>()
       let schemes = false
 
-      // Each module stylesheet declares the scheme classes to load alone. The
-      // complete stylesheet keeps the first declaration.
+      // Each module stylesheet declares the scheme classes and shared rules it
+      // uses to load alone. The complete stylesheet keeps the first declaration.
       for (const id of order(graph.dependencies, [
         ...moduleStylesheets.keys(),
       ])) {
@@ -686,6 +683,9 @@ export async function create(options: create.Options): Promise<Runtime> {
         const declares = Object.values(Scheme.classes).some((className) =>
           stylesheet.code.includes(`.${className}`),
         )
+        const names = [
+          ...(graph.modules[id]![ClassName.units]?.values() ?? []),
+        ].map((decision) => decision.name)
 
         parts.push(
           rebase(
@@ -693,9 +693,11 @@ export async function create(options: create.Options): Promise<Runtime> {
             name,
             css === false ? false : css.minify,
             schemes && declares,
+            new Set(names.filter((name) => units.has(name))),
           ),
         )
         schemes ||= declares
+        for (const name of names) units.add(name)
       }
 
       const complete = concatenate(parts)
@@ -1199,10 +1201,15 @@ function rebase(
   name: string,
   minify: boolean,
   schemes: boolean,
+  emitted: ReadonlySet<string>,
 ) {
   const directory = Path.posix.dirname(name)
 
-  if (!schemes && (directory === '.' || !stylesheet.code.includes('url(')))
+  if (
+    !schemes &&
+    !emitted.size &&
+    (directory === '.' || !stylesheet.code.includes('url('))
+  )
     return stylesheet
 
   const classes = Object.values(Scheme.classes)
@@ -1220,11 +1227,11 @@ function rebase(
           const [component, ...rest] = selector ?? []
 
           if (
-            schemes &&
             !others.length &&
             !rest.length &&
             component?.type === 'class' &&
-            classes.includes(component.name)
+            ((schemes && classes.includes(component.name)) ||
+              emitted.has(component.name))
           )
             return []
         },

package/src/node/internal/Contracts.ts

@@ -0,0 +1,384 @@
+/** Reads package contracts, deriving a missing sidecar from the package's JavaScript without executing it. @module */
+import * as Crypto from 'node:crypto'
+import * as Path from 'node:path'
+import * as Graph from '../../compiler/Graph.js'
+import * as Contract from '../../compiler/internal/Contract.js'
+import * as Syntax from '../../compiler/internal/Syntax.js'
+
+/** Creates a reader whose derived contracts persist across the builds of one adapter instance. */
+export function create() {
+  const derived = new Map<
+    string,
+    { contract: string | undefined; inputs: string }
+  >()
+  const syntax = new Map<
+    string,
+    { parsed: ReturnType<typeof Syntax.parse>; source: string }
+  >()
+
+  async function lookup(
+    file: string,
+    options: read.Options,
+    active: ReadonlySet<string>,
+  ): Promise<string | undefined> {
+    try {
+      return await options.read(`${file}.zyzz.json`)
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+
+      const contract = await derive(file, options, active)
+      if (contract === undefined && options.required) throw error
+      return contract
+    }
+  }
+
+  async function derive(
+    file: string,
+    options: read.Options,
+    active: ReadonlySet<string>,
+  ): Promise<string | undefined> {
+    const root = await manifest(file, options)
+    if (!root) return undefined
+
+    const { directory, name } = root
+    const id = (path: string) =>
+      `${name}/${Path.relative(directory, path).split(Path.sep).join('/')}`
+    const contracts: Record<string, string> = Object.create(null)
+    const external = new Map<string, string | undefined>()
+    const imports: Record<
+      string,
+      Record<string, string | null>
+    > = Object.create(null)
+    const modules: Record<string, string> = Object.create(null)
+    const programs = new Map<string, ReturnType<typeof Syntax.parse>>()
+    const next = new Set(active).add(file)
+    let authored = false
+
+    async function link(target: string, required = false) {
+      const known = external.get(target)
+      if (known !== undefined || (external.has(target) && !required))
+        return known
+
+      // A package cycle stays a runtime import.
+      const contract = next.has(target)
+        ? undefined
+        : await lookup(target, { ...options, required }, next)
+      external.set(target, contract)
+      if (contract === undefined) return undefined
+
+      contracts[target] = contract
+      for (const section of Contract.read(contract, new Map(), target)
+        .stylesheets) {
+        let owner = target
+        for (const specifier of section.dependency ?? []) {
+          const resolved = await options.resolve(specifier, owner)
+          if (!resolved)
+            throw new Error(
+              `Unable to resolve packed stylesheet dependency: ${specifier}`,
+            )
+
+          ;(imports[owner] ??= Object.create(null))[specifier] = resolved
+          await link(resolved, true)
+          owner = resolved
+        }
+      }
+      return contract
+    }
+
+    async function parse(path: string) {
+      const source = await options.read(path)
+      let entry = syntax.get(path)
+      if (entry?.source !== source) {
+        entry = { parsed: Syntax.parse({ moduleId: id(path), source }), source }
+        syntax.set(path, entry)
+      }
+      return entry
+    }
+
+    // Mirrors the Next.js loader: component exports stay runtime code, and the package ships their CSS.
+    async function callable(
+      path: string,
+      name: string,
+      seen = new Set<string>(),
+    ): Promise<boolean> {
+      const key = JSON.stringify([path, name])
+      if (seen.has(key)) return false
+      seen.add(key)
+
+      const { program } = (await parse(path)).parsed
+      const functions = new Set<string>()
+
+      for (const statement of program.body) {
+        const declaration =
+          statement.type === 'ExportNamedDeclaration' ||
+          statement.type === 'ExportDefaultDeclaration'
+            ? statement.declaration
+            : undefined
+        const exported =
+          statement.type === 'ExportDefaultDeclaration'
+            ? 'default'
+            : declaration &&
+                'id' in declaration &&
+                declaration.id?.type === 'Identifier'
+              ? declaration.id.name
+              : undefined
+
+        if (
+          exported &&
+          (declaration?.type === 'FunctionDeclaration' ||
+            declaration?.type === 'ClassDeclaration' ||
+            declaration?.type === 'ArrowFunctionExpression' ||
+            declaration?.type === 'FunctionExpression')
+        )
+          functions.add(exported)
+        if (declaration?.type === 'VariableDeclaration')
+          for (const item of declaration.declarations)
+            if (
+              item.id.type === 'Identifier' &&
+              (item.init?.type === 'ArrowFunctionExpression' ||
+                item.init?.type === 'FunctionExpression' ||
+                item.init?.type === 'ClassExpression')
+            )
+              functions.add(item.id.name)
+      }
+
+      // A merged namespace can carry style definitions beside the function.
+      for (const statement of program.body) {
+        const declaration =
+          statement.type === 'ExportNamedDeclaration'
+            ? statement.declaration
+            : statement
+        if (
+          declaration?.type === 'TSModuleDeclaration' &&
+          declaration.id.type === 'Identifier'
+        )
+          functions.delete(declaration.id.name)
+      }
+      if (functions.has(name)) return true
+
+      for (const statement of program.body) {
+        if (
+          statement.type !== 'ExportNamedDeclaration' ||
+          !statement.source ||
+          statement.exportKind === 'type'
+        )
+          continue
+
+        for (const specifier of statement.specifiers) {
+          const exported =
+            specifier.exported.type === 'Identifier'
+              ? specifier.exported.name
+              : specifier.exported.value
+          if (specifier.exportKind === 'type' || exported !== name) continue
+
+          const target = await options.resolve(statement.source.value, path)
+          if (!target || !inside(directory, target)) return false
+          return callable(
+            target,
+            specifier.local.type === 'Identifier'
+              ? specifier.local.name
+              : specifier.local.value,
+            seen,
+          )
+        }
+      }
+      return false
+    }
+
+    async function visit(path: string) {
+      const moduleId = id(path)
+      if (Object.hasOwn(modules, moduleId)) return
+
+      const entry = await parse(path)
+      modules[moduleId] = entry.source
+      programs.set(moduleId, entry.parsed)
+      const links: Record<string, string | null> = Object.create(null)
+      imports[moduleId] = links
+
+      for (const node of entry.parsed.program.body) {
+        if (
+          (node.type !== 'ImportDeclaration' &&
+            node.type !== 'ExportNamedDeclaration' &&
+            node.type !== 'ExportAllDeclaration') ||
+          !node.source
+        )
+          continue
+
+        const specifier = node.source.value
+        links[specifier] = null
+        if (
+          (node.type === 'ImportDeclaration'
+            ? node.importKind === 'type'
+            : node.exportKind === 'type') ||
+          ('specifiers' in node &&
+            node.specifiers.length &&
+            node.specifiers.every((specifier) =>
+              specifier.type === 'ImportSpecifier'
+                ? specifier.importKind === 'type'
+                : specifier.type === 'ExportSpecifier' &&
+                  specifier.exportKind === 'type',
+            ))
+        )
+          continue
+        if (
+          specifier === 'zyzz' ||
+          (specifier.startsWith('zyzz/') && specifier !== 'zyzz/default')
+        ) {
+          authored = true
+          continue
+        }
+        if (
+          /^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(specifier) ||
+          specifier.includes('?')
+        )
+          continue
+
+        const target = await options.resolve(specifier, path)
+        if (
+          !target ||
+          !Path.isAbsolute(target) ||
+          !/\.[cm]?[jt]sx?$/.test(target)
+        )
+          continue
+
+        if (!inside(directory, target)) {
+          if (await link(target)) links[specifier] = target
+          continue
+        }
+
+        if ('specifiers' in node && node.specifiers.length) {
+          const names = node.specifiers.map((item) => {
+            if (item.type === 'ImportDefaultSpecifier') return 'default'
+            if (item.type === 'ImportNamespaceSpecifier') return undefined
+            if (item.type === 'ImportSpecifier')
+              return item.importKind === 'type'
+                ? null
+                : item.imported.type === 'Identifier'
+                  ? item.imported.name
+                  : item.imported.value
+            if (item.exportKind === 'type') return null
+            return item.local.type === 'Identifier'
+              ? item.local.name
+              : item.local.value
+          })
+          const runtime = await Promise.all(
+            names.map((name) =>
+              name === null
+                ? true
+                : name === undefined
+                  ? false
+                  : callable(target, name),
+            ),
+          )
+          if (runtime.every(Boolean)) continue
+        }
+
+        links[specifier] = id(target)
+        await visit(target)
+      }
+    }
+
+    await visit(file)
+    if (!authored && !Object.keys(contracts).length) return undefined
+
+    const inputs = Crypto.createHash('sha256')
+      .update(JSON.stringify([modules, contracts, imports]))
+      .digest('hex')
+    const cached = derived.get(file)
+    if (cached?.inputs === inputs) return cached.contract
+
+    const graph = (() => {
+      try {
+        return Graph.compile({
+          [Syntax.cache]: programs,
+          compiler: false,
+          contracts,
+          imports,
+          modules,
+        })
+      } catch (error) {
+        throw new Error(
+          `Unable to derive the Zyzz contract of ${file}: ${(error as Error).message}`,
+          { cause: error },
+        )
+      }
+    })()
+
+    const contract = graph.contracts[id(file)]
+    derived.set(file, { contract, inputs })
+    return contract
+  }
+
+  return {
+    /**
+     * Returns the shipped `<file>.zyzz.json` contract, or derives it when the
+     * package depends on Zyzz and the module graph reaches its authoring APIs.
+     * Undefined marks a plain runtime import.
+     */
+    read(file: string, options: read.Options) {
+      return lookup(file, options, new Set())
+    },
+  }
+}
+
+/** Contract lookup contracts. */
+export declare namespace read {
+  /** Capabilities of the requesting bundler. */
+  type Options = {
+    /** Reads a file, rejecting with `ENOENT` when it is missing. Every file whose content or absence affects the contract passes through it. */
+    readonly read: (file: string) => Promise<string>
+    /** Rethrows the missing sidecar error when no contract can be derived. */
+    readonly required?: boolean | undefined
+    /** Resolves a specifier with the bundler's conditions. Undefined marks an external. */
+    readonly resolve: (
+      specifier: string,
+      importer: string,
+    ) => Promise<string | undefined>
+  }
+}
+
+function inside(directory: string, file: string) {
+  const relative = Path.relative(directory, file)
+
+  return (
+    !relative.startsWith(`..${Path.sep}`) &&
+    relative !== '..' &&
+    !Path.isAbsolute(relative) &&
+    !relative.split(Path.sep).includes('node_modules')
+  )
+}
+
+/** Finds the named package owning a file, when its manifest declares Zyzz. */
+async function manifest(file: string, options: read.Options) {
+  for (let directory = Path.dirname(file); ; ) {
+    const data = await options.read(Path.join(directory, 'package.json')).then(
+      (source) => JSON.parse(source) as Record<string, unknown>,
+      (error: NodeJS.ErrnoException) => {
+        if (error.code !== 'ENOENT') throw error
+        return undefined
+      },
+    )
+
+    // Nested manifests without a name, such as `{"type":"module"}`, belong to the enclosing package.
+    if (typeof data?.name === 'string')
+      return [
+        'dependencies',
+        'devDependencies',
+        'optionalDependencies',
+        'peerDependencies',
+      ].some((key) => {
+        const dependencies = data[key]
+        return (
+          !!dependencies &&
+          typeof dependencies === 'object' &&
+          Object.hasOwn(dependencies, 'zyzz')
+        )
+      })
+        ? { directory, name: data.name }
+        : undefined
+
+    const parent = Path.dirname(directory)
+    if (parent === directory) return undefined
+    directory = parent
+  }
+}

package/src/react-native/internal/Tokens.ts

@@ -32,12 +32,11 @@ export function resolve(
           (metadata.contract[Token.identity] !== undefined &&
             metadata.contract[Token.identity] ===
               value.contract[Token.identity]))
-      const next = shared
-        ? Object.hasOwn(metadata.values, value.path)
-          ? metadata.values[value.path]
-          : undefined
-        : value.value
-      if (next === undefined) throw new Error('Theme is missing a live token.')
+      // A set sharing its contract with an extension lacks the extension's added paths.
+      const next =
+        shared && Object.hasOwn(metadata.values, value.path)
+          ? metadata.values[value.path]!
+          : value.value
       active.add(value)
       const result = scalar(next)
       active.delete(value)

package/src/unplugin/index.ts

@@ -11,7 +11,9 @@ import type { UnpluginBuildContext } from 'unplugin'
 import * as Graph from '../compiler/Graph.js'
 import * as AtRules from '../compiler/internal/AtRules.js'
 import * as Catalogs from '../compiler/internal/Catalogs.js'
+import * as ClassName from '../web/internal/ClassName.js'
 import * as Contract from '../compiler/internal/Contract.js'
+import * as Contracts from '../node/internal/Contracts.js'
 import * as Vite from '../vite/index.js'
 import * as ThemeRules from '../web/internal/Themes.js'
 
@@ -32,6 +34,7 @@ const portable = createUnplugin<Options | undefined, false>(
   (options = {}, meta) => {
     const root = Path.resolve(options.root ?? process.cwd())
     const compiler = Graph.create()
+    const packages = Contracts.create()
     const snapshot = Snapshot.create()
     let graph: Graph.compile.ReturnType | undefined
     let pending: Promise<void> | undefined
@@ -204,20 +207,17 @@ const portable = createUnplugin<Options | undefined, false>(
             required = false,
           ): Promise<boolean> {
             if (Object.hasOwn(contracts, file)) return true
-            const sidecar = `${file}.zyzz.json`
 
-            files.add(sidecar)
-            try {
-              contracts[file] = await snapshot.read(sidecar)
-            } catch (error) {
-              if (
-                !required &&
-                (error as NodeJS.ErrnoException).code === 'ENOENT'
-              )
-                return false
-
-              throw error
-            }
+            const source = await packages.read(file, {
+              read(path) {
+                files.add(path)
+                return snapshot.read(path)
+              },
+              required,
+              resolve,
+            })
+            if (source === undefined) return false
+            contracts[file] = source
             const metadata = Contract.read(contracts[file]!, new Map(), file)
             for (const section of metadata.stylesheets) {
               let owner = file
@@ -287,6 +287,7 @@ const portable = createUnplugin<Options | undefined, false>(
 
           // Only the combined stylesheet is emitted, so generated theme rules are shared once.
           const result = compiler.compile({
+            [ClassName.complete]: true,
             [ThemeRules.shared]: 'all',
             [Syntax.cache]: snapshot.programs(modules),
             compiler: options.compiler,
@@ -354,6 +355,7 @@ const portable = createUnplugin<Options | undefined, false>(
             boundary: string,
             outputDirectory = '.',
             targets?: Readonly<Record<string, string>>,
+            emitted: ReadonlySet<string> = new Set(),
           ) {
             const urls = new Set<string>()
             AtRules.transform({
@@ -405,6 +407,18 @@ const portable = createUnplugin<Options | undefined, false>(
                 : { inputSourceMap: map, sourceMap: true }),
               visitor: {
                 Rule(rule) {
+                  // Shared rules repeat in each module that uses them, so keep the first.
+                  if (rule.type === 'style') {
+                    const [selector, ...others] = rule.value.selectors
+                    const [component, ...rest] = selector ?? []
+                    if (
+                      !others.length &&
+                      !rest.length &&
+                      component?.type === 'class' &&
+                      emitted.has(component.name)
+                    )
+                      return []
+                  }
                   if (rule.type !== 'import') return
                   const url = replacements.get(rule.value.url)
                   if (url) return AtRules.relocateImport(rule.value, url)
@@ -435,6 +449,7 @@ const portable = createUnplugin<Options | undefined, false>(
             },
           ]
           const seen = new Set<string>()
+          const units = new Set<string>()
           async function visit(id: string): Promise<void> {
             if (seen.has(id)) return
             seen.add(id)
@@ -442,12 +457,19 @@ const portable = createUnplugin<Options | undefined, false>(
               await visit(dependency)
             const output = result.modules[id]
             if (output) {
+              const names = [...(output[ClassName.units]?.values() ?? [])].map(
+                (decision) => decision.name,
+              )
               const processed = await stylesheet(
                 output.css,
                 JSON.stringify(output.cssMap),
                 Path.join(root, id.slice(4)),
                 await Fs.realpath(root),
+                '.',
+                undefined,
+                new Set(names.filter((name) => units.has(name))),
               )
+              for (const name of names) units.add(name)
               chunks.push({
                 code: Buffer.from(processed.code).toString(),
                 map: Buffer.from(processed.map!).toString(),