zyzz 0.0.18 → 0.0.19

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,
+              })
+            },
+          },
+        })
+      },
+    }
+  },
+}

package/src/oxlint/rules/validStyles.ts

@@ -0,0 +1,88 @@
+/** Reports statically known declaration errors using Zyzz's authoring validation. @module */
+import type { ESTree, Rule } from '@oxlint/plugins'
+import * as Bindings from '../internal/Bindings.js'
+import * as Declarations from '../internal/Declarations.js'
+import * as Literal from '../../internal/Literal.js'
+import * as Style from '../../Style.js'
+
+/** Validates known structure and values while leaving unresolved bindings to the compiler. */
+export const validStyles: Rule = {
+  meta: { messages: { invalid: '{{message}}' }, schema: [], type: 'problem' },
+  create(context) {
+    const bindings = Bindings.create(context)
+    const reported = new Set<number>()
+    function report(node: ESTree.Node, message: string) {
+      if (reported.has(node.start)) return
+      reported.add(node.start)
+      context.report({ data: { message }, messageId: 'invalid', node })
+    }
+    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) {
+              if (binding.themed && name === 'typography') return
+              if (
+                !binding.themed &&
+                !name.startsWith('--') &&
+                !Object.hasOwn(Literal.rules, name)
+              ) {
+                report(property.key, `Unknown CSS property '${name}'.`)
+                return
+              }
+              const value = bindings.expression(property.value)
+              if (value.type === 'ObjectExpression') {
+                report(
+                  value,
+                  'CSS declarations require scalar values or fallback arrays.',
+                )
+                return
+              }
+              if (
+                value.type === 'ArrayExpression' &&
+                value.elements.some((element) => !element)
+              ) {
+                report(
+                  value,
+                  'Fallback arrays require dense data entries without holes.',
+                )
+                return
+              }
+              const literal = Declarations.literal(value, bindings)
+              if (!literal) return
+              const values = Array.isArray(literal.value)
+                ? literal.value
+                : [literal.value]
+              if (
+                values.some(
+                  (value) =>
+                    typeof value !== 'string' && typeof value !== 'number',
+                )
+              ) {
+                report(
+                  value,
+                  'CSS declarations require string or number values.',
+                )
+                return
+              }
+              try {
+                Style.define({ lint: { [name]: literal.value } } as never)
+              } catch (error) {
+                if (!(error instanceof Style.InvalidError)) throw error
+                for (const diagnostic of error.diagnostics)
+                  report(value, diagnostic.message)
+              }
+            },
+            invalid: report,
+          },
+        })
+      },
+    }
+  },
+}