zyzz 0.0.17 → 0.0.19

package/src/oxlint/internal/Bindings.ts

@@ -0,0 +1,270 @@
+/** Resolves immutable authoring bindings without loading or evaluating modules. @module */
+import type { Context, ESTree, Variable } from '@oxlint/plugins'
+
+/** A recognized helper or locally declared style. */
+export type Binding = {
+  readonly kind:
+    | 'config'
+    | 'configFactory'
+    | 'configNamespace'
+    | 'cx'
+    | 'definition'
+    | 'module'
+    | 'style'
+    | 'variants'
+  readonly themed: boolean
+}
+
+/** Resolves helpers using lexical scope, configuration filenames, and explicit import sources. */
+export function create(context: Context) {
+  const settings = context.settings.zyzz
+  const imports = new Set(['zyzz', 'zyzz/default'])
+  if (settings && typeof settings === 'object' && !Array.isArray(settings)) {
+    const sources = settings.imports
+    if (Array.isArray(sources))
+      for (const source of sources)
+        if (typeof source === 'string') imports.add(source)
+  }
+
+  function variable(
+    node: Extract<ESTree.Node, { type: 'Identifier' }>,
+  ): Variable | undefined {
+    let scope = context.sourceCode.getScope(node)
+    while (scope) {
+      const found = scope.set.get(node.name)
+      if (found) return found
+      if (!scope.upper) break
+      scope = scope.upper
+    }
+    return undefined
+  }
+
+  function initializer(
+    node: Extract<ESTree.Node, { type: 'Identifier' }>,
+  ): ESTree.Node | undefined {
+    const binding = variable(node)
+    if (!binding || binding.defs.length !== 1) return undefined
+    const definition = binding.defs[0]!
+    if (definition.node.type !== 'VariableDeclarator') return undefined
+    if (
+      definition.node.parent.type !== 'VariableDeclaration' ||
+      definition.node.parent.kind !== 'const'
+    )
+      return undefined
+    if (
+      binding.references.some(
+        (reference) => reference.isWrite() && !reference.init,
+      )
+    )
+      return undefined
+    if (definition.node.id.type !== 'Identifier') return undefined
+    const input = definition.node.init && unwrap(definition.node.init)
+    if (
+      input?.type === 'ArrayExpression' ||
+      input?.type === 'ObjectExpression'
+    ) {
+      const mutable = binding.references.some((reference) => {
+        let value: ESTree.Node = reference.identifier
+        while (
+          value.parent &&
+          ((value.parent.type === 'MemberExpression' &&
+            value.parent.object === value) ||
+            unwrap(value.parent) === value)
+        )
+          value = value.parent
+        const parent = value.parent
+        if (
+          parent?.type === 'ArrayExpression' ||
+          (parent?.type === 'Property' && parent.value === value)
+        )
+          return true
+        if (parent?.type === 'AssignmentExpression' && parent.left === value)
+          return true
+        if (
+          parent?.type === 'UpdateExpression' ||
+          (parent?.type === 'UnaryExpression' && parent.operator === 'delete')
+        )
+          return true
+        if (parent?.type === 'CallExpression') {
+          if (parent.callee === value) return true
+          const callee = resolve(parent.callee)
+          return callee?.kind !== 'style' && callee?.kind !== 'variants'
+        }
+        return parent?.type === 'VariableDeclarator' && parent.init === value
+      })
+      if (mutable) return undefined
+    }
+    return definition.node.init ?? undefined
+  }
+
+  function expression(
+    node: ESTree.Node,
+    seen = new Set<ESTree.Node>(),
+  ): ESTree.Node {
+    node = unwrap(node)
+    if (seen.has(node)) return node
+    seen.add(node)
+    if (node.type === 'Identifier') {
+      const init = initializer(node)
+      if (init) return expression(init, seen)
+    }
+    return node
+  }
+
+  function member(
+    binding: Binding | undefined,
+    name: string | undefined,
+  ): Binding | undefined {
+    if (!binding || !name) return undefined
+    if (binding.kind === 'module') {
+      if (!binding.themed && name === 'Config')
+        return { kind: 'configNamespace', themed: true }
+      if (
+        name === 'style' ||
+        name === 'variants' ||
+        (!binding.themed && name === 'cx')
+      )
+        return { kind: name, themed: binding.themed }
+    }
+    if (binding.kind === 'configNamespace' && name === 'create')
+      return { kind: 'configFactory', themed: true }
+    if (binding.kind === 'config' && (name === 'style' || name === 'variants'))
+      return { kind: name, themed: true }
+    return undefined
+  }
+
+  function resolve(
+    node: ESTree.Node,
+    seen = new Set<ESTree.Node>(),
+  ): Binding | undefined {
+    node = unwrap(node)
+    if (seen.has(node)) return undefined
+    seen.add(node)
+
+    if (node.type === 'Identifier') {
+      const binding = variable(node)
+      if (!binding || binding.defs.length !== 1) return undefined
+      const definition = binding.defs[0]!
+      const declaration = definition.node
+      if (definition.type === 'ImportBinding') {
+        const parent = declaration.parent
+        if (
+          parent?.type !== 'ImportDeclaration' ||
+          parent.importKind === 'type' ||
+          (!imports.has(parent.source.value) &&
+            !/(?:^|\/)zyzz\.config\.[^/]+$/.test(parent.source.value))
+        )
+          return undefined
+        const module: Binding = {
+          kind: 'module',
+          themed: parent.source.value !== 'zyzz',
+        }
+        if (declaration.type === 'ImportNamespaceSpecifier') return module
+        if (
+          declaration.type === 'ImportSpecifier' &&
+          declaration.importKind !== 'type'
+        )
+          return member(
+            module,
+            declaration.imported.type === 'Identifier'
+              ? declaration.imported.name
+              : declaration.imported.value,
+          )
+        return undefined
+      }
+      if (
+        declaration.type !== 'VariableDeclarator' ||
+        !declaration.init ||
+        declaration.parent.type !== 'VariableDeclaration' ||
+        declaration.parent.kind !== 'const'
+      )
+        return undefined
+      if (
+        binding.references.some(
+          (reference) => reference.isWrite() && !reference.init,
+        )
+      )
+        return undefined
+      if (declaration.id.type === 'Identifier')
+        return resolve(declaration.init, seen)
+      if (declaration.id.type === 'ObjectPattern') {
+        const property = declaration.id.properties.find(
+          (property) =>
+            property.type === 'Property' &&
+            property.value.type === 'Identifier' &&
+            property.value.name === node.name,
+        )
+        if (property?.type === 'Property')
+          return member(resolve(declaration.init, seen), key(property))
+      }
+    }
+
+    if (node.type === 'MemberExpression') {
+      const name = key(node)
+      const known = member(resolve(node.object, new Set(seen)), name)
+      if (known) return known
+      if (node.object.type !== 'Identifier' || !name) return undefined
+      const namespace = variable(node.object)
+      if (!namespace || namespace.defs.length !== 1) return undefined
+      const declaration = namespace.defs[0]!.node
+      if (
+        declaration.type !== 'TSModuleDeclaration' ||
+        declaration.body?.type !== 'TSModuleBlock'
+      )
+        return undefined
+      for (const statement of declaration.body.body) {
+        if (
+          statement.type !== 'ExportNamedDeclaration' ||
+          statement.declaration?.type !== 'VariableDeclaration' ||
+          statement.declaration.kind !== 'const'
+        )
+          continue
+        for (const entry of statement.declaration.declarations)
+          if (
+            entry.id.type === 'Identifier' &&
+            entry.id.name === name &&
+            entry.init
+          )
+            return resolve(entry.init, seen)
+      }
+    }
+
+    if (node.type === 'CallExpression') {
+      const callee = resolve(node.callee, seen)
+      if (callee?.kind === 'configFactory')
+        return { kind: 'config', themed: true }
+      if (callee?.kind === 'style' || callee?.kind === 'variants')
+        return { kind: 'definition', themed: callee.themed }
+    }
+    return undefined
+  }
+
+  return { expression, resolve, variable }
+}
+
+/** Resolves only literal property names, never computed identifiers. */
+export function key(
+  node:
+    | ESTree.ObjectProperty
+    | ESTree.BindingProperty
+    | ESTree.MemberExpression,
+): string | undefined {
+  const property = node.type === 'Property' ? node.key : node.property
+  if (!node.computed && property.type === 'Identifier') return property.name
+  if (property.type === 'Literal' && typeof property.value === 'string')
+    return property.value
+  return undefined
+}
+
+/** Removes type-only wrappers while retaining the original source node. */
+export function unwrap(node: ESTree.Node): ESTree.Node {
+  while (
+    node.type === 'TSAsExpression' ||
+    node.type === 'TSSatisfiesExpression' ||
+    node.type === 'TSNonNullExpression' ||
+    node.type === 'TSTypeAssertion' ||
+    node.type === 'ParenthesizedExpression'
+  )
+    node = node.expression
+  return node
+}

