Skip to content

AI-native design editor. Open-source Figma alternative.

10.5 KB
Raw Blame
import { existsSync, readFileSync } from 'node:fs'
import { dirname, resolve } from 'node:path'

import { normalizedFilename } from '#lint/support/context.ts'
import {
  VUE_DIRECTIVE_NODE,
  VUE_ELEMENT_NODE,
  isVueSourceFile,
  vueTemplateAst,
  walkVueTemplateAst
} from '#lint/support/vue.ts'
import { defineRule } from '@oxlint/plugins'
import type { ESTree } from '@oxlint/plugins'
import { __unstable__loadDesignSystem } from '@tailwindcss/node'
import { compact } from 'es-toolkit/array'

type DesignSystem = Awaited<ReturnType<typeof __unstable__loadDesignSystem>>

interface Theme {
  stylesheet: string
  /** Tailwind's own model of the stylesheet's theme, utilities, and variants. */
  system: DesignSystem
}

/**
 * The stylesheet that builds each part of the repository, first match first: the SDK's
 * primitives and their examples, and the landing page, render in the docs site, everything else
 * in the app.
 */
const STYLESHEETS = [
  { files: 'packages/vue/src/', stylesheet: 'packages/docs/.vitepress/theme/tailwind.css' },
  { files: 'packages/docs/.vitepress/', stylesheet: 'packages/docs/.vitepress/theme/tailwind.css' },
  { files: '', stylesheet: 'src/app.css' }
]

/**
 * `bun run lint` and the rule's tests run Oxlint from the repository root; a run elsewhere has
 * no stylesheet to check against, and the rule stays quiet rather than keep the plugin's other
 * rules from loading.
 */
async function loadTheme(stylesheet: string): Promise<Theme | null> {
  const path = resolve(stylesheet)
  if (!existsSync(path)) return null
  const system = await __unstable__loadDesignSystem(readFileSync(path, 'utf8'), {
    base: dirname(path)
  })
  return { stylesheet, system }
}

const themes = await Promise.all(
  STYLESHEETS.map(async ({ files, stylesheet }) => ({ files, theme: await loadTheme(stylesheet) }))
)

function themeFor(file: string): Theme | null {
  const match = themes.find(({ files }) => file.startsWith(files) || file.includes(`/${files}`))
  return match?.theme ?? null
}

const verdicts = new WeakMap<Theme, Map<string, string | null>>()

/**
 * Why Tailwind cannot use a class, or null when it can or the class is not Tailwind's. A class
 * Tailwind parses as a utility but compiles to nothing names a value the theme lacks, such as a
 * color with no token. A color written as `[var(--color-*)]` has a utility of its own.
 */
function classProblem(theme: Theme, className: string): string | null {
  const { system, stylesheet } = theme
  let cache = verdicts.get(theme)
  if (!cache) {
    cache = new Map()
    verdicts.set(theme, cache)
  }
  const cached = cache.get(className)
  if (cached !== undefined) return cached
  const candidates = system.parseCandidate(className)
  const [css] = system.candidatesToCss([className])
  let problem: string | null = null
  if (!css) {
    if (candidates.length > 0)
      problem = `Tailwind has no \`${className}\`; ${stylesheet} defines no such value`
  } else {
    for (const candidate of candidates) {
      if (candidate.kind !== 'functional' || candidate.value?.kind !== 'arbitrary') continue
      const color = /^var\(--color-([\w-]+)\)$/.exec(candidate.value.value)
      if (!color) continue
      problem =
        system.resolveThemeValue(`--color-${color[1]}`) === undefined
          ? `\`${className}\` names \`--color-${color[1]}\`, which ${stylesheet} does not define`
          : `use \`${candidate.root}-${color[1]}\` instead of \`${className}\``
    }
  }
  cache.set(className, problem)
  return problem
}

function classNames(text: string): string[] {
  return compact(text.split(/\s+/))
}

const CLASS_KEYS = new Set(['class', 'className'])

/**
 * The class strings in a `:class` binding's source: array items and object keys, and values only
 * under `class`, since other keys pass arguments such as a variant (`menu({ justify: 'start' })`).
 */
function boundClassStrings(expression: string): string[] {
  const strings = /(?:([\w$]+)\s*:\s*)?(?:'([^']*)'|"([^"]*)"|`([^`$]*)`)/g
  return [...expression.matchAll(strings)].flatMap(([, key, ...quoted]) =>
    key && !CLASS_KEYS.has(key) ? [] : [quoted.find((text) => text !== undefined) ?? '']
  )
}

function propertyKey(node: ESTree.Node): string | null {
  if (node.type !== 'Property') return null
  if (node.key.type === 'Identifier') return node.key.name
  return node.key.type === 'Literal' && typeof node.key.value === 'string' ? node.key.value : null
}

/**
 * Whether a string is a class list, following tailwind-variants: `defaultVariants` and the
 * conditions of `compoundVariants` entries select variants, and their `class` holds classes.
 * Type literals and module paths are not classes either.
 */
function isClassString(node: ESTree.Node): boolean {
  let child: ESTree.Node = node
  for (let parent = node.parent; parent; child = parent, parent = parent.parent) {
    if (parent.type === 'TSLiteralType') return false
    if (
      (parent.type === 'ImportDeclaration' ||
        parent.type === 'ExportNamedDeclaration' ||
        parent.type === 'ExportAllDeclaration') &&
      parent.source === child
    )
      return false
    const key = propertyKey(parent)
    if (key === 'defaultVariants') return false
    const entry = parent.parent
    if (
      key !== null &&
      child === (parent.type === 'Property' ? parent.value : null) &&
      entry?.type === 'ObjectExpression' &&
      entry.parent?.type === 'ArrayExpression' &&
      propertyKey(entry.parent.parent ?? entry) === 'compoundVariants'
    )
      return CLASS_KEYS.has(key)
  }
  return true
}

