@lark-apaas/fullstack-presets 1.1.22 → 1.1.23-alpha.0

package/lib/custom-stylelint-rules/__test__/tailwind-theme-v4-required.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/custom-stylelint-rules/__test__/tailwind-theme-v4-required.test.js

@@ -0,0 +1,140 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const stylelint_1 = __importDefault(require("stylelint"));
+const node_path_1 = __importDefault(require("node:path"));
+const tailwind_theme_v4_required_1 = __importStar(require("../tailwind-theme-v4-required"));
+async function lint(code, codeFilename = 'tailwind-theme.css') {
+    return stylelint_1.default.lint({
+        code,
+        codeFilename: node_path_1.default.resolve(process.cwd(), codeFilename),
+        config: {
+            plugins: [tailwind_theme_v4_required_1.default],
+            rules: {
+                [tailwind_theme_v4_required_1.ruleName]: true,
+            },
+        },
+    });
+}
+(0, vitest_1.describe)('custom/tailwind-theme-v4-required', () => {
+    (0, vitest_1.it)('passes on v4 syntax (@theme inline + token map)', async () => {
+        const result = await lint(`
+      :root {
+        --background: hsl(0 0% 100%);
+        --primary: hsl(221 83% 53%);
+        --border: hsl(220 14% 89%);
+      }
+      @theme inline {
+        --color-background: var(--background);
+        --color-primary: var(--primary);
+        --color-border: var(--border);
+      }
+    `);
+        (0, vitest_1.expect)(result.results[0].warnings).toEqual([]);
+        (0, vitest_1.expect)(result.errored).toBe(false);
+    });
+    (0, vitest_1.it)('passes on plain @theme block (no inline)', async () => {
+        const result = await lint(`
+      @theme {
+        --color-background: hsl(0 0% 100%);
+        --color-primary: hsl(221 83% 53%);
+        --color-border: hsl(220 14% 89%);
+      }
+    `);
+        (0, vitest_1.expect)(result.results[0].warnings).toEqual([]);
+        (0, vitest_1.expect)(result.errored).toBe(false);
+    });
+    (0, vitest_1.it)('flags v3 @tailwind directives', async () => {
+        const result = await lint(`
+      @tailwind base;
+      @tailwind components;
+      @tailwind utilities;
+      :root {
+        --background: oklch(1 0 0);
+      }
+    `);
+        // 3 个 @tailwind 指令各报一次
+        (0, vitest_1.expect)(result.results[0].warnings.length).toBeGreaterThanOrEqual(3);
+        (0, vitest_1.expect)(result.results[0].warnings.some(w => w.text.includes('Tailwind v4'))).toBe(true);
+        (0, vitest_1.expect)(result.errored).toBe(true);
+    });
+    (0, vitest_1.it)('flags shadcn tokens without @theme block', async () => {
+        const result = await lint(`
+      :root {
+        --background: oklch(1 0 0);
+        --foreground: oklch(0.141 0.005 285.823);
+        --primary: oklch(0.685 0.168 243.8);
+        --border: oklch(0.92 0.004 286.32);
+      }
+    `);
+        (0, vitest_1.expect)(result.results[0].warnings.length).toBe(1);
+        (0, vitest_1.expect)(result.results[0].warnings[0].text).toContain('missing the `@theme`');
+        (0, vitest_1.expect)(result.errored).toBe(true);
+    });
+    (0, vitest_1.it)('skips files whose name does not contain tailwind-theme', async () => {
+        const result = await lint(`@tailwind base; :root { --background: white; }`, 'random-stylesheet.css');
+        (0, vitest_1.expect)(result.results[0].warnings).toEqual([]);
+        (0, vitest_1.expect)(result.errored).toBe(false);
+    });
+    (0, vitest_1.it)('reproduces W21 failing case (app_4k6tdqaryjmzr style v3 regression)', async () => {
+        // 真实 W21 失败 case 的退化写法
+        const result = await lint(`
+      @tailwind base;
+      @tailwind components;
+      @tailwind utilities;
+
+      @layer base {
+        :root {
+          --background: oklch(1 0 0);
+          --foreground: oklch(0.141 0.005 285.823);
+          --primary: oklch(0.685 0.168 243.8);
+          --border: oklch(0.92 0.004 286.32);
+        }
+      }
+
+      @layer base {
+        * { border-color: var(--border); }
+      }
+    `);
+        (0, vitest_1.expect)(result.errored).toBe(true);
+        // 至少 3 个 @tailwind 指令报错
+        const v3Errors = result.results[0].warnings.filter(w => w.text.includes('Tailwind v4'));
+        (0, vitest_1.expect)(v3Errors.length).toBeGreaterThanOrEqual(3);
+    });
+});