package/src/oxlint/internal/Declarations.ts

@@ -0,0 +1,137 @@
+/** Visits declaration positions in styles and recipes without evaluating expressions. @module */
+import type { ESTree } from '@oxlint/plugins'
+import * as Bindings from './Bindings.js'
+import * as Condition from '../../internal/Condition.js'
+
+/** Callbacks for known declaration blocks and malformed literal structures. */
+export type Visitors = {
+  readonly declaration: (property: ESTree.ObjectProperty, name: string) => void
+  readonly invalid?: ((node: ESTree.Node, message: string) => void) | undefined
+}
+
+/** Traverses actual style positions, excluding variant selections and callback internals. */
+export function visit(
+  node: ESTree.Node,
+  options: {
+    readonly bindings: ReturnType<typeof Bindings.create>
+    readonly recipe: boolean
+    readonly visitors: Visitors
+  },
+) {
+  const { bindings, visitors } = options
+  const seen = new Set<ESTree.Node>()
+
+  function object(
+    node: ESTree.Node,
+    callback: (node: ESTree.ObjectExpression) => void,
+  ) {
+    node = bindings.expression(node)
+    if (seen.has(node)) return
+    seen.add(node)
+    if (node.type === 'ObjectExpression') callback(node)
+    else if (node.type === 'Literal' || node.type === 'ArrayExpression')
+      visitors.invalid?.(node, 'Expected a style object.')
+  }
+
+  function entries(
+    node: ESTree.Node,
+    callback: (property: ESTree.ObjectProperty) => void,
+  ) {
+    object(node, (node) => {
+      for (const property of node.properties) {
+        if (property.type === 'SpreadElement') {
+          entries(property.argument, callback)
+          continue
+        }
+        if (property.kind !== 'init' || property.method) {
+          visitors.invalid?.(
+            property,
+            'Style objects require data properties, not methods or accessors.',
+          )
+          continue
+        }
+        callback(property)
+      }
+    })
+  }
+
+  function style(node: ESTree.Node) {
+    node = bindings.expression(node)
+    if (node.type === 'ArrowFunctionExpression') {
+      if (seen.has(node)) return
+      seen.add(node)
+      if (node.body.type !== 'BlockStatement') style(node.body)
+      else
+        for (const statement of node.body.body)
+          if (statement.type === 'ReturnStatement' && statement.argument)
+            style(statement.argument)
+      return
+    }
+    entries(node, (property) => {
+      const name = Bindings.key(property)
+      if (!name) return
+      if (name === 'selectors')
+        entries(property.value, (selector) => style(selector.value))
+      else if (name === 'targets')
+        entries(property.value, (target) => {
+          if (Bindings.key(target) === 'web') style(target.value)
+        })
+      else if (Condition.is(name)) style(property.value)
+      else if (name !== 'vars' && name !== 'variables')
+        visitors.declaration(property, name)
+    })
+  }
+
+  if (!options.recipe) style(node)
+  else
+    entries(node, (property) => {
+      const name = Bindings.key(property)
+      if (name === 'base') style(property.value)
+      else if (name === 'variants')
+        entries(property.value, (axis) =>
+          entries(axis.value, (choice) => style(choice.value)),
+        )
+      else if (name === 'compoundVariants') {
+        const value = bindings.expression(property.value)
+        if (value.type === 'ArrayExpression')
+          for (const entry of value.elements)
+            if (entry && entry.type !== 'SpreadElement')
+              entries(entry, (property) => {
+                if (Bindings.key(property) === 'style') style(property.value)
+              })
+      }
+    })
+}
+
+/** Extracts known scalar values and fallback arrays without executing user code. */
+export function literal(
+  node: ESTree.Node,
+  bindings: ReturnType<typeof Bindings.create>,
+  seen = new Set<ESTree.Node>(),
+): { readonly value: unknown } | undefined {
+  node = bindings.expression(node)
+  if (seen.has(node)) return undefined
+  seen = new Set(seen).add(node)
+  if (node.type === 'Literal') return { value: node.value }
+  if (node.type === 'TemplateLiteral' && node.expressions.length === 0)
+    return { value: node.quasis[0]?.value.cooked }
+  if (
+    node.type === 'UnaryExpression' &&
+    (node.operator === '-' || node.operator === '+')
+  ) {
+    const operand = literal(node.argument, bindings, seen)
+    if (typeof operand?.value === 'number')
+      return { value: node.operator === '-' ? -operand.value : operand.value }
+  }
+  if (node.type === 'ArrayExpression') {
+    const values: unknown[] = []
+    for (const entry of node.elements) {
+      if (!entry || entry.type === 'SpreadElement') return undefined
+      const result = literal(entry, bindings, seen)
+      if (!result) return undefined
+      values.push(result.value)
+    }
+    return { value: values }
+  }
+  return undefined
+}

