@tamagui/language-service 0.0.0-bootstrap.0 → 3.0.0-beta.643.1

package/src/check.ts

@@ -0,0 +1,204 @@
+// The project checker behind `tamagui check`.
+//
+// Node-only entry: walks a project's source files, extracts every static flat
+// value site with the sucrase tokenizer, and reports the same diagnostics the
+// editor plugin and eslint rule produce, formatted as readable code frames.
+
+import { readdirSync, readFileSync } from 'node:fs'
+import { join, relative } from 'node:path'
+// deep paths, spelled down to the file: sucrase publishes no `exports` map, and
+// a bare `sucrase/dist/parser` is a directory import that ESM cannot resolve
+import { parse } from 'sucrase/dist/parser/index.js'
+import { TokenType } from 'sucrase/dist/parser/tokenizer/types.js'
+
+import { createStyleTooling, type SerializedConfigFile } from './core'
+import {
+  createDocumentStyleTooling,
+  type DocumentDiagnostic,
+  type ExtractStyleSites,
+} from './document'
+import { createSucraseStyleSiteExtractor } from './extract-sucrase'
+
+const sourceExtensions = /\.(tsx|jsx)$/
+const skippedDirectories = new Set([
+  'node_modules',
+  'dist',
+  'build',
+  'out',
+  'coverage',
+  '.git',
+  '.next',
+  '.expo',
+  '.tamagui',
+])
+
+export interface CheckStyleFilesOptions {
+  /** project root; file discovery and relative display paths anchor here */
+  root: string
+  /** path to the compiler's config artifact; default `<root>/.tamagui/tamagui.config.json` */
+  configPath?: string
+  /** explicit files to check instead of walking the root */
+  files?: readonly string[]
+}
+
+export interface CheckedFile {
+  /** root-relative display path */
+  file: string
+  source: string
+  diagnostics: readonly DocumentDiagnostic[]
+}
+
+export interface CheckStyleFilesResult {
+  files: readonly CheckedFile[]
+  checkedFileCount: number
+  diagnosticCount: number
+}
+
+export class MissingConfigArtifactError extends Error {
+  constructor(configPath: string) {
+    super(
+      `no Tamagui config artifact at ${configPath} — run your dev server or \`tamagui generate\` once so the compiler emits it`
+    )
+    this.name = 'MissingConfigArtifactError'
+  }
+}
+
+function walkSourceFiles(directory: string, results: string[]): void {
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (!skippedDirectories.has(entry.name) && !entry.name.startsWith('.')) {
+        walkSourceFiles(join(directory, entry.name), results)
+      }
+      continue
+    }
+    if (sourceExtensions.test(entry.name)) results.push(join(directory, entry.name))
+  }
+}
+
+export function createProjectExtractor(
+  isStyleProp: (name: string) => boolean
+): ExtractStyleSites {
+  return createSucraseStyleSiteExtractor({ parse, TokenType }, { isStyleProp })
+}
+
+export function checkStyleFiles(options: CheckStyleFilesOptions): CheckStyleFilesResult {
+  const configPath =
+    options.configPath ?? join(options.root, '.tamagui', 'tamagui.config.json')
+  let contents: string
+  try {
+    contents = readFileSync(configPath, 'utf8')
+  } catch {
+    throw new MissingConfigArtifactError(configPath)
+  }
+  const tooling = createStyleTooling(JSON.parse(contents) as SerializedConfigFile)
+  if (!tooling) throw new MissingConfigArtifactError(configPath)
+
+  const document = createDocumentStyleTooling(
+    tooling,
+    createProjectExtractor((name) => tooling.isStyleProp(name))
+  )
+
+  let files: string[]
+  if (options.files) {
+    files = [...options.files]
+  } else {
+    files = []
+    walkSourceFiles(options.root, files)
+    files.sort()
+  }
+
+  const checked: CheckedFile[] = []
+  let diagnosticCount = 0
+  for (const file of files) {
+    let source: string
+    try {
+      source = readFileSync(file, 'utf8')
+    } catch {
+      continue
+    }
+    let diagnostics: readonly DocumentDiagnostic[]
+    try {
+      diagnostics = document.diagnostics(source)
+    } catch {
+      // a file sucrase cannot parse is a syntax error the real compiler will
+      // report; the style checker stays quiet about it
+      continue
+    }
+    if (diagnostics.length === 0) continue
+    diagnosticCount += diagnostics.length
+    checked.push({ file: relative(options.root, file), source, diagnostics })
+  }
+
+  return { files: checked, checkedFileCount: files.length, diagnosticCount }
+}
+
+const ansi = {
+  red: (text: string) => `\x1b[31m${text}\x1b[39m`,
+  dim: (text: string) => `\x1b[2m${text}\x1b[22m`,
+  bold: (text: string) => `\x1b[1m${text}\x1b[22m`,
+  cyan: (text: string) => `\x1b[36m${text}\x1b[39m`,
+}
+const plain = {
+  red: (text: string) => text,
+  dim: (text: string) => text,
+  bold: (text: string) => text,
+  cyan: (text: string) => text,
+}
+
+function lineStarts(source: string): number[] {
+  const starts = [0]
+  for (let index = 0; index < source.length; index++) {
+    if (source.charCodeAt(index) === 10) starts.push(index + 1)
+  }
+  return starts
+}
+
+function positionOf(starts: number[], offset: number): { line: number; column: number } {
+  let low = 0
+  let high = starts.length - 1
+  while (low < high) {
+    const mid = (low + high + 1) >> 1
+    if (starts[mid] <= offset) low = mid
+    else high = mid - 1
+  }
+  return { line: low, column: offset - starts[low] }
+}
+
+/** human-readable report: one code frame per diagnostic, caret-underlined */
+export function formatCheckResults(
+  result: CheckStyleFilesResult,
+  options: { color?: boolean } = {}
+): string {
+  const paint = options.color === false ? plain : ansi
+  const output: string[] = []
+
+  for (const checked of result.files) {
+    const starts = lineStarts(checked.source)
+    const lines = checked.source.split('\n')
+    for (const diagnostic of checked.diagnostics) {
+      const start = positionOf(starts, diagnostic.start)
+      const end = positionOf(starts, diagnostic.end)
+      output.push(
+        `${paint.bold(checked.file)}${paint.dim(`:${start.line + 1}:${start.column + 1}`)} ${paint.red('error')} ${diagnostic.message}`
+      )
+      const line = lines[start.line] ?? ''
+      const gutter = String(start.line + 1)
+      output.push(`  ${paint.dim(`${gutter} │`)} ${line}`)
+      const underlineLength =
+        end.line === start.line
+          ? Math.max(1, end.column - start.column)
+          : Math.max(1, line.length - start.column)
+      output.push(
+        `  ${paint.dim(`${' '.repeat(gutter.length)} │`)} ${' '.repeat(start.column)}${paint.red('^'.repeat(underlineLength))}`
+      )
+      output.push('')
+    }
+  }
+
+  const summary =
+    result.diagnosticCount === 0
+      ? `${paint.bold('✓')} ${result.checkedFileCount} files, no flat value problems`
+      : `${paint.red(paint.bold(`✗ ${result.diagnosticCount} problem${result.diagnosticCount === 1 ? '' : 's'}`))} in ${result.files.length} file${result.files.length === 1 ? '' : 's'} ${paint.dim(`(${result.checkedFileCount} checked)`)}`
+  output.push(summary)
+  return output.join('\n')
+}

