zyzz 0.0.0 → 0.0.3

package/src/internal/Value.ts

@@ -0,0 +1,320 @@
+/**
+ * Describes declaration fallbacks and separates importance from scalar values.
+ * @module
+ */
+import type * as Binding from './Binding.js'
+import type * as FunctionValue from './FunctionValue.js'
+import type * as RuleReference from './RuleReference.js'
+import type * as Grid from './Grid.js'
+import * as Lexical from './Lexical.js'
+import * as Literal from './Literal.js'
+import type * as Numeric from './Numeric.js'
+import * as Token from './Token.js'
+
+/** Scalar declarations optionally carrying a trailing importance marker. */
+export type Atom<value> =
+  | value
+  | `${Extract<value, string | number>} !important`
+
+/**
+ * Accepts canonical and case-insensitive CSS literals without folding token names or emitted data.
+ * Checks authored properties and retains validated input types to avoid expanding whole-property fallback unions.
+ */
+export type Accepted<style, properties> = {
+  [property in keyof style]: property extends keyof properties
+    ? style[property] extends Binding.Reference
+      ? Binding.Reference<style[property]['type']> extends Exclude<
+          properties[property],
+          undefined
+        >
+        ? style[property]
+        : never
+      : FunctionValue.Is<style[property]> extends true
+        ? FunctionValue.Accepted<
+            style[property],
+            Exclude<properties[property], undefined>,
+            property
+          >
+        : Exclude<style[property], undefined> extends Exclude<
+              properties[property],
+              undefined
+            >
+          ? Exclude<style[property], undefined>
+          : property extends keyof Literal.Properties
+            ? style[property] extends string | readonly (number | string)[]
+              ? Fold<style[property]> extends Input<
+                  | Lowercase<Extract<Literal.Properties[property], string>>
+                  | Extract<Literal.Properties[property], number>
+                >
+                ? style[property]
+                : Exclude<properties[property], undefined>
+              : Exclude<properties[property], undefined>
+            : Exclude<properties[property], undefined>
+    : never
+}
+
+type Fold<value> = value extends string
+  ? Lexical.Fold<Canonical<Spaces<Normalized<Lexical.Normalized<value>>>>>
+  : value extends readonly unknown[]
+    ? { [key in keyof value]: Fold<value[key]> }
+    : value
+
+/** Refines concrete scalar spellings; already-broad property contracts need no literal refinement. */
+export type Checked<style, tokens = {}> = {
+  [property in keyof style]: style[property] extends string & Binding.Reference
+    ? style[property] extends Binding.Reference<'*'>
+      ? unknown
+      : Checked<
+          { [key in property]: Binding.Reference<style[property]['type']> },
+          tokens
+        >[property]
+    : Literal.Properties extends style
+      ? unknown
+      : Importance<style[property]> &
+          RuleReference.Check<style[property], property> &
+          (property extends keyof typeof Literal.rules
+            ? style[property] extends (property extends
+                | 'gridArea'
+                | 'gridColumn'
+                | 'gridColumnEnd'
+                | 'gridColumnStart'
+                | 'gridRow'
+                | 'gridRowEnd'
+                | 'gridRowStart'
+                ? Fold<style[property]> extends Grid.Checked<
+                    Fold<style[property]>,
+                    property extends 'gridArea'
+                      ? 4
+                      : property extends 'gridColumn' | 'gridRow'
+                        ? 2
+                        : 1
+                  >
+                  ? unknown
+                  : never
+                : unknown) &
+                Check<
+                  style[property],
+                  Token.Names<tokens, property>,
+                  (typeof Literal.rules)[property]
+                >
+              ? unknown
+              : never
+            : unknown)
+}
+
+type Importance<value> = value extends readonly unknown[]
+  ? { [key in keyof value]: Importance<value[key]> }
+  : value extends `${infer body}!${infer suffix}`
+    ? body extends `${string}\\`
+      ? unknown
+      : Lowercase<TrimStart<Trim<Lexical.Normalized<suffix>>>> extends
+            | ''
+            | 'important'
+        ? value extends `${string} !important`
+          ? unknown
+          : never
+        : unknown
+    : unknown
+
+type Check<input, names, rule> =
+  FunctionValue.Is<input> extends true
+    ? input
+    : input extends readonly unknown[]
+      ? { [key in keyof input]: Check<input[key], names, rule> }
+      : input extends names
+        ? input
+        : input extends string
+          ? Plain<input> extends names
+            ? input
+            : Literal.Checked<
+                  Lexical.Fold<Plain<Normalized<Lexical.Normalized<input>>>>
+                > extends never
+              ? never
+              : Scalar<
+                    Lexical.Fold<Plain<Normalized<Lexical.Normalized<input>>>>,
+                    rule
+                  > extends never
+                ? never
+                : input
+          : Scalar<input, rule>
+
+type Scalar<input, rule> = number extends input
+  ? input
+  : input extends number | `${number}`
+    ? Numeric.Checked<
+        input,
+        rule extends { integer: true } ? true : false
+      > extends never
+      ? never
+      : Range<input, rule>
+    : input extends `${infer amount}${Literal.Unit | 'ms' | 's'}`
+      ? Range<amount, rule> extends never
+        ? never
+        : input
+      : input
+
+type Range<input, rule> = rule extends
+  | { kind: 'number' | 'percentage'; min: 0 | 1 }
+  | { negative: false }
+  ? input extends number | string
+    ? `${input}` extends `-${string}`
+      ? Numeric.Zero<input> extends true
+        ? rule extends { kind: 'number'; min: 1 }
+          ? never
+          : input
+        : never
+      : rule extends { kind: 'number'; min: 1 }
+        ? Numeric.Zero<input> extends true
+          ? never
+          : input
+        : input
+    : input
+  : input
+
+type Canonical<value extends string> = value extends `${infer body}!important`
+  ? `${Zeros<body>}!important`
+  : Zeros<value>
+
+type Zeros<value extends string> =
+  value extends `${infer before} ${infer after}`
+    ? `${Zeros<before>} ${Zeros<after>}`
+    : value extends `${infer before}/${infer after}`
+      ? `${Zeros<before>}/${Zeros<after>}`
+      : value extends `${infer before},${infer after}`
+        ? `${Zeros<before>},${Zeros<after>}`
+        : Zero<value>
+
+type Zero<value extends string> = [Numeric.Checked<value>] extends [never]
+  ? value
+  : Numeric.Zero<value> extends true
+    ? '0'
+    : value
+
+type Replace<
+  value extends string,
+  character extends string,
+  output extends string = '',
+> = value extends `${infer before}${character}${infer after}`
+  ? Replace<after, character, `${output}${before} `>
+  : `${output}${value}`
+
+type Collapse<value extends string> =
+  value extends `${infer before}  ${infer after}`
+    ? Collapse<`${before} ${after}`>
+    : value
+
+type Spaces<value extends string> = Collapse<
+  Replace<Replace<Replace<Replace<value, '\t'>, '\r'>, '\n'>, '\f'>
+>
+
+type Normalized<value extends string> =
+  TrimStart<Trim<value>> extends infer text extends string
+    ? text extends `${infer body}!${infer suffix}`
+      ? Lowercase<TrimStart<Trim<suffix>>> extends '' | 'important'
+        ? `${Trim<body>} !important`
+        : `${body}!${Normalized<suffix>}`
+      : text
+    : never
+
+type TrimStart<value extends string> =
+  value extends `${' ' | '\n' | '\r' | '\t' | '\f'}${infer body}`
+    ? TrimStart<body>
+    : value
+
+type Plain<value extends string> = value extends `${infer body}!${infer suffix}`
+  ? Lowercase<suffix> extends '' | 'important'
+    ? Trim<body>
+    : `${body}!${Plain<suffix>}`
+  : value
+
+type Trim<value extends string> =
+  value extends `${infer body}${' ' | '\n' | '\r' | '\t' | '\f'}`
+    ? Trim<body>
+    : value
+
+/** One atom or a nonempty ordered sequence of declaration fallback atoms. */
+export type Fallbacks<atom> = atom | readonly [atom, ...atom[]]
+
+/** One declaration or a nonempty ordered sequence of declaration fallbacks. */
+export type Input<value> = Fallbacks<Atom<Exclude<value, undefined>>>
+
+/** Splits a trailing importance marker without interpreting quoted or escaped text. */
+export function parse(
+  input: unknown,
+  property: keyof Literal.Properties,
+):
+  | { invalid: true }
+  | { important: boolean; value: number | string | Token.Expression }
+  | undefined {
+  if (Token.isExpression(input)) {
+    const text = input.parts
+      .map((part) => (typeof part === 'string' ? part : 'var(--z)'))
+      .join('')
+    const parsed = parse(text, property)
+    if (!parsed || 'invalid' in parsed) return parsed
+    if (typeof parsed.value === 'object') return undefined
+
+    const parts = [...input.parts]
+    let remaining = text.length - String(parsed.value).length
+
+    for (let index = parts.length - 1; remaining > 0 && index >= 0; index--) {
+      const part = parts[index]
+      if (typeof part !== 'string') return undefined
+
+      const count = Math.min(remaining, part.length)
+
+      parts[index] = part.slice(0, part.length - count)
+      remaining -= count
+    }
+
+    return { important: parsed.important, value: Token.compose(parts) }
+  }
+
+  if (typeof input !== 'string') return undefined
+
+  const valueText = input
+
+  function escaped(index: number): boolean {
+    let count = 0
+
+    while (index > 0 && valueText[index - 1] === '\\') {
+      count++
+      index--
+    }
+
+    return count % 2 === 1
+  }
+
+  let marker = input.lastIndexOf('!')
+
+  while (marker >= 0) {
+    const suffix = Lexical.normalize(input.slice(marker + 1)).replace(
+      /^[ \t\n\r\f]+|[ \t\n\r\f]+$/g,
+      '',
+    )
+
+    if (!escaped(marker) && (suffix === '' || suffix === 'important')) break
+
+    marker = marker === 0 ? -1 : input.lastIndexOf('!', marker - 1)
+  }
+
+  if (marker < 0) return undefined
+  if (input.slice(marker - 1) !== ' !important' || escaped(marker - 1))
+    return { invalid: true }
+
+  let end = marker
+
+  while (end > 0 && /[ \t\n\r\f]/.test(input[end - 1]!) && !escaped(end - 1))
+    end--
+
+  const text = input.slice(0, end)
+  const numeric =
+    Literal.rule(property)?.kind === 'number' ||
+    Literal.rule(property)?.kind === 'grid-line'
+  const value =
+    numeric && /^[+-]?(?:\d*\.\d+|\d+)(?:[eE][+-]?\d+)?$/.test(text)
+      ? Number(text)
+      : text
+
+  return { important: true as const, value }
+}