package/src/oxlint/rules/noConflictingProps.ts

@@ -0,0 +1,52 @@
+/** Finds JSX attributes that overwrite known Zyzz application props. @module */
+import type { ESTree, Rule } from '@oxlint/plugins'
+import * as Bindings from '../internal/Bindings.js'
+
+/** Reports competing style spreads and explicit styling attributes without rewriting JSX. */
+export const noConflictingProps: Rule = {
+  meta: {
+    messages: {
+      attribute:
+        "Pass '{{property}}' into the Zyzz style call to merge styling props.",
+      spread:
+        'Compose Zyzz applications with cx() instead of overwriting them with multiple JSX spreads.',
+    },
+    schema: [],
+    type: 'problem',
+  },
+  create(context) {
+    const bindings = Bindings.create(context)
+    function application(node: ESTree.Node): boolean {
+      node = bindings.expression(node)
+      if (node.type !== 'CallExpression') return false
+      const binding = bindings.resolve(node.callee)
+      return binding?.kind === 'definition' || binding?.kind === 'cx'
+    }
+    return {
+      JSXOpeningElement(node) {
+        const spreads = node.attributes.filter(
+          (attribute) =>
+            attribute.type === 'JSXSpreadAttribute' &&
+            application(attribute.argument),
+        )
+        if (!spreads.length) return
+        for (const attribute of node.attributes) {
+          if (
+            attribute.type !== 'JSXAttribute' ||
+            attribute.name.type !== 'JSXIdentifier'
+          )
+            continue
+          const property = attribute.name.name
+          if (property === 'className' || property === 'style')
+            context.report({
+              data: { property },
+              messageId: 'attribute',
+              node: attribute,
+            })
+        }
+        for (const spread of spreads.slice(1))
+          context.report({ messageId: 'spread', node: spread })
+      },
+    }
+  },
+}

