lightningcss-tailwindcss 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ice breaker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# lightningcss-tailwindcss
+
+Lightning CSS AST utilities for analyzing Tailwind CSS syntax.
+
+## Overview
+
+This package provides a Tailwind-oriented analysis layer on top of **Lightning CSS AST**.
+
+It extracts:
+
+- `@apply` utility candidates
+- `theme(...)` calls
+- Tailwind import directives
+- utility selectors declared in authored stylesheets
+- basic Tailwind version hints from parsed syntax
+- parser warnings emitted while Lightning CSS recovers invalid or custom syntax
+
+This package is useful when your tooling already depends on Lightning CSS AST and you want to inspect Tailwind-related syntax without switching to PostCSS.
+
+## Installation
+
+```bash
+pnpm add -D lightningcss-tailwindcss
+```
+
+## When To Use This Package
+
+Use `lightningcss-tailwindcss` when:
+
+- your pipeline already uses `lightningcss`
+- you want a fast Rust-backed parser with JS visitor access
+- you are comfortable with recovered/normalized AST output
+
+Use `postcss-tailwindcss` instead when:
+
+- you need more permissive authored-source parsing
+- you want direct PostCSS node references
+- you need project-aware Tailwind runtime/config resolution
+
+## API
+
+- `parseTailwindCss(input)`
+- `detectTailwindVersion(input)`
+- `collectApplyCandidates(input)`
+- `collectThemeCalls(input)`
+- `collectImportDirectives(input)`
+- `collectUtilitySelectors(input)`
+- `analyzeTailwindCss(input)`
+
+## Example
+
+```ts
+import { analyzeTailwindCss } from 'lightningcss-tailwindcss'
+
+const css = `
+@import "tailwindcss" source(none) prefix(tw);
+
+.button {
+  @apply flex hover:bg-red-500;
+  color: theme(colors.gray.900 / 75%);
+}
+`
+
+const result = analyzeTailwindCss(css)
+
+console.log(result.version)
+console.log(result.applyCandidates.map(item => item.candidate))
+console.log(result.warnings)
+```
+
+## Return Shape
+
+`analyzeTailwindCss()` returns:
+
+```ts
+interface TailwindAnalysis {
+  version: 3 | 4 | 'unknown'
+  applyCandidates: UtilityCandidate[]
+  themeCalls: ThemeCall[]
+  importDirectives: TailwindImportDirective[]
+  utilitySelectors: UtilitySelector[]
+  warnings: LightningWarning[]
+}
+```
+
+Unlike the PostCSS version, this package returns Lightning CSS AST fragments and `loc` data rather than PostCSS nodes.
+
+## Parsing Behavior
+
+This package relies on Lightning CSS `transform()` with `errorRecovery: true`.
+
+That means:
+
+- unsupported Tailwind syntax may still be preserved in recovered form
+- parser warnings are expected for some Tailwind-specific constructs
+- v4 `@import "tailwindcss" source(...) prefix(...)` is analyzable even if Lightning CSS treats parts of it as recovered tokens
+
+## Important Differences From `postcss-tailwindcss`
+
+- No Tailwind runtime resolution helpers
+- No PostCSS node references
+- More normalized AST output
+- Better fit for tools that already consume Lightning CSS visitors
+
+If you need to inspect the consuming project's installed Tailwind runtime or config file, use `postcss-tailwindcss`.

package/README.zh.md