package/lib/custom-stylelint-rules/tailwind-theme-v4-required.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 自定义 Stylelint 规则：禁止 tailwind-theme.css 退化到 Tailwind v3 写法
+ *
+ * 背景：
+ *   模板（nestjs-react-fullstack-template 等）2025-09-30 起已迁移到 Tailwind v4，
+ *   `client/src/tailwind-theme.css` 用 `@theme inline { --color-* }` 块把 shadcn
+ *   token 映射成 v4 utility（让 `border-border` `bg-primary` 等正常工作）。
+ *
+ *   W21 数据观察到 AI 在用户工程里**主动重写** tailwind-theme.css 时退化到
+ *   v3 写法：使用 `@tailwind base/components/utilities` 指令 + 删除
+ *   `@theme inline` 块，导致 v4 下所有依赖 token 映射的 utility（如
+ *   `border-border`、`bg-primary`、`focus:border-primary`）都报
+ *   "Cannot apply unknown utility class"，pre-commit lint 跑不到 className
+ *   层面，构建沙箱阶段才报错。
+ *
+ *   这条规则在 stylelint 阶段直接拦住 tailwind-theme.css 的退化写法。
+ *
+ * 检测的退化标志（任一命中即报错）：
+ *   1. 出现 `@tailwind base/components/utilities/screens/variants` 指令
+ *      （这些是 Tailwind v3 入口指令，v4 用 `@import "tailwindcss"` + `@theme`）
+ *   2. 文件中有任何 token 定义（如 `--background: ...`、`--primary: ...`）
+ *      但全文不含 `@theme` 块（v4 必备的 token 映射入口）
+ *
+ * 匹配文件：默认只对文件名包含 `tailwind-theme` 的 .css 生效；
+ *   通过 secondary options.filePattern 可自定义匹配模式。
+ *
+ * 修复指引：把 `:root { --xxx }` token 保留，删掉 `@tailwind ...` 指令，
+ *   并新增 `@theme inline { --color-xxx: var(--xxx); ... }` 块，
+ *   完整范例参考 nestjs-react-fullstack-template/client/src/tailwind-theme.css。
+ */
+import stylelint from 'stylelint';
+export declare const ruleName = "custom/tailwind-theme-v4-required";
+export declare const messages: {
+    v3Directive: (directive: string) => string;
+    missingThemeBlock: string;
+};
+export declare const meta: {
+    url: string;
+};
+declare const _default: stylelint.Plugin;
+export default _default;

package/lib/custom-stylelint-rules/tailwind-theme-v4-required.js