package/src/oxlint/rules/noUnused.ts

@@ -0,0 +1,67 @@
+/** Finds unused style members in local TypeScript namespaces. @module */
+import type { ESTree, Rule } from '@oxlint/plugins'
+import * as Bindings from '../internal/Bindings.js'
+
+/** Leaves module exports and escaped namespaces available to unknown consumers. */
+export const noUnused: Rule = {
+  meta: {
+    messages: { unused: "Style '{{name}}' is never used." },
+    schema: [],
+    type: 'suggestion',
+  },
+  create(context) {
+    const bindings = Bindings.create(context)
+    const declarations: ESTree.VariableDeclarator[] = []
+    return {
+      VariableDeclarator(node) {
+        if (
+          node.id.type === 'Identifier' &&
+          node.init &&
+          bindings.resolve(node.init)?.kind === 'definition'
+        )
+          declarations.push(node)
+      },
+      'Program:exit'() {
+        for (const declaration of declarations) {
+          if (declaration.id.type !== 'Identifier') continue
+          let parent: ESTree.Node = declaration.parent
+          while (
+            parent.type === 'VariableDeclaration' ||
+            parent.type === 'ExportNamedDeclaration'
+          )
+            parent = parent.parent
+          if (
+            parent.type !== 'TSModuleBlock' ||
+            parent.parent.type !== 'TSModuleDeclaration'
+          )
+            continue
+          const namespace = parent.parent
+          if (namespace.id.type !== 'Identifier') continue
+          // Nested and exported namespaces may have consumers outside this local scope.
+          if (namespace.parent.type !== 'Program') continue
+          const variable = bindings.variable(declaration.id)
+          const owner = bindings.variable(namespace.id)
+          if (!variable || !owner || owner.defs.length !== 1) continue
+          if (variable.references.some((reference) => reference.isRead()))
+            continue
+          const used = owner.references.some((reference) => {
+            if (!reference.isRead()) return false
+            const member = reference.identifier.parent
+            return (
+              member.type !== 'MemberExpression' ||
+              member.object !== reference.identifier ||
+              Bindings.key(member) === undefined ||
+              Bindings.key(member) === variable.name
+            )
+          })
+          if (!used)
+            context.report({
+              data: { name: `${namespace.id.name}.${variable.name}` },
+              messageId: 'unused',
+              node: declaration.id,
+            })
+        }
+      },
+    }
+  },
+}