@@ -0,0 +1,101 @@
+# lightningcss-tailwindcss
+
+用于分析 Tailwind CSS 语法的 Lightning CSS AST 工具集。
+
+## 概览
+
+这个包是在 **Lightning CSS AST** 之上做的一层 Tailwind 语法分析能力。
+
+它可以提取：
+
+- `@apply` 中的 utility candidate
+- `theme(...)` 调用
+- Tailwind import 指令
+- 手写样式中声明的 utility selector
+- 基于语法信号推断的 Tailwind 版本
+- Lightning CSS 在容错解析过程中产生的 warning
+
+如果你的工具链本身已经依赖 Lightning CSS AST，而你又想分析 Tailwind 相关语法，这个包会比较合适。
+
+## 安装
+
+```bash
+pnpm add -D lightningcss-tailwindcss
+```
+
+## 适用场景
+
+推荐在这些情况下使用 `lightningcss-tailwindcss`：
+
+- 你的分析流程已经基于 `lightningcss`
+- 你希望用 Rust 驱动的解析器 + JS visitor
+- 你可以接受“恢复后”的 AST 输出
+
+如果你需要更宽松的源码级解析、PostCSS 节点引用，或者需要解析使用方项目的 Tailwind 安装与配置，请使用 `postcss-tailwindcss`。
+
+## API
+
+- `parseTailwindCss(input)`
+- `detectTailwindVersion(input)`
+- `collectApplyCandidates(input)`
+- `collectThemeCalls(input)`
+- `collectImportDirectives(input)`
+- `collectUtilitySelectors(input)`
+- `analyzeTailwindCss(input)`
+
+## 示例
+
+```ts
+import { analyzeTailwindCss } from 'lightningcss-tailwindcss'
+
+const css = `
+@import "tailwindcss" source(none) prefix(tw);
+
+.button {
+  @apply flex hover:bg-red-500;
+  color: theme(colors.gray.900 / 75%);
+}
+`
+
+const result = analyzeTailwindCss(css)
+
+console.log(result.version)
+console.log(result.applyCandidates.map(item => item.candidate))
+console.log(result.warnings)
+```
+
+## 返回结果
+
+`analyzeTailwindCss()` 返回：
+
+```ts
+interface TailwindAnalysis {
+  version: 3 | 4 | 'unknown'
+  applyCandidates: UtilityCandidate[]
+  themeCalls: ThemeCall[]
+  importDirectives: TailwindImportDirective[]
+  utilitySelectors: UtilitySelector[]
+  warnings: LightningWarning[]
+}
+```
+
+和 PostCSS 版本不同，这里返回的是 Lightning CSS AST 片段与 `loc` 信息，而不是 PostCSS 节点对象。
+
+## 解析特性
+
+这个包内部依赖 Lightning CSS 的 `transform()`，并开启了 `errorRecovery: true`。
+
+这意味着：
+
+- 某些 Tailwind 扩展语法会以“容错恢复”的形式保留下来
+- 对部分 Tailwind 特有写法出现 warning 是预期行为
+- v4 的 `@import "tailwindcss" source(...) prefix(...)` 仍然可以被分析，即使 Lightning CSS 不会把它完全当成标准语法
+
+## 与 `postcss-tailwindcss` 的区别
+
+- 不提供 Tailwind 运行时/配置解析能力
+- 不返回 PostCSS 节点
+- AST 结果更偏“规范化输出”
+- 更适合已经基于 Lightning CSS visitor 的工具
+
+如果你还需要感知使用方项目里真实安装的 Tailwind 版本和配置文件位置，应该选 `postcss-tailwindcss`。

package/dist/index.d.ts

@@ -0,0 +1,60 @@
+import { ImportRule, Location2, Selector, StyleSheet, UnknownAtRule } from "lightningcss";
+
+//#region src/index.d.ts
+type TailwindVersion = 3 | 4 | 'unknown';
+interface LightningWarning {
+  message: string;
+  type: string;
+  loc?: {
+    filename?: string;
+    line: number;
+    column: number;
+  };
+}
+interface ParseTailwindCssResult {
+  stylesheet: StyleSheet;
+  warnings: LightningWarning[];
+}
+interface UtilityCandidate {
+  candidate: string;
+  ruleName: string;
+  loc: UnknownAtRule['loc'];
+}
+interface ThemeCall {
+  raw: string;
+  path: string;
+  opacity: string | null;
+  functionName: string;
+}
+interface TailwindImportDirective {
+  importTarget: string;
+  functions: Array<{
+    name: string;
+    value: string;
+  }>;
+  hasLayerKeyword: boolean;
+  mediaQuery: string | null;
+  loc: ImportRule['loc'];
+}
+interface UtilitySelector {
+  className: string;
+  selector: Selector;
+  loc: Location2;
+}
+interface TailwindAnalysis {
+  version: TailwindVersion;
+  applyCandidates: UtilityCandidate[];
+  themeCalls: ThemeCall[];
+  importDirectives: TailwindImportDirective[];
+  utilitySelectors: UtilitySelector[];
+  warnings: LightningWarning[];
+}
+declare function parseTailwindCss(input: string): ParseTailwindCssResult;
+declare function detectTailwindVersion(input: string): TailwindVersion;
+declare function collectApplyCandidates(input: string): UtilityCandidate[];
+declare function collectThemeCalls(input: string): ThemeCall[];
+declare function collectImportDirectives(input: string): TailwindImportDirective[];
+declare function collectUtilitySelectors(input: string): UtilitySelector[];
+declare function analyzeTailwindCss(input: string): TailwindAnalysis;
+//#endregion
+export { LightningWarning, ParseTailwindCssResult, TailwindAnalysis, TailwindImportDirective, TailwindVersion, ThemeCall, UtilityCandidate, UtilitySelector, analyzeTailwindCss, collectApplyCandidates, collectImportDirectives, collectThemeCalls, collectUtilitySelectors, detectTailwindVersion, parseTailwindCss };