package/src/core.ts

@@ -0,0 +1,355 @@
+// The standalone Tamagui style tooling core.
+//
+// Browser-safe by contract: no node imports, no typescript imports. Everything
+// here works from the serialized config JSON the Tamagui compiler emits
+// (`.tamagui/tamagui.config.json`), so the same engine powers the tsserver
+// plugin, the VS Code extension, the CLI checker, and in-browser IDEs.
+//
+// The @tamagui/style-grammar engine owns candidate meaning; this module adds
+// the two things the engine's config view deliberately drops — token and theme
+// VALUES — and projects everything into editor-shaped results: completions,
+// diagnostics, hover, and color swatches.
+
+import { normalizeCSSColor, rgba } from '@tamagui/normalize-css-color'
+import {
+  annotateStyleValue,
+  completeStyleValueAtCursor,
+  createCandidatePropertyVocabulary,
+  createGrammarConfigViewFromSerializedConfig,
+  createModifierRegistry,
+  createStylePropSet,
+  diagnoseStyleValueProgram,
+  programEligibility,
+  stateModifierNames,
+  type DiagnoseStyleValueOptions,
+  type ModifierKind,
+  type SerializedGrammarSourceConfig,
+  type StyleValueAnnotation,
+  type StyleValueCompletion,
+  type StyleValueCursorCompletions,
+  type StyleValueDiagnostic,
+} from '@tamagui/style-grammar/tooling'
+
+export type {
+  StyleValueAnnotation,
+  StyleValueCompletion,
+  StyleValueCursorCompletions,
+  StyleValueDiagnostic,
+}
+
+/** the shape of the JSON artifact the Tamagui compiler writes */
+export interface SerializedConfigFile {
+  tamaguiConfig?: SerializedGrammarSourceConfig
+  tamaguiConfigMetadata?: unknown
+}
+
+export interface RgbaColor {
+  r: number
+  g: number
+  b: number
+  a: number
+}
+
+export interface StyleValueColor {
+  /** character span within the authored value */
+  start: number
+  end: number
+  text: string
+  color: RgbaColor
+  /** the theme the preview value came from, when theme-resolved */
+  theme?: string
+}
+
+export interface StyleValueHover {
+  /** character span within the authored value */
+  start: number
+  end: number
+  text: string
+  /** markdown suitable for an editor hover */
+  markdown: string
+  /** a representative color for colorish targets */
+  color?: RgbaColor
+}
+
+const modifierKindLabel: Readonly<Record<ModifierKind, string>> = {
+  state: 'state modifier',
+  media: 'media modifier',
+  theme: 'theme modifier',
+  platform: 'platform modifier',
+  group: 'group modifier',
+  container: 'container modifier',
+}
+
+const modifierKindSort: Readonly<Record<ModifierKind, string>> = {
+  state: '00',
+  group: '01',
+  media: '02',
+  container: '03',
+  theme: '04',
+  platform: '05',
+}
+
+const stateModifierSort = new Map(
+  stateModifierNames.map((name, index) => [name, index] as const)
+)
+
+/**
+ * The one sort key every host uses for completion entries, so ordering does
+ * not drift between tsserver, LSP, and in-browser consumers: states first in
+ * interaction order, then groups, media, containers, themes, platforms, then
+ * configured values, then keywords.
+ */
+export function completionSortText(
+  completion: StyleValueCompletion,
+  modifierKind: ModifierKind | undefined
+): string {
+  if (modifierKind) {
+    const stateOrder =
+      modifierKind === 'state'
+        ? `${String(stateModifierSort.get(completion.value) ?? 999).padStart(3, '0')}:`
+        : ''
+    return `${modifierKindSort[modifierKind]}:${stateOrder}${completion.value}`
+  }
+  return `${completion.kind === 'configured' ? '10' : '11'}:${completion.value}`
+}
+
+/** unwraps a compiler-serialized token variable to its raw value */
+function tokenValue(entry: unknown): unknown {
+  if (entry && typeof entry === 'object' && 'val' in entry) {
+    return (entry as { val: unknown }).val
+  }
+  return entry
+}
+
+function parseColor(value: unknown, opacity?: number): RgbaColor | null {
+  if (typeof value !== 'string') return null
+  const normalized = normalizeCSSColor(value)
+  if (normalized === null) return null
+  const color = rgba(normalized)
+  if (opacity !== undefined) color.a = color.a * (opacity / 100)
+  return color
+}
+
+export interface StyleTooling {
+  /** every prop name treated as a flat style value site */
+  styleProps: ReadonlySet<string>
+  /** engine options, for hosts that call @tamagui/style-grammar directly */
+  engine: DiagnoseStyleValueOptions
+  isStyleProp(name: string): boolean
+  /** the longhand a prop resolves to through the configured shorthands */
+  targetProperty(name: string): string
+  /**
+   * cursor completions for one value slot, or null when the property takes no
+   * flat program (unknown props, legacy part props)
+   */
+  completions(
+    property: string,
+    value: string,
+    cursor: number
+  ): StyleValueCursorCompletions | null
+  /** the complete static verdict for one authored value */
+  diagnostics(property: string, value: string): readonly StyleValueDiagnostic[]
+  /** classified spans: modifiers, tokens, keywords, literals */
+  annotations(property: string, value: string): readonly StyleValueAnnotation[]
+  /** hover content for the annotation under `offset`, or null */
+  hover(property: string, value: string, offset: number): StyleValueHover | null
+  /** every span that resolves to a presentable color */
+  colors(property: string, value: string): readonly StyleValueColor[]
+  /** the modifier kind of a registered modifier name */
+  modifierKind(name: string): ModifierKind | undefined
+  /** root theme names, preview themes first */
+  previewThemes: readonly string[]
+}
+
+export function createStyleTooling(file: SerializedConfigFile): StyleTooling | null {
+  const serialized = file.tamaguiConfig
+  if (!serialized) return null
+
+  const config = createGrammarConfigViewFromSerializedConfig(
+    serialized,
+    file.tamaguiConfigMetadata
+  )
+  const registry = createModifierRegistry(config).registry
+  const candidates = createCandidatePropertyVocabulary(config)
+  const engine: DiagnoseStyleValueOptions = { config, registry, candidates }
+  const styleProps = createStylePropSet(config)
+
+  // themes and tokens keep their VALUES here; the grammar view keeps names only
+  const themes = (serialized.themes || {}) as Readonly<
+    Record<string, Readonly<Record<string, unknown>> | undefined>
+  >
+  const rootThemes = Object.keys(themes).filter((name) => !name.includes('_'))
+  const previewThemes = [
+    ...['light', 'dark'].filter((name) => rootThemes.includes(name)),
+    ...rootThemes.filter((name) => name !== 'light' && name !== 'dark'),
+  ]
+  const tokens = (serialized.tokens || {}) as Readonly<
+    Record<string, Readonly<Record<string, unknown>> | undefined>
+  >
+  const media = (serialized.media || {}) as Readonly<Record<string, unknown>>
+
+  const targetProperty = (name: string): string => config.shorthands?.[name] || name
+
+  const themeValue = (name: string): { theme: string; value: unknown } | null => {
+    for (const theme of previewThemes) {
+      const value = themes[theme]?.[name]
+      if (value !== undefined) return { theme, value }
+    }
+    return null
+  }
+
+  const annotationColor = (
+    annotation: StyleValueAnnotation
+  ): { color: RgbaColor; theme?: string } | null => {
+    if (annotation.kind === 'token' || annotation.kind === 'identifier') {
+      const name =
+        annotation.opacity !== undefined
+          ? annotation.text.slice(0, annotation.text.lastIndexOf('/'))
+          : annotation.text
+      if (annotation.tokenCategory === 'color') {
+        const themed = themeValue(name)
+        if (themed) {
+          const color = parseColor(themed.value, annotation.opacity)
+          return color ? { color, theme: themed.theme } : null
+        }
+        const color = parseColor(tokenValue(tokens.color?.[name]), annotation.opacity)
+        return color ? { color } : null
+      }
+      if (annotation.kind === 'identifier') {
+        // literal CSS colors: hex, rgb()/hsl() never annotate (functions are
+        // skipped), but hex runs and named colors do
+        const color = parseColor(name)
+        return color ? { color } : null
+      }
+      return null
+    }
+    if (annotation.kind === 'keyword' && annotation.text === 'transparent') {
+      return { color: { r: 0, g: 0, b: 0, a: 0 } }
+    }
+    return null
+  }
+
+  const annotations = (property: string, value: string) =>
+    annotateStyleValue(property, value, engine)
+
+  const formatRgba = (color: RgbaColor): string =>
+    color.a === 1
+      ? `rgb(${color.r}, ${color.g}, ${color.b})`
+      : `rgba(${color.r}, ${color.g}, ${color.b}, ${Number(color.a.toFixed(3))})`
+
+  return {
+    styleProps,
+    engine,
+    previewThemes,
+    isStyleProp: (name) => styleProps.has(name),
+    targetProperty,
+    modifierKind: (name) => registry.get(name),
+
+    completions(property, value, cursor) {
+      const target = targetProperty(property)
+      if (programEligibility(target) === 'legacy-part') return null
+      if (!styleProps.has(property)) return null
+      return completeStyleValueAtCursor(property, value, cursor, engine)
+    },
+
+    diagnostics(property, value) {
+      if (!styleProps.has(property)) return []
+      return diagnoseStyleValueProgram(property, value, engine)
+    },
+
+    annotations,
+
+    colors(property, value) {
+      if (!styleProps.has(property)) return []
+      const results: StyleValueColor[] = []
+      for (const annotation of annotations(property, value)) {
+        const resolved = annotationColor(annotation)
+        if (!resolved) continue
+        results.push({
+          start: annotation.start,
+          end: annotation.end,
+          text: annotation.text,
+          color: resolved.color,
+          ...(resolved.theme !== undefined && { theme: resolved.theme }),
+        })
+      }
+      return results
+    },
+
+    hover(property, value, offset) {
+      if (!styleProps.has(property)) return null
+      const annotation = annotations(property, value).find(
+        (entry) => offset >= entry.start && offset <= entry.end
+      )
+      if (!annotation) return null
+
+      const lines: string[] = []
+      let color: RgbaColor | undefined
+
+      if (annotation.kind === 'modifier' && annotation.modifierKind) {
+        lines.push(
+          `**${annotation.text}** · Tamagui ${modifierKindLabel[annotation.modifierKind]}`
+        )
+        if (annotation.modifierKind === 'media') {
+          const query = media[annotation.text]
+          if (query !== undefined) {
+            lines.push('```json\n' + JSON.stringify(query) + '\n```')
+          }
+        }
+      } else if (annotation.kind === 'token') {
+        const name =
+          annotation.opacity !== undefined
+            ? annotation.text.slice(0, annotation.text.lastIndexOf('/'))
+            : annotation.text
+        if (annotation.tokenCategory === 'color') {
+          lines.push(`**${name}** · Tamagui color`)
+          let shown = 0
+          for (const theme of previewThemes) {
+            const value = themes[theme]?.[name]
+            if (value === undefined || shown >= 4) continue
+            shown++
+            lines.push(`- ${theme}: \`${String(value)}\``)
+          }
+          if (shown === 0) {
+            const value = tokenValue(tokens.color?.[name])
+            if (value !== undefined) lines.push(`- \`${String(value)}\``)
+          }
+          if (annotation.opacity !== undefined) {
+            lines.push(`- opacity: ${annotation.opacity}%`)
+          }
+        } else {
+          const value = tokenValue(tokens[annotation.tokenCategory || '']?.[name])
+          lines.push(
+            `**${name}** · Tamagui ${annotation.tokenCategory} token` +
+              (value !== undefined ? ` = \`${String(value)}\`` : '')
+          )
+        }
+        const resolved = annotationColor(annotation)
+        if (resolved) {
+          color = resolved.color
+          lines.push(`- resolves: \`${formatRgba(resolved.color)}\``)
+        }
+      } else if (annotation.kind === 'keyword') {
+        lines.push(
+          `**${annotation.text}** · CSS keyword` +
+            (annotation.property ? ` for \`${annotation.property}\`` : '')
+        )
+      } else {
+        const resolved = annotationColor(annotation)
+        if (!resolved) return null
+        color = resolved.color
+        lines.push(
+          `**${annotation.text}** · CSS color = \`${formatRgba(resolved.color)}\``
+        )
+      }
+
+      return {
+        start: annotation.start,
+        end: annotation.end,
+        text: annotation.text,
+        markdown: lines.join('\n\n'),
+        ...(color !== undefined && { color }),
+      }
+    },
+  }
+}

