@open-dy/vibecoding-sdk-taro 0.0.1-beta.5 → 0.0.1-beta.7

package/src/eslint/eslint-plugin-microapp-pages.mjs

@@ -0,0 +1,659 @@
+/**
+ * 校验小程序页面路由与 app.config.ts 中 pages 一致，避免「写了跳转 / 建了页面但未注册」。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+/** TypeScript 为 CJS 包，在 ESLint 的 ESM 插件里用 require 才能拿到完整的 ts 命名空间 API */
+const ts = createRequire(import.meta.url)('typescript');
+
+const NAV_METHODS = new Set([
+  'navigateTo',
+  'redirectTo',
+  'reLaunch',
+  'switchTab',
+]);
+const PAGE_SOURCE_EXTENSIONS = ['.tsx', '.ts', '.jsx', '.js'];
+
+/** @param {string} route */
+function normalizeRoute(route) {
+  if (!route || typeof route !== 'string') return '';
+  const noQuery = route.split('?')[0];
+  return noQuery.replace(/^\/+/, '').replace(/\/+$/, '');
+}
+
+function splitTailwindClassToken(token) {
+  let bracketDepth = 0;
+  let lastSeparatorIndex = -1;
+
+  for (let index = 0; index < token.length; index += 1) {
+    const char = token[index];
+
+    if (char === '[') bracketDepth += 1;
+    if (char === ']') bracketDepth -= 1;
+    if (char === ':' && bracketDepth === 0) lastSeparatorIndex = index;
+  }
+
+  return lastSeparatorIndex >= 0
+    ? token.slice(lastSeparatorIndex + 1)
+    : token;
+}
+
+function collectStaticStrings(node, result = []) {
+  if (!node) return result;
+
+  if (node.type === 'Literal' && typeof node.value === 'string') {
+    result.push(node.value);
+    return result;
+  }
+
+  if (node.type === 'TemplateLiteral') {
+    for (const quasi of node.quasis) {
+      if (quasi.value.cooked) result.push(quasi.value.cooked);
+    }
+
+    for (const expression of node.expressions) {
+      collectStaticStrings(expression, result);
+    }
+
+    return result;
+  }
+
+  for (const key of [
+    'left',
+    'right',
+    'argument',
+    'callee',
+    'test',
+    'consequent',
+    'alternate',
+    'object',
+    'property',
+  ]) {
+    collectStaticStrings(node[key], result);
+  }
+
+  for (const key of ['arguments', 'elements', 'expressions']) {
+    if (Array.isArray(node[key])) {
+      for (const child of node[key]) collectStaticStrings(child, result);
+    }
+  }
+
+  return result;
+}
+
+function routeFromPageFilename(filePath) {
+  const normalized = filePath.replace(/\\/g, '/');
+  const match = normalized.match(/\/src\/pages\/(.+)\/index\.[jt]sx?$/);
+  if (!match) return '';
+
+  return normalizeRoute(`pages/${match[1]}/index`);
+}
+
+function getPageFileCandidates(cwd, route) {
+  const normalized = normalizeRoute(route);
+  return PAGE_SOURCE_EXTENSIONS.map((extension) =>
+    path.join(cwd, 'src', `${normalized}${extension}`));
+}
+
+function formatRelativeCandidates(cwd, candidates) {
+  return candidates.map((candidate) => path.relative(cwd, candidate));
+}
+
+function buildMissingPageSuggestion(route) {
+  const normalized = normalizeRoute(route);
+  const indexRoute = normalized.endsWith('/index') ? normalized : `${normalized}/index`;
+  const indexSource = `src/${indexRoute}.tsx`;
+  const directSource = `src/${normalized}.tsx`;
+
+  if (normalized.endsWith('/index')) {
+    return (
+      `如果实际页面文件是 ${indexSource}，请保持 pages 中声明为 '${indexRoute}'；` +
+      ` 否则请创建 ${directSource} / .ts / .jsx / .js 中的一个。`
+    );
+  }
+
+  return (
+    `如果实际页面文件是 ${indexSource}，请把 pages 中的 '${normalized}' 改成 '${indexRoute}'；` +
+    ` 如果你本来想声明单文件页面，请创建 ${directSource} / .ts / .jsx / .js 中的一个。`
+  );
+}
+
+function isDirectReturnedJsxElementAttribute(node) {
+  const element = node.parent?.parent;
+  if (element?.type !== 'JSXElement') return false;
+
+  let parent = element.parent;
+  while (
+    parent &&
+    [
+      'ParenthesizedExpression',
+      'ChainExpression',
+      'TSAsExpression',
+      'TSTypeAssertion',
+      'TSNonNullExpression',
+      'ConditionalExpression',
+      'LogicalExpression',
+    ].includes(parent.type)
+  ) {
+    parent = parent.parent;
+  }
+
+  return parent?.type === 'ReturnStatement' || parent?.type === 'ArrowFunctionExpression';
+}
+
+/**
+ * @param {string} pagesRoot absolute path to src/pages
+ * @returns {string[]}
+ */
+function collectPageRoutesFromDisk(pagesRoot) {
+  const routes = [];
+  if (!fs.existsSync(pagesRoot)) return routes;
+
+  function walk(dir, parts) {
+    for (const name of fs.readdirSync(dir)) {
+      const full = path.join(dir, name);
+      if (!fs.statSync(full).isDirectory()) continue;
+      const nextParts = [...parts, name];
+      const indexTsx = path.join(full, 'index.tsx');
+      const indexTs = path.join(full, 'index.ts');
+      if (fs.existsSync(indexTsx) || fs.existsSync(indexTs)) {
+        routes.push(`pages/${nextParts.join('/')}/index`);
+      }
+      walk(full, nextParts);
+    }
+  }
+
+  walk(pagesRoot, []);
+  return routes;
+}
+
+/**
+ * @param {string} filePath
+ * @param {string} text
+ * @returns {string[] | null}
+ */
+function extractPagesFromAppConfigSource(filePath, text) {
+  const sf = ts.createSourceFile(
+    filePath,
+    text,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS
+  );
+
+  /** @type {string[] | null} */
+  let pages = null;
+
+  function fromObjectLiteral(obj) {
+    let foundPagesKey = false;
+    const out = [];
+    for (const prop of obj.properties) {
+      if (!ts.isPropertyAssignment(prop)) continue;
+      const key =
+        ts.isIdentifier(prop.name) ? prop.name.text
+        : ts.isStringLiteral(prop.name) ? prop.name.text
+        : null;
+      if (key !== 'pages' || !ts.isArrayLiteralExpression(prop.initializer)) continue;
+      foundPagesKey = true;
+      for (const el of prop.initializer.elements) {
+        if (ts.isStringLiteral(el) || ts.isNoSubstitutionTemplateLiteral(el)) {
+          out.push(el.text);
+        }
+      }
+    }
+    return foundPagesKey ? out : null;
+  }
+
+  function visit(node) {
+    if (pages !== null) return;
+
+    // TS 5.x 将「export default expr」解析为 ExportAssignment（isExportEquals === false），
+    // 不再使用 ExportDefaultDeclaration / isExportDefaultDeclaration。
+    if (ts.isExportAssignment(node) && !node.isExportEquals && node.expression) {
+      const expr = node.expression;
+      if (ts.isCallExpression(expr) && expr.arguments[0]) {
+        const arg0 = expr.arguments[0];
+        if (ts.isObjectLiteralExpression(arg0)) {
+          pages = fromObjectLiteral(arg0);
+        }
+      } else if (ts.isObjectLiteralExpression(expr)) {
+        pages = fromObjectLiteral(expr);
+      }
+    }
+
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sf);
+  return pages;
+}
+
+/**
+ * @param {string} filePath
+ * @param {string} text
+ * @returns {{ hasTabBar: boolean; pagePaths: string[] } | null}
+ */
+function extractTabBarFromAppConfigSource(filePath, text) {
+  const sf = ts.createSourceFile(
+    filePath,
+    text,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS
+  );
+
+  /** @type {{ hasTabBar: boolean; pagePaths: string[] } | null} */
+  let tabBar = null;
+
+  function getPropertyName(prop) {
+    return ts.isIdentifier(prop.name) ? prop.name.text
+      : ts.isStringLiteral(prop.name) ? prop.name.text
+      : null;
+  }
+
+  function getStringProperty(obj, propertyName) {
+    for (const prop of obj.properties) {
+      if (!ts.isPropertyAssignment(prop) || getPropertyName(prop) !== propertyName) continue;
+      if (ts.isStringLiteral(prop.initializer) || ts.isNoSubstitutionTemplateLiteral(prop.initializer)) {
+        return prop.initializer.text;
+      }
+    }
+
+    return null;
+  }
+
+  function fromObjectLiteral(obj) {
+    let foundTabBar = false;
+    const pagePaths = [];
+
+    for (const prop of obj.properties) {
+      if (!ts.isPropertyAssignment(prop) || getPropertyName(prop) !== 'tabBar') continue;
+      foundTabBar = true;
+      if (!ts.isObjectLiteralExpression(prop.initializer)) continue;
+
+      for (const tabBarProp of prop.initializer.properties) {
+        if (!ts.isPropertyAssignment(tabBarProp) || getPropertyName(tabBarProp) !== 'list') continue;
+        if (!ts.isArrayLiteralExpression(tabBarProp.initializer)) continue;
+
+        for (const item of tabBarProp.initializer.elements) {
+          if (!ts.isObjectLiteralExpression(item)) continue;
+          const pagePath = getStringProperty(item, 'pagePath');
+          if (pagePath) pagePaths.push(pagePath);
+        }
+      }
+    }
+
+    return foundTabBar ? { hasTabBar: true, pagePaths } : { hasTabBar: false, pagePaths: [] };
+  }
+
+  function visit(node) {
+    if (tabBar !== null) return;
+
+    if (ts.isExportAssignment(node) && !node.isExportEquals && node.expression) {
+      const expr = node.expression;
+      if (ts.isCallExpression(expr) && expr.arguments[0]) {
+        const arg0 = expr.arguments[0];
+        if (ts.isObjectLiteralExpression(arg0)) {
+          tabBar = fromObjectLiteral(arg0);
+        }
+      } else if (ts.isObjectLiteralExpression(expr)) {
+        tabBar = fromObjectLiteral(expr);
+      }
+    }
+
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sf);
+  return tabBar;
+}
+
+/** @type {Map<string, { pages: string[]; mtime: number } | { error: string }>} */
+const pagesCache = new Map();
+
+/** @type {Map<string, { hasTabBar: boolean; pagePaths: string[]; mtime: number } | { error: string }>} */
+const tabBarCache = new Map();
+
+/** 解析 app.config 失败时，每个 cwd 只提示一次，避免每个 navigateTo 都报错 */
+const appConfigParseErrorLogged = new Set();
+
+function loadRegisteredPages(cwd) {
+  const appConfigPath = path.join(cwd, 'src/app.config.ts');
+  if (!fs.existsSync(appConfigPath)) {
+    return { pages: [], skip: true };
+  }
+
+  try {
+    const st = fs.statSync(appConfigPath);
+    const cacheKey = appConfigPath;
+    const cached = pagesCache.get(cacheKey);
+    if (cached && !('error' in cached) && cached.mtime === st.mtimeMs) {
+      return { pages: cached.pages, skip: false };
+    }
+
+    const text = fs.readFileSync(appConfigPath, 'utf8');
+    const parsed = extractPagesFromAppConfigSource(appConfigPath, text);
+    if (!parsed) {
+      pagesCache.set(cacheKey, { error: '无法解析 pages 数组' });
+      return { pages: [], skip: true, parseError: true };
+    }
+
+    const normalized = parsed.map(p => normalizeRoute(p));
+    pagesCache.set(cacheKey, { pages: normalized, mtime: st.mtimeMs });
+    return { pages: normalized, skip: false };
+  } catch (e) {
+    return { pages: [], skip: true, parseError: true };
+  }
+}
+
+function loadTabBarPages(cwd) {
+  const appConfigPath = path.join(cwd, 'src/app.config.ts');
+  if (!fs.existsSync(appConfigPath)) {
+    return { hasTabBar: false, pagePaths: [], skip: true };
+  }
+
+  try {
+    const st = fs.statSync(appConfigPath);
+    const cached = tabBarCache.get(appConfigPath);
+    if (cached && !('error' in cached) && cached.mtime === st.mtimeMs) {
+      return { hasTabBar: cached.hasTabBar, pagePaths: cached.pagePaths, skip: false };
+    }
+
+    const text = fs.readFileSync(appConfigPath, 'utf8');
+    const parsed = extractTabBarFromAppConfigSource(appConfigPath, text);
+    if (!parsed) {
+      tabBarCache.set(appConfigPath, { error: '无法解析 tabBar 配置' });
+      return { hasTabBar: false, pagePaths: [], skip: true, parseError: true };
+    }
+
+    const normalized = parsed.pagePaths.map(p => normalizeRoute(p));
+    tabBarCache.set(appConfigPath, {
+      hasTabBar: parsed.hasTabBar,
+      pagePaths: normalized,
+      mtime: st.mtimeMs,
+    });
+
+    return { hasTabBar: parsed.hasTabBar, pagePaths: normalized, skip: false };
+  } catch (e) {
+    return { hasTabBar: false, pagePaths: [], skip: true, parseError: true };
+  }
+}
+
+function isStaticUrlString(node) {
+  if (!node) return null;
+  if (node.type === 'Literal' && typeof node.value === 'string') return node.value;
+  if (node.type === 'TemplateLiteral' && node.expressions.length === 0 && node.quasis.length === 1) {
+    return node.quasis[0].value.cooked ?? node.quasis[0].value.raw;
+  }
+  return null;
+}
+
+function getUrlFromNavigateArg(arg) {
+  if (!arg || arg.type !== 'ObjectExpression') return null;
+  for (const prop of arg.properties) {
+    if (prop.type !== 'Property' || prop.key == null) continue;
+    const key =
+      prop.key.type === 'Identifier' ? prop.key.name
+      : prop.key.type === 'Literal' && typeof prop.key.value === 'string' ? prop.key.value
+      : null;
+    if (key !== 'url') continue;
+    return isStaticUrlString(prop.value);
+  }
+  return null;
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+const navUrlInAppPages = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Taro.navigateTo / redirectTo / reLaunch / switchTab 的静态 url 必须在 src/app.config.ts 的 pages 中注册',
+    },
+    schema: [],
+  },
+  create(context) {
+    const cwd = context.cwd ?? process.cwd();
+    const taroDefaultName = new Map(); // local name -> true
+    const taroNavLocals = new Set();
+
+    return {
+      ImportDeclaration(node) {
+        if (node.source.value !== '@tarojs/taro') return;
+        for (const sp of node.specifiers) {
+          if (sp.type === 'ImportDefaultSpecifier') {
+            taroDefaultName.set(sp.local.name, true);
+          }
+          if (sp.type === 'ImportNamespaceSpecifier') {
+            taroDefaultName.set(sp.local.name, true);
+          }
+          if (sp.type === 'ImportSpecifier' && sp.imported && sp.imported.type === 'Identifier') {
+            const name = sp.imported.name;
+            if (NAV_METHODS.has(name)) {
+              taroNavLocals.add(sp.local.name);
+            }
+          }
+        }
+      },
+
+      CallExpression(node) {
+        const callee = node.callee;
+        let method = null;
+
+        if (callee.type === 'MemberExpression' && !callee.computed && callee.property.type === 'Identifier') {
+          const obj = callee.object;
+          const prop = callee.property.name;
+          if (!NAV_METHODS.has(prop)) return;
+          if (obj.type === 'Identifier' && taroDefaultName.has(obj.name)) {
+            method = prop;
+          }
+        } else if (callee.type === 'Identifier' && taroNavLocals.has(callee.name)) {
+          method = callee.name;
+        }
+
+        if (!method) return;
+
+        const arg0 = node.arguments[0];
+        if (!arg0 || arg0.type !== 'ObjectExpression') return;
+
+        const rawUrl = getUrlFromNavigateArg(arg0);
+        if (rawUrl == null) return;
+
+        const { pages, skip, parseError } = loadRegisteredPages(cwd);
+        if (skip) {
+          if (parseError && !appConfigParseErrorLogged.has(cwd)) {
+            appConfigParseErrorLogged.add(cwd);
+            context.report({
+              node,
+              message:
+                '无法读取或解析 src/app.config.ts 中的 pages，请确认 defineAppConfig({ pages: [...] }) 写法正确。',
+            });
+          }
+          return;
+        }
+
+        const normalized = normalizeRoute(rawUrl);
+        if (!normalized) return;
+
+        if (!pages.includes(normalized)) {
+          context.report({
+            node,
+            message:
+              `路由未在 app.config.ts 的 pages 中注册：「${normalized}」。请把该路径加入 pages 数组后再跳转（当前已注册：${pages.length ? pages.join(', ') : '无'}）。`,
+          });
+        }
+      },
+    };
+  },
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const pageDirsInAppPages = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'src/pages 下每个含 index 的页面目录必须在 app.config.ts 的 pages 中注册',
+    },
+    schema: [],
+  },
+  create(context) {
+    const filePath = context.filename.replace(/\\/g, '/');
+    if (!filePath.endsWith('src/app.config.ts')) {
+      return {};
+    }
+
+    return {
+      Program(node) {
+        const cwd = context.cwd ?? process.cwd();
+        const pagesRoot = path.join(cwd, 'src/pages');
+        const diskRoutes = collectPageRoutesFromDisk(pagesRoot);
+        const sc = context.sourceCode;
+        const sourceText = sc.getText(node);
+        const declared = extractPagesFromAppConfigSource(filePath, sourceText);
+
+        if (!declared) {
+          context.report({
+            node,
+            message:
+              '无法从本文件解析 pages 数组，请使用 defineAppConfig({ pages: [ \'pages/...\' ] }) 形式声明。',
+          });
+          return;
+        }
+
+        const declaredSet = new Set(declared.map(p => normalizeRoute(p)));
+
+        for (const route of diskRoutes) {
+          const n = normalizeRoute(route);
+          const shorthand = n.replace(/\/index$/, '');
+          if (shorthand !== n && declaredSet.has(shorthand)) {
+            continue;
+          }
+          if (!declaredSet.has(n)) {
+            context.report({
+              node,
+              message: `磁盘上存在页面「${n}」，但未在 pages 数组中注册。请添加 '${route}'（或等价路径）。`,
+            });
+          }
+        }
+      },
+    };
+  },
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const declaredPagesMustExist = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'app.config.ts 中声明的 pages 必须映射到真实页面文件',
+    },
+    schema: [],
+  },
+  create(context) {
+    const filePath = context.filename.replace(/\\/g, '/');
+    if (!filePath.endsWith('src/app.config.ts')) {
+      return {};
+    }
+
+    return {
+      Program(node) {
+        const cwd = context.cwd ?? process.cwd();
+        const sc = context.sourceCode;
+        const sourceText = sc.getText(node);
+        const declared = extractPagesFromAppConfigSource(filePath, sourceText);
+
+        if (!declared) {
+          context.report({
+            node,
+            message:
+              '无法从本文件解析 pages 数组，请使用 defineAppConfig({ pages: [ \'pages/...\' ] }) 形式声明。',
+          });
+          return;
+        }
+
+        for (const route of declared) {
+          const normalized = normalizeRoute(route);
+          const candidates = getPageFileCandidates(cwd, normalized);
+          const exists = candidates.some((candidate) => fs.existsSync(candidate));
+
+          if (exists) continue;
+
+          context.report({
+            node,
+            message:
+              `src/app.config.ts 的 pages 配置有误：声明了不存在的页面「${normalized}」。` +
+              ` Taro 这里需要填写完整的“路径 + 文件名”。` +
+              ` ${buildMissingPageSuggestion(normalized)}` +
+              ` 当前尝试匹配：${formatRelativeCandidates(cwd, candidates).join(', ')}。`,
+          });
+        }
+      },
+    };
+  },
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const noScreenHeightInTabBarPage = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'TabBar 页面根容器禁止使用 min-h-screen / h-screen，避免超过 taro-tabbar__panel 已计算的可用高度',
+    },
+    schema: [],
+  },
+  create(context) {
+    const cwd = context.cwd ?? process.cwd();
+    const pageRoute = routeFromPageFilename(context.filename);
+    if (!pageRoute) return {};
+
+    const { hasTabBar, pagePaths, skip } = loadTabBarPages(cwd);
+    if (skip || !hasTabBar || !pagePaths.includes(pageRoute)) return {};
+
+    function reportScreenHeightClass(node, className) {
+      const violating = className
+        .split(/\s+/)
+        .map(token => token.trim())
+        .filter(Boolean)
+        .filter(token => /^(?:!)?(?:min-h-screen|h-screen)$/.test(splitTailwindClassToken(token)));
+
+      if (violating.length === 0) return;
+
+      context.report({
+        node,
+        message:
+          `TabBar 页面高度规范：检测到 [${violating.join(', ')}]。` +
+          'Taro TabBar 页面已由 taro-tabbar__panel 计算可用高度，页面根容器请改用 h-full flex flex-col，内容区使用 flex-1 overflow-auto。',
+      });
+    }
+
+    return {
+      JSXAttribute(node) {
+        if (node.name?.name !== 'className') return;
+        if (!isDirectReturnedJsxElementAttribute(node)) return;
+
+        if (node.value?.type === 'Literal' && typeof node.value.value === 'string') {
+          reportScreenHeightClass(node, node.value.value);
+          return;
+        }
+
+        if (node.value?.type !== 'JSXExpressionContainer') return;
+
+        for (const className of collectStaticStrings(node.value.expression)) {
+          reportScreenHeightClass(node, className);
+        }
+      },
+    };
+  },
+};
+
+export default {
+  rules: {
+    'nav-url-in-app-pages': navUrlInAppPages,
+    'page-dirs-in-app-pages': pageDirsInAppPages,
+    'declared-pages-must-exist': declaredPagesMustExist,
+    'no-screen-height-in-tabbar-page': noScreenHeightInTabBarPage,
+  },
+};