zyzz 0.0.0 → 0.0.3

package/src/compiler/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Exposes static source extraction and module rewriting without a file host.
+ * @module
+ */
+/** Source graph compilation with shared theme contracts. */
+export * as Graph from './Graph.js'
+/** Static native source compilation and finite callable output. */
+export * as Native from './Native.js'
+/** Static source extraction without application evaluation or file loading. */
+export * as Source from './Source.js'
+/** Literal module rewriting and source maps for web output. */
+export * as Transform from './Transform.js'

package/src/compiler/internal/Applications.ts

@@ -0,0 +1,378 @@
+/** Finds nonescaping local static callables whose applications can become props. @module */
+import type * as Ast from '@oxc-project/types'
+import * as Walker from 'oxc-walker'
+import * as Scope from './Scope.js'
+import type * as Source from '../Source.js'
+
+/** Conservatively proves direct applications without changing binding reads. */
+export function create(
+  program: Ast.Program,
+  calls: readonly Source.Call[],
+  options: create.Options = {},
+): Collector | undefined {
+  const definitions = new Map(calls.map((call) => [call.start, call]))
+  const memberBindings = new Map<number, string>()
+  const referencedDefinitions = new Set<string>()
+  const namespaceCounts = new Map<string, number>()
+
+  for (const statement of program.body) {
+    const node =
+      statement.type === 'ExportNamedDeclaration'
+        ? statement.declaration
+        : statement
+
+    if (node?.type === 'TSModuleDeclaration' && node.id.type === 'Identifier')
+      namespaceCounts.set(
+        node.id.name,
+        (namespaceCounts.get(node.id.name) ?? 0) + 1,
+      )
+  }
+
+  const candidates: {
+    declaration: {
+      id: Extract<Ast.Node, { type: 'Identifier' }>
+    }
+    direct: Source.Call | undefined
+    members: Map<string, Source.Call>
+  }[] = []
+
+  for (const statement of program.body) {
+    if (
+      statement.type === 'TSModuleDeclaration' &&
+      statement.id.type === 'Identifier' &&
+      statement.body?.type === 'TSModuleBlock'
+    ) {
+      const members = new Map<string, Source.Call>()
+      let valid = true
+
+      for (const member of statement.body.body) {
+        const node =
+          member.type === 'ExportNamedDeclaration'
+            ? member.declaration
+            : undefined
+
+        if (node?.type !== 'VariableDeclaration' || node.kind !== 'const') {
+          valid = false
+          break
+        }
+
+        for (const declaration of node.declarations) {
+          const call =
+            declaration.init && definitions.get(declaration.init.start)
+
+          if (
+            declaration.id.type !== 'Identifier' ||
+            declaration.init?.type !== 'CallExpression' ||
+            declaration.init.end !== call?.end ||
+            members.has(declaration.id.name)
+          ) {
+            valid = false
+            break
+          }
+
+          members.set(declaration.id.name, call)
+          memberBindings.set(declaration.id.start, call.name)
+        }
+      }
+
+      if (valid && members.size)
+        candidates.push({
+          declaration: { id: statement.id },
+          direct: undefined,
+          members,
+        })
+
+      continue
+    }
+
+    // Exported values can escape and object members can subsequently be replaced.
+    if (statement.type !== 'VariableDeclaration' || statement.kind !== 'const')
+      continue
+
+    for (const declaration of statement.declarations) {
+      if (declaration.id.type !== 'Identifier' || !declaration.init) continue
+
+      const members = new Map<string, Source.Call>()
+      const candidate = definitions.get(declaration.init.start)
+
+      const direct =
+        declaration.init.type === 'CallExpression' &&
+        declaration.init.end === candidate?.end
+          ? candidate
+          : undefined
+
+      if (!direct) {
+        if (declaration.init.type !== 'ObjectExpression') continue
+
+        let valid = true
+
+        for (const property of declaration.init.properties) {
+          if (
+            property.type !== 'Property' ||
+            property.computed ||
+            property.method ||
+            property.kind !== 'init'
+          ) {
+            valid = false
+            break
+          }
+
+          const key =
+            property.key.type === 'Identifier' ? property.key.name : undefined
+          const candidate = definitions.get(property.value.start)
+
+          const call =
+            property.value.type === 'CallExpression' &&
+            property.value.end === candidate?.end
+              ? candidate
+              : undefined
+
+          if (!key || key === '__proto__' || !call || members.has(key)) {
+            valid = false
+            break
+          }
+
+          members.set(key, call)
+        }
+
+        if (!valid || !members.size) continue
+      }
+
+      candidates.push({
+        declaration: { ...declaration, id: declaration.id },
+        direct,
+        members,
+      })
+    }
+  }
+
+  if (!candidates.length) return undefined
+
+  const lexical = new Set<Ast.Node>()
+  const scope = new Scope.Tracker({ preserveExitedScopes: true })
+  Walker.walk(program, { scopeTracker: scope })
+  scope.freeze()
+  const ancestors: Ast.Node[] = []
+  Walker.walk(program, {
+    scopeTracker: scope,
+    enter(node, parent) {
+      ancestors.push(node)
+      if (
+        node.type !== 'Identifier' ||
+        !parent ||
+        !Walker.isReferenceIdentifier(node, parent)
+      )
+        return
+      if (
+        ancestors.some((node) =>
+          [
+            'TSTypeQuery',
+            'TSTypeAnnotation',
+            'TSTypeAliasDeclaration',
+            'TSInterfaceDeclaration',
+            'TSTypeParameterInstantiation',
+            'TSTypeParameterDeclaration',
+          ].includes(node.type),
+        )
+      )
+        return
+      const binding = scope.getDeclaration(node.name, { mode: 'value' })
+      const id = binding?.node
+      const member = id && memberBindings.get(id.start)
+      if (member) referencedDefinitions.add(member)
+      if (
+        id &&
+        candidates.some(
+          (candidate) => candidate.declaration.id.start === id.start,
+        )
+      )
+        lexical.add(node)
+    },
+    leave() {
+      ancestors.pop()
+    },
+  })
+
+  const parents = new Map<Ast.Node, Ast.Node>()
+  const references = new Map<
+    string,
+    Extract<Ast.Node, { type: 'Identifier' }>[]
+  >(candidates.map(({ declaration }) => [declaration.id.name, []]))
+  let evaluation = false
+
+  return {
+    dead() {
+      if (evaluation) return new Set<string>()
+
+      const result = new Set<string>()
+      const counts = new Map<string, number>()
+
+      for (const { declaration } of candidates)
+        counts.set(
+          declaration.id.name,
+          (counts.get(declaration.id.name) ?? 0) + 1,
+        )
+
+      for (const { declaration, direct, members } of candidates) {
+        if (
+          counts.get(declaration.id.name)! > 1 ||
+          (namespaceCounts.get(declaration.id.name) ?? 0) > 1
+        )
+          continue
+
+        const reads = references.get(declaration.id.name) ?? []
+
+        if (direct) {
+          if (!reads.length) result.add(direct.name)
+          continue
+        }
+
+        const used = new Set<string>()
+        let escapes = false
+
+        for (const reference of reads) {
+          const member = parents.get(reference)
+
+          if (
+            member?.type !== 'MemberExpression' ||
+            member.object !== reference ||
+            member.computed ||
+            member.optional ||
+            member.property.type !== 'Identifier'
+          ) {
+            escapes = true
+            break
+          }
+
+          used.add(member.property.name)
+        }
+
+        if (!escapes)
+          for (const [name, call] of members)
+            if (!used.has(name) && !referencedDefinitions.has(call.name))
+              result.add(call.name)
+      }
+
+      return result
+    },
+    enter(node, parent) {
+      if (
+        node.type === 'MemberExpression' &&
+        node.object.type === 'Identifier' &&
+        references.has(node.object.name) &&
+        parent
+      )
+        parents.set(node, parent)
+
+      if (node.type !== 'Identifier') return
+
+      if (node.name === 'eval') evaluation = true
+
+      if (!lexical.has(node)) return
+
+      const nodes = references.get(node.name)
+      if (!nodes) return
+
+      nodes.push(node)
+
+      if (parent) parents.set(node, parent)
+    },
+    find() {
+      if (evaluation) return []
+
+      const result: Application[] = []
+
+      for (const { declaration, direct, members } of candidates) {
+        const applications: Application[] = []
+        let valid = true
+
+        for (const reference of references.get(declaration.id.name) ?? []) {
+          if (reference === declaration.id) continue
+
+          let callee: Ast.Node = reference
+          let call = direct
+
+          if (!direct) {
+            const member = parents.get(reference)
+
+            if (
+              member?.type !== 'MemberExpression' ||
+              member.object !== reference ||
+              member.computed ||
+              member.optional ||
+              member.property.type !== 'Identifier'
+            ) {
+              valid = false
+              break
+            }
+
+            call = members.get(member.property.name)
+            callee = member
+          }
+
+          if (
+            call?.composition ||
+            call?.runtimeComposition ||
+            (!options.dynamic && (call?.slots || call?.recipe))
+          )
+            continue
+
+          const application = parents.get(callee)
+
+          if (
+            !call ||
+            application?.type !== 'CallExpression' ||
+            application.callee !== callee ||
+            application.optional ||
+            (!options.dynamic && application.arguments.length)
+          ) {
+            valid = false
+            break
+          }
+
+          applications.push({
+            calleeEnd: callee.end,
+            end: application.end,
+            name: call.name,
+            start: application.start,
+          })
+        }
+
+        if (valid) result.push(...applications)
+      }
+
+      return result
+    },
+  }
+}
+
+/** Proven call site and its compiled definition. */
+type Application = {
+  /** End of the original binding or property read. */
+  readonly calleeEnd: number
+  /** End of the application. */
+  readonly end: number
+  /** Extracted class identity. */
+  readonly name: string
+  /** Start of the application. */
+  readonly start: number
+}
+
+/** Binding references gathered during the transform's existing walk. */
+type Collector = {
+  /** Definitions with no observable value reads, retaining escaped containers. */
+  dead: () => ReadonlySet<string>
+  /** Records relevant reads and their immediate parents. */
+  enter: (node: Ast.Node, parent: Ast.Node | null | undefined) => void
+  /** Resolves applications after traversal completes. */
+  find: () => readonly Application[]
+}
+
+/** Local application collection modes. */
+export declare namespace create {
+  /** Controls whether arguments are retained for fixed runtime compositions. */
+  type Options = {
+    /** Includes recipe/value applications while preserving their runtime calls. */
+    readonly dynamic?: boolean | undefined
+  }
+}