const CLASS_HELPERS = new Set(['tv', 'twMerge', 'twJoin'])

function isClassHelperCall(node: ESTree.CallExpression): boolean {
  return node.callee.type === 'Identifier' && CLASS_HELPERS.has(node.callee.name)
}

/** Why a class is a problem for a rule, or null; `theme` builds the file's classes. */
type ClassCheck = (theme: Theme, className: string, file: string) => string | null

/**
 * A rule over every class Tailwind reads: Vue class attributes and bindings, `tv`, `twMerge` and
 * `twJoin` calls, and theme modules under `src/theme/`.
 */
function defineClassRule(description: string, problemFor: ClassCheck) {
  return defineRule({
    meta: { type: 'problem', docs: { description } },
    create(context) {
      const file = normalizedFilename(context)
      const theme = themeFor(file)
      if (!theme) return {}
      const themeModule = file.startsWith('src/theme/') || file.includes('/src/theme/')

      const check = (node: ESTree.Node, text: string) => {
        for (const className of classNames(text)) {
          const problem = problemFor(theme, className, file)
          if (problem) context.report({ node, message: `Tailwind class: ${problem}.` })
        }
      }

      function checkStrings(node: ESTree.Node) {
        if (!isClassString(node)) return
        if (node.type === 'Literal' && typeof node.value === 'string') check(node, node.value)
        else if (node.type === 'TemplateLiteral')
          for (const quasi of node.quasis) check(node, quasi.value.cooked ?? quasi.value.raw)
      }

      let helperDepth = 0
      return {
        Program(node) {
          if (!isVueSourceFile(file)) return
          const template = vueTemplateAst(context.sourceCode.getText(), file)
          if (!template) return
          walkVueTemplateAst(template, (templateNode) => {
            if (templateNode.type !== VUE_ELEMENT_NODE) return
            for (const prop of templateNode.props) {
              if (prop.type !== VUE_DIRECTIVE_NODE) {
                if (prop.name === 'class' && prop.value) check(node, prop.value.content)
                continue
              }
              const arg = prop.arg?.type === 4 ? prop.arg.content : null
              const expression = prop.exp?.type === 4 ? prop.exp.content : null
              if (prop.name === 'bind' && arg === 'class' && expression)
                for (const text of boundClassStrings(expression)) check(node, text)
            }
          })
        },
        CallExpression(node) {
          if (isClassHelperCall(node)) helperDepth++
        },
        'CallExpression:exit'(node: ESTree.CallExpression) {
          if (isClassHelperCall(node)) helperDepth--
        },
        Literal(node) {
          if (themeModule || helperDepth > 0) checkStrings(node)
        },
        TemplateLiteral(node) {
          if (themeModule || helperDepth > 0) checkStrings(node)
        }
      }
    }
  })
}

/**
 * Require every class Tailwind reads to be one it can build. It drops a class it does not know
 * without a warning, so a typo or a color with no token leaves the element unstyled.
 */
export const noUnknownTailwindClassesRule = defineClassRule(
  'Require Tailwind classes to be ones the app theme can build.',
  (theme, className) => classProblem(theme, className)
)

/** Sources sized with the interface: the app and the SDK's primitives. */
const INTERFACE_SOURCES = ['src/', 'packages/vue/src/']
const PX_LENGTH = /(?:^|[\s(,])-?(?:\d*\.)?\d+px\b/i

/**
 * The pixel length in a class's arbitrary value, such as `text-[11px]` or `grid-cols-[24px_1fr]`.
 * Shadows keep pixel offsets: they are decoration, not layout. `content` values are text.
 */
function pxValue(theme: Theme, className: string): string | null {
  for (const candidate of theme.system.parseCandidate(className)) {
    const value = arbitraryValue(candidate)
    if (value !== null && PX_LENGTH.test(value)) return value
  }
  return null
}

type Candidate = ReturnType<DesignSystem['parseCandidate']>[number]

/** Whether a utility or property takes values that are not sizes: shadows and text content. */
function exempt(name: string): boolean {
  return name.endsWith('shadow') || name === 'content'
}

/** A class's arbitrary size value, `[width:10px]` or `w-[10px]`. */
function arbitraryValue(candidate: Candidate): string | null {
  if (candidate.kind === 'arbitrary') return exempt(candidate.property) ? null : candidate.value
  if (candidate.kind !== 'functional' || candidate.value?.kind !== 'arbitrary') return null
  return exempt(candidate.root) ? null : candidate.value.value
}

/**
 * Require interface sizes in rem, so the interface follows the root font size: Tailwind's scale,
 * the theme's text sizes, or a rem arbitrary value.
 */
export const noPxTailwindValuesRule = defineClassRule(
  'Require Tailwind sizes in the interface to be in rem.',
  (theme, className, file) => {
    if (!INTERFACE_SOURCES.some((root) => file.startsWith(root) || file.includes(`/${root}`)))
      return null
    if (pxValue(theme, className) === null) return null
    return `size \`${className}\` in rem so it follows the root font size: use the spacing scale (\`h-6.5\`), a theme size (\`text-2xs\`, \`rounded-md\`), or a rem value`
  }
)