@open-dy/vibecoding-cli 0.0.1-beta.1

package/src/adapters/interest-card/opencard/validate-widget-shell.mjs

@@ -0,0 +1,902 @@
+#!/usr/bin/env node
+/**
+ * 兴趣卡底板校验：页面根 View 必须是盖在 9:16 背景上的半透明圆角面板。
+ * 规则来自 design-skill widget.md；由 pnpm lint 执行，不要手工 grep。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { formatFinding } from './lynx-css-rules.mjs';
+import { lintCssText } from './lint-lynx-css.mjs';
+
+const __dirname = path.join(process.env.VIBECODING_OPENCARD_ROOT || process.cwd(), 'scripts');
+const ROOT = path.resolve(__dirname, '..');
+const SRC = path.join(ROOT, 'src');
+const PAGE_ENTRY = path.join(SRC, 'pages/index/index.tsx');
+const require = createRequire(path.join(ROOT, 'scripts', 'package.json'));
+
+const SHELL_CLASS = 'widget-root';
+const REQUIRED_RADIUS_PX = 12;
+
+const BORDER_STYLES = new Set([
+  'none',
+  'hidden',
+  'solid',
+  'dashed',
+  'dotted',
+  'double',
+  'groove',
+  'ridge',
+  'inset',
+  'outset',
+]);
+
+export function splitSelectorList(selector) {
+  const parts = [];
+  let current = '';
+  let depth = 0;
+  for (let i = 0; i < selector.length; i += 1) {
+    const ch = selector[i];
+    if (ch === '(') depth += 1;
+    else if (ch === ')') depth = Math.max(0, depth - 1);
+    else if (depth === 0 && ch === ',') {
+      if (current.trim()) parts.push(current.trim());
+      current = '';
+      continue;
+    }
+    current += ch;
+  }
+  if (current.trim()) parts.push(current.trim());
+  return parts;
+}
+
+export function lastCompound(selectorPart) {
+  let idx = 0;
+  for (let i = 0; i < selectorPart.length; i += 1) {
+    const ch = selectorPart[i];
+    if (ch === '(') {
+      let depth = 1;
+      i += 1;
+      while (i < selectorPart.length && depth > 0) {
+        if (selectorPart[i] === '(') depth += 1;
+        else if (selectorPart[i] === ')') depth -= 1;
+        i += 1;
+      }
+      i -= 1;
+      continue;
+    }
+    if ((ch === ' ' || ch === '>' || ch === '+' || ch === '~') && i + 1 < selectorPart.length) {
+      idx = i + 1;
+    }
+  }
+  return selectorPart.slice(idx).trim();
+}
+
+export function classesInCompound(compound) {
+  const names = [];
+  const stripped = compound.replace(/:[^\s.#[]+/g, '');
+  const re = /\.(-?[_A-Za-z]+[_A-Za-z0-9-]*)/g;
+  let match;
+  while ((match = re.exec(stripped))) names.push(match[1]);
+  return names;
+}
+
+export function selectorAppliesToClasses(selector, classSet) {
+  return splitSelectorList(selector).some((part) => {
+    const classes = classesInCompound(lastCompound(part));
+    return classes.length > 0 && classes.every((name) => classSet.has(name));
+  });
+}
+
+export function isRootSelector(selector) {
+  return splitSelectorList(selector).some((part) => {
+    const compound = lastCompound(part);
+    return /(?:^|[^A-Za-z0-9_-]):root(?![A-Za-z0-9_-])/.test(compound);
+  });
+}
+
+function splitCssTokens(value) {
+  const parts = [];
+  let current = '';
+  let depth = 0;
+  for (let i = 0; i < value.length; i += 1) {
+    const ch = value[i];
+    if (ch === '(') depth += 1;
+    else if (ch === ')') depth = Math.max(0, depth - 1);
+    if (depth === 0 && /\s/.test(ch)) {
+      if (current) parts.push(current);
+      current = '';
+    } else {
+      current += ch;
+    }
+  }
+  if (current) parts.push(current);
+  return parts;
+}
+
+export function expandRadius(value) {
+  const tokens = splitCssTokens(value).filter((token) => token !== '/');
+  if (tokens.length === 1) return [tokens[0], tokens[0], tokens[0], tokens[0]];
+  if (tokens.length === 2) return [tokens[0], tokens[1], tokens[0], tokens[1]];
+  if (tokens.length === 3) return [tokens[0], tokens[1], tokens[2], tokens[1]];
+  if (tokens.length >= 4) return tokens.slice(0, 4);
+  return [null, null, null, null];
+}
+
+export function parseBorderShorthand(value) {
+  const result = {};
+  for (const token of splitCssTokens(value)) {
+    const lower = token.toLowerCase();
+    if (BORDER_STYLES.has(lower)) {
+      result['border-style'] = lower;
+      continue;
+    }
+    if (/^[\d.]+(%|px|vh|vw|rem|em)?$/.test(lower) || lower === 'thin' || lower === 'medium' || lower === 'thick') {
+      result['border-width'] = token;
+      continue;
+    }
+    result['border-color'] = token;
+  }
+  return result;
+}
+
+function extractBackgroundColor(value) {
+  const trimmed = value.trim();
+  if (!trimmed) return trimmed;
+  if (/^(none|transparent)$/i.test(trimmed)) return trimmed.toLowerCase();
+  const tokens = splitCssTokens(trimmed);
+  const colorLike = [...tokens].reverse().find((token) => {
+    const lower = token.toLowerCase();
+    return (
+      lower === 'transparent' ||
+      lower === 'none' ||
+      lower.startsWith('var(') ||
+      lower.startsWith('#') ||
+      lower.startsWith('rgb') ||
+      lower.startsWith('hsl') ||
+      /^[a-z]+$/i.test(token)
+    );
+  });
+  return colorLike || trimmed;
+}
+
+export function applyDecl(style, prop, value) {
+  const p = String(prop).trim().toLowerCase();
+  const v = String(value ?? '')
+    .replace(/\s*!important\s*$/i, '')
+    .trim();
+  if (!p || !v) return;
+
+  if (p.startsWith('--')) {
+    style[p] = v;
+    return;
+  }
+  if (p === 'background' || p === 'background-color') {
+    style['background-color'] = extractBackgroundColor(v);
+    return;
+  }
+  if (p === 'border') {
+    Object.assign(style, parseBorderShorthand(v));
+    return;
+  }
+  if (p === 'border-radius') {
+    const [tl, tr, br, bl] = expandRadius(v);
+    style['border-top-left-radius'] = tl;
+    style['border-top-right-radius'] = tr;
+    style['border-bottom-right-radius'] = br;
+    style['border-bottom-left-radius'] = bl;
+    return;
+  }
+  style[p] = v;
+}
+
+export function resolveValue(value, customProps, depth = 0) {
+  if (value == null) return '';
+  if (depth > 8) return String(value);
+  return String(value).replace(
+    /var\(\s*(--[A-Za-z0-9_-]+)\s*(?:,\s*((?:[^)(]+|\([^)(]*\))*))?\)/g,
+    (_, name, fallback) => {
+      if (customProps[name]) return resolveValue(customProps[name], customProps, depth + 1);
+      if (fallback) return resolveValue(fallback.trim(), customProps, depth + 1);
+      return '';
+    },
+  );
+}
+
+function parseNumber(token) {
+  const match = String(token)
+    .trim()
+    .match(/^(-?[\d.]+)(px|vh|vw|rem|em|%)?$/i);
+  if (!match) return null;
+  return { num: Number(match[1]), unit: (match[2] || '').toLowerCase() };
+}
+
+export function isTransparentColor(value) {
+  const v = String(value ?? '')
+    .trim()
+    .toLowerCase();
+  if (!v || v === 'transparent' || v === 'none' || v === 'unset' || v === 'initial') {
+    return true;
+  }
+  if (/^#(?:[0-9a-f]{3}|[0-9a-f]{6})00$/i.test(v) || /^#(?:[0-9a-f]{4})$/i.test(v) && v.endsWith('0')) {
+    return true;
+  }
+  const rgba = v.match(/^rgba?\(\s*([\d.]+)[%]?\s*[, ]\s*([\d.]+)[%]?\s*[, ]\s*([\d.]+)[%]?(?:\s*[,/]\s*([\d.]+%?))?\s*\)$/);
+  if (rgba && rgba[4] != null) {
+    const raw = rgba[4];
+    const alpha = raw.endsWith('%') ? Number(raw.slice(0, -1)) / 100 : Number(raw);
+    return Number.isFinite(alpha) && alpha === 0;
+  }
+  const hsla = v.match(/^hsla?\(/);
+  if (hsla) {
+    const alphaMatch = v.match(/[,/]\s*([\d.]+%?)\s*\)$/);
+    if (alphaMatch) {
+      const raw = alphaMatch[1];
+      const alpha = raw.endsWith('%') ? Number(raw.slice(0, -1)) / 100 : Number(raw);
+      return Number.isFinite(alpha) && alpha === 0;
+    }
+  }
+  return false;
+}
+
+export function isZeroLength(value) {
+  const parsed = parseNumber(value);
+  return parsed != null && parsed.num === 0;
+}
+
+export function isPx(value, px) {
+  const parsed = parseNumber(value);
+  return parsed != null && parsed.unit === 'px' && parsed.num === px;
+}
+
+function containsViewportHeight(value) {
+  return /(?:^|[^A-Za-z0-9_-])100vh(?:$|[^A-Za-z0-9_-])/i.test(String(value ?? ''));
+}
+
+function collectStaticStrings(node, result = []) {
+  if (!node) return result;
+  if (node.type === 'StringLiteral' || (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;
+  }
+  if (node.type === 'JSXExpressionContainer') {
+    return collectStaticStrings(node.expression, result);
+  }
+  for (const key of [
+    'left',
+    'right',
+    'argument',
+    'callee',
+    'test',
+    'consequent',
+    'alternate',
+    'object',
+    'property',
+    'init',
+    'body',
+  ]) {
+    if (node[key] && typeof node[key] === 'object') collectStaticStrings(node[key], result);
+  }
+  for (const key of ['arguments', 'elements', 'expressions', 'properties']) {
+    if (Array.isArray(node[key])) {
+      for (const child of node[key]) collectStaticStrings(child, result);
+    }
+  }
+  return result;
+}
+
+function addClassTokens(classes, chunk) {
+  for (const token of String(chunk).split(/\s+/)) {
+    if (token && !token.includes('${')) classes.add(token);
+  }
+}
+
+function classNamesFromJSX(el) {
+  const classes = new Set();
+  const attrs = el.openingElement?.attributes || [];
+  for (const attr of attrs) {
+    if (attr.type !== 'JSXAttribute' || attr.name?.name !== 'className') continue;
+    for (const chunk of collectStaticStrings(attr.value)) addClassTokens(classes, chunk);
+  }
+  return classes;
+}
+
+function unwrapJSX(node) {
+  if (!node) return null;
+  if (node.type === 'JSXElement') return node;
+  if (node.type === 'JSXFragment') return node;
+  if (node.type === 'ParenthesizedExpression') return unwrapJSX(node.expression);
+  if (node.type === 'TSAsExpression' || node.type === 'TSSatisfiesExpression') {
+    return unwrapJSX(node.expression);
+  }
+  if (node.type === 'ConditionalExpression') {
+    return [unwrapJSX(node.consequent), unwrapJSX(node.alternate)].flat().filter(Boolean);
+  }
+  if (node.type === 'LogicalExpression') {
+    return [unwrapJSX(node.left), unwrapJSX(node.right)].flat().filter(Boolean);
+  }
+  return null;
+}
+
+function jsxName(el) {
+  const name = el.openingElement?.name;
+  if (name?.type === 'JSXIdentifier') return name.name;
+  return '';
+}
+
+function loadBabel() {
+  try {
+    const parser = require('@babel/parser');
+    const traverseMod = require('@babel/traverse');
+    const traverse = traverseMod.default ?? traverseMod;
+    return { parser, traverse };
+  } catch {
+    return null;
+  }
+}
+
+function resolveDefaultComponent(ast, traverse) {
+  let target = null;
+  traverse(ast, {
+    ExportDefaultDeclaration(pathNode) {
+      const decl = pathNode.node.declaration;
+      if (
+        decl.type === 'FunctionDeclaration' ||
+        decl.type === 'ArrowFunctionExpression' ||
+        decl.type === 'FunctionExpression'
+      ) {
+        target = pathNode.get('declaration');
+        return;
+      }
+      if (decl.type === 'Identifier') {
+        const binding = pathNode.scope.getBinding(decl.name);
+        if (!binding) return;
+        const bindPath = binding.path;
+        if (bindPath.isFunctionDeclaration()) {
+          target = bindPath;
+          return;
+        }
+        if (bindPath.isVariableDeclarator()) {
+          const init = bindPath.get('init');
+          if (init.isFunction() || init.isArrowFunctionExpression()) target = init;
+        }
+      }
+    },
+  });
+  return target;
+}
+
+function collectPageRootClassSetsRegex(source) {
+  const match = /<View\b([\s\S]*?)>/.exec(source);
+  if (!match) return [];
+  const classes = new Set();
+  for (const quoted of match[1].matchAll(/["'`]([^"'`]+)["'`]/g)) {
+    addClassTokens(classes, quoted[1]);
+  }
+  return [{ type: 'View', classes }];
+}
+
+export function collectPageRootClassSets(source) {
+  const babel = loadBabel();
+  if (!babel) return collectPageRootClassSetsRegex(source);
+
+  let ast;
+  try {
+    ast = babel.parser.parse(source, {
+      sourceType: 'module',
+      plugins: ['jsx', 'typescript'],
+    });
+  } catch {
+    return [];
+  }
+
+  const componentPath = resolveDefaultComponent(ast, babel.traverse);
+  if (!componentPath) return [];
+
+  const roots = [];
+  const takeReturned = (argument) => {
+    const unwrapped = unwrapJSX(argument);
+    const nodes = Array.isArray(unwrapped) ? unwrapped : unwrapped ? [unwrapped] : [];
+    for (const node of nodes) {
+      if (node.type === 'JSXFragment') {
+        roots.push({ type: 'fragment', classes: new Set() });
+        continue;
+      }
+      roots.push({ type: jsxName(node), classes: classNamesFromJSX(node) });
+    }
+  };
+
+  const body = componentPath.get('body');
+  if (body.isJSXElement() || body.isJSXFragment() || body.isParenthesizedExpression()) {
+    takeReturned(componentPath.node.body);
+  } else {
+    componentPath.traverse({
+      Function(inner) {
+        if (inner.node !== componentPath.node) inner.skip();
+      },
+      ReturnStatement(retPath) {
+        takeReturned(retPath.node.argument);
+      },
+    });
+  }
+
+  return uniqueRoots(roots);
+}
+
+function uniqueRoots(roots) {
+  const seen = new Set();
+  const out = [];
+  for (const root of roots) {
+    const key = `${root.type}:${[...root.classes].sort().join(',')}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(root);
+  }
+  return out;
+}
+
+function uniqueFindings(findings) {
+  const seen = new Set();
+  const out = [];
+  for (const item of findings) {
+    const key = `${item.id}|${item.file}|${item.message}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(item);
+  }
+  return out;
+}
+
+function listFiles(dir, test, acc = []) {
+  if (!fs.existsSync(dir)) return acc;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const target = path.join(dir, entry.name);
+    if (entry.isDirectory()) listFiles(target, test, acc);
+    else if (test(entry.name)) acc.push(target);
+  }
+  return acc;
+}
+
+function rel(file) {
+  return path.relative(ROOT, file).replace(/\\/g, '/');
+}
+
+function cssFileOrder(file) {
+  const name = rel(file);
+  if (name === 'src/app.css') return `0:${name}`;
+  return `1:${name}`;
+}
+
+export function collectCssRules(cssFiles) {
+  const rules = [];
+  const sorted = [...cssFiles].sort((a, b) => cssFileOrder(a).localeCompare(cssFileOrder(b)));
+  for (const file of sorted) {
+    const filename = path.isAbsolute(file) ? rel(file) : file;
+    const source = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : file.source;
+    const parsed = lintCssText(source, { filename });
+    for (const rule of parsed.rules) {
+      rules.push({
+        ...rule,
+        file: filename,
+      });
+    }
+  }
+  return rules;
+}
+
+export function collectCustomProps(rules) {
+  const props = {};
+  for (const rule of rules) {
+    if (!isRootSelector(rule.selector) && !selectorAppliesToClasses(rule.selector, new Set([SHELL_CLASS]))) {
+      continue;
+    }
+    for (const decl of rule.decls) {
+      if (decl.prop.startsWith('--')) props[decl.prop] = decl.value;
+    }
+  }
+  return props;
+}
+
+export function mergeStyleForClasses(rules, classSet) {
+  const style = {};
+  let loc = { file: 'src/pages/index/index.css', line: 1, column: 1 };
+  for (const rule of rules) {
+    if (!selectorAppliesToClasses(rule.selector, classSet)) continue;
+    loc = { file: rule.file, line: rule.line, column: rule.column };
+    for (const decl of rule.decls) applyDecl(style, decl.prop, decl.value);
+  }
+  return { style, loc };
+}
+
+function finding(id, message, loc) {
+  return {
+    id,
+    message,
+    file: loc?.file || 'src/pages/index/index.tsx',
+    line: loc?.line || 1,
+    column: loc?.column || 1,
+  };
+}
+
+export function validateMergedShell(style, customProps, loc) {
+  const findings = [];
+  const resolved = (prop) => resolveValue(style[prop], { ...customProps, ...style });
+
+  const heightValue = resolved('height');
+  const minHeight = resolved('min-height');
+  const maxHeight = resolved('max-height');
+  if ([heightValue, minHeight, maxHeight, resolved('width')].some(containsViewportHeight)) {
+    findings.push(
+      finding(
+        'no-100vh',
+        '底板不要用 100vh。根铺满卡位请用 width/height: 100%。',
+        loc,
+      ),
+    );
+  }
+
+  if (resolved('width') !== '100%' || resolved('height') !== '100%') {
+    findings.push(
+      finding(
+        'size-100',
+        '底板必须 width: 100%; height: 100%，直接承接宿主卡位。',
+        loc,
+      ),
+    );
+  }
+
+  if (resolved('box-sizing') !== 'border-box') {
+    findings.push(
+      finding('box-sizing', '底板必须 box-sizing: border-box。', loc),
+    );
+  }
+
+  if (resolved('display') !== 'flex' || resolved('flex-direction') !== 'column') {
+    findings.push(
+      finding(
+        'flex-column',
+        '底板必须 display: flex; flex-direction: column。',
+        loc,
+      ),
+    );
+  }
+
+  const background = resolved('background-color');
+  if (!style['background-color'] || isTransparentColor(background)) {
+    findings.push(
+      finding(
+        'opaque-bg',
+        '底板必须有非透明背景（background: var(--widget-bg)），禁止 transparent / none，不要让内容直接浮在 9:16 背景上。',
+        loc,
+      ),
+    );
+  }
+
+  const borderStyle = resolved('border-style');
+  const borderWidth = resolved('border-width');
+  const borderColor = resolved('border-color');
+  const missingBorder =
+    !style['border-style'] && !style['border-width'] && !style['border-color'];
+  if (
+    missingBorder ||
+    borderStyle === 'none' ||
+    borderStyle === 'hidden' ||
+    isZeroLength(borderWidth) ||
+    isTransparentColor(borderColor)
+  ) {
+    findings.push(
+      finding(
+        'border',
+        '底板必须有 1px 描边（border: 1px solid var(--widget-border)），禁止 border: 0 / none。',
+        loc,
+      ),
+    );
+  }
+
+  const corners = [
+    resolved('border-top-left-radius'),
+    resolved('border-top-right-radius'),
+    resolved('border-bottom-right-radius'),
+    resolved('border-bottom-left-radius'),
+  ];
+  const missingCorner = corners.some((value) => !value || isZeroLength(value));
+  const notTwelve = corners.some((value) => value && !isPx(value, REQUIRED_RADIUS_PX));
+  if (missingCorner || notTwelve) {
+    findings.push(
+      finding(
+        'radius',
+        `底板四角都必须是 border-radius: ${REQUIRED_RADIUS_PX}px，不要直角，也不要只圆上面或只圆下面。`,
+        loc,
+      ),
+    );
+  }
+
+  return findings;
+}
+
+export function lintWidgetShell({
+  pageSource,
+  pageFile = 'src/pages/index/index.tsx',
+  rules,
+}) {
+  const findings = [];
+  const roots = collectPageRootClassSets(pageSource);
+  if (roots.length === 0) {
+    findings.push(
+      finding(
+        'root-view',
+        '找不到页面根节点。opencard/src/pages/index/index.tsx 的默认导出必须 return 根 View。',
+        { file: pageFile, line: 1, column: 1 },
+      ),
+    );
+    return findings;
+  }
+
+  const customProps = collectCustomProps(rules);
+
+  for (const root of roots) {
+    if (root.type === 'fragment') {
+      findings.push(
+        finding(
+          'root-view',
+          '页面根节点必须是 View，不能是 Fragment。底板写在根 class widget-root 上。',
+          { file: pageFile, line: 1, column: 1 },
+        ),
+      );
+      continue;
+    }
+    if (root.type !== 'View') {
+      findings.push(
+        finding(
+          'root-view',
+          `页面根节点必须是 View（当前是 <${root.type || 'unknown'}>）。`,
+          { file: pageFile, line: 1, column: 1 },
+        ),
+      );
+      continue;
+    }
+    if (!root.classes.has(SHELL_CLASS)) {
+      findings.push(
+        finding(
+          'shell-class',
+          '页面根 View 必须带 className widget-root（design-skill 底板）。Loading / Empty 同样落在这块面板上，不要另起一层铺满的透明根。',
+          { file: pageFile, line: 1, column: 1 },
+        ),
+      );
+      continue;
+    }
+
+    const { style, loc } = mergeStyleForClasses(rules, root.classes);
+    if (!Object.keys(style).length) {
+      findings.push(
+        finding(
+          'shell-css',
+          '找不到 .widget-root 的 CSS。请在页面 CSS 里写底板：非透明背景、1px 边、四角 12px。',
+          { file: 'src/pages/index/index.css', line: 1, column: 1 },
+        ),
+      );
+      continue;
+    }
+    findings.push(...validateMergedShell(style, customProps, loc));
+  }
+
+  return uniqueFindings(findings);
+}
+
+function parseInlineCssFiles(files) {
+  return files.map((item) => {
+    const parsed = lintCssText(item.source, { filename: item.filename });
+    return parsed.rules.map((rule) => ({ ...rule, file: item.filename }));
+  }).flat();
+}
+
+export function lintWidgetShellFromSources({ pageSource, cssFiles }) {
+  const rules = parseInlineCssFiles(cssFiles);
+  return lintWidgetShell({ pageSource, rules });
+}
+
+function assertSelfTest() {
+  const page = (className) => `
+    export default function IndexPage() {
+      return (
+        <View className="${className}">
+          <Text>ok</Text>
+        </View>
+      );
+    }
+  `;
+
+  const goodCss = `
+    :root {
+      --bg-default: rgba(255,255,255,0.08);
+      --line-subtle: rgba(255,255,255,0.08);
+      --widget-bg: var(--bg-default);
+      --widget-border: var(--line-subtle);
+      --radius-xl: 0.75rem;
+    }
+    .widget-root {
+      box-sizing: border-box;
+      display: flex;
+      flex-direction: column;
+      width: 100%;
+      height: 100%;
+      margin: 0;
+      padding: 1rem 1.25rem;
+      background: var(--widget-bg);
+      border: 1px solid var(--widget-border);
+      border-radius: 12px;
+      overflow: hidden;
+    }
+  `;
+
+  const cases = [
+    {
+      name: 'good shell',
+      page: page('widget-root'),
+      css: goodCss,
+      id: null,
+    },
+    {
+      name: 'missing class',
+      page: page('opencard-page'),
+      css: goodCss.replaceAll('.widget-root', '.opencard-page'),
+      id: 'shell-class',
+    },
+    {
+      name: 'transparent background',
+      page: page('widget-root'),
+      css: goodCss.replace('background: var(--widget-bg);', 'background: transparent;'),
+      id: 'opaque-bg',
+    },
+    {
+      name: 'missing border',
+      page: page('widget-root'),
+      css: goodCss.replace('border: 1px solid var(--widget-border);', 'border: 0;'),
+      id: 'border',
+    },
+    {
+      name: 'top-only radius',
+      page: page('widget-root'),
+      css: goodCss.replace('border-radius: 12px;', 'border-radius: 12px 12px 0 0;'),
+      id: 'radius',
+    },
+    {
+      name: '16px radius',
+      page: page('widget-root'),
+      css: goodCss.replace('border-radius: 12px;', 'border-radius: 16px;'),
+      id: 'radius',
+    },
+    {
+      name: '100vh',
+      page: page('widget-root'),
+      css: goodCss.replace('height: 100%;', 'height: 100vh;'),
+      id: 'no-100vh',
+    },
+    {
+      name: 'duplicate returns report once',
+      page: `
+        export default function IndexPage() {
+          if (loading) {
+            return (
+              <View className="widget-root">
+                <Text>a</Text>
+              </View>
+            );
+          }
+          if (!data) {
+            return (
+              <View className="widget-root">
+                <Text>b</Text>
+              </View>
+            );
+          }
+          return (
+            <View className="widget-root">
+              <Text>c</Text>
+            </View>
+          );
+        }
+      `,
+      css: ':root { --widget-bg: rgba(255,255,255,0.08); }',
+      id: 'shell-css',
+      once: true,
+    },
+    {
+      name: 'intro modifier clears panel',
+      page: `
+        export default function IndexPage() {
+          return (
+            <View className={isIntro ? "widget-root widget-root-intro" : "widget-root"}>
+              <Text>ok</Text>
+            </View>
+          );
+        }
+      `,
+      css: `${goodCss}
+        .widget-root-intro {
+          background: transparent;
+          border-color: transparent;
+        }
+      `,
+      id: 'opaque-bg',
+    },
+  ];
+
+  const failures = [];
+  for (const item of cases) {
+    const findings = lintWidgetShellFromSources({
+      pageSource: item.page,
+      cssFiles: [
+        { filename: 'src/app.css', source: item.css.includes(':root') ? item.css : '' },
+        { filename: 'src/pages/index/index.css', source: item.css },
+      ],
+    });
+    const ids = findings.map((f) => f.id);
+    const hitCount = ids.filter((id) => id === item.id).length;
+    const ok =
+      item.id === null
+        ? findings.length === 0
+        : item.once
+          ? hitCount === 1
+          : hitCount > 0;
+    if (!ok) {
+      failures.push({ name: item.name, expected: item.id, actual: ids });
+    }
+  }
+
+  if (failures.length) {
+    console.error(`[widget-shell self-test] ${failures.length} failed`);
+    for (const fail of failures) {
+      console.error(`  ${fail.name}: expected ${fail.expected}, got ${JSON.stringify(fail.actual)}`);
+    }
+    process.exit(1);
+  }
+  console.log(`[widget-shell self-test] ${cases.length} passed`);
+}
+
+function lintProject() {
+  if (!fs.existsSync(PAGE_ENTRY)) {
+    return [
+      finding(
+        'root-view',
+        '缺少 src/pages/index/index.tsx。兴趣卡页面入口必须在这里，根 View 使用 widget-root 底板。',
+        { file: 'src/pages/index/index.tsx', line: 1, column: 1 },
+      ),
+    ];
+  }
+
+  const cssFiles = listFiles(SRC, (name) => name.endsWith('.css'));
+  const rules = collectCssRules(cssFiles);
+  return lintWidgetShell({
+    pageSource: fs.readFileSync(PAGE_ENTRY, 'utf8'),
+    pageFile: rel(PAGE_ENTRY),
+    rules,
+  });
+}
+
+export function main() {
+  if (process.argv.includes('--self-test')) {
+    assertSelfTest();
+    return;
+  }
+  const reports = lintProject();
+  if (reports.length === 0) return;
+  console.warn(
+    `WARN: 兴趣卡底板校验未通过（${reports.length}），不阻断构建：根 View 必须是半透明圆角面板（.widget-root），不要透明根或直角底板。`,
+  );
+  for (const item of reports) {
+    console.warn(formatFinding(item.file, item.line, item.column, item.message));
+  }
+}
+
+const invoked =
+  process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+if (invoked) main();