@manohub/kit 0.6.1 → 0.7.0

package/skills/lint.mjs

@@ -0,0 +1,500 @@
+#!/usr/bin/env node
+/**
+ * `kit lint` —— 接入方的**机械护栏**（0.6.0 曾整批下线，0.7.0 起恢复最小三组）。
+ *
+ * 为什么恢复：0.6.0 把三条脚本护栏下线、改成「CONTRACT.md + §7 手工自检」之后，成本立刻兑现 ——
+ * 三个应用迁完就累计出「3 份重复 reset」「1 处登记描述错误」「1 处注释引错文件名」，
+ * 每一项都是「有脚本就当场红」的类型。手工自检的问题不是不认真，是**每次都要重新认真一遍**。
+ *
+ * ## 分组（各自独立，可单独跑；默认全跑）
+ *
+ * | 组 | 检查 | 对应条款 |
+ * | --- | --- | --- |
+ * | `style` | `!important` / `.mh-*` 覆写 / 裸元素与 `*` / `rem` / `tailwind` | L1-3 L1-6 L1-7 |
+ * | `source` | 从白名单之外取外观（第三方组件库 / CSS 框架 / 图标库 / 深引子路径 / 旧包名） | L3-3 |
+ * | `namespace` | 业务类名不以本仓命名空间开头 | L1-5（需 `--namespace`） |
+ * | `property` | L1-4 属性闭集（视觉属性越界） | L1-4 |
+ *
+ * ⚠️ **这是应用侧工具，别对着四包源码跑。** L1-4 / L1-6 约束的是**应用自绘的东西**
+ * （不许自绘颜色、不许用裸元素、不许碰 `.mh-*`），而库本身就是这些外观的实现方 ——
+ * 实测对 `packages/ui/src` 跑会输出 **1141 处**「覆写库的类」，全是假红。
+ * 脚本因此**按包名拦住四包**（`@manohub/{kit,ui,theme,icon}`）并提示该给哪个根，
+ * 而不是吐一堆不可执行的红。
+ *
+ * ## 覆盖范围（**有意保守，宁可漏报不误报**）
+ *
+ * - `style`：扫 `.css` 全文；`.vue` / `.tsx` / `.html` 只扫 `<style>` 块与 `class=` 的字面值。
+ *   动态拼出来的类名（`` `mh-x--${x}` ``）**不判**；裸元素**只看第一段复合选择器**
+ *   （`.foo > span` 里的 `span` 不报 —— 应用自绘样式本就挂在自有类名下），
+ *   带属性锚点（`input[type='text']`）也放行。
+ * - `source`：按**已知外观库**黑名单判（不可能穷举，故同时看白名单前缀与子路径）。
+ * - `namespace`：需 `--namespace <前缀>`（可多次）；不给则跳过并提示（本仓命名空间见 `docs/kit-namespaces.md`）。
+ * - **判不了的一律不报**：组件默认值是否与文档一致（§3.6 / §3.10 A4 那一类）需要读文档，属 §7 自检。
+ *
+ * ## 用法
+ *
+ *   pnpm exec kit lint --root apps/skill-topic --namespace topic
+ *   pnpm exec kit lint --group source            # 只跑一组（可多次）
+ *   pnpm exec kit lint --json                    # 机器可读输出
+ *
+ * 退出码：有违规 → 1；否则 0。**这里红的是「条款」，不是「风格偏好」** ——
+ * 修不了时按契约 §11 登记，登记后仍违规的几类（自绘页头 / 原生控件承载外观 / `!important` …）
+ * 本脚本**不会**为你放行，请改实现。
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, relative, resolve, sep } from 'node:path'
+// 与 bin/kit.mjs 同源：pnpm 把包放在 .pnpm 下、消费方引用的是软链，
+// 直接比较 argv[1] 与 import.meta.url 会字面不等 → 脚本静默不执行。
+import { isDirectRun } from './install.mjs'
+
+/* ============================================================
+ * 一、契约里抄下来的闭集（**改契约时同步改这里**）
+ * ============================================================ */
+
+/** L1-4 属性白名单（逐字展开自 `CONTRACT.md` §3「L1-4 的属性白名单」） */
+const PROPERTY_WHITELIST = new Set([
+  // 盒模型与定位
+  'display', 'position', 'inset', 'top', 'right', 'bottom', 'left', 'z-index', 'box-sizing',
+  'width', 'height', 'min-width', 'min-height', 'max-width', 'max-height',
+  'margin', 'margin-top', 'margin-right', 'margin-bottom', 'margin-left',
+  'padding', 'padding-top', 'padding-right', 'padding-bottom', 'padding-left',
+  'overflow', 'overflow-x', 'overflow-y', 'gap', 'row-gap', 'column-gap', 'aspect-ratio', 'resize',
+  // 弹性与栅格
+  'flex', 'flex-direction', 'flex-wrap', 'flex-grow', 'flex-shrink', 'flex-basis',
+  'align-items', 'align-self', 'align-content', 'justify-content', 'justify-items', 'justify-self',
+  'order', 'place-items', 'place-content', 'grid-template-columns', 'grid-template-rows',
+  'grid-auto-flow', 'grid-auto-columns', 'grid-auto-rows', 'grid-column', 'grid-row',
+  // 文字流（不含颜色与字号）
+  'white-space', 'text-overflow', 'overflow-wrap', 'word-break', 'text-align', 'vertical-align',
+  'line-clamp', '-webkit-line-clamp', 'hyphens', 'direction', 'writing-mode',
+  // 交互与动效
+  'cursor', 'user-select', 'pointer-events', 'visibility',
+  'transition', 'transition-property', 'transition-duration', 'transition-delay', 'transition-timing-function',
+  'animation', 'animation-name', 'animation-duration', 'animation-delay', 'animation-iteration-count',
+  'animation-direction', 'animation-fill-mode',
+  'transform', 'transform-origin', 'will-change', 'scroll-behavior', 'overscroll-behavior',
+  'touch-action', 'scrollbar-width',
+  // 其他
+  'content', 'list-style', 'list-style-type', 'list-style-position', 'isolation', 'contain',
+  'object-fit', 'object-position', 'clip-path',
+])
+
+/** 唯一重置例外（`border: 0` / `border: none`）；其余 border* 一律违规 */
+const BORDER_RESET_OK = /^(0|none)$/
+
+/** L1-6 的唯一例外：入口基线 —— 这几个选择器（及其高度链）在应用侧合法 */
+const ENTRY_BASELINE_SELECTORS = new Set(['html', 'body', ':root', '#app'])
+
+/**
+ * 由 kit 写入、但**不带 `mh-` 前缀**的 shell 类：`createSubApp` 会无条件用 `.app-container`
+ * 包裹子应用（并写 `data-manohub-ui` 锚）。它不属于「应用自绘」，因此不参与 L1-5 命名空间判定
+ * —— 应用侧引它只能靠 `class="app-container"`，报红等于要求应用改不了的东西。
+ */
+const SHELL_CLASSES = new Set(['app-container'])
+
+/** L3-3：已知的「外观来源」第三方库（黑名单，不可能穷举；白名单前缀见下） */
+const FORBIDDEN_SOURCE_PATTERNS = [
+  /^@farris\//, /^element-plus/, /^ant-design-vue/, /^@arco-design/, /^naive-ui/, /^vant/, /^@vant\//,
+  /^vue-lucide/, /^lucide(-|$)/, /^@iconify/, /^@iconfu/, /^bootstrap/, /^bulma/, /^tailwindcss/,
+  /^@tailwindcss\//, /^@manohub\/app-/, /^@manohub\/base-ui/, /^@manohub\/components/,
+]
+
+/** L3-3：允许取外观的包与其**允许的**子路径（深引其它子路径违规） */
+const ALLOWED_SOURCES = [
+  { name: '@manohub/ui', subpaths: ['/styles.css'] },
+  { name: '@manohub/icon', subpaths: ['/glyphs'] },
+  { name: '@manohub/theme', subpaths: ['/default.css', '/farris.css'] },
+  { name: '@manohub/kit', subpaths: ['/entry', '/CONTRACT.md'] },
+]
+
+/**
+ * 四包自身 —— `kit lint` **面向消费方**，对本仓这四个包跑毫无意义：
+ * 契约的 L1-4 / L1-6 约束的是**应用自绘样式**（不许自绘颜色、不许用裸元素、不许碰 `.mh-*`），
+ * 而库本身就是外观的实现方 —— 在库源码上跑必然满屏假红（实测 `packages/ui/src` 1141 处）。
+ * 与其输出一堆不可执行的红，不如**按包名直接拦住**并说清该给哪个根。
+ */
+const LIBRARY_PACKAGES = new Set(['@manohub/kit', '@manohub/ui', '@manohub/theme', '@manohub/icon'])
+
+/* ============================================================
+ * 二、扫描
+ * ============================================================ */
+
+const SCAN_EXT = ['.css', '.vue', '.tsx', '.ts', '.html']
+const SKIP_DIRS = new Set(['node_modules', 'dist', '.git', '.vite', 'coverage'])
+
+/** 递归列出文件（返回**相对 root** 的路径，便于报错时读得懂） */
+function walkFiles(root, dir = root, out = []) {
+  for (const entry of readdirSync(dir)) {
+    if (SKIP_DIRS.has(entry)) continue
+    const full = join(dir, entry)
+    const info = statSync(full)
+    if (info.isDirectory()) walkFiles(root, full, out)
+    else if (SCAN_EXT.some((ext) => entry.endsWith(ext))) out.push(full)
+  }
+  return out
+}
+
+/** 剥 CSS 注释（注释里会举反例写法，不剥就会把说明当成实现）。
+ *  **保留换行与字节偏移**：把注释内容换成空格而非删掉，这样后面算出的行号才是原文件的行号。 */
+const stripCssComments = (text) => text.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '))
+
+/** 按文件类型剥注释：`.css` 只有块注释；其余还要剥 JS 行注释（`// 别用 !important` 这类说明）。 */
+function stripComments(text, isCss) {
+  const code = stripCssComments(text)
+  if (isCss) return code
+  return code.replace(/(?<!:)\/\/[^\n]*/g, (m) => m.replace(/[^\n]/g, ' '))
+}
+
+/** 取 `.css` 里的 `选择器 { 声明块 }`（不支持嵌套；够用且不会误判），带起始偏移（用于行号） */
+function cssBlocks(source) {
+  const blocks = []
+  const re = /([^{}]+)\{([^{}]*)\}/g
+  let match
+  while ((match = re.exec(source))) {
+    blocks.push({ selector: match[1].trim(), body: match[2], index: match.index })
+  }
+  return blocks
+}
+
+/** 偏移 → 行号（1 基） */
+const lineAt = (text, index) => text.slice(0, index).split('\n').length
+
+/** 选择器可能写很多行（逗号列表），报错时只留第一行，别把输出淹掉 */
+const firstLine = (text) => text.split('\n')[0].trim()
+
+/** `{ display: 'flex', border: '0' }` / `style="display: flex"` → 属性名清单（kebab） */
+function inlineStyleProps(text) {
+  const props = []
+  for (const block of text.match(/style\s*=\s*\{([^}]*)\}/g) ?? []) {
+    for (const pair of block.matchAll(/([A-Za-z-]+)\s*:/g)) {
+      props.push(pair[1].replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`))
+    }
+  }
+  for (const block of text.match(/style\s*=\s*"([^"]*)"/g) ?? []) {
+    for (const pair of block.matchAll(/([a-z-]+)\s*:/g)) props.push(pair[1])
+  }
+  return props
+}
+
+/** 从一条声明块里取 `属性: 值` 对（跳过自定义属性 `--x`） */
+function declarations(body) {
+  const out = []
+  for (const raw of body.split(';')) {
+    const index = raw.indexOf(':')
+    if (index < 0) continue
+    const prop = raw.slice(0, index).trim().toLowerCase()
+    const value = raw.slice(index + 1).trim()
+    if (!prop || prop.startsWith('--') || prop.startsWith('@')) continue
+    out.push({ prop, value })
+  }
+  return out
+}
+
+/** 选择器里是否出现**裸元素 / `*`**（只看第一段复合选择器；入口基线除外） */
+function bareElementSelectors(selector) {
+  const offenders = []
+  for (const part of selector.split(',').map((s) => s.trim())) {
+    if (!part || part.startsWith('%') || part.startsWith('@')) continue
+    // 只看第一段（到第一个组合符为止）：`.foo > span` 里的 span 不报 —— 应用侧的自绘样式
+    // 本就该挂在自有类名下，`span` 只是它内部的结构，误报面大于收益。
+    const first = part.split(/[\s>+~]+/)[0]
+    if (!first) continue
+    const core = first.replace(/::?[\w-]*(\([^)]*\))?/g, '')
+    if (!core) continue // 第一段整体是伪类（`:hover` / `:where(…)`）→ 不算裸元素
+    if (/[.#[]/.test(core)) continue // 有类 / id / 属性锚点 → 已限定作用域，放行
+    if (ENTRY_BASELINE_SELECTORS.has(core)) continue
+    if (/^(\*|[a-z][\w-]*)$/i.test(core)) offenders.push(first)
+  }
+  return offenders
+}
+
+/* ============================================================
+ * 三、检查组
+ * ============================================================ */
+
+/** 把每个文件交给回调：(相对路径, 全文, 是否 .css, 已剥注释的同长度文本) */
+function eachFile(root, files, visit) {
+  for (const file of files) {
+    const text = readFileSync(file, 'utf8')
+    const isCss = file.endsWith('.css')
+    const rel = relative(root, file).split(sep).join('/')
+    visit(rel, text, isCss, stripComments(text, isCss))
+  }
+}
+
+/** 取文件里所有 `选择器 { 声明块 }` —— 传进来的必须是**已剥注释**的文本（偏移才与原文一致） */
+function styleBlocksOf(code, isCss) {
+  if (isCss) return cssBlocks(code)
+  const out = []
+  for (const tag of code.matchAll(/<style[^>]*>([\s\S]*?)<\/style>/g)) {
+    const inner = tag[1]
+    const offset = tag.index + tag[0].indexOf(inner)
+    for (const block of cssBlocks(inner)) out.push({ ...block, index: offset + block.index })
+  }
+  return out
+}
+
+/** `style` 组：应用侧红线条（L1-3 / L1-6 / L1-7） */
+function checkStyle(root, files) {
+  const issues = []
+  eachFile(root, files, (rel, text, isCss, code) => {
+    const push = (rule, detail, line) => issues.push({ rule, file: rel, detail, line })
+
+    // 全文件级三条：`!important` 与 tailwind 在任何地方都是红线；`rem` 是几何口径
+    for (const m of code.matchAll(/!important/g)) {
+      push('L1-6', '出现 !important（契约 §11 红线，登记也不放行）', lineAt(text, m.index))
+    }
+    for (const m of code.matchAll(/(?:^|[\s:(,])(-?\d*\.?\d+)rem\b/g)) {
+      push('L1-3', `出现 rem（几何取 px 令牌，不跟根字号走）：${m[1]}rem`, lineAt(text, m.index))
+    }
+    for (const m of code.matchAll(/tailwindcss|@tailwindcss\/|\b@theme\b/g)) {
+      push('L1-7', '出现 tailwind 相关引用', lineAt(text, m.index))
+    }
+
+    for (const { selector, index } of styleBlocksOf(code, isCss)) {
+      const line = lineAt(text, index)
+      if (/\.mh-[\w-]/.test(selector)) push('L1-6', `选择器 ${firstLine(selector)} 覆写了库的类`, line)
+      for (const bare of bareElementSelectors(selector)) {
+        push('L1-6', `选择器 ${bare} 用了裸元素 / *（入口基线 html/body/#app/:root 除外）`, line)
+      }
+    }
+
+    if (isCss) return
+    // 非 CSS：`class=` 的字面值里出现库的类名（覆写库外观的另一条路）
+    for (const cls of code.matchAll(/class(?:Name)?\s*=\s*["'`]([^"'`]*)["'`]/g)) {
+      for (const token of cls[1].split(/\s+/)) {
+        if (token.startsWith('mh-')) push('L1-6', `class 里出现库的类名 ${token}`, lineAt(text, cls.index))
+      }
+    }
+  })
+  return issues
+}
+
+/** `property` 组：L1-4 属性闭集 —— **只在应用根跑**（库是实现方，跑它必然满屏假红） */
+function checkProperty(root, files) {
+  const issues = []
+  eachFile(root, files, (rel, text, isCss, code) => {
+    const badBorder = (prop, value) => {
+      if (prop === 'border') return !BORDER_RESET_OK.test(value)
+      return ['width', 'style', 'color'].includes(prop.split('-')[1])
+    }
+
+    for (const { selector, body, index } of styleBlocksOf(code, isCss)) {
+      const line = lineAt(text, index)
+      const where = `选择器 ${firstLine(selector)}`
+      for (const { prop, value } of declarations(body)) {
+        if (prop === 'border' || prop.startsWith('border-')) {
+          if (badBorder(prop, value)) {
+            issues.push({ rule: 'L1-4', file: rel, detail: `${where} 的 ${prop}（只允许 border: 0 / none）`, line })
+          }
+          continue
+        }
+        if (!PROPERTY_WHITELIST.has(prop)) {
+          issues.push({ rule: 'L1-4', file: rel, detail: `${where} 用了非白名单属性 ${prop}`, line })
+        }
+      }
+    }
+
+    if (isCss) return
+    for (const prop of inlineStyleProps(code)) {
+      if (prop === 'border' || prop.startsWith('border-')) continue
+      if (!PROPERTY_WHITELIST.has(prop)) {
+        issues.push({ rule: 'L1-4', file: rel, detail: `内联 style 用了非白名单属性 ${prop}` })
+      }
+    }
+  })
+  return issues
+}
+
+function checkSource(root, files) {
+  const issues = []
+  eachFile(root, files, (rel, text) => {
+    for (const match of text.matchAll(/(?:from|import|require\()\s*['"]([^'"]+)['"]/g)) {
+      const spec = match[1]
+      if (!spec || spec.startsWith('.') || spec.startsWith('/') || spec.startsWith('node:')) continue
+
+      const forbidden = FORBIDDEN_SOURCE_PATTERNS.find((re) => re.test(spec))
+      if (forbidden) {
+        issues.push({ rule: 'L3-3', file: rel, detail: `${spec} 是白名单之外的外观来源` })
+        continue
+      }
+
+      const allowed = ALLOWED_SOURCES.find((item) => spec === item.name || spec.startsWith(`${item.name}/`))
+      if (!allowed) continue
+      const sub = spec.slice(allowed.name.length)
+      if (sub && !allowed.subpaths.some((p) => sub === p || sub.startsWith(`${p}/`))) {
+        issues.push({ rule: 'L3-3', file: rel, detail: `${spec} 深引了未开放的子路径` })
+      }
+    }
+  })
+  return issues
+}
+
+/** `namespace` 组：业务类名必须以本仓命名空间开头（L1-5）；库的 `.mh-*` 与 shell 类天然放行 */
+function checkNamespace(root, files, namespaces) {
+  const issues = []
+  eachFile(root, files, (rel, text, isCss, code) => {
+    const known = (selector, line) => {
+      for (const part of selector.split(',').map((s) => s.trim())) {
+        for (const cls of part.matchAll(/\.([A-Za-z][\w-]*)/g)) {
+          const name = cls[1]
+          if (name.startsWith('mh-') || SHELL_CLASSES.has(name)) continue
+          if (!namespaces.some((ns) => name.startsWith(`${ns}-`))) {
+            issues.push({ rule: 'L1-5', file: rel, line, detail: `类名 ${name} 不以本仓命名空间开头（${namespaces.join(' / ')}）` })
+          }
+        }
+      }
+    }
+
+    for (const { selector, index } of styleBlocksOf(code, isCss)) known(selector, lineAt(text, index))
+    if (isCss) return
+    for (const cls of code.matchAll(/class(?:Name)?\s*=\s*["'`]([^"'`]*)["'`]/g)) {
+      const line = lineAt(text, cls.index)
+      for (const token of cls[1].split(/\s+/)) if (token) known(`.${token}`, line)
+    }
+  })
+  return issues
+}
+
+/* ============================================================
+ * 四、CLI
+ * ============================================================ */
+
+/** 全部可跑的组（应用侧全跑；`property` 见头注释为何不能对着库跑） */
+export const GROUPS = { style: checkStyle, source: checkSource, namespace: checkNamespace, property: checkProperty }
+
+/** 缺省跑的组 —— 四组全跑（根已被限定为消费方） */
+export const DEFAULT_GROUPS = Object.keys(GROUPS)
+
+export function parseArgs(argv = []) {
+  const options = { root: process.cwd(), namespaces: [], groups: [], json: false, help: false }
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === '--help' || arg === '-h') options.help = true
+    else if (arg === '--json') options.json = true
+    else if (arg === '--root') options.root = resolve(argv[++i] ?? '.')
+    else if (arg === '--namespace') options.namespaces.push(argv[++i] ?? '')
+    else if (arg === '--group') options.groups.push(argv[++i] ?? '')
+  }
+  return options
+}
+
+export const USAGE = [
+  'kit lint —— 接入契约的机械护栏',
+  '',
+  '用法：kit lint [--root <dir>] [--namespace <前缀>]… [--group <组>]… [--json]',
+  '',
+  '  --root        要检查的目录（缺省 cwd；应用侧给 apps/<app>）',
+  '  --namespace   本仓业务类名前缀，可多次（如 topic / role；见 docs/kit-namespaces.md）',
+  '                不给则跳过 L1-5 检查（不瞎猜前缀）',
+  '  --group       只跑指定组，可多次；缺省四组全跑',
+  '',
+  '组：',
+  '  style         红线条（!important / .mh-* 覆写 / 裸元素与 * / rem / tailwind）',
+  '  source        外观来源白名单（第三方组件库 / CSS 框架 / 图标库 / 深引子路径 / 旧包名）',
+  '  namespace     业务类名前缀（L1-5，需 --namespace）',
+  '  property      L1-4 属性闭集（视觉属性越界）',
+  '',
+  '退出码：有违规 1 / 无 0。',
+].join('\n')
+
+/** 读目录自身的 `package.json` 名字（读不到返回 null —— 任意目录也能扫） */
+function packageNameOf(root) {
+  try {
+    return JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).name ?? null
+  } catch {
+    return null
+  }
+}
+
+export function runLint(options) {
+  const root = options.root
+  if (!existsSync(root)) return { root, issues: [], error: `目录不存在：${root}` }
+
+  const pkgName = packageNameOf(root)
+  if (pkgName && LIBRARY_PACKAGES.has(pkgName)) {
+    return {
+      root,
+      issues: [],
+      error:
+        `${pkgName} 是四包之一（库本体）。kit lint 检查的是**消费方自绘的东西**，` +
+        '对它跑只会满屏假红（L1-4 不许自绘颜色、L1-6 不许碰 .mh-* —— 库正是这两条的实现方）。' +
+        '请指向应用根，如 --root apps/skill-topic。',
+    }
+  }
+
+  const wantGroups = options.groups.length ? options.groups : DEFAULT_GROUPS
+  const unknown = wantGroups.filter((g) => !GROUPS[g])
+  if (unknown.length) return { root, issues: [], error: `未知的检查组：${unknown.join(', ')}（可用：${Object.keys(GROUPS).join(' / ')}）` }
+
+  const files = walkFiles(root)
+  const seen = new Set()
+  const issues = []
+  const collect = (list) => {
+    for (const issue of list) {
+      // 去重：同一处（规则 + 文件 + 行 + 说明）只报一次。
+      // `.app-container` 在 app.css 里出现 13 次就是同一类事的 13 份拷贝，重复输出只会稀释信号。
+      const key = `${issue.rule}|${issue.file}|${issue.line ?? ''}|${issue.detail}`
+      if (seen.has(key)) continue
+      seen.add(key)
+      issues.push(issue)
+    }
+  }
+
+  for (const group of wantGroups) {
+    if (group === 'namespace') {
+      if (!options.namespaces.length) continue // 没给前缀就跳过（不瞎猜）
+      collect(checkNamespace(root, files, options.namespaces))
+    } else {
+      collect(GROUPS[group](root, files))
+    }
+  }
+  const skipped = wantGroups.includes('namespace') && !options.namespaces.length ? ['namespace'] : []
+  return { root, issues, scanned: files.length, groups: wantGroups, skipped }
+}
+
+/** 打印结果；返回退出码 */
+export function report(result, options) {
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2))
+    return result.error || result.issues.length ? 1 : 0
+  }
+  if (result.error) {
+    console.error(`[kit lint] ${result.error}`)
+    return 1
+  }
+  const hint = result.skipped?.includes('namespace') ? '；L1-5 已跳过，加 --namespace <前缀> 才查' : ''
+  if (!result.issues.length) {
+    console.log(`[kit lint] 通过（扫了 ${result.scanned} 个文件，根：${result.root}${hint}）`)
+    return 0
+  }
+  const byRule = new Map()
+  for (const issue of result.issues) {
+    const list = byRule.get(issue.rule) ?? []
+    list.push(issue)
+    byRule.set(issue.rule, list)
+  }
+  for (const [rule, list] of byRule) {
+    console.error(`\n[${rule}] ${list.length} 处`)
+    for (const issue of list) {
+      const where = issue.line ? `${issue.file}:${issue.line}` : issue.file
+      console.error(`  ${where}  ${issue.detail}`)
+    }
+  }
+  console.error(`\n[kit lint] 共 ${result.issues.length} 处违规（${result.root}${hint}）`)
+  console.error('修不了时按契约 §11 登记；登记不放行的几类（自绘页头 / 原生控件承载外观 / !important …）请改实现。')
+  return 1
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2))
+  if (options.help) {
+    console.log(USAGE)
+    return
+  }
+  process.exitCode = report(runLint(options), options)
+}
+
+if (isDirectRun(process.argv[1], import.meta.url)) {
+  main()
+}