@@ -0,0 +1,130 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.meta = exports.messages = exports.ruleName = void 0;
+// @ts-nocheck
+/**
+ * 自定义 Stylelint 规则：禁止 tailwind-theme.css 退化到 Tailwind v3 写法
+ *
+ * 背景：
+ *   模板（nestjs-react-fullstack-template 等）2025-09-30 起已迁移到 Tailwind v4，
+ *   `client/src/tailwind-theme.css` 用 `@theme inline { --color-* }` 块把 shadcn
+ *   token 映射成 v4 utility（让 `border-border` `bg-primary` 等正常工作）。
+ *
+ *   W21 数据观察到 AI 在用户工程里**主动重写** tailwind-theme.css 时退化到
+ *   v3 写法：使用 `@tailwind base/components/utilities` 指令 + 删除
+ *   `@theme inline` 块，导致 v4 下所有依赖 token 映射的 utility（如
+ *   `border-border`、`bg-primary`、`focus:border-primary`）都报
+ *   "Cannot apply unknown utility class"，pre-commit lint 跑不到 className
+ *   层面，构建沙箱阶段才报错。
+ *
+ *   这条规则在 stylelint 阶段直接拦住 tailwind-theme.css 的退化写法。
+ *
+ * 检测的退化标志（任一命中即报错）：
+ *   1. 出现 `@tailwind base/components/utilities/screens/variants` 指令
+ *      （这些是 Tailwind v3 入口指令，v4 用 `@import "tailwindcss"` + `@theme`）
+ *   2. 文件中有任何 token 定义（如 `--background: ...`、`--primary: ...`）
+ *      但全文不含 `@theme` 块（v4 必备的 token 映射入口）
+ *
+ * 匹配文件：默认只对文件名包含 `tailwind-theme` 的 .css 生效；
+ *   通过 secondary options.filePattern 可自定义匹配模式。
+ *
+ * 修复指引：把 `:root { --xxx }` token 保留，删掉 `@tailwind ...` 指令，
+ *   并新增 `@theme inline { --color-xxx: var(--xxx); ... }` 块，
+ *   完整范例参考 nestjs-react-fullstack-template/client/src/tailwind-theme.css。
+ */
+const stylelint_1 = __importDefault(require("stylelint"));
+exports.ruleName = 'custom/tailwind-theme-v4-required';
+const { report, ruleMessages, validateOptions } = stylelint_1.default.utils;
+exports.messages = ruleMessages(exports.ruleName, {
+    v3Directive: (directive) => `tailwind-theme.css must use Tailwind v4 syntax. Remove the v3 directive \`@tailwind ${directive}\` and use \`@theme\` block instead. See https://tailwindcss.com/docs/v4-beta#migrating-from-v3`,
+    missingThemeBlock: 'tailwind-theme.css defines CSS tokens but is missing the `@theme` (or `@theme inline`) block that maps them to v4 utilities. Without it, utility classes like `border-border`/`bg-primary` will not work. Add a `@theme inline { --color-*: var(--*); ... }` block.',
+});
+exports.meta = {
+    url: 'https://github.com/bytedance/fullstack-plugin/tree/main/packages/tools/fullstack-presets/src/custom-stylelint-rules/tailwind-theme-v4-required.ts',
+};
+const V3_DIRECTIVES = new Set([
+    'tailwind',
+]);
+// Tokens that strongly indicate this is a shadcn / tailwind theme file
+// (rather than an unrelated stylesheet that happens to use CSS variables).
+const SHADCN_TOKEN_HINTS = [
+    '--background',
+    '--foreground',
+    '--primary',
+    '--secondary',
+    '--accent',
+    '--destructive',
+    '--border',
+    '--ring',
+];
+const rule = (primary, secondary) => {
+    return (root, result) => {
+        const validOptions = validateOptions(result, exports.ruleName, {
+            actual: primary,
+            possible: [true],
+        }, {
+            actual: secondary,
+            possible: {
+                filePattern: [v => typeof v === 'string'],
+            },
+            optional: true,
+        });
+        if (!validOptions || !primary)
+            return;
+        const sourceFile = root.source?.input?.file ?? '';
+        const filePattern = secondary?.filePattern ?? 'tailwind-theme';
+        // Only apply rule to files matching the configured pattern (filename substring match).
+        if (!sourceFile.includes(filePattern))
+            return;
+        let hasV3Directive = false;
+        let hasThemeBlock = false;
+        let hasShadcnToken = false;
+        // 1) 扫所有 @tailwind / @theme at-rules
+        root.walkAtRules(atRule => {
+            const name = atRule.name.toLowerCase();
+            if (V3_DIRECTIVES.has(name)) {
+                const params = atRule.params.trim().split(/\s+/)[0]?.toLowerCase() ?? '';
+                // 仅 @tailwind base / components / utilities / screens / variants 才是 v3 入口指令；
+                // @tailwind 后跟其他内容（不太可能）也一并拦下。
+                hasV3Directive = true;
+                report({
+                    message: exports.messages.v3Directive(params || atRule.params),
+                    node: atRule,
+                    result,
+                    ruleName: exports.ruleName,
+                });
+            }
+            if (name === 'theme') {
+                hasThemeBlock = true;
+            }
+        });
+        // 2) 扫所有声明里的 token，标记是否含 shadcn 风格 token
+        if (!hasThemeBlock) {
+            root.walkDecls(decl => {
+                if (hasShadcnToken)
+                    return;
+                if (!decl.prop.startsWith('--'))
+                    return;
+                if (SHADCN_TOKEN_HINTS.some(hint => decl.prop === hint)) {
+                    hasShadcnToken = true;
+                }
+            });
+            if (hasShadcnToken) {
+                // 文件有 shadcn token 但没 @theme 块 → v3 残留 / 缺映射
+                report({
+                    message: exports.messages.missingThemeBlock,
+                    node: root,
+                    result,
+                    ruleName: exports.ruleName,
+                });
+            }
+        }
+    };
+};
+rule.ruleName = exports.ruleName;
+rule.messages = exports.messages;
+rule.meta = exports.meta;
+exports.default = stylelint_1.default.createPlugin(exports.ruleName, rule);

package/lib/simple/recommend/eslint/eslint-client.d.ts