package/src/oxlint/rules/restrictedProperties.ts

@@ -0,0 +1,92 @@
+/** Applies explicit project restrictions to known web declarations. @module */
+import type { Rule } from '@oxlint/plugins'
+import * as Bindings from '../internal/Bindings.js'
+import * as Declarations from '../internal/Declarations.js'
+
+/** Reports forbidden properties or literal values outside an explicit allowlist. */
+export const restrictedProperties: Rule = {
+  meta: {
+    messages: {
+      restricted: "Property '{{property}}' is restricted. {{reason}}",
+    },
+    schema: [
+      {
+        additionalProperties: {
+          additionalProperties: false,
+          properties: {
+            reason: { type: 'string' },
+            values: { items: { type: ['string', 'number'] }, type: 'array' },
+          },
+          type: 'object',
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+  create(context) {
+    const bindings = Bindings.create(context)
+    const restrictions = context.options[0]
+    const reported = new Set<number>()
+    return {
+      CallExpression(node) {
+        if (
+          !restrictions ||
+          typeof restrictions !== 'object' ||
+          Array.isArray(restrictions)
+        )
+          return
+        const binding = bindings.resolve(node.callee)
+        if (binding?.kind !== 'style' && binding?.kind !== 'variants') return
+        const input = node.arguments[0]
+        if (!input || input.type === 'SpreadElement') return
+        Declarations.visit(input, {
+          bindings,
+          recipe: binding.kind === 'variants',
+          visitors: {
+            declaration(property, name) {
+              if (
+                !Object.hasOwn(restrictions, name) ||
+                reported.has(property.start)
+              )
+                return
+              const restriction = restrictions[name]
+              if (
+                !restriction ||
+                typeof restriction !== 'object' ||
+                Array.isArray(restriction)
+              )
+                return
+              const allowed = restriction.values
+              if (Array.isArray(allowed)) {
+                const literal = Declarations.literal(property.value, bindings)
+                if (!literal) return
+                const values: unknown[] = Array.isArray(literal.value)
+                  ? literal.value
+                  : [literal.value]
+                if (
+                  values.every((value) =>
+                    allowed.some((allowed) => allowed === value),
+                  )
+                )
+                  return
+              }
+              reported.add(property.start)
+              context.report({
+                data: {
+                  property: name,
+                  reason:
+                    typeof restriction.reason === 'string'
+                      ? restriction.reason
+                      : 'Use an approved property or value.',
+                },
+                messageId: 'restricted',
+                node: property.key,
+              })
+            },
+          },
+        })
+      },
+    }
+  },
+}

package/src/oxlint/rules/useLogicalProperties.ts

@@ -0,0 +1,81 @@
+/** Encourages logical CSS properties in web style declarations. @module */
+import type { Rule } from '@oxlint/plugins'
+import * as Bindings from '../internal/Bindings.js'
+import * as Declarations from '../internal/Declarations.js'
+
+const replacements: Readonly<Record<string, string>> = {
+  borderBottomLeftRadius: 'borderEndStartRadius',
+  borderBottomRightRadius: 'borderEndEndRadius',
+  borderLeft: 'borderInlineStart',
+  borderLeftColor: 'borderInlineStartColor',
+  borderLeftStyle: 'borderInlineStartStyle',
+  borderLeftWidth: 'borderInlineStartWidth',
+  borderRight: 'borderInlineEnd',
+  borderRightColor: 'borderInlineEndColor',
+  borderRightStyle: 'borderInlineEndStyle',
+  borderRightWidth: 'borderInlineEndWidth',
+  borderTopLeftRadius: 'borderStartStartRadius',
+  borderTopRightRadius: 'borderStartEndRadius',
+  insetLeft: 'insetInlineStart',
+  insetRight: 'insetInlineEnd',
+  left: 'insetInlineStart',
+  marginLeft: 'marginInlineStart',
+  marginRight: 'marginInlineEnd',
+  paddingLeft: 'paddingInlineStart',
+  paddingRight: 'paddingInlineEnd',
+  right: 'insetInlineEnd',
+  scrollMarginLeft: 'scrollMarginInlineStart',
+  scrollMarginRight: 'scrollMarginInlineEnd',
+  scrollPaddingLeft: 'scrollPaddingInlineStart',
+  scrollPaddingRight: 'scrollPaddingInlineEnd',
+}
+
+/** Reports physical properties without changing direction-dependent behavior. */
+export const useLogicalProperties: Rule = {
+  meta: {
+    messages: {
+      logical:
+        "Use a CSS logical property instead of '{{property}}', such as '{{replacement}}' for horizontal LTR layouts.",
+    },
+    schema: [],
+    type: 'suggestion',
+  },
+  create(context) {
+    const bindings = Bindings.create(context)
+    const reported = new Set<number>()
+    return {
+      CallExpression(node) {
+        const binding = bindings.resolve(node.callee)
+        if (binding?.kind !== 'style' && binding?.kind !== 'variants') return
+        const input = node.arguments[0]
+        if (!input || input.type === 'SpreadElement') return
+        Declarations.visit(input, {
+          bindings,
+          recipe: binding.kind === 'variants',
+          visitors: {
+            declaration(property, name) {
+              const replacement = Object.hasOwn(replacements, name)
+                ? replacements[name]
+                : undefined
+              if (!replacement || reported.has(property.start)) return
+              if (
+                context.sourceCode
+                  .getCommentsBefore(property)
+                  .some((comment) =>
+                    comment.value.includes('allow-physical-property'),
+                  )
+              )
+                return
+              reported.add(property.start)
+              context.report({
+                data: { property: name, replacement },
+                messageId: 'logical',
+                node: property.key,
+              })
+            },
+          },
+        })
+      },
+    }
+  },
+}