@af-mobile/eslint-plugin 2.0.4 → 2.1.0

package/index.js

@@ -1,5 +1,5 @@
 // af-mobile UI —— eslint-plugin-af-mobile 入口（ESLint 9 flat config 兼容）
-// 20 条规则：L1(2) + L2(7) + L3(6) + L3.5(5)
+// 24 条规则：L1(2) + L2(8) + L3(6) + L3.5(5) + k(3)
 // （definePage 消费端 7 条规则已随 definePage 全局单例移除）
 import noTokenModification from './rules/no-token-modification.js';
 import noInlineStyle from './rules/no-inline-style.js';
@@ -10,6 +10,7 @@ import noArbitraryValue from './rules/no-arbitrary-value.js';
 import noTailwindSyntax from './rules/no-tailwind-syntax.js';
 import preferComponent from './rules/prefer-component.js';
 import atomicDuplicate from './rules/atomic-duplicate.js';
+import noEmojiIcon from './rules/no-emoji-icon.js';
 import noRegisterAll from './rules/no-register-all.js';
 import wcLightNoStyle from './rules/wc-light-no-style.js';
 import wcShadowUseToken from './rules/wc-shadow-use-token.js';
@@ -21,15 +22,18 @@ import wcBlockNoInternalRef from './rules/wc-block-no-internal-ref.js';
 import wcBlockPropsCount from './rules/wc-block-props-count.js';
 import wcBlockStates from './rules/wc-block-states.js';
 import wcBlockVariantEnum from './rules/wc-block-variant-enum.js';