package/src/metro/Graph.ts

@@ -0,0 +1,78 @@
+/** Reads a closed local source graph for native authoring without evaluating modules. @module */
+import * as Fs from 'node:fs'
+import * as Path from 'node:path'
+import * as Parser from 'oxc-parser'
+import type * as Graph from '../compiler/Graph.js'
+
+/** Collects relative source imports; package and asset imports remain owned by Metro. */
+export function read(
+  filename: string,
+  source: string,
+  platform: string,
+  root: string,
+) {
+  const files = new Set<string>()
+  const modules: Record<string, string> = Object.create(null)
+  const imports: Record<string, Record<string, string | null>> = 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}`,
+      )
+    return relative
+  }
+  function visit(filename: string, source: string) {
+    files.add(filename)
+    const id = identity(filename)
+    if (Object.hasOwn(modules, id)) return
+    modules[id] = source
+    const resolved: Record<string, string | null> = Object.create(null)
+    imports[id] = resolved
+    for (const statement of Parser.parseSync(filename, source).program.body) {
+      if (
+        !('source' in statement) ||
+        !statement.source ||
+        typeof statement.source !== 'object' ||
+        !('value' in statement.source) ||
+        typeof statement.source.value !== 'string'
+      )
+        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, Fs.readFileSync(target, 'utf8'))
+    }
+  }
+  visit(filename, source)
+  return {
+    moduleId: identity(filename),
+    modules,
+    imports,
+    files: [...files],
+  } satisfies Pick<Graph.compile.Options, 'modules' | 'imports'> & {
+    moduleId: string
+    files: readonly string[]
+  }
+}

package/src/metro/Watch.ts

@@ -0,0 +1,88 @@
+/** Keeps Metro's transform cache and delta graph aligned with imported authoring. @module */
+import * as Crypto from 'node:crypto'
+import * as Fs from 'node:fs'
+import * as Path from 'node:path'
+import type { EventEmitter } from 'node:events'
+import * as Graph from './Graph.js'
+
+type Options = {
+  readonly platform?: string
+  readonly customTransformOptions?: Readonly<Record<string, unknown>>
+}
+type Bundler = {
+  getDependencyGraph(): Promise<{ getWatcher(): EventEmitter }>
+  transformFile(
+    filename: string,
+    options: Options,
+    buffer?: Buffer,
+  ): Promise<unknown>
+}
+/** Metro server methods used by its own serializers and development middleware. */
+export type Server = { getBundler(): { getBundler(): Bundler } }
+type Changes = {
+  rootDir: string
+  changes: {
+    addedFiles: Iterable<readonly [string, unknown]>
+    modifiedFiles: Iterable<readonly [string, unknown]>
+    removedFiles: Iterable<readonly [string, unknown]>
+  }
+}
+
+/** 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 dependencies = new Map<string, Map<string, Set<string>>>()
+  const transform = bundler.transformFile.bind(bundler)
+  bundler.transformFile = (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')
+    )
+      return transform(filename, options, buffer)
+    const source = buffer?.toString('utf8') ?? Fs.readFileSync(filename, 'utf8')
+    const input = Graph.read(filename, source, options.platform, root)
+    const platforms =
+      dependencies.get(filename) ?? new Map<string, Set<string>>()
+    platforms.set(options.platform, new Set(input.files))
+    dependencies.set(filename, platforms)
+    const hash = Crypto.hash('sha256', JSON.stringify(input))
+    return transform(
+      filename,
+      {
+        ...options,
+        customTransformOptions: {
+          ...options.customTransformOptions,
+          zyzzGraph: hash,
+        },
+      },
+      buffer,
+    )
+  }
+  graph.getWatcher().prependListener('change', (event: Changes) => {
+    const entries = [
+      ...event.changes.addedFiles,
+      ...event.changes.modifiedFiles,
+      ...event.changes.removedFiles,
+    ]
+    const changed = new Set(
+      entries.map(([path]) => Path.join(event.rootDir, path)),
+    )
+    const modified = new Map(event.changes.modifiedFiles)
+    const metadata = { isSymlink: false, modifiedTime: Date.now() }
+    for (const [filename, imports] of dependencies) {
+      if (
+        changed.has(filename) ||
+        ![...imports.values()].some((paths) =>
+          [...paths].some((path) => changed.has(path)),
+        ) ||
+        !Fs.existsSync(filename)
+      )
+        continue
+      modified.set(Path.relative(event.rootDir, filename), metadata)
+    }
+    event.changes = { ...event.changes, modifiedFiles: modified }
+  })
+}

package/src/metro/index.ts

@@ -0,0 +1,99 @@
+/** Configures native Zyzz compilation in Metro without a separate generation command. @module */
+import type { NativeOptions } from '../babel/index.js'
+import * as Crypto from 'node:crypto'
+import * as Fs from 'node:fs'
+import * as Module from 'node:module'
+import * as Path from 'node:path'
+import * as Watch from './Watch.js'
+
+/** 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 transformer configuration, including Expo's Babel transformer. */
+  readonly transformer?:
+    | {
+        /** Upstream Babel transformer to preserve. */
+        readonly babelTransformerPath?: string | undefined
+      }
+    | undefined
+}
+
+/**
+ * Preserves Metro configuration and chains Zyzz before the existing Babel transformer.
+ * Writes an immutable adapter entrypoint under `.zyzz/metro`, not compiled application files.
+ */
+export function zyzz<const config extends Config>(
+  config: config,
+  options: Omit<
+    NativeOptions,
+    'platform' | 'target' | 'moduleId' | 'modules' | 'imports' | 'colorScheme'
+  > = {},
+): zyzz.ReturnType<config> {
+  if (Object.hasOwn(options, 'colorScheme'))
+    throw new Error(
+      'Select colorScheme through the React provider, not Metro configuration.',
+    )
+  const root = Path.resolve(config.projectRoot ?? process.cwd())
+  const require = Module.createRequire(Path.join(root, 'package.json'))
+  const upstream = config.transformer?.babelTransformerPath
+  if (!upstream)
+    throw new Error('Zyzz requires a configured Metro Babel transformer.')
+
+  const adapter = Module.createRequire(import.meta.url).resolve(
+    'zyzz/metro/transformer',
+  )
+  const code = `module.exports = require(${JSON.stringify(adapter)}).create(${JSON.stringify(require.resolve(upstream))}, ${JSON.stringify({ ...options, root })});\n`
+  const directory = Path.join(root, '.zyzz', 'metro')
+  const filename = Path.join(directory, `${Crypto.hash('sha256', code)}.cjs`)
+  Fs.mkdirSync(directory, { recursive: true })
+  try {
+    Fs.writeFileSync(filename, code, { flag: 'wx' })
+  } catch (error) {
+    if (!(error instanceof Error && 'code' in error && error.code === 'EEXIST'))
+      throw error
+  }
+
+  const enhance =
+    config.server &&
+    (Reflect.get(config.server, 'enhanceMiddleware') as
+      | ((middleware: Middleware, server: Watch.Server) => Middleware)
+      | undefined)
+  type Middleware = (...args: unknown[]) => unknown
+  return {
+    ...config,
+    server: {
+      ...config.server,
+      enhanceMiddleware(middleware: Middleware, server: Watch.Server) {
+        const ready = Watch.attach(server, root)
+        const next = enhance
+          ? enhance.call(config.server, middleware, server)
+          : middleware
+        return (...args: unknown[]) =>
+          ready.then(
+            () => next(...args),
+            (error: unknown) => {
+              const report = args[2]
+              if (typeof report === 'function') return report(error)
+              throw error
+            },
+          )
+      },
+    },
+    transformer: { ...config.transformer, babelTransformerPath: filename },
+  } as zyzz.ReturnType<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'> & {
+    /** Existing transformer configuration with the native compilation entrypoint. */
+    transformer: Omit<
+      NonNullable<config['transformer']>,
+      'babelTransformerPath'
+    > & { babelTransformerPath: string }
+  }
+}

package/src/metro/transformer.ts

@@ -0,0 +1,97 @@
+/** Chains native authoring compilation into the configured Metro Babel transformer. @module */
+import type * as Babel from '@babel/core'
+import * as Crypto from 'node:crypto'
+import * as Fs from 'node:fs'
+import * as Module from 'node:module'
+import * as Path from 'node:path'
+import * as Graph from './Graph.js'
+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 plugins?: readonly Babel.PluginItem[] | undefined
+  readonly src: string
+}
+
+type Upstream = {
+  getCacheKey?: ((...args: readonly unknown[]) => string) | undefined
+  transform: (input: Input) => unknown
+}
+
+/** Creates a transformer with isolated options and the existing upstream implementation. */
+export function create(
+  upstreamPath: string,
+  options: Omit<
+    NativeOptions,
+    'platform' | 'target' | 'moduleId' | 'modules' | 'imports' | 'colorScheme'
+  > & { readonly root: string },
+) {
+  const upstream: Upstream = Module.createRequire(import.meta.url)(upstreamPath)
+  return {
+    getCacheKey(...args: readonly unknown[]) {
+      const hash = Crypto.createHash('sha256')
+      hash.update(upstream.getCacheKey?.(...args) ?? '')
+      hash.update(JSON.stringify(options))
+      function sources(directory: string) {
+        for (const entry of Fs.readdirSync(directory, {
+          withFileTypes: true,
+        }).sort((a, b) => a.name.localeCompare(b.name))) {
+          if (
+            entry.name.startsWith('.') ||
+            ['node_modules', 'dist'].includes(entry.name)
+          )
+            continue
+          const path = Path.join(directory, entry.name)
+          if (entry.isDirectory()) sources(path)
+          else if (entry.isFile() && /\.[cm]?[jt]sx?$/.test(entry.name)) {
+            hash.update(path)
+            hash.update(Fs.readFileSync(path))
+          }
+        }
+      }
+      sources(options.root)
+      // Metro only hashes the generated entrypoint. Include the library implementation it delegates to.
+      const root = Path.resolve(import.meta.dirname, '..')
+      for (const name of Fs.readdirSync(root, { recursive: true })
+        .map(String)
+        .sort()) {
+        if (
+          /\.[cm]?[jt]sx?$/.test(name) &&
+          !/\.(?:d|test|test-d|bench|bench-d)\.[cm]?[jt]sx?$/.test(name)
+        ) {
+          hash.update(name)
+          hash.update(Fs.readFileSync(Path.join(root, name)))
+        }
+      }
+      return hash.digest('hex')
+    },
+    transform(input: Input) {
+      const platform = input.options.platform
+      const filename = Path.resolve(options.root, input.filename)
+      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}`)
+      )
+        return upstream.transform(input)
+      return upstream.transform({
+        ...input,
+        plugins: [
+          [
+            zyzz,
+            {
+              ...options,
+              platform,
+              target: 'native',
+              ...Graph.read(filename, input.src, platform, options.root),
+            },
+          ],
+          ...(input.plugins ?? []),
+        ],
+      })
+    },
+  }
+}