@@ -17,6 +17,7 @@ declare const _default: ({
     plugins: {
         'react-hooks': any;
         import: any;
+        tailwindcss: any;
     };
     settings: {
         'import/resolver': {
@@ -27,6 +28,9 @@ declare const _default: ({
         'import/parsers': {
             '@typescript-eslint/parser': string[];
         };
+        tailwindcss: {
+            callees: string[];
+        };
     };
     rules: any;
 } | {

package/lib/simple/recommend/eslint/eslint-client.js

@@ -5,6 +5,7 @@ const globals = require('globals');
 const reactHooks = require('eslint-plugin-react-hooks');
 const tseslint = require('typescript-eslint');
 const importPlugin = require('eslint-plugin-import');
+const tailwindPlugin = require('eslint-plugin-tailwindcss');
 const fs = require('fs');
 const path = require('path');
 // 检查是否启用宽松 lint 模式
@@ -149,6 +150,7 @@ const baseConfig = {
     plugins: {
         'react-hooks': reactHooks,
         import: importPlugin,
+        tailwindcss: tailwindPlugin,
         ...looseSpecificPlugins,
     },
     settings: {
@@ -160,6 +162,12 @@ const baseConfig = {
         'import/parsers': {
             '@typescript-eslint/parser': ['.ts', '.tsx'],
         },
+        // eslint-plugin-tailwindcss v4+ 默认会自动发现 tailwind config（v4 用 CSS @theme）
+        // callees 列出运行时会拼 className 的工具函数；plugin 会扫这些函数的字符串参数
+        tailwindcss: {
+            callees: ['classnames', 'clsx', 'cn', 'cva', 'twMerge'],
+            // 用户工程可自定义 entryPoint（默认探测 tailwind.config.* 与 @config 指令）
+        },
     },
     rules: {
         // React Hooks 推荐规则
@@ -173,6 +181,14 @@ const baseConfig = {
         '@lark-apaas/no-styled-jsx-data-uri-url-ref': 'error',
         // styled-jsx + 多行模板 className → 下游 transpiler 可能产出 "Unterminated string literal"
         '@lark-apaas/no-multiline-styled-jsx-classname': 'error',
+        // Tailwind className 校验：拦截 AI 自创、tailwind.config 没声明的 utility class
+        // W21 数据：22 条 Tailwind 失败里有 9 条是 AI 凭空起名（brutal-shadow / label-micro / divider-accent 等）
+        // 此前 lint 链路里没有任何工具检查 className 字符串，错误一直要到 vite build PostCSS 才报
+        'tailwindcss/no-custom-classname': 'error',
+        // 同类 utility 冲突（如 p-2 + p-4 同时出现）
+        'tailwindcss/no-contradicting-classname': 'error',
+        // class 排序规则噪音大且不影响功能，关闭
+        'tailwindcss/classnames-order': 'off',
         // 自定义规则：HTTP 调用响应类型必须定义在 shared/（默认关闭，需 y 位升级后对新应用开启）
         '@lark-apaas/require-shared-request-type': 'off',
         // TypeScript 规则

package/lib/simple/recommend/eslint/index.d.ts

@@ -16,6 +16,7 @@ export declare const eslintPresets: {
         plugins: {
             'react-hooks': any;
             import: any;
+            tailwindcss: any;
         };
         settings: {
             'import/resolver': {
@@ -26,6 +27,9 @@ export declare const eslintPresets: {
             'import/parsers': {
                 '@typescript-eslint/parser': string[];
             };
+            tailwindcss: {
+                callees: string[];
+            };
         };
         rules: any;
     } | {

package/lib/simple/recommend/stylelint/index.d.ts

@@ -3,5 +3,6 @@ export declare const stylelintPresets: {
     rules: {
         'declaration-block-no-duplicate-custom-properties': boolean;
         "custom/hsl-valid-value": true | null;
+        "custom/tailwind-theme-v4-required": boolean | null;
     };
 };

package/lib/simple/recommend/stylelint/index.js

@@ -35,11 +35,13 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.stylelintPresets = void 0;
 const hsl_variable_1 = __importStar(require("../../../custom-stylelint-rules/hsl-variable"));
+const tailwind_theme_v4_required_1 = __importStar(require("../../../custom-stylelint-rules/tailwind-theme-v4-required"));
 const isLooseMode = process.env.FORCE_FRAMEWORK_LINT_LOOSE_MODE === 'true';
 exports.stylelintPresets = {
-    plugins: [hsl_variable_1.default],
+    plugins: [hsl_variable_1.default, tailwind_theme_v4_required_1.default],
     rules: {
         'declaration-block-no-duplicate-custom-properties': true,
         [hsl_variable_1.ruleName]: isLooseMode || null,
+        [tailwind_theme_v4_required_1.ruleName]: isLooseMode ? null : true,
     },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/fullstack-presets",
-  "version": "1.1.22",
+  "version": "1.1.23-alpha.0",
   "files": [
     "lib"
   ],
@@ -31,6 +31,7 @@
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^5.2.0",
+    "eslint-plugin-tailwindcss": "^4.0.0-beta.0",
     "globals": "^16.4.0",
     "stylelint": "^17.3.0",
     "tailwindcss-animate": "^1.0.7"