@manohub/app-kit 0.2.0 → 0.2.3

package/lint/shared.mjs

@@ -1,347 +1,462 @@
-/**
- * 护栏共享基建：配置加载 / 文件遍历 / 注释剥离 / 违规输出与 correction 表。
- *
- * 三条护栏脚本（style / component / structure）与 run-all 统一依赖本文件，
- * 保证「同一份配置 + 同一种输出契约」，消费方只需写一个配置文件。
- *
- * 输出契约（大模型自我修正的前提）：
- *   { app, file, rule, line, severity, message, snippet,
- *     correction: { summary, example, doc } }
- */
-import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs'
-import { join, relative, extname, sep } from 'node:path'
-import { execSync } from 'node:child_process'
-
-/** 默认配置（消费方可覆盖）；`apps[].dir` 相对消费仓根（= process.cwd()）。 */
-export const DEFAULT_CONFIG = {
-  apps: [],
-  srcGlobs: ['src/**/*.ts', 'src/**/*.tsx'],
-  styleGlobs: ['src/**/*.css'],
-  exemptionRegistry: null,
-  contractDoc: 'node_modules/@manohub/app-kit/CONTRACT.md',
-  ignore: ['node_modules', 'dist'],
-}
-
-export function loadConfig(cwd = process.cwd()) {
-  const path = join(cwd, 'appkit-guardrails.config.json')
-  if (!existsSync(path)) {
-    fail(
-      `未找到护栏配置：${path}\n` +
-        `请在应用包根创建 appkit-guardrails.config.json（结构见 @manohub/app-kit/lint/guardrails.config.schema.json）。`,
-    )
-  }
-  const raw = JSON.parse(readFileSync(path, 'utf8'))
-  const config = { ...DEFAULT_CONFIG, ...raw }
-  if (!Array.isArray(config.apps) || config.apps.length === 0) {
-    fail('配置里的 apps 不能为空（至少要列出被审计的应用目录）。')
-  }
-  return config
-}
-
-export function fail(message) {
-  process.stderr.write(`\n[guardrails] ${message}\n\n`)
-  process.exit(2)
-}
-
-/** 简易 CLI 参数解析：--json / --strict / --changed / --app=<name> / --cwd=<path> */
-export function parseArgs(argv = process.argv.slice(2)) {
-  const args = { json: false, strict: false, changed: false, app: null, cwd: process.cwd() }
-  for (const raw of argv) {
-    if (raw === '--json') args.json = true
-    else if (raw === '--strict') args.strict = true
-    else if (raw === '--changed') args.changed = true
-    else if (raw.startsWith('--app=')) args.app = raw.slice('--app='.length)
-    else if (raw.startsWith('--cwd=')) args.cwd = raw.slice('--cwd='.length)
-  }
-  return args
-}
-
-/** 递归收集文件：按扩展名 + 配置的 glob 范围过滤，跳过 ignore 目录与 .d.ts。 */
-export function collectFiles(root, config, extensions, globs = null) {
-  const out = []
-  const ignore = new Set(config.ignore)
-  const matchers = (globs ?? []).map(globToRegExp)
-  const walk = (dir) => {
-    if (!existsSync(dir)) return
-    for (const entry of readdirSync(dir)) {
-      if (ignore.has(entry) || entry.startsWith('.')) continue
-      const full = join(dir, entry)
-      const st = statSync(full)
-      if (st.isDirectory()) {
-        walk(full)
-      } else if (extensions.includes(extname(entry)) && !entry.endsWith('.d.ts')) {
-        if (matchers.length > 0) {
-          const rel = relative(root, full).split(sep).join('/')
-          if (!matchers.some((m) => m.test(rel))) continue
-        }
-        out.push(full)
-      }
-    }
-  }
-  walk(root)
-  return out
-}
-
-/**
- * 极简 glob → RegExp（支持 `**` 与 `*`），用于 srcGlobs / styleGlobs。
- *
- * 注意替换顺序：双星号通配（globstar）必须先换成**占位符**，再做单星号替换，
- * 否则刚插入的 `.*` 会被单星号那条规则二次改坏
- * —— 曾因此只匹配到顶层文件、嵌套目录被静默漏扫（自测里有回归用例）。
- */
-const GLOBSTAR_SLASH = '\u0000GS\u0000'
-const GLOBSTAR = '\u0000G\u0000'
-
-export function globToRegExp(glob) {
-  const escaped = glob.replace(/[.+^${}()|[\]\\]/g, '\\$&')
-  const re = escaped
-    .replace(/\*\*\//g, GLOBSTAR_SLASH)
-    .replace(/\*\*/g, GLOBSTAR)
-    .replace(/\*/g, '[^/]*')
-    .replace(new RegExp(GLOBSTAR_SLASH, 'g'), '(?:.*/)?')
-    .replace(new RegExp(GLOBSTAR, 'g'), '.*')
-  return new RegExp(`^${re}$`)
-}
-
-/** `--changed` 用的 git 改动文件集（相对仓根，posix 分隔符）。 */
-export function changedFiles(cwd) {
-  try {
-    const raw = execSync('git diff --name-only HEAD', { cwd, encoding: 'utf8' })
-    return new Set(raw.split('\n').map((s) => s.trim()).filter(Boolean))
-  } catch {
-    return null // 非 git 环境或 git 不可用：不裁剪（宁可多检查）
-  }
-}
-
-/**
- * 剥离注释，但**保留行号**（违规行号必须与源码一致）。
- * 处理 `/* *\/` 与 `//`；引号内的 `//`（如 URL）不会被误判。
- */
-export function stripComments(source) {
-  let out = ''
-  let i = 0
-  const n = source.length
-  let inBlock = false
-  let inLine = false
-  let quote = null
-  while (i < n) {
-    const ch = source[i]
-    const next = source[i + 1]
-    if (inBlock) {
-      if (ch === '*' && next === '/') {
-        out += '  '
-        i += 2
-        inBlock = false
-        continue
-      }
-      out += ch === '\n' ? '\n' : ' '
-      i += 1
-      continue
-    }
-    if (inLine) {
-      if (ch === '\n') {
-        out += '\n'
-        inLine = false
-      } else {
-        out += ' '
-      }
-      i += 1
-      continue
-    }
-    if (quote) {
-      out += ch
-      if (ch === '\\') {
-        out += source[i + 1] ?? ''
-        i += 2
-        continue
-      }
-      if (ch === quote) quote = null
-      i += 1
-      continue
-    }
-    if (ch === '/' && next === '*') {
-      out += '  '
-      i += 2
-      inBlock = true
-      continue
-    }
-    if (ch === '/' && next === '/') {
-      out += '  '
-      i += 2
-      inLine = true
-      continue
-    }
-    if (ch === '"' || ch === "'" || ch === '`') quote = ch
-    out += ch
-    i += 1
-  }
-  return out
-}
-
-/** 相对仓根的展示路径（统一 posix 分隔符）。 */
-export function displayPath(cwd, file) {
-  return relative(cwd, file).split(sep).join('/')
-}
-
-/** correction：唯一改法 + 正确写法 + CONTRACT.md 锚点（大模型据此自我修正）。 */
-export const CORRECTIONS = {
-  'style/tailwind': {
-    summary: '删掉 Tailwind 引入；样式走 app-kit 三行链与 --ui-* 令牌。',
-    example: '@import "@manohub/app-kit/styles.css";',
-    doc: 'CONTRACT.md#1-消费方式',
-  },
-  'style/token': {
-    summary: '不要在应用侧定义 CSS 变量/@theme；需要新令牌请在 app-kit 内加。',
-    example: '给 app-kit 提 issue/PR，在 packages/app-kit/src/styles/tokens.css 增加令牌',
-    doc: 'CONTRACT.md#6-样式纪律',
-  },
-  'style/visual': {
-    summary: '视觉属性一律删除，改由组件承载或使用 --ui-* 令牌。',
-    example: 'background: var(--ui-base-200); →（删除，交给组件/令牌）',
-    doc: 'CONTRACT.md#6-样式纪律',
-  },
-  'style/important': {
-    summary: '删掉 !important；确需覆写底层组件库内部样式时，写进包内 farris-bridge.css。',
-    example: '（app 侧）height: 2rem;   // 去掉 !important',
-    doc: 'CONTRACT.md#6-样式纪律',
-  },
-  'style/bare-element': {
-    summary: '裸元素选择器会污染宿主，改为带应用前缀的类名。',
-    example: '.vm-manage button { … } → .vm-toolbar-action { … }',
-    doc: 'CONTRACT.md#6-样式纪律',
-  },
-  'style/prefix': {
-    summary: '选择器首段必须匹配本应用登记前缀（见配置文件 apps[].prefixes）。',
-    example: '.my-app-header { … }（前缀已在配置中登记）',
-    doc: 'CONTRACT.md#6-样式纪律',
-  },
-  'style/ak-selector': {
-    summary: '删除 .ak-* 选择器：那是 app-kit 的类名，应用侧只能用它的组件。',
-    example: '<AppPanel> 替代对 .ak-panel 的样式覆写',
-    doc: 'CONTRACT.md#6-样式纪律',
-  },
-  'style/rem': {
-    summary: '删掉自写 rem 尺寸：全仓统一 px 令牌，不跟随根字号缩放（见已知偏差）。',
-    example: 'padding: var(--ui-space-2);   // 不要 0.5rem',
-    doc: 'CONTRACT.md#9-已知偏差',
-  },
-  'api/farris-import': {
-    summary: '删掉对底层组件库的直接 import，改用 app-kit 的 App* 件；缺件走建件流程。',
-    example: "import { AppTable } from '@manohub/app-kit'",
-    doc: 'CONTRACT.md#7-缺件处置流程',
-  },
-  'api/old-ui-import': {
-    summary: '禁止引入旧 UI 包；组件与图标分别用 @manohub/app-kit 与 @manohub/icon。',
-    example: "import { Icon } from '@manohub/icon'",
-    doc: 'CONTRACT.md#2-四条铁律',
-  },
-  'api/legacy-prop': {
-    summary: '这是底层组件库的写法；换成 app-kit 的统一 prop 词表。',
-    example: 'options={[{ label, value }]} / modelValue / onChange',
-    doc: 'CONTRACT.md#3-统一-prop-词表',
-  },
-  'structure/no-shell': {
-    summary: '路由级页面必须用 AppShell 承载结构。',
-    example: '<AppShell><AppShell.Header title="…" /><AppShell.Body mode="table">…</AppShell.Body></AppShell>',
-    doc: 'CONTRACT.md#41-三种页面模板',
-  },
-  'structure/header-title': {
-    summary: 'AppShell.Header 必须传 title（或登记为自定义页头白名单）。',
-    example: '<AppShell.Header title={t("page.title")} />',
-    doc: 'CONTRACT.md#41-三种页面模板',
-  },
-  'structure/body-mode': {
-    summary: 'AppShell.Body 必须显式声明 mode。',
-    example: '<AppShell.Body mode="table|scroll|plain">',
-    doc: 'CONTRACT.md#44-两级滚动归属不要混',
-  },
-  'structure/native-control': {
-    summary:
-      '原生控件（含无 href 的锚点）不要用来承载交互/外观：按钮 → AppButton、输入 → AppInput/AppTextarea、下拉 → AppSelect。',
-    example: '<AppButton shape="link" tone="error" onClick={() => remove(row)}>删除</AppButton>',
-    doc: 'CONTRACT.md#7-缺件处置流程',
-  },
-  'structure/viewport-height': {
-    summary: '禁用 100vh / h-screen；高度用 height:100%（子应用被注入宿主容器）。',
-    example: 'height: 100%;',
-    doc: 'CONTRACT.md#41-三种页面模板',
-  },
-  'structure/self-header': {
-    summary: '删掉自绘页头/面板头/表格框：页头→AppShell.Header、面板头→AppPanel、表格框→AppTable framed。',
-    example: '<AppPanel title="业务域"><AppTree … /></AppPanel>',
-    doc: 'CONTRACT.md#43-apppanel区域容器无框',
-  },
-  'structure/toolbar-fields': {
-    summary: '单个面板 toolbar 的字段数不得超过 3；超出请上提为页面级 AppShell.Filter。',
-    example: '<AppShell.Filter>…4 个以上字段…</AppShell.Filter>',
-    doc: 'CONTRACT.md#45-四处操作位唯一化先问过滤谁的数据再问几个字段',
-  },
-  'structure/self-border': {
-    summary: '删掉 Split 栏子元素上的竖直边框：分隔线由 AppShell.Split 统一提供。',
-    example: '（删除 border-right / border-left）',
-    doc: 'CONTRACT.md#42-appshellsplit双栏',
-  },
-  'structure/pagination-scope': {
-    summary:
-      '分页要与承载表格的容器同层：表格在 AppPanel 内 → 分页放 AppPanel.Footer；只有表格直接挂在 AppShell.Body 下才用 AppShell.Footer。',
-    example: '<AppPanel title="列表"><AppTable … /><AppPanel.Footer><AppPagination … /></AppPanel.Footer></AppPanel>',
-    doc: 'CONTRACT.md#43-apppanel区域容器无框',
-  },
-}
-
-export function makeViolation({ app, file, rule, line, severity = 'error', message, snippet }) {
-  return {
-    app,
-    file,
-    rule,
-    line,
-    severity,
-    message,
-    snippet: (snippet ?? '').trim().slice(0, 160),
-    correction: CORRECTIONS[rule] ?? null,
-  }
-}
-
-/**
- * 统一报告：人读格式 + 退出码。
- *
- * `pending` 语义：配置里 `apps[].pending = true` 的应用属**存量挂起** —— 照常报告违规，
- * 但**不计入退出码**（迁移完成后把它置回 false 即自动纳入门禁）；`--strict` 时 pending 也计入。
- * warn 一律不计入退出码（用于"建议上提"这类不可机械判定的项）。
- */
-export function report(title, violations, args, config = null, extra = '') {
-  const pending = new Set(
-    (config?.apps ?? []).filter((a) => a.pending).map((a) => a.name ?? a.dir),
-  )
-  const isPending = (v) => pending.has(v.app)
-  const errors = violations.filter((v) => v.severity === 'error')
-  const warns = violations.filter((v) => v.severity !== 'error')
-  const blocking = args.strict ? errors : errors.filter((v) => !isPending(v))
-  const pendingErrors = errors.length - blocking.length
-
-  if (args.json) {
-    process.stdout.write(JSON.stringify({ audit: title, violations }, null, 2) + '\n')
-  } else {
-    if (violations.length === 0) {
-      process.stdout.write(`✓ ${title}：无违规${extra ? `（${extra}）` : ''}\n`)
-    } else {
-      process.stdout.write(
-        `\n${title}：${errors.length} 个 error / ${warns.length} 个 warn` +
-          (pendingErrors > 0 ? `（其中 ${pendingErrors} 个属存量挂起，不计入退出码）` : '') +
-          '\n',
-      )
-      for (const v of violations) {
-        process.stdout.write(
-          `  [${v.severity}${isPending(v) ? '/pending' : ''}] ${v.file}:${v.line}  ${v.rule}\n` +
-            `      ${v.message}\n` +
-            (v.snippet ? `      > ${v.snippet}\n` : '') +
-            (v.correction
-              ? `      改法：${v.correction.summary}\n      写法：${v.correction.example}\n      出处：${v.correction.doc}\n`
-              : ''),
-        )
-      }
-    }
-    process.stdout.write('\n')
-  }
-  return blocking.length > 0 ? 1 : 0
-}
+/**
+ * 护栏共享基建：配置加载 / 文件遍历 / 注释剥离 / 违规输出与 correction 表。
+ *
+ * 三条护栏脚本（style / component / structure）与 run-all 统一依赖本文件，
+ * 保证「同一份配置 + 同一种输出契约」，消费方只需写一个配置文件。
+ *
+ * 输出契约（大模型自我修正的前提）：
+ *   { app, file, rule, line, severity, message, snippet,
+ *     correction: { summary, example, doc } }
+ */
+import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs'
+import { join, relative, extname, sep } from 'node:path'
+import { execSync } from 'node:child_process'
+
+/** 默认配置（消费方可覆盖）；`apps[].dir` 相对消费仓根（= process.cwd()）。 */
+export const DEFAULT_CONFIG = {
+  apps: [],
+  srcGlobs: ['src/**/*.ts', 'src/**/*.tsx'],
+  styleGlobs: ['src/**/*.css'],
+  exemptionRegistry: null,
+  contractDoc: 'node_modules/@manohub/app-kit/CONTRACT.md',
+  ignore: ['node_modules', 'dist'],
+}
+
+/**
+ * 规则通配匹配：支持精确名（`api/farris-import`）与整类通配（`structure/*`）。
+ *
+ * 只允许「尾部一个 `*`」这一种通配：规则名是 `域/规则` 两段，`*` 只用来表达「整个域」，
+ * 中间含 `*` 的写法（如 `style/*-element`）会让人以为能精确匹配、实际很难推理，不实现。
+ */
+export function matchRule(pattern, rule) {
+  if (typeof pattern !== 'string' || !pattern || typeof rule !== 'string') return false
+  if (pattern === rule) return true
+  if (pattern.endsWith('/*')) return rule.startsWith(`${pattern.slice(0, -1)}`)
+  return false
+}
+
+/** 取某应用登记的豁免规则模式（兼容 `"rule"` 简写与 `{ rule, reason }` 对象两种写法） */
+export function waivedPatternsOf(app) {
+  return (app?.waivedRules ?? [])
+    .map((entry) => (typeof entry === 'string' ? entry : entry?.rule))
+    .filter((rule) => typeof rule === 'string' && rule.length > 0)
+}
+
+export function loadConfig(cwd = process.cwd()) {
+  const path = join(cwd, 'appkit-guardrails.config.json')
+  if (!existsSync(path)) {
+    fail(
+      `未找到护栏配置：${path}\n` +
+        `请在应用包根创建 appkit-guardrails.config.json（结构见 @manohub/app-kit/lint/guardrails.config.schema.json）。`,
+    )
+  }
+  const raw = JSON.parse(readFileSync(path, 'utf8'))
+  const config = { ...DEFAULT_CONFIG, ...raw }
+  if (!Array.isArray(config.apps) || config.apps.length === 0) {
+    fail('配置里的 apps 不能为空（至少要列出被审计的应用目录）。')
+  }
+  // 豁免必须写明理由：豁免是「暂时接受的技术债」，不是开关。
+  // 不写理由的豁免等于给了个静音键，半年后没人知道为什么留着。
+  for (const app of config.apps) {
+    const name = app?.name ?? app?.dir ?? '(未命名应用)'
+    for (const entry of app?.waivedRules ?? []) {
+      const rule = typeof entry === 'string' ? entry : entry?.rule
+      const reason = typeof entry === 'string' ? '' : entry?.reason
+      if (typeof rule !== 'string' || !rule) {
+        fail(`应用 ${name} 的 waivedRules 里有条目缺少 rule（应为 "域/规则" 或 "域/*"）。`)
+      }
+      if (!reason) {
+        fail(
+          `应用 ${name} 的 waivedRules 里 ${rule} 缺少 reason：\n` +
+            `豁免要写清「为什么暂时不查」与「什么时候收口」，形如\n` +
+            `  { "rule": "${rule}", "reason": "只迁骨架（Shell-only），组件替换在下一批次", "since": "2026-09-18" }`,
+        )
+      }
+    }
+  }
+  return config
+}
+
+export function fail(message) {
+  process.stderr.write(`\n[guardrails] ${message}\n\n`)
+  process.exit(2)
+}
+
+/** 简易 CLI 参数解析：--json / --strict / --changed / --app=<name> / --cwd=<path> */
+export function parseArgs(argv = process.argv.slice(2)) {
+  const args = { json: false, strict: false, changed: false, app: null, cwd: process.cwd() }
+  for (const raw of argv) {
+    if (raw === '--json') args.json = true
+    else if (raw === '--strict') args.strict = true
+    else if (raw === '--changed') args.changed = true
+    else if (raw.startsWith('--app=')) args.app = raw.slice('--app='.length)
+    else if (raw.startsWith('--cwd=')) args.cwd = raw.slice('--cwd='.length)
+  }
+  return args
+}
+
+/** 递归收集文件：按扩展名 + 配置的 glob 范围过滤，跳过 ignore 目录与 .d.ts。 */
+export function collectFiles(root, config, extensions, globs = null) {
+  const out = []
+  const ignore = new Set(config.ignore)
+  const matchers = (globs ?? []).map(globToRegExp)
+  const walk = (dir) => {
+    if (!existsSync(dir)) return
+    for (const entry of readdirSync(dir)) {
+      if (ignore.has(entry) || entry.startsWith('.')) continue
+      const full = join(dir, entry)
+      const st = statSync(full)
+      if (st.isDirectory()) {
+        walk(full)
+      } else if (extensions.includes(extname(entry)) && !entry.endsWith('.d.ts')) {
+        if (matchers.length > 0) {
+          const rel = relative(root, full).split(sep).join('/')
+          if (!matchers.some((m) => m.test(rel))) continue
+        }
+        out.push(full)
+      }
+    }
+  }
+  walk(root)
+  return out
+}
+
+/**
+ * 极简 glob → RegExp（支持 `**` 与 `*`），用于 srcGlobs / styleGlobs。
+ *
+ * 注意替换顺序：双星号通配（globstar）必须先换成**占位符**，再做单星号替换，
+ * 否则刚插入的 `.*` 会被单星号那条规则二次改坏
+ * —— 曾因此只匹配到顶层文件、嵌套目录被静默漏扫（自测里有回归用例）。
+ */
+const GLOBSTAR_SLASH = '\u0000GS\u0000'
+const GLOBSTAR = '\u0000G\u0000'
+
+export function globToRegExp(glob) {
+  const escaped = glob.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+  const re = escaped
+    .replace(/\*\*\//g, GLOBSTAR_SLASH)
+    .replace(/\*\*/g, GLOBSTAR)
+    .replace(/\*/g, '[^/]*')
+    .replace(new RegExp(GLOBSTAR_SLASH, 'g'), '(?:.*/)?')
+    .replace(new RegExp(GLOBSTAR, 'g'), '.*')
+  return new RegExp(`^${re}$`)
+}
+
+/**
+ * `--changed` 用的 git 改动文件集（相对仓根，posix 分隔符）。
+ *
+ * **必须是两半之和**：
+ * 1. `git diff --name-only HEAD` —— 已跟踪文件的改动（含已暂存）；
+ * 2. `git ls-files --others --exclude-standard` —— **未加入索引的新增文件**。
+ *
+ * 少了第 2 半会出「假绿」：新写一个页面（还没 `git add`）时，`--changed` 根本看不到它，
+ * 于是「新增文件必须归零」的自检输出全绿 —— 而新增文件恰恰是最该查的一类。
+ */
+export function changedFiles(cwd) {
+  // `stdio` 显式关掉 stderr 透传：execSync 默认会把子进程 stderr 直接打到终端，
+  // 于是非 git 目录下跑 `--changed` 会甩出一整屏 git 用法说明（那是正常的「不裁剪」分支，不是错误）。
+  const opts = { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }
+  let tracked
+  try {
+    tracked = execSync('git diff --name-only HEAD', opts)
+  } catch {
+    return null // 非 git 环境或 git 不可用：不裁剪（宁可多检查）
+  }
+  let untracked = ''
+  try {
+    untracked = execSync('git ls-files --others --exclude-standard', opts)
+  } catch {
+    untracked = '' // 取不到新增列表时退回「只看已跟踪改动」，不因次要命令失败而整条放弃
+  }
+  return new Set(
+    `${tracked}\n${untracked}`
+      .split('\n')
+      .map((s) => s.trim())
+      .filter(Boolean),
+  )
+}
+
+/**
+ * 剥离注释，但**保留行号**（违规行号必须与源码一致）。
+ * 处理 `/* *\/` 与 `//`；引号内的 `//`（如 URL）不会被误判。
+ */
+export function stripComments(source) {
+  let out = ''
+  let i = 0
+  const n = source.length
+  let inBlock = false
+  let inLine = false
+  let quote = null
+  while (i < n) {
+    const ch = source[i]
+    const next = source[i + 1]
+    if (inBlock) {
+      if (ch === '*' && next === '/') {
+        out += '  '
+        i += 2
+        inBlock = false
+        continue
+      }
+      out += ch === '\n' ? '\n' : ' '
+      i += 1
+      continue
+    }
+    if (inLine) {
+      if (ch === '\n') {
+        out += '\n'
+        inLine = false
+      } else {
+        out += ' '
+      }
+      i += 1
+      continue
+    }
+    if (quote) {
+      out += ch
+      if (ch === '\\') {
+        out += source[i + 1] ?? ''
+        i += 2
+        continue
+      }
+      if (ch === quote) quote = null
+      i += 1
+      continue
+    }
+    if (ch === '/' && next === '*') {
+      out += '  '
+      i += 2
+      inBlock = true
+      continue
+    }
+    if (ch === '/' && next === '/') {
+      out += '  '
+      i += 2
+      inLine = true
+      continue
+    }
+    if (ch === '"' || ch === "'" || ch === '`') quote = ch
+    out += ch
+    i += 1
+  }
+  return out
+}
+
+/** 相对仓根的展示路径（统一 posix 分隔符）。 */
+export function displayPath(cwd, file) {
+  return relative(cwd, file).split(sep).join('/')
+}
+
+/** correction：唯一改法 + 正确写法 + CONTRACT.md 锚点（大模型据此自我修正）。 */
+export const CORRECTIONS = {
+  'style/tailwind': {
+    summary: '删掉 Tailwind 引入；样式走 app-kit 三行链与 --ui-* 令牌。',
+    example: '@import "@manohub/app-kit/styles.css";',
+    doc: 'CONTRACT.md#1-消费方式',
+  },
+  'style/token': {
+    summary: '不要在应用侧定义 CSS 变量/@theme；需要新令牌请在 app-kit 内加。',
+    example: '给 app-kit 提 issue/PR，在 packages/app-kit/src/styles/tokens.css 增加令牌',
+    doc: 'CONTRACT.md#6-样式纪律',
+  },
+  'style/visual': {
+    summary: '视觉属性一律删除，改由组件承载或使用 --ui-* 令牌。',
+    example: 'background: var(--ui-base-200); →（删除，交给组件/令牌）',
+    doc: 'CONTRACT.md#6-样式纪律',
+  },
+  'style/important': {
+    summary: '删掉 !important；确需覆写底层组件库内部样式时，写进包内 farris-bridge.css。',
+    example: '（app 侧）height: 2rem;   // 去掉 !important',
+    doc: 'CONTRACT.md#6-样式纪律',
+  },
+  'style/bare-element': {
+    summary: '裸元素选择器会污染宿主，改为带应用前缀的类名。',
+    example: '.vm-manage button { … } → .vm-toolbar-action { … }',
+    doc: 'CONTRACT.md#6-样式纪律',
+  },
+  'style/prefix': {
+    summary: '选择器首段必须匹配本应用登记前缀（见配置文件 apps[].prefixes）。',
+    example: '.my-app-header { … }（前缀已在配置中登记）',
+    doc: 'CONTRACT.md#6-样式纪律',
+  },
+  'style/ak-selector': {
+    summary: '删除 .ak-* 选择器：那是 app-kit 的类名，应用侧只能用它的组件。',
+    example: '<AppPanel> 替代对 .ak-panel 的样式覆写',
+    doc: 'CONTRACT.md#6-样式纪律',
+  },
+  'style/rem': {
+    summary: '删掉自写 rem 尺寸：全仓统一 px 令牌，不跟随根字号缩放（见已知偏差）。',
+    example: 'padding: var(--ui-space-2);   // 不要 0.5rem',
+    doc: 'CONTRACT.md#9-已知偏差',
+  },
+  'api/farris-import': {
+    summary: '删掉对底层组件库的直接 import，改用 app-kit 的 App* 件；缺件走建件流程。',
+    example: "import { AppTable } from '@manohub/app-kit'",
+    doc: 'CONTRACT.md#7-缺件处置流程',
+  },
+  'api/old-ui-import': {
+    summary: '禁止引入旧 UI 包；组件与图标分别用 @manohub/app-kit 与 @manohub/icon。',
+    example: "import { Icon } from '@manohub/icon'",
+    doc: 'CONTRACT.md#2-四条铁律',
+  },
+  'api/legacy-prop': {
+    summary: '这是底层组件库的写法；换成 app-kit 的统一 prop 词表。',
+    example: 'options={[{ label, value }]} / modelValue / onChange',
+    doc: 'CONTRACT.md#3-统一-prop-词表',
+  },
+  'structure/no-shell': {
+    summary: '路由级页面必须用 AppShell 承载结构。',
+    example: '<AppShell><AppShell.Header title="…" /><AppShell.Body mode="table">…</AppShell.Body></AppShell>',
+    doc: 'CONTRACT.md#41-三种页面模板',
+  },
+  'structure/header-title': {
+    summary: 'AppShell.Header 必须传 title（或登记为自定义页头白名单）。',
+    example: '<AppShell.Header title={t("page.title")} />',
+    doc: 'CONTRACT.md#41-三种页面模板',
+  },
+  'structure/body-mode': {
+    summary: 'AppShell.Body 必须显式声明 mode。',
+    example: '<AppShell.Body mode="table|scroll|plain">',
+    doc: 'CONTRACT.md#44-两级滚动归属不要混',
+  },
+  'structure/native-control': {
+    summary:
+      '原生控件（含无 href 的锚点）不要用来承载交互/外观：按钮 → AppButton、输入 → AppInput/AppTextarea、下拉 → AppSelect。',
+    example: '<AppButton shape="link" tone="error" onClick={() => remove(row)}>删除</AppButton>',
+    doc: 'CONTRACT.md#7-缺件处置流程',
+  },
+  'structure/viewport-height': {
+    summary: '禁用 100vh / h-screen；高度用 height:100%（子应用被注入宿主容器）。',
+    example: 'height: 100%;',
+    doc: 'CONTRACT.md#41-三种页面模板',
+  },
+  'structure/self-header': {
+    summary: '删掉自绘页头/面板头/表格框：页头→AppShell.Header、面板头→AppPanel、表格框→AppTable framed。',
+    example: '<AppPanel title="业务域"><AppTree … /></AppPanel>',
+    doc: 'CONTRACT.md#43-apppanel区域容器无框',
+  },
+  'structure/toolbar-fields': {
+    summary: '单个面板 toolbar 的字段数不得超过 3；超出请上提为页面级 AppShell.Filter。',
+    example: '<AppShell.Filter>…4 个以上字段…</AppShell.Filter>',
+    doc: 'CONTRACT.md#45-四处操作位唯一化先问过滤谁的数据再问几个字段',
+  },
+  'structure/self-border': {
+    summary: '删掉 Split 栏子元素上的竖直边框：分隔线由 AppShell.Split 统一提供。',
+    example: '（删除 border-right / border-left）',
+    doc: 'CONTRACT.md#42-appshellsplit双栏',
+  },
+  'structure/pagination-scope': {
+    summary:
+      '分页要与承载表格的容器同层：表格在 AppPanel 内 → 分页放 AppPanel.Footer；只有表格直接挂在 AppShell.Body 下才用 AppShell.Footer。',
+    example: '<AppPanel title="列表"><AppTable … /><AppPanel.Footer><AppPagination … /></AppPanel.Footer></AppPanel>',
+    doc: 'CONTRACT.md#43-apppanel区域容器无框',
+  },
+}
+
+export function makeViolation({ app, file, rule, line, severity = 'error', message, snippet }) {
+  return {
+    app,
+    file,
+    rule,
+    line,
+    severity,
+    message,
+    snippet: (snippet ?? '').trim().slice(0, 160),
+    correction: CORRECTIONS[rule] ?? null,
+  }
+}
+
+/**
+ * 统一报告：人读格式 + 退出码。
+ *
+ * 两级「暂不拦断」的机制，都**照常报告、只是不计入退出码**（技术债必须可见）：
+ *
+ * - `pending`（应用级）：`apps[].pending = true` —— 整个应用挂起，用于存量应用刚接入时产基线。
+ * - `waivedRules`（规则级）：`apps[].waivedRules` 里登记的规则（支持 `structure/*`）——
+ *   用于**分阶段迁移**，典型是「只迁骨架（Shell-only）」：结构类规则即刻纳入门禁，
+ *   组件直连与样式类登记豁免、下一批次再收。
+ *
+ * 两者在 `--strict` 时**一律失效**：收口验收就是跑一次 `--strict`，确认「不再有任何东西被挡着」。
+ * warn 一律不计入退出码（用于"建议上提"这类不可机械判定的项）。
+ *
+ * 另：豁免当前 0 条命中时会提示可撤销 —— 豁免只该在"还没迁到那一层"期间存在，
+ * 迁完就撤，否则它会静默地一直关着门。
+ */
+export function report(title, violations, args, config = null, extra = '') {
+  const apps = config?.apps ?? []
+  const pending = new Set(apps.filter((a) => a.pending).map((a) => a.name ?? a.dir))
+  const isPending = (v) => pending.has(v.app)
+
+  // 规则级豁免（分阶段迁移用）：`--strict` 时一律失效 —— 收口验收就靠它。
+  const waivers = new Map(apps.map((a) => [a.name ?? a.dir, waivedPatternsOf(a)]))
+  const hitsByPattern = new Map()
+  const isWaived = (v) => {
+    if (args.strict) return false
+    for (const pattern of waivers.get(v.app) ?? []) {
+      if (matchRule(pattern, v.rule)) {
+        hitsByPattern.set(`${v.app}\u0000${pattern}`, (hitsByPattern.get(`${v.app}\u0000${pattern}`) ?? 0) + 1)
+        return true
+      }
+    }
+    return false
+  }
+
+  const rawErrors = violations.filter((v) => v.severity === 'error')
+  const waived = new Set(rawErrors.filter(isWaived))
+  const errors = rawErrors.filter((v) => !waived.has(v))
+  const warns = violations.filter((v) => v.severity !== 'error')
+  const blocking = args.strict ? errors : errors.filter((v) => !isPending(v))
+  const pendingErrors = errors.length - blocking.length
+
+  /** 豁免里「当前 0 条命中」的项：迁移往前走了，这些豁免该撤销了 */
+  const staleWaivers = []
+  for (const app of apps) {
+    if (args.app && app.name !== args.app && app.dir !== args.app) continue
+    for (const pattern of waivedPatternsOf(app)) {
+      if (!hitsByPattern.has(`${app.name ?? app.dir}\u0000${pattern}`)) {
+        staleWaivers.push(`${app.name ?? app.dir} 的 ${pattern}`)
+      }
+    }
+  }
+
+  if (args.json) {
+    const payload = violations.map((v) => (waived.has(v) ? { ...v, waived: true } : v))
+    process.stdout.write(JSON.stringify({ audit: title, violations: payload }, null, 2) + '\n')
+    return blocking.length > 0 ? 1 : 0
+  }
+
+  if (violations.length === 0) {
+    process.stdout.write(`✓ ${title}：无违规${extra ? `（${extra}）` : ''}\n`)
+  } else {
+    const notes = []
+    if (pendingErrors > 0) notes.push(`${pendingErrors} 个属存量挂起`)
+    if (waived.size > 0) notes.push(`${waived.size} 条属已登记豁免`)
+    process.stdout.write(
+      `\n${title}：${errors.length} 个 error / ${warns.length} 个 warn` +
+        (notes.length > 0 ? `（其中 ${notes.join('、')}，不计入退出码）` : '') +
+        '\n',
+    )
+    for (const v of violations) {
+      const labels = [v.severity]
+      if (isPending(v)) labels.push('pending')
+      if (waived.has(v)) labels.push('waived')
+      process.stdout.write(
+        `  [${labels.join('/')}] ${v.file}:${v.line}  ${v.rule}\n` +
+          `      ${v.message}\n` +
+          (v.snippet ? `      > ${v.snippet}\n` : '') +
+          (waived.has(v) ? `      豁免：已登记（不参与门禁；用 --strict 可验证「收口后会怎样」）\n` : '') +
+          (v.correction
+            ? `      改法：${v.correction.summary}\n      写法：${v.correction.example}\n      出处：${v.correction.doc}\n`
+            : ''),
+      )
+    }
+  }
+  if (staleWaivers.length > 0) {
+    process.stdout.write(
+      `  提示：以下豁免当前 0 条命中，可以撤销了（撤销后该规则即刻纳入门禁）：\n` +
+        staleWaivers.map((item) => `        - ${item}`).join('\n') +
+        '\n',
+    )
+  }
+  process.stdout.write('\n')
+  return blocking.length > 0 ? 1 : 0
+}