@q1travel/design-system 0.9.0 → 0.10.0

package/bin/q1-design.mjs

@@ -4,6 +4,7 @@
 // read-only cache under the consumer repo; `verify` proves that cache was
 // never hand-edited and still matches the installed package version.
 
+import { execFileSync } from 'node:child_process';
 import { createRequire } from 'node:module';
 import {
   cpSync,
@@ -19,7 +20,7 @@ import {
 } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const PACKAGE_NAME = '@q1travel/design-system';
 const SKILL_RELATIVE_DIR = '.claude/skills/product-design';
@@ -30,8 +31,160 @@ const CONTRACTS_SOURCE_SUBPATH = 'contracts';
 const LINT_EXTENSIONS = new Set(['.css', '.js', '.jsx', '.ts', '.tsx', '.mjs']);
 const DASH_DS_PATTERN = /--ds-/;
 const TRANSITION_ALL_PATTERN = /transition(?:-property)?\s*:\s*all\b/;
-const HEX_COLOR_PATTERN = /#[0-9a-fA-F]{3,8}\b/;
-const COLOR_FUNCTION_PATTERN = /\b(?:rgb|rgba|hsl)\s*\(/i;
+// Q1-DS-501 的匹配面（issue #130）。此前是两条无语法感知的裸正则，两个方向都错：
+//   假阳——`url(#fade)`、CSS 注释里的 `#142` 这类非颜色的 # 引用被当成 hex 色值；
+//   假阴——`hsla()` / `oklch()` / CSS 命名色完全不在匹配面内。
+// 但收紧必须避开一个陷阱：`oklch(from var(--q1-color-status-success) …)` 与
+// `color-mix(in srgb, var(--x) …)` 是**从 token 派生**，不是裸字面量，本就不该报。
+// 因此判定不能只看函数名，还要看实参里有没有 var()。
+const HEX_COLOR_PATTERN = /#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{4}|[0-9a-fA-F]{3})(?![0-9a-fA-F])/;
+const COLOR_FUNCTION_NAMES = 'rgb|rgba|hsl|hsla|hwb|lab|lch|oklab|oklch';
+const COLOR_FUNCTION_PATTERN = new RegExp(`\\b(?:${COLOR_FUNCTION_NAMES})\\s*\\(`, 'i');
+const URL_CALL_PATTERN = /\burl\s*\([^)]*\)/gi;
+const LINE_COMMENT_PATTERN = /\/\/.*$/;
+// W3C CSS 命名色全表。只在值位置（冒号之后）匹配，避免命中 `.tomato-card` 这类标识符。
+const NAMED_COLORS = new Set(
+  ('aliceblue antiquewhite aqua aquamarine azure beige bisque black blanchedalmond blue blueviolet brown burlywood ' +
+    'cadetblue chartreuse chocolate coral cornflowerblue cornsilk crimson cyan darkblue darkcyan darkgoldenrod ' +
+    'darkgray darkgreen darkgrey darkkhaki darkmagenta darkolivegreen darkorange darkorchid darkred darksalmon ' +
+    'darkseagreen darkslateblue darkslategray darkslategrey darkturquoise darkviolet deeppink deepskyblue dimgray ' +
+    'dimgrey dodgerblue firebrick floralwhite forestgreen fuchsia gainsboro ghostwhite gold goldenrod gray green ' +
+    'greenyellow grey honeydew hotpink indianred indigo ivory khaki lavender lavenderblush lawngreen lemonchiffon ' +
+    'lightblue lightcoral lightcyan lightgoldenrodyellow lightgray lightgreen lightgrey lightpink lightsalmon ' +
+    'lightseagreen lightskyblue lightslategray lightslategrey lightsteelblue lightyellow lime limegreen linen ' +
+    'magenta maroon mediumaquamarine mediumblue mediumorchid mediumpurple mediumseagreen mediumslateblue ' +
+    'mediumspringgreen mediumturquoise mediumvioletred midnightblue mintcream mistyrose moccasin navajowhite navy ' +
+    'oldlace olive olivedrab orange orangered orchid palegoldenrod palegreen paleturquoise palevioletred papayawhip ' +
+    'peachpuff peru pink plum powderblue purple rebeccapurple red rosybrown royalblue saddlebrown salmon sandybrown ' +
+    'seagreen seashell sienna silver skyblue slateblue slategray slategrey snow springgreen steelblue tan teal ' +
+    'thistle tomato turquoise violet wheat white whitesmoke yellow yellowgreen').split(' '),
+);
+
+// 逐行扫描时维护块注释状态：注释里的 `#142`、`#deadbeef` 不是颜色。
+export function stripCssNoise(lineContent, commentState) {
+  let out = '';
+  let index = 0;
+  while (index < lineContent.length) {
+    if (commentState.inBlockComment) {
+      const close = lineContent.indexOf('*/', index);
+      if (close === -1) return out;
+      commentState.inBlockComment = false;
+      index = close + 2;
+      continue;
+    }
+    const open = lineContent.indexOf('/*', index);
+    if (open === -1) {
+      out += lineContent.slice(index);
+      break;
+    }
+    out += lineContent.slice(index, open);
+    commentState.inBlockComment = true;
+    index = open + 2;
+  }
+  // url(...) 里的 # 是片段引用，不是颜色；行注释同理。
+  return out.replace(LINE_COMMENT_PATTERN, '').replace(URL_CALL_PATTERN, 'url()');
+}
+
+// 实参里出现 var() 即视为从 token 派生，不是裸字面量。
+function colorFunctionIsRaw(lineContent) {
+  const match = COLOR_FUNCTION_PATTERN.exec(lineContent);
+  if (!match) return false;
+  const argsStart = lineContent.indexOf('(', match.index);
+  let depth = 0;
+  for (let index = argsStart; index < lineContent.length; index += 1) {
+    if (lineContent[index] === '(') depth += 1;
+    else if (lineContent[index] === ')') {
+      depth -= 1;
+      if (depth === 0) {
+        return !/\bvar\s*\(/.test(lineContent.slice(argsStart, index + 1));
+      }
+    }
+  }
+  // 括号未闭合（跨行声明）：保守地按未派生处理，宁可报出来让人看一眼。
+  return !/\bvar\s*\(/.test(lineContent.slice(argsStart));
+}
+
+function hasNamedColorValue(lineContent) {
+  const colon = lineContent.indexOf(':');
+  if (colon === -1) return false;
+  const value = lineContent.slice(colon + 1);
+  if (/\bvar\s*\(/.test(value)) return false;
+  return (value.match(/[a-zA-Z]+/g) ?? []).some((word) => NAMED_COLORS.has(word.toLowerCase()));
+}
+
+export { createSuppressionTracker, parsePragma };
+
+export function findsRawColorLiteral(lineContent, commentState) {
+  const scannable = stripCssNoise(lineContent, commentState);
+  if (!scannable.trim()) return false;
+  if (HEX_COLOR_PATTERN.test(scannable)) return true;
+  if (colorFunctionIsRaw(scannable)) return true;
+  return hasNamedColorValue(scannable);
+}
+
+// Q1-DS-404：运动值必须来自 token。匹配面只认 transition / animation 简写与
+// transition-duration / transition-timing-function / animation-duration /
+// animation-timing-function 这几个**值位置**，不扫全文——`width: 0.15s` 不存在，
+// 但 `grid-template-columns: 200ms` 这种误报要靠限定属性名挡住。
+//
+// 判定为裸值的两种情况：
+//   时长——值里出现 <number>s / <number>ms 且该数值不是来自 var()；
+//   缓动——出现 cubic-bezier()，或出现 CSS 关键字缓动（ease / ease-in / …）。
+// `linear` 与 `steps()` 不算裸缓动：它们是离散/恒速的功能性选择，没有可调的house 曲线形状，
+// 逼它们走 token 只会造出恒等别名，或造出一条无处可迁的规则。
+const MOTION_PROPERTY_PATTERN =
+  /(?:^|[;{\s])(transition|animation)(?:-(?:duration|timing-function))?\s*:/i;
+const BARE_DURATION_PATTERN = /(?:^|[^\w.-])\d*\.?\d+m?s(?![\w-])/;
+const BARE_EASING_PATTERN = /\bcubic-bezier\s*\(|\bease(?:-in-out|-in|-out)?\b/;
+const VAR_CALL_PATTERN = /\bvar\s*\([^()]*(?:\([^()]*\)[^()]*)*\)/g;
+
+// 顶层逗号切段：`cubic-bezier(0.23, 1, 0.32, 1)` 内部也有逗号，按深度切才不会把一条缓动切碎。
+function splitMotionSegments(declaration) {
+  const segments = [];
+  let depth = 0;
+  let start = 0;
+  for (let index = 0; index < declaration.length; index += 1) {
+    const character = declaration[index];
+    if (character === '(') depth += 1;
+    else if (character === ')') depth -= 1;
+    else if (character === ',' && depth === 0) {
+      segments.push(declaration.slice(start, index));
+      start = index + 1;
+    }
+  }
+  segments.push(declaration.slice(start));
+  return segments;
+}
+
+export function findsRawMotionLiteral(lineContent, commentState) {
+  const scannable = stripCssNoise(lineContent, commentState);
+
+  // 逐行扫描，但判定按**整条声明**做，理由有二：
+  //   `animation:\n  spinner-fade 1.2s\n  linear infinite;` 的 infinite 落在后续行，
+  //   按行判会把中间那行误报；
+  //   反过来 `animation: pulse 2s ease-in-out infinite, fade 0.3s ease;` 里 infinite 只属于
+  //   前一支，按行判会连带放过后一支。攒满一条再判，两个方向都对，且一条声明只报一次。
+  if (commentState.motionValue == null) {
+    const propertyMatch = MOTION_PROPERTY_PATTERN.exec(scannable);
+    if (!propertyMatch) return false;
+    commentState.motionValue = scannable.slice(scannable.indexOf(':', propertyMatch.index) + 1);
+  } else {
+    commentState.motionValue += ` ${scannable}`;
+  }
+  if (!/[;}]/.test(commentState.motionValue)) return false;
+
+  const declaration = commentState.motionValue;
+  commentState.motionValue = null;
+  return splitMotionSegments(declaration).some((segment) => {
+    // infinite 循环动画不判，且只豁免它自己那一支。时长 token 是**响应预算**——衡量
+    // 「用户动作到界面回应完毕」有多久；无限循环按定义不是对输入的响应，它的周期是该组件
+    // 自己的节奏（spinner 1.2s、skeleton 1.6s），塞进 120–300ms 只会压坏它，或逼出假 token。
+    if (/\binfinite\b/.test(segment)) return false;
+    // 值来自 var() 时不判——`transition: var(--q1-navigation-chevron-transition)` 是合法组件 token。
+    const withoutVars = segment.replace(VAR_CALL_PATTERN, '');
+    return BARE_DURATION_PATTERN.test(withoutVars) || BARE_EASING_PATTERN.test(withoutVars);
+  });
+}
 
 function resolveInstalledPackageRoot(consumerRootDir) {
   const require = createRequire(join(consumerRootDir, 'package.json'));
@@ -401,8 +554,55 @@ function isTokensPath(absolutePath, baseDir) {
   return toPosixPath(relative(baseDir, absolutePath)).includes('tokens');
 }
 
-function hasDisablePragma(fileContent, ruleId) {
-  return new RegExp(`q1-lint-disable\\s+${ruleId}\\b`).test(fileContent);
+// 抑制 pragma（issue #130 清理时重做粒度）。原实现只有文件级：整份文件里任意位置出现
+// `q1-lint-disable <RULE>` 就关掉该文件的规则。对真实代码库过粗——一处刻意例外会让整个文件失明，
+// 而 components.css 这类大文件正是刻意例外最集中的地方。
+//
+// 三种形态：
+//   q1-lint-disable-file <RULE> <理由>        整份文件
+//   q1-lint-disable-next-line <RULE> <理由>   仅下一行
+//   q1-lint-disable <RULE> <理由> … q1-lint-enable <RULE>   区间
+//
+// 硬规则：**没写理由的抑制不生效**。抑制本身若无解释，就只是把债务换了个地方藏。
+const PRAGMA_PATTERN =
+  /q1-lint-(disable-file|disable-next-line|disable|enable)\s+([A-Z0-9-]+)\b[ \t]*([^*\n]*)/;
+
+function parsePragma(lineContent, ruleId) {
+  const match = PRAGMA_PATTERN.exec(lineContent);
+  if (!match) return null;
+  const [, kind, matchedRuleId, rawReason] = match;
+  if (matchedRuleId !== ruleId) return null;
+  const reason = rawReason.replace(/\*\/\s*$/, '').trim();
+  if (kind !== 'enable' && !reason) return { kind: 'invalid', reason: '' };
+  return { kind, reason };
+}
+
+function hasFileDisablePragma(fileContent, ruleId) {
+  return fileContent
+    .split('\n')
+    .some((lineContent) => parsePragma(lineContent, ruleId)?.kind === 'disable-file');
+}
+
+// 返回一个「该行是否被抑制」的判定器；调用方必须逐行喂，以维护区间与 next-line 状态。
+function createSuppressionTracker(ruleId) {
+  let inDisabledRange = false;
+  let skipNextLine = false;
+
+  return (lineContent) => {
+    const suppressedByPreviousLine = skipNextLine;
+    skipNextLine = false;
+
+    const pragma = parsePragma(lineContent, ruleId);
+    if (pragma) {
+      if (pragma.kind === 'disable-next-line') skipNextLine = true;
+      else if (pragma.kind === 'disable') inDisabledRange = true;
+      else if (pragma.kind === 'enable') inDisabledRange = false;
+      // pragma 行本身不是代码行，不参与判定。
+      return true;
+    }
+
+    return suppressedByPreviousLine || inDisabledRange;
+  };
 }
 
 function truncateLine(lineContent, maxLength = 100) {
@@ -412,6 +612,35 @@ function truncateLine(lineContent, maxLength = 100) {
     : trimmed;
 }
 
+// 三条规则统一走同一套「是否适用 + 是否被抑制」流程。此前只有 Q1-DS-501 认 pragma，
+// Q1-DS-001 / Q1-DS-401 无论写什么注释都拦不住——包括规则命中讲述该规则的文档这种自指误报。
+const LINT_RULES = [
+  {
+    ruleId: 'Q1-DS-001',
+    appliesToFile: () => true,
+    matches: (lineContent) => DASH_DS_PATTERN.test(lineContent),
+  },
+  {
+    ruleId: 'Q1-DS-401',
+    appliesToFile: () => true,
+    matches: (lineContent) => TRANSITION_ALL_PATTERN.test(lineContent),
+  },
+  {
+    ruleId: 'Q1-DS-404',
+    // 与 Q1-DS-501 同款豁免：tokens.css 是这些字面量的**定义处**，规则不能咬住自己的源头。
+    appliesToFile: ({ isCssFile, isTokens }) => isCssFile && !isTokens,
+    createState: () => ({ inBlockComment: false, motionValue: null }),
+    matches: (lineContent, state) => findsRawMotionLiteral(lineContent, state),
+  },
+  {
+    ruleId: 'Q1-DS-501',
+    appliesToFile: ({ isCssFile, isTokens }) => isCssFile && !isTokens,
+    // 该规则需要跨行的块注释状态，故用 createState 携带。
+    createState: () => ({ inBlockComment: false }),
+    matches: (lineContent, state) => findsRawColorLiteral(lineContent, state),
+  },
+];
+
 function collectLintHits(inputPaths, baseDir) {
   const targetFiles = collectLintTargetFiles(inputPaths, baseDir);
   const hits = [];
@@ -419,41 +648,27 @@ function collectLintHits(inputPaths, baseDir) {
   for (const absoluteFilePath of targetFiles) {
     const fileContent = readFileSync(absoluteFilePath, 'utf8');
     const relativeFilePath = toPosixPath(relative(baseDir, absoluteFilePath));
-    const isCssFile = extname(absoluteFilePath) === '.css';
-    const q1ds501Applicable =
-      isCssFile &&
-      !isTokensPath(absoluteFilePath, baseDir) &&
-      !hasDisablePragma(fileContent, 'Q1-DS-501');
+    const fileFacts = {
+      isCssFile: extname(absoluteFilePath) === '.css',
+      isTokens: isTokensPath(absoluteFilePath, baseDir),
+    };
+
+    const activeRules = LINT_RULES.map((rule) => ({
+      rule,
+      applicable: rule.appliesToFile(fileFacts) && !hasFileDisablePragma(fileContent, rule.ruleId),
+      state: rule.createState?.(),
+      isSuppressed: createSuppressionTracker(rule.ruleId),
+    }));
 
     fileContent.split('\n').forEach((lineContent, index) => {
       const lineNumber = index + 1;
-      if (DASH_DS_PATTERN.test(lineContent)) {
-        hits.push({
-          ruleId: 'Q1-DS-001',
-          filePath: relativeFilePath,
-          lineNumber,
-          lineContent,
-        });
-      }
-      if (TRANSITION_ALL_PATTERN.test(lineContent)) {
-        hits.push({
-          ruleId: 'Q1-DS-401',
-          filePath: relativeFilePath,
-          lineNumber,
-          lineContent,
-        });
-      }
-      if (
-        q1ds501Applicable &&
-        (HEX_COLOR_PATTERN.test(lineContent) ||
-          COLOR_FUNCTION_PATTERN.test(lineContent))
-      ) {
-        hits.push({
-          ruleId: 'Q1-DS-501',
-          filePath: relativeFilePath,
-          lineNumber,
-          lineContent,
-        });
+      for (const { rule, applicable, state, isSuppressed } of activeRules) {
+        // 匹配与抑制状态都必须逐行推进，因此无论该规则是否适用本文件都要各过一遍，
+        // 否则块注释与区间抑制的状态会在跳过的行上错位。
+        const matched = rule.matches(lineContent, state);
+        const suppressed = isSuppressed(lineContent);
+        if (!applicable || !matched || suppressed) continue;
+        hits.push({ ruleId: rule.ruleId, filePath: relativeFilePath, lineNumber, lineContent });
       }
     });
   }
@@ -461,8 +676,39 @@ function collectLintHits(inputPaths, baseDir) {
   return hits;
 }
 
-function runLint(inputPaths, consumerRootDir) {
-  const hits = collectLintHits(inputPaths, consumerRootDir);
+// --diff <base>：只扫相对 base 有改动的文件（issue #130 缺口 1）。
+//
+// 存量包袱重的仓库无法把 lint 当门禁——q1travel-web 有上万处 legacy --ds-*，全量扫描一开就淹没。
+// 但止血不需要先还完存量：只拦新增就够，而「新增」用 git diff 现算即可。
+//
+// 刻意不做票面写的 baseline 快照：快照要生成、要更新、会和现实分叉，凭空多出一份需要维护的状态；
+// 而 CI 本来就知道 base ref。--diff 用远小的成本覆盖同一个用途。
+export function selectChangedFiles(inputPaths, baseRef, runGit) {
+  const output = runGit(['diff', '--no-renames', '--name-only', `${baseRef}...HEAD`]);
+  const changed = output.split('\n').map((line) => line.trim()).filter(Boolean);
+  if (changed.length === 0) return [];
+  // 与全量模式同源：改动集要和 inputPaths 求交，否则 --diff 反而会把扫描面扩大到范围之外。
+  const scopes = inputPaths.filter(Boolean);
+  if (scopes.length === 0) return changed;
+  return changed.filter((changedPath) =>
+    scopes.some((scope) => changedPath === scope || changedPath.startsWith(`${scope}/`)),
+  );
+}
+
+function runLint(inputPaths, consumerRootDir, diffBaseRef) {
+  let scanPaths = inputPaths;
+  if (diffBaseRef) {
+    const changed = selectChangedFiles(inputPaths, diffBaseRef, (args) =>
+      execFileSync('git', args, { cwd: consumerRootDir, encoding: 'utf8' }),
+    ).filter((path) => LINT_EXTENSIONS.has(extname(path)) && existsSync(join(consumerRootDir, path)));
+    if (changed.length === 0) {
+      console.log(`[q1-design] lint ✓（相对 ${diffBaseRef} 无可扫描的改动文件）`);
+      return;
+    }
+    scanPaths = changed;
+  }
+
+  const hits = collectLintHits(scanPaths, consumerRootDir);
 
   if (hits.length === 0) {
     console.log('[q1-design] lint ✓');
@@ -531,27 +777,172 @@ function runEval() {
   }
 }
 
+// —— ls / doc ——
+// 组件清单与 API 不另建一份数据文件：它们**现推自随包发布的 dist-pkg/design-system.d.ts**。
+// 另建数据文件意味着多一处会与真实导出面分叉的东西，而分叉的那天没人会发现——
+// .d.ts 由 tsc 从源码生成，它不可能对不上。
+//
+// 存在的理由是「查阅便捷」：消费方（人或 agent）想知道有哪些组件、某个组件收什么 props，
+// 不该被迫开浏览器翻文档站，也不该去 node_modules 里翻六万行 .d.ts。
+const TYPES_RELATIVE_PATH = 'dist-pkg/design-system.d.ts';
+
+function resolveTypesPath(consumerRootDir) {
+  const packageRootDir = resolveInstalledPackageRoot(consumerRootDir);
+  const candidates = [
+    packageRootDir && join(packageRootDir, TYPES_RELATIVE_PATH),
+    // 本仓直跑：没有「安装的自己」，退回到自己的构建产物。
+    join(consumerRootDir, TYPES_RELATIVE_PATH),
+  ].filter(Boolean);
+  return candidates.find((candidate) => existsSync(candidate)) ?? null;
+}
+
+// 逐条切出顶层声明。按大括号深度收尾，因为 props 类型体经常跨几十行；
+// 单行声明（type 别名、函数签名）以 `;` 收尾。
+export function parseTypeDeclarations(typesSource) {
+  const declarations = [];
+  const lines = typesSource.split('\n');
+  for (let index = 0; index < lines.length; index += 1) {
+    // 未导出的 `declare type` 也收：Button 的 props 形状就住在未导出的 ButtonProps 里，
+    // 而 `doc Button` 不给出 props 形状就没有存在价值。exported 标记保留，供调用方区分。
+    const match = /^(export )?declare (?:function|type|const|class) ([A-Za-z0-9_]+)/.exec(lines[index]);
+    if (!match) continue;
+    const body = [lines[index]];
+    let depth = (lines[index].match(/\{/g) ?? []).length - (lines[index].match(/\}/g) ?? []).length;
+    while (depth > 0 && index + 1 < lines.length) {
+      index += 1;
+      body.push(lines[index]);
+      depth += (lines[index].match(/\{/g) ?? []).length - (lines[index].match(/\}/g) ?? []).length;
+    }
+    const words = match[0].split(' ');
+    declarations.push({
+      name: match[2],
+      kind: words[match[1] ? 2 : 1],
+      exported: Boolean(match[1]),
+      text: body.join('\n'),
+    });
+  }
+  return declarations;
+}
+
+// 组件 = 首字母大写的导出函数。小写导出（addDays、useToast 之类）是工具与 hook，
+// 单列一档而不是混进组件清单——把它们混在一起，清单就不再回答「有哪些组件」这个问题了。
+const isComponentName = (name) => /^[A-Z]/.test(name);
+
+function loadDeclarations(consumerRootDir) {
+  const typesPath = resolveTypesPath(consumerRootDir);
+  if (!typesPath) {
+    console.error(`[q1-design] 找不到 ${TYPES_RELATIVE_PATH}。请先安装 ${PACKAGE_NAME}，或在本仓先跑 npm run build。`);
+    process.exit(1);
+  }
+  return parseTypeDeclarations(readFileSync(typesPath, 'utf8'));
+}
+
+function runList(consumerRootDir) {
+  const declarations = loadDeclarations(consumerRootDir);
+  const components = declarations
+    .filter(({ kind, name, exported }) => exported && kind === 'function' && isComponentName(name))
+    .map(({ name }) => name)
+    .sort();
+  const hooks = declarations
+    .filter(({ kind, name, exported }) => exported && kind === 'function' && !isComponentName(name))
+    .map(({ name }) => name)
+    .sort();
+
+  console.log(`组件 (${components.length})`);
+  for (const name of components) console.log(`  ${name}`);
+  if (hooks.length > 0) {
+    console.log(`\n工具与 hook (${hooks.length})`);
+    console.log(`  ${hooks.join('  ')}`);
+  }
+  console.log(`\n查看某个组件的 API：q1-design doc <名称>`);
+}
+
+function runDoc(consumerRootDir, requestedName) {
+  if (!requestedName) {
+    console.error('Usage: q1-design doc <组件名>');
+    process.exit(1);
+  }
+  const declarations = loadDeclarations(consumerRootDir);
+  // 连带打印同前缀的**类型**（ButtonProps / ButtonVariant / ButtonSize…）：
+  // 只给函数签名等于把 props 的形状藏起来，读者还得自己再翻一次。
+  // 但只带类型，不带同前缀的另一个组件——`doc Button` 不该顺手塞来 ButtonLink，
+  // 那是另一个组件，有它自己的一页。
+  // 同前缀的类型归属于「最长的那个同前缀组件」：ButtonLinkProps 属于 ButtonLink，
+  // 不该在 `doc Button` 里露面。按最长前缀判归属，不必维护一张后缀白名单。
+  const componentNames = declarations
+    .filter(({ kind, name, exported }) => exported && kind === 'function' && isComponentName(name))
+    .map(({ name }) => name);
+  const belongsElsewhere = (typeName) =>
+    componentNames.some(
+      (candidate) => candidate.length > requestedName.length && typeName.startsWith(candidate),
+    );
+  const related = declarations.filter(
+    ({ name, kind }) =>
+      name === requestedName ||
+      (kind === 'type' && name.startsWith(requestedName) && !belongsElsewhere(name)),
+  );
+  if (related.length === 0) {
+    const suggestions = declarations
+      .filter(({ name }) => name.toLowerCase().includes(requestedName.toLowerCase()))
+      .map(({ name }) => name);
+    console.error(`[q1-design] 没有导出名为 ${requestedName} 的成员。`);
+    if (suggestions.length > 0) console.error(`  是否想找：${suggestions.join(', ')}`);
+    else console.error('  用 q1-design ls 看完整清单。');
+    process.exit(1);
+  }
+  for (const declaration of related) {
+    console.log(declaration.text);
+    console.log('');
+  }
+}
+
 function printUsage() {
-  console.error('Usage: q1-design <sync|verify|lint|eval>');
+  console.error('Usage: q1-design <ls|doc|sync|verify|lint|eval>');
+  console.error('  ls              列出随包发布的组件与 hook');
+  console.error('  doc <组件名>     打印该组件的公共 API（函数签名 + 同名前缀的类型）');
   console.error(
     '  lint [路径...]  扫描 .css/.js/.jsx/.ts/.tsx/.mjs,默认 src,目录递归',
   );
+  console.error(
+    '  lint --diff <base-ref> [路径...]  只扫相对 base-ref 有改动的文件（存量重的仓库用它当增量门禁）',
+  );
   console.error('  eval            对 tooling/scripts/evals 的 fixtures 跑 before/after 断言');
 }
 
-const subcommand = process.argv[2];
-const consumerRootDir = process.cwd();
-
-if (subcommand === 'sync') {
-  runSync(consumerRootDir);
-} else if (subcommand === 'verify') {
-  runVerify(consumerRootDir);
-} else if (subcommand === 'lint') {
-  const inputPaths = process.argv.slice(3);
-  runLint(inputPaths.length > 0 ? inputPaths : ['src'], consumerRootDir);
-} else if (subcommand === 'eval') {
-  runEval();
-} else {
-  printUsage();
-  process.exit(1);
+// 直跑守卫（与 scripts/ci-path-filter.mjs 同款）：被 import 时只暴露纯函数，不执行 CLI，
+// 这样 Q1-DS-501 的匹配逻辑可以被单测直接覆盖，而不必靠拉起子进程去反推。
+const isDirectRun =
+  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+
+if (isDirectRun) {
+  const subcommand = process.argv[2];
+  const consumerRootDir = process.cwd();
+
+  if (subcommand === 'ls') {
+    runList(consumerRootDir);
+  } else if (subcommand === 'doc') {
+    runDoc(consumerRootDir, process.argv[3]);
+  } else if (subcommand === 'sync') {
+    runSync(consumerRootDir);
+  } else if (subcommand === 'verify') {
+    runVerify(consumerRootDir);
+  } else if (subcommand === 'lint') {
+    const args = process.argv.slice(3);
+    const diffIndex = args.indexOf('--diff');
+    let diffBaseRef;
+    if (diffIndex !== -1) {
+      diffBaseRef = args[diffIndex + 1];
+      if (!diffBaseRef || diffBaseRef.startsWith('--')) {
+        console.error('Usage: q1-design lint --diff <base-ref> [路径...]');
+        process.exit(1);
+      }
+      args.splice(diffIndex, 2);
+    }
+    runLint(args.length > 0 ? args : ['src'], consumerRootDir, diffBaseRef);
+  } else if (subcommand === 'eval') {
+    runEval();
+  } else {
+    printUsage();
+    process.exit(1);
+  }
 }

package/contracts/implementation-map.md

@@ -27,3 +27,12 @@ README owns the repository inventory and generated-file boundary. This file owns
 - Token references are the design source for production code. Current theme resolved values are clipboard output only.
 - The same public navigation groups remain in the product surface: `基础`, `品牌`, and `组件`.
 - If a capability is missing from a shared component, add the capability to that component before adding another page-local pattern.
+
+## Documentation Section Ownership
+
+Two component-page sections are q1travel supersets with no external counterpart, so their scope is defined here rather than inferred page by page.
+
+- **设计 Token** — every Tier B native-semantic control page (Button, Input, Textarea, Select, Checkbox, Radio, Switch) MUST carry this section. Those controls take their whole surface from semantic tokens, so the role/token/usage table is the only place a consumer can see which tokens to override. Tier A and Tier C pages MUST NOT add it by default: their appearance comes mostly from structure, and a token table there restates the global palette without telling the reader anything component-specific. **Tabs is the one recorded exception** — a Tier A component whose surface is likewise entirely token-driven; it keeps its table, and it does not license other Tier A pages to add one.
+- **API 与行为矩阵** — reserved for composite host components that the consumer assembles while the host owns the state (ContextSwitcher, Navigation, Sidebar). The table exists to state who owns what; a component that owns its own state does not need it.
+
+Rows in these tables reference semantic tokens (`--q1-color-*`, `--q1-shadow-*`, `--q1-radius-*`), not component-private custom properties. Component-private properties driven by props (for example an avatar diameter) are implementation detail and MUST NOT be documented as a consumer-facing token contract.