package/dist/index.js

@@ -0,0 +1,310 @@
+import { Buffer } from "node:buffer";
+import { transform } from "lightningcss";
+//#region src/index.ts
+const WHITESPACE_RE = /\s/;
+function tokenToString(token) {
+	switch (token.type) {
+		case "ident":
+		case "at-keyword":
+		case "hash":
+		case "id-hash":
+		case "white-space":
+		case "comment":
+		case "string":
+		case "unquoted-url":
+		case "delim":
+		case "bad-string":
+		case "bad-url": return token.value;
+		case "number": return String(token.value);
+		case "percentage": return `${token.value * 100}%`;
+		case "dimension": return `${token.value}${token.unit}`;
+		case "colon": return ":";
+		case "semicolon": return ";";
+		case "comma": return ",";
+		case "include-match": return "~=";
+		case "dash-match": return "|=";
+		case "prefix-match": return "^=";
+		case "suffix-match": return "$=";
+		case "substring-match": return "*=";
+		case "cdo": return "<!--";
+		case "cdc": return "-->";
+		case "function": return `${token.value}(`;
+		case "parenthesis-block": return "(";
+		case "square-bracket-block": return "[";
+		case "curly-bracket-block": return "{";
+		case "close-parenthesis": return ")";
+		case "close-square-bracket": return "]";
+		case "close-curly-bracket": return "}";
+		default: return "";
+	}
+}
+function tokenOrValueListToString(nodes) {
+	let output = "";
+	for (const [index, node] of nodes.entries()) {
+		const rendered = tokenOrValueToString(node);
+		if (node.type === "token" && node.value.type === "number" && index > 0) {
+			const previous = nodes[index - 1];
+			if (previous && previous.type === "token" && previous.value.type === "ident") {
+				const numericValue = node.value.value;
+				const normalized = numericValue > 0 && numericValue < 1 ? String(Math.round(numericValue * 1e3)) : rendered;
+				output += `.${normalized}`;
+				continue;
+			}
+		}
+		output += rendered;
+	}
+	return output;
+}
+function tokenOrValueToString(node) {
+	switch (node.type) {
+		case "token": return tokenToString(node.value);
+		case "function": return `${node.value.name}(${tokenOrValueListToString(node.value.arguments)})`;
+		case "dashed-ident":
+		case "animation-name": return String(node.value);
+		case "length": return `${node.value.value}${node.value.unit}`;
+		case "angle": return `${node.value.value}${node.value.type}`;
+		case "time": return `${node.value.value}${node.value.type === "seconds" ? "s" : "ms"}`;
+		case "resolution": return `${node.value.value}${node.value.type}`;
+		case "url": return `url(${String(node.value.url)})`;
+		case "var": return `var(${String(node.value.name)})`;
+		case "env": return `env(${String(node.value.name)})`;
+		case "color":
+		case "unresolved-color": return JSON.stringify(node.value);
+		default: return "";
+	}
+}
+function splitCandidateList(input) {
+	const candidates = [];
+	let current = "";
+	let bracketDepth = 0;
+	let parenDepth = 0;
+	let quote = null;
+	let escaped = false;
+	for (const char of input) {
+		if (escaped) {
+			current += char;
+			escaped = false;
+			continue;
+		}
+		if (char === "\\") {
+			current += char;
+			escaped = true;
+			continue;
+		}
+		if (quote) {
+			current += char;
+			if (char === quote) quote = null;
+			continue;
+		}
+		if (char === "\"" || char === "'") {
+			current += char;
+			quote = char;
+			continue;
+		}
+		if (char === "[") {
+			bracketDepth += 1;
+			current += char;
+			continue;
+		}
+		if (char === "]") {
+			bracketDepth = Math.max(0, bracketDepth - 1);
+			current += char;
+			continue;
+		}
+		if (char === "(") {
+			parenDepth += 1;
+			current += char;
+			continue;
+		}
+		if (char === ")") {
+			parenDepth = Math.max(0, parenDepth - 1);
+			current += char;
+			continue;
+		}
+		if (WHITESPACE_RE.test(char) && bracketDepth === 0 && parenDepth === 0) {
+			const value = current.trim();
+			if (value) candidates.push(value);
+			current = "";
+			continue;
+		}
+		current += char;
+	}
+	const last = current.trim();
+	if (last) candidates.push(last);
+	return candidates;
+}
+function parseThemeArgument(raw) {
+	let bracketDepth = 0;
+	let parenDepth = 0;
+	let slashIndex = -1;
+	for (let i = 0; i < raw.length; i += 1) {
+		const char = raw[i];
+		if (char === "[") bracketDepth += 1;
+		else if (char === "]") bracketDepth = Math.max(0, bracketDepth - 1);
+		else if (char === "(") parenDepth += 1;
+		else if (char === ")") parenDepth = Math.max(0, parenDepth - 1);
+		else if (char === "/" && bracketDepth === 0 && parenDepth === 0) {
+			slashIndex = i;
+			break;
+		}
+	}
+	if (slashIndex === -1) return {
+		path: raw.trim(),
+		opacity: null
+	};
+	return {
+		path: raw.slice(0, slashIndex).trim(),
+		opacity: raw.slice(slashIndex + 1).trim() || null
+	};
+}
+function parseWithLightningCss(input) {
+	let stylesheetRef;
+	const result = transform({
+		filename: "input.css",
+		code: Buffer.from(input),
+		errorRecovery: true,
+		visitor: { StyleSheet(stylesheet) {
+			stylesheetRef = stylesheet;
+		} }
+	});
+	if (!stylesheetRef) throw new Error("Failed to capture Lightning CSS stylesheet");
+	return {
+		stylesheet: stylesheetRef,
+		warnings: result.warnings.map((warning) => ({
+			message: warning.message,
+			type: warning.type,
+			loc: warning.loc
+		}))
+	};
+}
+function parseTailwindCss(input) {
+	return parseWithLightningCss(input);
+}
+function walkRules(rules, visit) {
+	for (const rule of rules) {
+		visit(rule);
+		if (rule.type === "style") walkRules(rule.value.rules ?? [], visit);
+		else if (rule.type === "media" || rule.type === "supports" || rule.type === "container" || rule.type === "scope" || rule.type === "starting-style" || rule.type === "layer-block") walkRules(rule.value.rules, visit);
+	}
+}
+function detectTailwindVersion(input) {
+	const { stylesheet } = parseWithLightningCss(input);
+	let hasV3 = false;
+	let hasV4 = false;
+	walkRules(stylesheet.rules, (rule) => {
+		if (rule.type === "import") {
+			if (rule.value.url.includes("tailwindcss")) hasV4 = true;
+			return;
+		}
+		if (rule.type !== "unknown") return;
+		if (["tailwind", "config"].includes(rule.value.name)) hasV3 = true;
+		if ([
+			"theme",
+			"source",
+			"utility",
+			"variant",
+			"custom-variant",
+			"plugin",
+			"reference"
+		].includes(rule.value.name)) hasV4 = true;
+	});
+	if (hasV4) return 4;
+	if (hasV3) return 3;
+	return "unknown";
+}
+function collectApplyCandidates(input) {
+	const { stylesheet } = parseWithLightningCss(input);
+	const candidates = [];
+	walkRules(stylesheet.rules, (rule) => {
+		if (rule.type !== "unknown" || rule.value.name !== "apply") return;
+		const prelude = tokenOrValueListToString(rule.value.prelude);
+		for (const candidate of splitCandidateList(prelude)) candidates.push({
+			candidate,
+			ruleName: rule.value.name,
+			loc: rule.value.loc
+		});
+	});
+	return candidates;
+}
+function collectThemeCalls(input) {
+	const calls = [];
+	transform({
+		filename: "input.css",
+		code: Buffer.from(input),
+		errorRecovery: true,
+		visitor: { Function: { theme(fn) {
+			const raw = tokenOrValueListToString(fn.arguments).trim();
+			const { path, opacity } = parseThemeArgument(raw);
+			calls.push({
+				raw,
+				path,
+				opacity,
+				functionName: fn.name
+			});
+		} } }
+	});
+	return calls;
+}
+function collectImportDirectives(input) {
+	const { stylesheet } = parseWithLightningCss(input);
+	const directives = [];
+	walkRules(stylesheet.rules, (rule) => {
+		if (rule.type !== "import" || !rule.value.url.includes("tailwindcss")) return;
+		const condition = rule.value.media?.mediaQueries[0]?.condition;
+		const tokens = condition?.type === "unknown" ? condition.value : [];
+		const functions = tokens.filter((item) => item.type === "function").filter((item) => [
+			"source",
+			"prefix",
+			"layer",
+			"supports"
+		].includes(item.value.name)).map((item) => ({
+			name: item.value.name,
+			value: tokenOrValueListToString(item.value.arguments).trim()
+		}));
+		const mediaQuery = tokenOrValueListToString(tokens.filter((item) => {
+			return !(item.type === "function" && [
+				"source",
+				"prefix",
+				"layer",
+				"supports"
+			].includes(item.value.name));
+		})).trim() || null;
+		directives.push({
+			importTarget: rule.value.url,
+			functions,
+			hasLayerKeyword: Boolean(rule.value.layer),
+			mediaQuery,
+			loc: rule.value.loc
+		});
+	});
+	return directives;
+}
+function collectUtilitySelectors(input) {
+	const { stylesheet } = parseWithLightningCss(input);
+	const selectors = [];
+	walkRules(stylesheet.rules, (rule) => {
+		if (rule.type !== "style") return;
+		for (const selector of rule.value.selectors) for (const component of selector) {
+			if (component.type !== "class") continue;
+			selectors.push({
+				className: component.name,
+				selector,
+				loc: rule.value.loc
+			});
+		}
+	});
+	return selectors;
+}
+function analyzeTailwindCss(input) {
+	const parsed = parseWithLightningCss(input);
+	return {
+		version: detectTailwindVersion(input),
+		applyCandidates: collectApplyCandidates(input),
+		themeCalls: collectThemeCalls(input),
+		importDirectives: collectImportDirectives(input),
+		utilitySelectors: collectUtilitySelectors(input),
+		warnings: parsed.warnings
+	};
+}
+//#endregion
+export { analyzeTailwindCss, collectApplyCandidates, collectImportDirectives, collectThemeCalls, collectUtilitySelectors, detectTailwindVersion, parseTailwindCss };

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "lightningcss-tailwindcss",
+  "type": "module",
+  "version": "0.0.0",
+  "description": "Lightning CSS AST utilities for analyzing Tailwind CSS syntax",
+  "author": "ice breaker <1324318532@qq.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sonofmagic/dev-configs.git",
+    "directory": "packages/lightningcss-tailwindcss"
+  },
+  "bugs": {
+    "url": "https://github.com/sonofmagic/dev-configs/issues"
+  },
+  "keywords": [
+    "dev-configs",
+    "icebreakers",
+    "lightningcss",
+    "tailwindcss"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "README.md",
+    "README.zh.md",
+    "dist"
+  ],
+  "dependencies": {
+    "lightningcss": "^1.31.1"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "dev": "tsdown --watch --sourcemap",
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:dev": "vitest",
+    "release": "pnpm publish",
+    "sync": "cnpm sync lightningcss-tailwindcss",
+    "typecheck": "tsc --noEmit"
+  }
+}