package/src/document.ts

@@ -0,0 +1,140 @@
+// Document-level orchestration: an extractor locates the style value sites in
+// one source file, the core answers inside each site, and this module joins
+// the two so every host (browser IDE, LSP wrapper, CLI checker) gets
+// file-offset results from one code path.
+//
+// Extractors are pluggable because hosts already own a parse: the tsserver
+// plugin walks TypeScript's AST, the eslint rule walks ESTree, soot's bundler
+// holds sucrase tokens. Each adapter reduces its tree to the same StyleSite
+// contract; nothing downstream re-parses.
+
+import type {
+  StyleTooling,
+  StyleValueColor,
+  StyleValueDiagnostic,
+  StyleValueHover,
+} from './core'
+import type { StyleValueCursorCompletions } from './core'
+
+/** one static string style value in a source file */
+export interface StyleSite {
+  /** the authored prop name (`bg`, `padding`) */
+  property: string
+  /** the cooked string value */
+  value: string
+  /** file offset of the value's first character (inside the quotes) */
+  start: number
+  /** file offset just past the value's last character */
+  end: number
+  /** how the site was authored, for hosts that filter */
+  kind: 'jsx-attribute' | 'styled-property'
+}
+
+export type ExtractStyleSites = (
+  source: string,
+  fileName?: string
+) => readonly StyleSite[]
+
+export interface DocumentDiagnostic extends StyleValueDiagnostic {
+  site: StyleSite
+}
+
+export interface DocumentColor extends StyleValueColor {
+  site: StyleSite
+}
+
+export interface DocumentHover extends StyleValueHover {
+  site: StyleSite
+}
+
+export interface DocumentCompletions extends StyleValueCursorCompletions {
+  site: StyleSite
+}
+
+export interface DocumentStyleTooling {
+  sites(source: string, fileName?: string): readonly StyleSite[]
+  /** completions at a file offset, spans mapped to file offsets */
+  completionsAt(
+    source: string,
+    offset: number,
+    fileName?: string
+  ): DocumentCompletions | null
+  /** every diagnostic in the file, spans mapped to file offsets */
+  diagnostics(source: string, fileName?: string): readonly DocumentDiagnostic[]
+  /** hover at a file offset, span mapped to file offsets */
+  hoverAt(source: string, offset: number, fileName?: string): DocumentHover | null
+  /** every color swatch in the file, spans mapped to file offsets */
+  colors(source: string, fileName?: string): readonly DocumentColor[]
+}
+
+export function createDocumentStyleTooling(
+  tooling: StyleTooling,
+  extract: ExtractStyleSites
+): DocumentStyleTooling {
+  const siteAt = (sites: readonly StyleSite[], offset: number): StyleSite | undefined =>
+    sites.find((site) => offset >= site.start && offset <= site.end)
+
+  return {
+    sites: (source, fileName) => extract(source, fileName),
+
+    completionsAt(source, offset, fileName) {
+      const site = siteAt(extract(source, fileName), offset)
+      if (!site) return null
+      const completions = tooling.completions(
+        site.property,
+        site.value,
+        offset - site.start
+      )
+      if (!completions) return null
+      return {
+        ...completions,
+        replaceStart: site.start + completions.replaceStart,
+        site,
+      }
+    },
+
+    diagnostics(source, fileName) {
+      const results: DocumentDiagnostic[] = []
+      for (const site of extract(source, fileName)) {
+        for (const diagnostic of tooling.diagnostics(site.property, site.value)) {
+          results.push({
+            ...diagnostic,
+            index: site.start + diagnostic.index,
+            start: site.start + diagnostic.start,
+            end: site.start + diagnostic.end,
+            site,
+          })
+        }
+      }
+      return results
+    },
+
+    hoverAt(source, offset, fileName) {
+      const site = siteAt(extract(source, fileName), offset)
+      if (!site) return null
+      const hover = tooling.hover(site.property, site.value, offset - site.start)
+      if (!hover) return null
+      return {
+        ...hover,
+        start: site.start + hover.start,
+        end: site.start + hover.end,
+        site,
+      }
+    },
+
+    colors(source, fileName) {
+      const results: DocumentColor[] = []
+      for (const site of extract(source, fileName)) {
+        for (const color of tooling.colors(site.property, site.value)) {
+          results.push({
+            ...color,
+            start: site.start + color.start,
+            end: site.start + color.end,
+            site,
+          })
+        }
+      }
+      return results
+    },
+  }
+}