package/src/compiler/internal/AtRules.ts

@@ -0,0 +1,202 @@
+/** Adapts standard descriptor extensions that precede the pinned parser's grammar. @module */
+import * as ColorProfiles from './ColorProfiles.js'
+import * as Descriptors from './Descriptors.js'
+import * as Functions from './Functions.js'
+import * as Identifiers from './Identifiers.js'
+import * as Keyframes from './Keyframes.js'
+import * as Lightning from 'lightningcss'
+import * as Properties from './Properties.js'
+import * as ViewTransitions from './ViewTransitions.js'
+
+/** Parses structured contributions while retaining newer font descriptors. */
+export function transform<C extends Lightning.CustomAtRules>(
+  options: Lightning.TransformOptions<C>,
+): Lightning.TransformResult {
+  // Stylesheets without an @ byte cannot require at-keyword transport.
+  if (!options.code.includes(64)) return Lightning.transform(options)
+
+  const source = new TextDecoder().decode(options.code)
+  if (
+    /@(?:counter-style|custom-media|document|font-face|font-palette-values|page)\b/i.test(
+      source,
+    )
+  )
+    Descriptors.validate(source)
+  if (/@function\b/i.test(source)) Functions.validate(source)
+  const properties = /@property\b/i.test(source) && Properties.validate(source)
+  let propertyMarker = 'zyzz-property'
+  while (source.includes(propertyMarker)) propertyMarker += '-x'
+  validateFeatures(source)
+  // The pinned visitor cannot round-trip the nested Option used for anonymous import layers.
+  // Give emitted anonymous layers a temporary name while URL visitors run, then restore them.
+  let importMarker = 'zyzz-anonymous-import'
+  while (source.includes(importMarker)) importMarker += '-x'
+  const imports = options.visitor
+    ? source.replace(
+        /^(\s*@import\s+(?:url\()?"(?:\\.|[^"\\])*"\)?\s+)layer(?=[\s;])/gm,
+        `$1layer(${importMarker})`,
+      )
+    : source
+  const lower = source.toLowerCase()
+  let marker = '-zyzz-ffv-000000000'
+  let suffix = 0
+  while (lower.includes(marker))
+    marker = `-zyzz-ffv-${(++suffix).toString(36).padStart(9, '0')}`
+  let paletteMarker = '-zyzz-fpv-000000000'
+  let paletteSuffix = 0
+  while (lower.includes(paletteMarker))
+    paletteMarker = `-zyzz-fpv-${(++paletteSuffix).toString(36).padStart(9, '0')}`
+  // The pinned parser silently drops font-family lists from palette rules.
+  const registered = properties
+    ? rename(imports, 'property', propertyMarker)
+    : imports
+  const features = lower.includes('@font-feature-values')
+    ? rename(registered, 'font-feature-values', marker)
+    : registered
+  const renamed = lower.includes('@font-palette-values')
+    ? rename(features, 'font-palette-values', paletteMarker)
+    : features
+  if (lower.includes('@color-profile')) ColorProfiles.validate(renamed)
+  if (lower.includes('@keyframes')) Keyframes.validate(renamed)
+  if (source.toLowerCase().includes('@view-transition')) {
+    let marker = '-zyzz-view-transition'
+    while (source.includes(marker)) marker += '-x'
+    ViewTransitions.validate(rename(renamed, 'view-transition', marker), marker)
+  }
+  if (source === renamed) return Lightning.transform(options)
+  const result = Lightning.transform({
+    ...options,
+    code: new TextEncoder().encode(renamed),
+  })
+  return {
+    ...result,
+    code: new TextEncoder().encode(
+      rename(
+        rename(
+          rename(
+            new TextDecoder()
+              .decode(result.code)
+              .replaceAll(`layer(${importMarker})`, 'layer'),
+            propertyMarker,
+            'property',
+          ),
+          marker,
+          'font-feature-values',
+        ),
+        paletteMarker,
+        'font-palette-values',
+      ),
+    ),
+  }
+}
+
+// Contribution extraction validates feature blocks and their descriptors before this adapter.
+// At-keyword substitution keeps Lightning's token/URL traversal without discarding newer descriptors.
+/** Renames actual at-keywords without touching strings, comments, or function arguments. */
+export function rename(source: string, before: string, after: string): string {
+  let output = ''
+  let quote = ''
+  let parentheses = 0
+  for (let index = 0; index < source.length; index++) {
+    const char = source[index]!
+    if (char === '\\') {
+      output += char + (source[++index] ?? '')
+      continue
+    }
+    if (quote) {
+      output += char
+      if (char === quote) quote = ''
+      continue
+    }
+    if (char === '"' || char === "'") quote = char
+    else if (char === '/' && source[index + 1] === '*') {
+      const end = source.indexOf('*/', index + 2)
+      if (end < 0) return source
+      output += source.slice(index, end + 2)
+      index = end + 1
+      continue
+    } else if (char === '(') parentheses++
+    else if (char === ')') parentheses--
+    else if (
+      !parentheses &&
+      char === '@' &&
+      source.slice(index + 1, index + 1 + before.length).toLowerCase() ===
+        before &&
+      !/[\w-]/.test(source[index + 1 + before.length] ?? '')
+    ) {
+      output += `@${after}`
+      index += before.length
+      continue
+    }
+    output += char
+  }
+  return output
+}
+
+/** Relocates an import while omitting absent conditions in the parser's visitor return format. */
+export function relocateImport(
+  value: Lightning.ImportRule,
+  url: string,
+): Lightning.ReturnedRule {
+  const { layer, supports, ...rest } = value
+  return {
+    type: 'import',
+    value: {
+      ...rest,
+      url,
+      ...(layer ? { layer } : {}),
+      ...(supports ? { supports } : {}),
+    },
+  }
+}
+
+// Validate the standard rule before shielding the newer font-display descriptor.
+function validateFeatures(source: string): void {
+  if (!source.toLowerCase().includes('@font-feature-values')) return
+  const masked = source.replace(
+    /"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|\/\*[\s\S]*?\*\//g,
+    (value) => ' '.repeat(value.length),
+  )
+  for (const match of masked.matchAll(/@font-feature-values(?=[\s{])/gi)) {
+    const start = match.index
+    const open = masked.indexOf('{', start)
+    if (open < 0) throw new Error('Invalid font-feature-values block.')
+    let depth = 1
+    let end = open + 1
+    let plain = source.slice(start, open + 1)
+    let cursor = open + 1
+    for (; end < masked.length && depth; end++) {
+      const char = masked[end]
+      if (char === '{') depth++
+      else if (char === '}') depth--
+      else if (depth === 1 && masked.slice(end).match(/^font-display\s*:/i)) {
+        const finish = masked.indexOf(';', end)
+        const close = masked.indexOf('}', end)
+        const boundary = finish >= 0 && finish < close ? finish : close
+        if (boundary < 0) throw new Error('Invalid font-display descriptor.')
+        const descriptor = source.slice(end, boundary)
+        const names = Identifiers.list(
+          descriptor.slice(descriptor.indexOf(':') + 1),
+          'space',
+        )
+        if (
+          names?.length !== 1 ||
+          !['auto', 'block', 'fallback', 'optional', 'swap'].includes(
+            names[0]!.replace(/[A-Z]/g, (letter) => letter.toLowerCase()),
+          )
+        )
+          throw new Error('Invalid font-display descriptor.')
+        plain += source.slice(cursor, end)
+        cursor = boundary + (boundary === finish ? 1 : 0)
+        end = cursor - 1
+      }
+    }
+    if (depth) throw new Error('Invalid font-feature-values block.')
+    plain += source.slice(cursor, end)
+    Lightning.transform({
+      filename: 'font-feature-values.css',
+      code: new TextEncoder().encode(plain),
+      errorRecovery: false,
+    })
+  }
+}

package/src/compiler/internal/Catalogs.ts

@@ -0,0 +1,114 @@
+/** Reads configuration theme catalogs from packed contracts and serializes their root initialization. @module */
+import * as Appearance from '../../runtime/Appearance.js'
+import * as ThemeValues from '../../web/internal/Themes.js'
+
+/** Initialization inputs read from one compiled configuration. */
+export type Catalog = {
+  /** Theme names paired with the compiled scope classes the stylesheet emits. */
+  readonly entries: readonly (readonly [string, string])[]
+  /** Configuration identity that prefixes every scope key. */
+  readonly identity: string
+  /** localStorage key shared by the configuration's script and root controls. */
+  readonly storageKey: string | undefined
+}
+
+/** Reads each configuration's theme catalog and storage key from a contract, one per configuration identity. */
+export function read(contract: string): readonly Catalog[] {
+  const parsed = JSON.parse(contract) as {
+    exports?: Record<
+      string,
+      {
+        kind?: string
+        members?: Record<string, { theme?: string }>
+        options?: { storageKey?: string; themes?: Record<string, unknown> }
+        selection?: boolean
+        theme?: string
+      }
+    >
+    configurations?: readonly {
+      identity?: string
+      storageKey?: string
+      themes?: readonly string[]
+    }[]
+    themes?: Record<string, { identity?: string }>
+  }
+  const configurations = new Map<
+    string,
+    { entries: Map<string, string>; storageKey: string | undefined }
+  >()
+
+  // Local configuration calls publish their catalogs without an export.
+  for (const local of parsed.configurations ?? []) {
+    if (!local.identity) continue
+
+    const configuration = configurations.get(local.identity) ?? {
+      entries: new Map<string, string>(),
+      storageKey: local.storageKey,
+    }
+
+    configurations.set(local.identity, configuration)
+
+    for (const name of local.themes ?? [])
+      configuration.entries.set(name, `${local.identity}-${name}`)
+  }
+
+  for (const binding of Object.values(parsed.exports ?? {})) {
+    if (binding.kind !== 'config' || binding.theme === undefined) continue
+
+    // A binding names its selected default scope; the theme metadata carries
+    // the configuration identity that prefixes every scope key.
+    const identity = parsed.themes?.[binding.theme]?.identity ?? binding.theme
+    let configuration = configurations.get(identity)
+
+    if (!configuration) {
+      configuration = {
+        entries: new Map(),
+        storageKey: binding.options?.storageKey,
+      }
+      configurations.set(identity, configuration)
+    }
+
+    // Script and root bindings carry no members, so the catalog derives their scope keys.
+    for (const name of Object.keys(binding.options?.themes ?? {}))
+      configuration.entries.set(name, `${identity}-${name}`)
+
+    for (const [path, member] of Object.entries(binding.members ?? {})) {
+      const names = JSON.parse(path) as readonly string[]
+      const name = (() => {
+        if (binding.selection) return names.length === 1 ? names[0] : undefined
+        return names.length === 2 && names[0] === 'themes'
+          ? names[1]
+          : undefined
+      })()
+
+      if (name !== undefined && member.theme)
+        configuration.entries.set(name, member.theme)
+    }
+  }
+
+  // Scope keys become classes through the same escaping the emitted stylesheet used.
+  return [...configurations].map(([identity, { entries, storageKey }]) => ({
+    entries: [...entries].map(
+      ([name, scope]) =>
+        [name, `z_theme-${ThemeValues.encode(scope)}`] as const,
+    ),
+    identity,
+    storageKey,
+  }))
+}
+
+/**
+ * Serializes the initialization script of every configuration, once per
+ * distinct script so configurations sharing a catalog and key run once.
+ * @param catalogs - Configurations read from the contracts a document loads.
+ * @returns Self-contained scripts that restore a saved selection before paint.
+ */
+export function scripts(catalogs: readonly Catalog[]): readonly string[] {
+  return [
+    ...new Set(
+      catalogs.map(({ entries, storageKey }) =>
+        Appearance.create(entries, { storageKey })(),
+      ),
+    ),
+  ]
+}