+import kNoBareAnd from './rules/k-no-bare-and.js';
+import kNoObjectInterpolation from './rules/k-no-object-interpolation.js';
+import kForRequireKey from './rules/k-for-require-key.js';
 
 const plugin = {
-  meta: { name: 'eslint-plugin-af-mobile', version: '2.0.4' },
+  meta: { name: 'eslint-plugin-af-mobile', version: '2.1.0' },
   rules: {
     // L1（2 条，全部 error；tokens-css-locked 由 CODEOWNERS + 分支保护，非 ESLint 规则）
     'no-token-modification': noTokenModification,
     'no-inline-style': noInlineStyle,
     // L1-3 tokens-css-locked 是 CODEOWNERS + 分支保护，非 ESLint 规则
-    // L2（7 条：4 error + 3 warn）
+    // L2（8 条：4 error + 4 warn）
     'token-whitelist': tokenWhitelist,
     'no-recipe-break': noRecipeBreak,
     'no-variant-conflict': noVariantConflict,
@@ -37,6 +41,7 @@ const plugin = {
     'no-tailwind-syntax': noTailwindSyntax,
     'prefer-component': preferComponent,
     'atomic-duplicate': atomicDuplicate,
+    'no-emoji-icon': noEmojiIcon,
     // L3（6 条：4 error + 2 warn）
     'wc-light-no-style': wcLightNoStyle,
     'wc-shadow-use-token': wcShadowUseToken,
@@ -50,6 +55,11 @@ const plugin = {
     'wc-block-props-count': wcBlockPropsCount,
     'wc-block-states': wcBlockStates,
     'wc-block-variant-enum': wcBlockVariantEnum,
+    // k 层（3 条：D-001=B 应用层推广的配套约束；仅对从 @af-mobile/ui/k 导入的 html/For 生效，
+    // 主包同名 API 语义不同不受约束，规则内经 collectKImports 判定）
+    'k-no-bare-and': kNoBareAnd,
+    'k-no-object-interpolation': kNoObjectInterpolation,
+    'k-for-require-key': kForRequireKey,
   },
   configs: {},
 };
@@ -73,6 +83,7 @@ Object.assign(plugin.configs, {
       'af-mobile/no-variant-conflict': 'warn',
       'af-mobile/prefer-component': 'warn',
       'af-mobile/atomic-duplicate': 'warn',
+      'af-mobile/no-emoji-icon': 'warn',
       // L3 error
       'af-mobile/wc-light-no-style': 'error',
       'af-mobile/wc-shadow-use-token': 'error',
@@ -88,6 +99,11 @@ Object.assign(plugin.configs, {
       // L3.5 error（按需引入铁律：registerAll 全量注册 = 全局引入，一律禁止）
       'af-mobile/no-register-all': 'error',
       'af-mobile/wc-block-variant-enum': 'warn',
+      // k 层（k 渲染/应用层：裸 && 渲染 "false"、对象插值 "[object Object]" 是静默 bug → error；
+      // For 缺 key 对对象列表破坏 keyed 复用但原始值列表合法 → warn）
+      'af-mobile/k-no-bare-and': 'error',
+      'af-mobile/k-no-object-interpolation': 'error',
+      'af-mobile/k-for-require-key': 'warn',
     },
   },
 });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@af-mobile/eslint-plugin",
-  "version": "2.0.4",
-  "description": "af-mobile UI ESLint plugin — 27 rules (L1/L2/L3/L3.5) enforcing design-system + Web Component constraints",
+  "version": "2.1.0",
+  "description": "af-mobile UI ESLint plugin — 24 rules (L1/L2/L3/L3.5/k) enforcing design-system + Web Component + k-layer constraints",
   "type": "module",
   "main": "./index.js",
   "module": "./index.js",

package/rules/atomic-duplicate.js

@@ -2,13 +2,21 @@
 // 检测：同一 class 属性内出现两个同属性原子（如 p-4 p-2），保留最后一个
 import { extractAllClassLists } from '../utils/helpers.js';
 
-// 属性前缀映射：p-* → padding, m-* → margin, t-* → font-size, r-* → border-radius
+// 字重类与字号类共享 t- 前缀但作用于不同属性（font-weight vs font-size），必须分桶判定：
+// t-xl t-b 是"大字号+粗体"的合法排版组合，不是字号重复
+// （v1.6.1 修复：旧前缀正则曾把两者混为 font-size，autofix 直接删掉字号类，破坏视觉强调）
+const FONT_SIZE = new Set(['t-display', 't-xs', 't-sm', 't-md', 't-lg', 't-xl']);
+const FONT_WEIGHT = new Set(['t-b', 't-m', 't-semibold']);
+
+// 属性桶：p-* → padding, m-* → margin, t-* → font-size, r-* → border-radius, 字重类 → font-weight
 function getPropPrefix(cls) {
+  if (FONT_WEIGHT.has(cls)) return 'fw';
+  if (FONT_SIZE.has(cls)) return 't';
   const m = cls.match(/^([pmtr])-(.+)$/);
   return m ? m[1] : null;
 }
 
-const PROP_LABELS = { p: 'padding', m: 'margin', t: 'font-size', r: 'border-radius' };
+const PROP_LABELS = { p: 'padding', m: 'margin', t: 'font-size', r: 'border-radius', fw: 'font-weight' };
 
 export default {
   meta: {

package/rules/k-for-require-key.js

@@ -0,0 +1,33 @@
+// k-3 af-mobile/k-for-require-key（warn）
+// For 省略 key 时以项本身为键：原始值列表语义正确；对象列表以引用为键——
+// 数据源每次 set 新数组即整行重建，keyed 复用失效（src/k/README.md 词表卡 key 边界）
+// 修正：显式传 key: 'id'（稳定字段名）；纯原始值列表可显式关闭本规则
+// 仅对从 k 入口（@af-mobile/ui/k）导入的 For 生效
+import { collectKImports } from '../utils/helpers.js';
+
+export default {
+  meta: {
+    type: 'suggestion',
+    docs: { description: 'k For 建议显式传 key（对象项省略 key 以引用为键，引用变则整行重建）' },
+    schema: [],
+    messages: {
+      forKeyMissing: 'For is missing "key" — object items are keyed by reference when omitted, so every source change rebuilds all rows; pass key: "id" (primitive lists may disable this rule)',
+    },
+  },
+  create(context) {
+    const kNames = collectKImports(context.sourceCode.ast.body);
+    if (kNames.For.size === 0) return {};
+    return {
+      CallExpression(node) {
+        if (node.callee.type !== 'Identifier' || !kNames.For.has(node.callee.name)) return;
+        const arg = node.arguments[0];
+        if (!arg || arg.type !== 'ObjectExpression') return;
+        const hasKey = arg.properties.some((p) => p.type === 'Property' && (
+          (p.key.type === 'Identifier' && p.key.name === 'key')
+          || (p.key.type === 'Literal' && p.key.value === 'key')
+        ));
+        if (!hasKey) context.report({ node: arg, messageId: 'forKeyMissing' });
+      },
+    };
+  },
+};

package/rules/k-no-bare-and.js

@@ -0,0 +1,31 @@
+// k-1 af-mobile/k-no-bare-and（error）
+// k 的 html`` 子位渲染 String(val)：裸 && 在假值时把字面量 "false" 渲染成文本节点
+// （JSX `cond && <X/>` 的幻觉写法；k 无"假值不渲染"语义）
+// 修正：三元 `${cond ? x : null}`（null → 空串）或 Show({ when, kids })
+// 仅对从 k 入口（@af-mobile/ui/k）导入的 html 生效；主包 html``（字符串拼接）不受约束
+import { collectKImports } from '../utils/helpers.js';
+
+export default {
+  meta: {
+    type: 'problem',
+    docs: { description: 'k html`` 子位禁止裸 && 表达式（假值渲染 "false" 文本）' },
+    schema: [],
+    messages: {
+      bareAnd: 'Bare && in k html`` renders literal text "false" when falsy — use a ternary `${cond ? x : null}` or Show({ when, kids })',
+    },
+  },
+  create(context) {
+    const kNames = collectKImports(context.sourceCode.ast.body);
+    if (kNames.html.size === 0) return {};
+    return {
+      TaggedTemplateExpression(node) {
+        if (node.tag.type !== 'Identifier' || !kNames.html.has(node.tag.name)) return;
+        for (const expr of node.quasi.expressions) {
+          if (expr.type === 'LogicalExpression' && expr.operator === '&&') {
+            context.report({ node: expr, messageId: 'bareAnd' });
+          }
+        }
+      },
+    };
+  },
+};

package/rules/k-no-object-interpolation.js

@@ -0,0 +1,31 @@
+// k-2 af-mobile/k-no-object-interpolation（error）
+// k 的 html`` 插值经 String(val)：对象字面量渲染成 "[object Object]" 文本
+// 典型来源：主包 html`` 的可信 HTML 语法 `${{ raw: '<b>x</b>' }}` 在 k 不存在（JSX/主包双重幻觉）
+// 修正：插 signal/getter、字符串或 DOM 节点；数组合法（bindKids 展开为多节点）不报
+// 仅对从 k 入口（@af-mobile/ui/k）导入的 html 生效；主包 html`` 的 { raw } 语法不受约束
+import { collectKImports } from '../utils/helpers.js';
+
+export default {
+  meta: {
+    type: 'problem',
+    docs: { description: 'k html`` 插值禁止对象字面量（渲染 "[object Object]"；k 无 { raw } 语法）' },
+    schema: [],
+    messages: {
+      objectInterpolation: 'Object literal in k html`` renders "[object Object]" — k has no { raw } syntax; interpolate a signal/getter, string, or DOM node instead (arrays are legal, they expand to multiple nodes)',
+    },
+  },
+  create(context) {
+    const kNames = collectKImports(context.sourceCode.ast.body);
+    if (kNames.html.size === 0) return {};
+    return {
+      TaggedTemplateExpression(node) {
+        if (node.tag.type !== 'Identifier' || !kNames.html.has(node.tag.name)) return;
+        for (const expr of node.quasi.expressions) {
+          if (expr.type === 'ObjectExpression') {
+            context.report({ node: expr, messageId: 'objectInterpolation' });
+          }
+        }
+      },
+    };
+  },
+};

package/rules/no-emoji-icon.js

@@ -0,0 +1,69 @@
+// L2-8 af-mobile/no-emoji-icon（warn）
+// 检测 emoji 当图标——"廉价感"第一视觉来源（v1.6.1 规则化，配套 prompt 图标规范）
+// 检测点（低误报，只查图标语境）：
+//   1. icon 属性值：tabs/tabbar 配置对象 { label: 'x', icon: '📋' }（旧 few-shot 示例的反模式）
+//   2. HTML 字符串中 tab-item 元素 / data-role="icon" 元素的文本内容含 emoji
+// 修正：用 24px stroke SVG（prompt 图标 path 库）；af-tabbar 的 icon 仅支持文本字符，需要图标时省略 icon 字段
+const EMOJI_RE = /\p{Extended_Pictographic}/u;
+
+function firstEmoji(str) {
+  const m = str.match(EMOJI_RE);
+  return m ? m[0] : null;
+}
+
+// HTML 字符串中的图标语境：tab-item 元素 / data-role="icon" 元素（取开闭标签之间的纯文本段）
+const ICON_CONTEXT_RES = [
+  /<[\w-]+[^>]*\bclass="[^"]*\btab-item\b[^"]*"[^>]*>([^<]*)</g,
+  /<[\w-]+[^>]*\bdata-role="icon"[^>]*>([^<]*)</g,
+];
+
+function checkHtmlString(str, node, report) {
+  for (const re of ICON_CONTEXT_RES) {
+    re.lastIndex = 0;
+    let m;
+    while ((m = re.exec(str))) {
+      const emoji = firstEmoji(m[1]);
+      if (emoji) report(node, emoji);
+    }
+  }
+}
+
+export default {
+  meta: {
+    type: 'suggestion',
+    docs: { description: '禁止 emoji 当图标（用 24px stroke SVG）' },
+    schema: [],
+    messages: {
+      emojiIcon: "Emoji {{emoji}} used as icon — use a 24px stroke SVG instead; af-tabbar's icon prop only supports text characters",
+    },
+  },
+  create(context) {
+    const report = (node, emoji) => context.report({ node, messageId: 'emojiIcon', data: { emoji } });
+    return {
+      // { icon: '📋' } 配置对象（af-tabbar / af-tabs 的 tabs 数组）
+      Property(node) {
+        const keyName = node.key.type === 'Identifier'
+          ? node.key.name
+          : (node.key.type === 'Literal' ? String(node.key.value) : null);
+        if (keyName !== 'icon') return;
+        const v = node.value;
+        if (v.type === 'Literal' && typeof v.value === 'string') {
+          const emoji = firstEmoji(v.value);
+          if (emoji) report(v, emoji);
+        } else if (v.type === 'TemplateLiteral' && v.expressions.length === 0) {
+          const emoji = firstEmoji(v.quasis[0].value.raw);
+          if (emoji) report(v, emoji);
+        }
+      },
+      // HTML 字符串（含 template literal）中的图标语境元素
+      Literal(node) {
+        if (typeof node.value !== 'string') return;
+        checkHtmlString(node.value, node, report);
+      },
+      TemplateElement(node) {
+        if (!node.value || !node.value.raw) return;
+        checkHtmlString(node.value.raw, node, report);
+      },
+    };
+  },
+};

package/rules/no-inline-style.js

@@ -66,13 +66,15 @@ export default {
       additionalProperties: false,
     }],
     messages: {
-      forbidden: "Inline style '{{value}}' is forbidden. Use class instead",
+      // v1.6.1：报错带具体违规属性名（旧报错只给整段 style，AI 修正时只能整段删掉重猜，加剧样式削平）
+      forbidden: "Inline style property '{{prop}}' is forbidden in '{{value}}'. Use class instead",
     },
   },
 
   create(context) {
     const options = context.options[0] || {};
     const extraAllow = new Set(options.allowProperties || []);
+    const nodeText = (node) => (context.sourceCode || context.getSourceCode()).getText(node);
 
     return {
       // 检测字符串字面量（含 template literal）
@@ -81,7 +83,7 @@ export default {
         const violations = checkStyleString(node.value);
         for (const v of violations) {
           if (extraAllow.has(v.prop)) continue;
-          context.report({ node, messageId: 'forbidden', data: { value: v.value } });
+          context.report({ node, messageId: 'forbidden', data: { prop: v.prop, value: v.value } });
         }
       },
       TemplateElement(node) {
@@ -89,7 +91,7 @@ export default {
         const violations = checkStyleString(node.value.raw);
         for (const v of violations) {
           if (extraAllow.has(v.prop)) continue;
-          context.report({ node, messageId: 'forbidden', data: { value: v.value } });
+          context.report({ node, messageId: 'forbidden', data: { prop: v.prop, value: v.value } });
         }
       },
       // 检测 el.style.setProperty('color', ...) / el.style.xxx = '...' 绕过
@@ -106,7 +108,7 @@ export default {
         if (propArg.value.startsWith('--')) return;
         const prop = propArg.value.toLowerCase();
         if (FORBIDDEN.has(prop) && !ALLOWED_LAYOUT.has(prop) && !extraAllow.has(prop)) {
-          context.report({ node, messageId: 'forbidden', data: { value: `${prop}` } });
+          context.report({ node, messageId: 'forbidden', data: { prop, value: nodeText(node) } });
         }
       },
       AssignmentExpression(node) {
@@ -119,7 +121,7 @@ export default {
         // kebab-case 转换：backgroundColor → background-color
         const kebab = propName.replace(/[A-Z]/g, m => '-' + m.toLowerCase());
         if (FORBIDDEN.has(kebab) && !ALLOWED_LAYOUT.has(kebab) && !extraAllow.has(kebab)) {
-          context.report({ node, messageId: 'forbidden', data: { value: kebab } });
+          context.report({ node, messageId: 'forbidden', data: { prop: kebab, value: nodeText(node) } });
         }
       },
     };

package/rules/no-variant-conflict.js

@@ -6,16 +6,27 @@ import { extractAllClassLists } from '../utils/helpers.js';
 const CONFLICT_GROUPS = [
   ['btn-sm', 'btn-lg'],
   ['tag-ok', 'tag-warn', 'tag-danger'],
+  // 描边式语义色标签（v1.6.1 新增，同 tag 语义色互斥规则）
+  ['tag-plain-ok', 'tag-plain-warn', 'tag-plain-danger'],
   // 圆角类
   ['r-s', 'r-m', 'r-l', 'r-f'],
   // padding 类
   ['p-0', 'p-1', 'p-2', 'p-3', 'p-4', 'p-5', 'p-6', 'p-7', 'p-8', 'p-10'],
+  // 定向 padding 类（v1.6.1 新增，同为 padding-left/right 或 padding-top/bottom）
+  ['px-1', 'px-2', 'px-3', 'px-4'],
+  ['py-1', 'py-2', 'py-3', 'py-4'],
   // display 类（同为 display 属性）
   ['f', 'fi', 'fc'],
+  // 网格类（v1.6.1 新增，同为 display:grid，grid-2/3 含列定义）
+  ['grid', 'grid-2', 'grid-3'],
+  // 比例类（v1.6.1 新增，同为 aspect-ratio）
+  ['aspect-1', 'aspect-4-3', 'aspect-16-9'],
   // 行高类
   ['lh-tight', 'lh-normal'],
-  // 背景类
-  ['bg-brand', 'bg-card', 'bg-muted'],
+  // 背景类（v1.6.1 新增渐变/彩色底并入同组：同为 background 属性）
+  ['bg-brand', 'bg-card', 'bg-muted', 'bg-brand-soft', 'bg-danger', 'bg-success', 'bg-grad-brand', 'bg-grad-brand-soft'],
+  // 边框类（v1.6.1 新增，同为 border）
+  ['border', 'border-brand'],
 ];
 
 export default {

package/utils/helpers.js

@@ -82,3 +82,25 @@ export function suggestNearest(name, candidates) {
   }
   return best ? ` Did you mean '${best}'?` : '';
 }
+
+// k 层导入源：发布名 @af-mobile/ui/k，或仓库内相对路径 k/index.js / k/flow.js
+const K_SOURCE_RE = /^@af-mobile\/ui\/k$|(?:^|[\\/])k[\\/](?:index|flow)\.[cm]?js$/;
+
+// 收集从 k 入口导入的绑定名（含别名）：{ html: Set<localName>, For: Set<localName> }
+// k 层规则（k-no-bare-and 等）只对从 k 入口导入的 html/For 生效——
+// 主包 html``（返回字符串）语义不同，不受 k 规则约束
+export function collectKImports(programBody) {
+  const names = { html: new Set(), For: new Set() };
+  for (const stmt of programBody) {
+    if (stmt.type !== 'ImportDeclaration') continue;
+    if (!K_SOURCE_RE.test(stmt.source.value)) continue;
+    for (const spec of stmt.specifiers) {
+      if (spec.type !== 'ImportSpecifier') continue;
+      const imported = spec.imported.type === 'Identifier'
+        ? spec.imported.name
+        : String(spec.imported.value);
+      if (names[imported]) names[imported].add(spec.local.name);
+    }
+  }
+  return names;
+}

package/utils/whitelist-v1.json

@@ -1,6 +1,6 @@
 {
   "version": "v1",
-  "af-mobileVersion": "1.5.2",
+  "af-mobileVersion": "1.7.0",
   "classes": {
     "recipe": [
       "actions",
@@ -19,10 +19,13 @@
       "btn-success",
       "caption",
       "card",
+      "card-media",
+      "card-shadow",
       "cell",
       "center",
       "checkbox",
       "checkbox-sm",
+      "chips",
       "clp",
       "clp-ct",
       "clp-sum",
@@ -30,12 +33,17 @@
       "cob-fx",
       "display",
       "divider",
+      "dot",
+      "dot-on",
+      "dots",
       "empty",
       "eyebrow",
       "form-err",
       "form-row",
       "form-row-h",
       "hero",
+      "hero-grad",
+      "icon-badge",
       "input",
       "input-bar",
       "input-bar-fx",
@@ -45,6 +53,7 @@
       "list-item",
       "list-item-cp",
       "meta",
+      "nav-transparent",
       "navbar",
       "navbar-fixed",
       "notice",
@@ -54,6 +63,7 @@
       "page-col",
       "price",
       "price-del",
+      "price-lg",
       "progress",
       "progress-danger",
       "progress-lg",
@@ -77,6 +87,7 @@
       "section-tt",
       "seg",
       "seg-blk",
+      "seg-brand",
       "seg-it",
       "sheet",
       "sk",
@@ -92,6 +103,7 @@
       "spinner",
       "spinner-lg",
       "spinner-sm",
+      "stat-num",
       "stats-grid",
       "step",
       "step-active",
@@ -114,6 +126,9 @@
       "tag-md",
       "tag-ok",
       "tag-plain",
+      "tag-plain-danger",
+      "tag-plain-ok",
+      "tag-plain-warn",
       "tag-warn",
       "textarea",
       "thumb",
@@ -127,9 +142,19 @@
     ],
     "atomic": [
       "aic",
+      "aspect-1",
+      "aspect-16-9",
+      "aspect-4-3",
       "bg-brand",
+      "bg-brand-soft",
       "bg-card",
+      "bg-danger",
+      "bg-grad-brand",
+      "bg-grad-brand-soft",
       "bg-muted",
+      "bg-success",
+      "border",
+      "border-brand",
       "ellipsis",
       "ellipsis-2",
       "f",
@@ -141,6 +166,9 @@
       "g-2",
       "g-3",
       "g-4",
+      "grid",
+      "grid-2",
+      "grid-3",
       "hl-b",
       "hl-t",
       "jcc",
@@ -155,6 +183,7 @@
       "m-3",
       "m-4",
       "m-5",
+      "min-w-0",
       "navbar",
       "p-0",
       "p-1",
@@ -166,6 +195,14 @@
       "p-6",
       "p-7",
       "p-8",
+      "px-1",
+      "px-2",
+      "px-3",
+      "px-4",
+      "py-1",
+      "py-2",
+      "py-3",
+      "py-4",
       "r-0",
       "r-f",
       "r-l",
@@ -189,9 +226,12 @@
       "t-xs",
       "text-brand",
       "text-danger",
+      "text-gray-7",
       "text-muted",
+      "text-onbrand",
       "text-success",
       "w-full",
+      "wrap",
       "ws-nowrap"
     ]
   },