zyzz 0.0.5 → 0.0.7

package/src/internal/Value.ts

@@ -21,6 +21,60 @@ export type Atom<value> =
  * Checks authored properties and retains validated input types to avoid expanding whole-property fallback unions.
  */
 export type Accepted<style, properties> = {
+  [property in keyof style]: AcceptedValue<
+    style[property],
+    property,
+    properties
+  >
+}
+
+type AcceptedValue<value, property extends PropertyKey, properties> =
+  Extract<value, `[${string}]` | `[${string}] !important`> extends never
+    ? AcceptedMember<Record<property, value>, properties>[property]
+    : value extends unknown
+      ? AcceptedMember<Record<property, value>, properties>[property]
+      : never
+
+type AcceptedMember<style, properties> = {
+  [property in keyof style]: property extends keyof properties
+    ? style[property] extends `[${infer value}]` | `[${infer value}] !important`
+      ?
+          | (property extends 'gridTemplateColumns' | 'gridTemplateRows'
+              ? style[property] extends LiteralAccepted<
+                  Pick<style, property>,
+                  Literal.Properties
+                >[property]
+                ? style[property]
+                : never
+              : never)
+          | (ScalarValue<value, property> extends LiteralAccepted<
+              Record<property, ScalarValue<value, property>>,
+              Literal.Properties
+            >[property]
+              ? style[property]
+              : never)
+      : style[property] extends readonly [unknown, ...unknown[]]
+        ? AcceptedArray<style[property], property, properties>
+        : LiteralAccepted<Pick<style, property>, properties>[property]
+    : never
+}
+
+type ScalarValue<value, property> =
+  value extends `${infer numeric extends number}`
+    ? property extends keyof Literal.Properties
+      ? number extends Literal.Properties[property]
+        ? numeric
+        : value
+      : value
+    : value
+
+type AcceptedArray<values, property extends PropertyKey, properties> = {
+  [index in keyof values]: values[index] extends readonly unknown[]
+    ? never
+    : Accepted<Record<property, values[index]>, properties>[property]
+}
+
+type LiteralAccepted<style, properties> = {
   [property in keyof style]: property extends keyof properties
     ? style[property] extends { readonly [Token.scalar]: infer scalar }
       ? property extends keyof Literal.Properties
@@ -80,6 +134,22 @@ type Fold<value> = value extends string
 
 /** Refines concrete scalar spellings; already-broad property contracts need no literal refinement. */
 export type Checked<style, tokens = {}> = {
+  [property in keyof style]: style[property] extends
+    | `[${infer value}]`
+    | `[${infer value}] !important`
+    ?
+        | (property extends 'gridTemplateColumns' | 'gridTemplateRows'
+            ? LiteralChecked<Pick<style, property>>[property]
+            : never)
+        | LiteralChecked<
+            Record<property, ScalarValue<value, property>>
+          >[property]
+    : style[property] extends readonly [unknown, ...unknown[]]
+      ? CheckedArray<style[property], property, tokens>
+      : LiteralChecked<Pick<style, property>, tokens>[property]
+}
+
+type LiteralChecked<style, tokens = {}> = {
   [property in keyof style]: style[property] extends string & Binding.Reference
     ? style[property] extends Binding.Reference<'*'>
       ? unknown
@@ -121,6 +191,40 @@ export type Checked<style, tokens = {}> = {
             : unknown)
 }
 
+type CheckedArray<values, property extends PropertyKey, tokens> = {
+  [index in keyof values]: Checked<
+    Record<property, values[index]>,
+    tokens
+  >[property]
+}
+
+/** Requires tokens for properties with configured values. */
+export type Tokens<
+  value,
+  tokens,
+  property extends keyof Literal.Properties,
+> = property extends `--${string}`
+  ? unknown
+  : [Token.Names<tokens, property>] extends [never]
+    ? unknown
+    : value extends readonly unknown[]
+      ? { [index in keyof value]: Tokens<value[index], tokens, property> }
+      : value extends
+            | Binding.Reference
+            | Token.Reference
+            | Token.Variable
+            | `${Token.Variable} !important`
+            | `[${string}]`
+            | `[${string}] !important`
+        ? unknown
+        : value extends Atom<Token.Names<tokens, property>>
+          ? unknown
+          : value extends number
+            ? `${value}` extends Token.Names<tokens, property>
+              ? unknown
+              : never
+            : never
+
 type Importance<value> = value extends readonly unknown[]
   ? { [key in keyof value]: Importance<value[key]> }
   : value extends `${infer body}!${infer suffix}`
@@ -263,7 +367,11 @@ export function parse(
   property: keyof Literal.Properties,
 ):
   | { invalid: true }
-  | { important: boolean; value: number | string | Token.Expression }
+  | {
+      custom?: true
+      important: boolean
+      value: number | string | Token.Expression
+    }
   | undefined {
   if (Token.isExpression(input)) {
     const text = input.parts
@@ -275,6 +383,16 @@ export function parse(
 
     const parts = [...input.parts]
     let remaining = text.length - String(parsed.value).length
+    if (parsed.custom) {
+      for (let index = 0; index < parts.length; index++) {
+        const part = parts[index]
+        if (part === '') continue
+        if (typeof part !== 'string') return undefined
+        parts[index] = part.slice(1)
+        break
+      }
+      remaining--
+    }
 
     for (let index = parts.length - 1; remaining > 0 && index >= 0; index--) {
       const part = parts[index]
@@ -286,7 +404,11 @@ export function parse(
       remaining -= count
     }
 
-    return { important: parsed.important, value: Token.compose(parts) }
+    return {
+      ...(parsed.custom ? { custom: true } : {}),
+      important: parsed.important,
+      value: Token.compose(parts.filter((part) => part !== '')),
+    }
   }
 
   if (typeof input !== 'string') return undefined
@@ -317,7 +439,15 @@ export function parse(
     marker = marker === 0 ? -1 : input.lastIndexOf('!', marker - 1)
   }
 
-  if (marker < 0) return undefined
+  if (marker < 0) {
+    if (bracketed(input))
+      return {
+        custom: true,
+        important: false,
+        value: scalar(input.slice(1, -1)),
+      }
+    return undefined
+  }
   if (input.slice(marker - 1) !== ' !important' || escaped(marker - 1))
     return { invalid: true }
 
@@ -326,14 +456,54 @@ export function parse(
   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)
+  const body = input.slice(0, end)
+  const custom = bracketed(body)
+  const text = custom ? body.slice(1, -1) : body
+  const value = scalar(text)
+
+  return {
+    ...(custom ? { custom: true } : {}),
+    important: true as const,
+    value,
+  }
+
+  function scalar(text: string): number | string {
+    const numeric =
+      Literal.rule(property)?.kind === 'number' ||
+      Literal.rule(property)?.kind === 'grid-line'
+    return numeric && /^[+-]?(?:\d*\.\d+|\d+)(?:[eE][+-]?\d+)?$/.test(text)
       ? Number(text)
       : text
+  }
+}
 
-  return { important: true as const, value }
+/** Recognizes one enclosing pair without consuming native grid line lists. */
+function bracketed(value: string): boolean {
+  if (!value.startsWith('[') || !value.endsWith(']')) return false
+  let depth = 0
+  let quote = ''
+  for (let index = 0; index < value.length; index++) {
+    const character = value[index]!
+    if (character === '\\') {
+      index++
+      continue
+    }
+    if (quote) {
+      if (character === quote) quote = ''
+      continue
+    }
+    if (character === '/' && value[index + 1] === '*') {
+      const end = value.indexOf('*/', index + 2)
+      if (end < 0) return false
+      index = end + 1
+      continue
+    }
+    if (character === '"' || character === "'") {
+      quote = character
+      continue
+    }
+    if (character === '[') depth++
+    if (character === ']' && --depth === 0) return index === value.length - 1
+  }
+  return false
 }

package/src/next/index.ts

@@ -9,21 +9,26 @@ import * as Path from 'node:path'
  * Preserves existing configuration hooks and creates `.zyzz/next` beneath the working directory.
  * Throws file-system errors during setup; compilation errors are reported by the bundler.
  */
-export function zyzz(config: NextConfig): NextConfig
-export function zyzz(config: zyzz.Factory): zyzz.Factory
-export function zyzz(config: Promise<NextConfig>): Promise<NextConfig>
+export function zyzz(config: NextConfig, options?: zyzz.Options): NextConfig
+export function zyzz(config: zyzz.Factory, options?: zyzz.Options): zyzz.Factory
+export function zyzz(
+  config: Promise<NextConfig>,
+  options?: zyzz.Options,
+): Promise<NextConfig>
 export function zyzz(
   config: NextConfig | zyzz.Factory | Promise<NextConfig>,
+  options: zyzz.Options = {},
 ): NextConfig | zyzz.Factory | Promise<NextConfig> {
   if (typeof config === 'function')
-    return async (phase, context) => zyzz(await config(phase, context))
-  if (config instanceof Promise) return config.then(zyzz)
+    return async (phase, context) => zyzz(await config(phase, context), options)
+  if (config instanceof Promise)
+    return config.then((value) => zyzz(value, options))
 
   const loader = Module.createRequire(import.meta.url).resolve(
     'zyzz/next/loader',
   )
-  const options = { root: process.cwd() }
-  const shared = Path.join(options.root, '.zyzz', 'next', 'shared.css')
+  const loaderOptions = { reset: options.reset ?? false, root: process.cwd() }
+  const shared = Path.join(loaderOptions.root, '.zyzz', 'next', 'shared.css')
   Fs.mkdirSync(Path.dirname(shared), { recursive: true })
   try {
     Fs.writeFileSync(shared, '', { flag: 'wx' })
@@ -37,7 +42,10 @@ export function zyzz(
       all: [{ not: 'foreign' as const }, { not: { query: /zyzz-style/ } }],
     },
     loaders: [
-      { loader, options: { ...options, bundler: 'turbopack', mode: 'source' } },
+      {
+        loader,
+        options: { ...loaderOptions, bundler: 'turbopack', mode: 'source' },
+      },
     ],
   }
 
@@ -67,7 +75,11 @@ export function zyzz(
             loaders: [
               {
                 loader,
-                options: { ...options, bundler: 'turbopack', mode: 'style' },
+                options: {
+                  ...loaderOptions,
+                  bundler: 'turbopack',
+                  mode: 'style',
+                },
               },
             ],
             as: '*.css',
@@ -77,7 +89,11 @@ export function zyzz(
           loaders: [
             {
               loader,
-              options: { ...options, bundler: 'turbopack', mode: 'shared' },
+              options: {
+                ...loaderOptions,
+                bundler: 'turbopack',
+                mode: 'shared',
+              },
             },
           ],
         },
@@ -90,12 +106,12 @@ export function zyzz(
       result.module.rules.push({
         enforce: 'pre',
         exclude: /node_modules/,
-        include: options.root,
+        include: loaderOptions.root,
         test: /\.[cm]?[jt]sx?$/,
         use: [
           {
             loader,
-            options: { ...options, bundler: 'webpack', mode: 'source' },
+            options: { ...loaderOptions, bundler: 'webpack', mode: 'source' },
           },
         ],
       })
@@ -111,4 +127,10 @@ export declare namespace zyzz {
     phase: string,
     context: { defaultConfig: NextConfig },
   ) => NextConfig | Promise<NextConfig>
+
+  /** Web stylesheet delivery settings. */
+  type Options = {
+    /** Include the CSS reset. Defaults to false. */
+    readonly reset?: boolean | undefined
+  }
 }

package/src/next/internal/Project.ts

@@ -0,0 +1,337 @@
+/** Retains filesystem snapshots and an incremental graph within a Next.js loader worker. @module */
+import * as Contract from '../../compiler/internal/Contract.js'
+import * as Fs from 'node:fs/promises'
+import * as Graph from '../../compiler/Graph.js'
+import type * as NativeFs from 'node:fs'
+import * as Path from 'node:path'
+import * as Reset from '../../node/Reset.js'
+import * as Syntax from '../../compiler/internal/Syntax.js'
+
+/** Resolution and dependency notifications supplied by the active loader invocation. */
+export type Context = {
+  /** Track graph membership changes. */
+  addContextDependency(directory: string): void
+  /** Track source and contract edits. */
+  addDependency(file: string): void
+  /** Resolve with the active bundler's aliases and conditions. */
+  getResolve(
+    options: object,
+  ): (
+    directory: string,
+    specifier: string,
+    callback: (error: Error | null, file?: string | false) => void,
+  ) => void
+  /** Physical loader resource. */
+  resourcePath: string
+}
+
+/** Creates project state owned by a loader configuration in one worker process. */
+export function create(options: create.Options) {
+  let compiler = Graph.create()
+  const directories = new Map<
+    string,
+    { items: NativeFs.Dirent[]; track: boolean; version: string }
+  >()
+  const files = new Map<string, { source: string; version: string }>()
+  const libraries = new Map<
+    string,
+    { dependencies: readonly (readonly string[])[]; source: string }
+  >()
+  const reset = options.reset ? Reset.read() : undefined
+  const syntax = new Map<
+    string,
+    { parsed: ReturnType<typeof Syntax.parse>; source: string }
+  >()
+  let pending = Promise.resolve()
+
+  return {
+    /** Compiles a fresh snapshot while retaining unchanged syntax and graph results. */
+    compile(context: Context, source?: string) {
+      // Loader calls may overlap, but only one immutable snapshot updates the compiler at a time.
+      const result = pending.then(async () => {
+        try {
+          return await compile(context, source)
+        } catch (error) {
+          // Failed discovery or extraction may leave a partial filesystem snapshot.
+          compiler = Graph.create()
+          directories.clear()
+          files.clear()
+          libraries.clear()
+          syntax.clear()
+          throw error
+        }
+      })
+
+      // A failed generation must not prevent recovery after the source is corrected.
+      pending = result.then(
+        () => {},
+        () => {},
+      )
+
+      return result
+    },
+  }
+
+  async function compile(context: Context, source?: string) {
+    const root = options.root
+    const programs = new Map<string, ReturnType<typeof Syntax.parse>>()
+    const seenDirectories = new Set<string>()
+    const seenFiles = new Set<string>()
+    async function read(file: string) {
+      seenFiles.add(file)
+      const version = await stamp(file)
+      let entry = files.get(file)
+      if (entry?.version !== version) {
+        entry = { source: await Fs.readFile(file, 'utf8'), version }
+        files.set(file, entry)
+      }
+      return entry.source
+    }
+
+    const modules: Record<string, string> = Object.create(null)
+    const imports: Record<
+      string,
+      Record<string, string | null>
+    > = Object.create(null)
+    const contracts: Record<string, string> = Object.create(null)
+    const resolve = context.getResolve({})
+    const id = (file: string) =>
+      `app/${Path.relative(root, file).split(Path.sep).join('/')}`
+    const eligible = (file: string) =>
+      /\.[cm]?[jt]sx?$/.test(file) &&
+      !/\.(?:d|test|test-d|bench|bench-d)\.[cm]?[jt]sx?$/.test(file) &&
+      !Path.relative(root, file)
+        .split(Path.sep)
+        .some(
+          (part) =>
+            part === '..' || part === 'node_modules' || part.startsWith('.'),
+        )
+
+    async function visit(file: string, text?: string): Promise<void> {
+      const name = id(file)
+      if (Object.hasOwn(modules, name)) return
+
+      context.addDependency(file)
+      seenFiles.add(file)
+      modules[name] = text ?? (await read(file))
+      const links: Record<string, string | null> = Object.create(null)
+      imports[name] = links
+      let entry = syntax.get(name)
+      if (entry?.source !== modules[name]) {
+        entry = {
+          source: modules[name]!,
+          parsed: Syntax.parse({ moduleId: name, source: modules[name]! }),
+        }
+        syntax.set(name, entry)
+      }
+      programs.set(name, entry.parsed)
+      const parsed = entry.parsed
+
+      for (const node of parsed.program.body) {
+        if (
+          (node.type !== 'ImportDeclaration' &&
+            node.type !== 'ExportNamedDeclaration' &&
+            node.type !== 'ExportAllDeclaration') ||
+          !node.source
+        )
+          continue
+        if (
+          node.type === 'ImportDeclaration'
+            ? node.importKind === 'type'
+            : node.exportKind === 'type'
+        )
+          continue
+
+        const specifier = node.source.value
+        links[specifier] = null
+        // Next owns this virtual module, which has no physical stylesheet contract.
+        if (specifier === 'next/root-params') continue
+        if (
+          specifier === 'zyzz' ||
+          (specifier.startsWith('zyzz/') && specifier !== 'zyzz/default') ||
+          specifier.startsWith('node:')
+        )
+          continue
+
+        const resolved = await new Promise<string | false | undefined>(
+          (accept, reject) => {
+            resolve(Path.dirname(file), specifier, (error, value) =>
+              error ? reject(error) : accept(value),
+            )
+          },
+        )
+        if (!resolved || !/\.[cm]?[jt]sx?$/.test(resolved)) continue
+        if (eligible(resolved)) {
+          links[specifier] = id(resolved)
+          await visit(resolved)
+          continue
+        }
+
+        const sidecar = `${resolved}.zyzz.json`
+        try {
+          contracts[resolved] = await read(sidecar)
+          context.addDependency(sidecar)
+          links[specifier] = resolved
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+        }
+      }
+    }
+
+    async function discover(directory: string): Promise<void> {
+      const version = await stamp(directory)
+      let cached = directories.get(directory)
+      if (cached?.version !== version) {
+        const items = await Fs.readdir(directory, { withFileTypes: true })
+        cached = {
+          items,
+          track:
+            !items.some((item) => item.name === 'node_modules') ||
+            !(await loops(directory)),
+          version,
+        }
+        directories.set(directory, cached)
+      }
+      seenDirectories.add(directory)
+      const items = cached.items
+
+      // Linked package roots are tracked through children to avoid recursive dependency loops.
+      if (cached.track) context.addContextDependency(directory)
+
+      for (const item of items) {
+        if (
+          item.name.startsWith('.') ||
+          [
+            'node_modules',
+            'dist',
+            'build',
+            'coverage',
+            'test',
+            'tests',
+            '__tests__',
+          ].includes(item.name)
+        )
+          continue
+        const file = Path.join(directory, item.name)
+        if (item.isDirectory()) await discover(file)
+        else if (item.isFile() && eligible(file)) await visit(file)
+      }
+    }
+
+    if (source !== undefined) await visit(context.resourcePath, source)
+    await discover(root)
+    const loaded = new Set<string>()
+    async function dependencies(file: string): Promise<void> {
+      if (loaded.has(file)) return
+      loaded.add(file)
+
+      let library = libraries.get(file)
+      if (!library || library.source !== contracts[file]) {
+        library = {
+          source: contracts[file]!,
+          dependencies: Contract.read(
+            contracts[file]!,
+            new Map(),
+            file,
+          ).stylesheets.map((section) => section.dependency ?? []),
+        }
+        libraries.set(file, library)
+      }
+      for (const dependency of library.dependencies) {
+        let owner = file
+        for (const specifier of dependency) {
+          const target = await new Promise<string | false | undefined>(
+            (accept, reject) => {
+              resolve(Path.dirname(owner), specifier, (error, value) =>
+                error ? reject(error) : accept(value),
+              )
+            },
+          )
+          if (!target || !Path.isAbsolute(target))
+            throw new Error('Unable to resolve packed stylesheet dependency.')
+
+          const links = (imports[owner] ??= Object.create(null))
+          links[specifier] = target
+          if (!Object.hasOwn(contracts, target)) {
+            const sidecar = `${target}.zyzz.json`
+            contracts[target] = await read(sidecar)
+            context.addDependency(sidecar)
+          }
+          await dependencies(target)
+          owner = target
+        }
+      }
+    }
+    for (const file of Object.keys(contracts)) await dependencies(file)
+
+    const graph = compiler.compile({
+      [Syntax.cache]: programs,
+      contracts,
+      imports,
+      modules,
+      reset,
+    })
+
+    for (const file of files.keys())
+      if (!seenFiles.has(file)) files.delete(file)
+    for (const file of directories.keys())
+      if (!seenDirectories.has(file)) directories.delete(file)
+    for (const file of libraries.keys())
+      if (!Object.hasOwn(contracts, file)) libraries.delete(file)
+    for (const name of syntax.keys())
+      if (!programs.has(name)) syntax.delete(name)
+
+    return graph
+  }
+}
+
+/** Project cache settings. */
+export declare namespace create {
+  /** Isolates source discovery and shared stylesheet options. */
+  type Options = {
+    /** Include the packaged reset in shared CSS. */
+    readonly reset?: boolean | undefined
+    /** Absolute application directory. */
+    readonly root: string
+  }
+}
+
+async function stamp(file: string) {
+  const stat = await Fs.stat(file, { bigint: true })
+  return `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`
+}
+
+/** Whether an installed dependency links back to the directory or one of its ancestors. */
+async function loops(directory: string): Promise<boolean> {
+  const installed = Path.join(directory, 'node_modules')
+  const entries = await Fs.readdir(installed, { withFileTypes: true }).catch(
+    () => [],
+  )
+  const candidates = (
+    await Promise.all(
+      entries.map(async (entry) => {
+        if (!entry.name.startsWith('@'))
+          return [Path.join(installed, entry.name)]
+
+        const scoped = Path.join(installed, entry.name)
+
+        return (await Fs.readdir(scoped).catch(() => [])).map((name) =>
+          Path.join(scoped, name),
+        )
+      }),
+    )
+  ).flat()
+
+  for (const candidate of candidates) {
+    const stat = await Fs.lstat(candidate).catch(() => undefined)
+    if (!stat?.isSymbolicLink()) continue
+
+    const target = await Fs.realpath(candidate).catch(() => undefined)
+    if (target === undefined) continue
+
+    const relative = Path.relative(target, directory)
+    if (!relative.startsWith('..') && !Path.isAbsolute(relative)) return true
+  }
+
+  return false
+}