@manohub/app-kit 0.1.0

package/lint/component-audit.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+/**
+ * component-audit —— 组件使用护栏。
+ *
+ * 规则：
+ *   api/farris-import  禁 `from '@farris/ui-vue'`（底层组件库必须被收在 app-kit 内）
+ *   api/old-ui-import  禁 `from '@manohub/ui'`（Tailwind + reka 栈，与本仓样式纪律冲突）
+ *   api/tailwind       禁 Tailwind 相关 import
+ *   api/legacy-prop    禁底层组件库风格 prop / 写法（按**键名**判定）
+ *
+ * 口径（CONTRACT.md §3）：
+ *   - 判定依据是「这个键属于谁」，不是「长得像不像对象」：
+ *     `selection={{…}}` 是 app-kit 自己的结构化契约，**合法**；
+ *     而 `rowOption` / `columnOption` / `enableSelectRow` / `enabelSelectRow` 等属于底层，一律禁止。
+ *
+ * 用法：node node_modules/@manohub/app-kit/lint/component-audit.mjs [--json] [--changed]
+ */
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import {
+  loadConfig,
+  parseArgs,
+  collectFiles,
+  changedFiles,
+  stripComments,
+  displayPath,
+  makeViolation,
+  report,
+} from './shared.mjs'
+
+const args = parseArgs()
+const cwd = args.cwd
+const config = loadConfig(cwd)
+const changed = args.changed ? changedFiles(cwd) : null
+
+/** 禁止的 import 源（子串匹配）。 */
+const BANNED_IMPORTS = [
+  { pattern: /from\s+['"]@farris\/ui-vue['"]/, rule: 'api/farris-import', message: '禁止直接 import 底层组件库（@farris/ui-vue）' },
+  { pattern: /from\s+['"]@manohub\/ui['"]/, rule: 'api/old-ui-import', message: '禁止 import 旧 UI 包（@manohub/ui）' },
+  { pattern: /from\s+['"](?:tailwindcss|@tailwindcss\/[^'"]+)['"]/, rule: 'api/tailwind', message: '禁止 Tailwind 相关 import' },
+  // 样式/hook 层面：@gsp-sys 的 request 属另一体系，但本仓值映射已自建客户端，禁止回退
+  { pattern: /from\s+['"]@farris\/ui-vue\/[^'"]+['"]/, rule: 'api/farris-import', message: '禁止 import 底层组件库子路径' },
+]
+
+/** 底层风格 prop / 写法黑名单（正则片段，按**键名/属性名**匹配）。 */
+const LEGACY_PROPS = [
+  'valueField',
+  'textField',
+  'idField',
+  'enumValueType',
+  'columnTemplate',
+  'headerFormatter',
+  'emptyTemplate',
+  'rowOption',
+  'columnOption',
+  'treeNodeIconsData',
+  'updateDataSource',
+  'updateColumns',
+  'fitColumns',
+  'fitMode',
+  'multiSelectMode',
+  'keepSelectingOnPaging',
+  'searchPlaceHolder',
+  'showCheckbox',
+  'showSelectAll',
+  'enableSelectRow',
+  'enabelSelectRow',
+  'customClass',
+  'customStyle',
+  'iconClass',
+  'showBorder',
+  'showStripe',
+  'onDoubleClickRow',
+  'onClickRow',
+  'showCloseButton',
+]
+
+const LEGACY_PROP_RE = new RegExp(
+  `(?:^|[\\s{,(])(${LEGACY_PROPS.map((p) => p.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')})\\s*(?:=|:|\\s*\\?\\s*:)`,
+)
+const ROW_RAW_RE = /\brow\.raw\b|\bvisualDataRow\b/
+
+function violation(app, file, rule, line, message, snippet, severity = 'error') {
+  return makeViolation({ app, file: displayPath(cwd, file), rule, line, severity, message, snippet })
+}
+
+const violations = []
+for (const app of config.apps) {
+  if (args.app && app.name !== args.app && app.dir !== args.app) continue
+  const root = join(cwd, app.dir)
+  // `.vue` 必须一起扫：SFC 里直连底层组件库、用底层风格 prop 同样违规
+  // （vm 子应用的演示页 `views/form.vue` 曾因此漏网：模板里 `<f-input-group>` + farris import 都没被报出来）
+  for (const file of collectFiles(root, config, ['.ts', '.tsx', '.vue'], config.srcGlobs)) {
+    if (changed) {
+      const rel = displayPath(cwd, file)
+      if (![...changed].some((c) => c === rel || c.endsWith(rel))) continue
+    }
+    const source = stripComments(readFileSync(file, 'utf8'))
+    const lines = source.split('\n')
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i]
+      const lineNo = i + 1
+      for (const banned of BANNED_IMPORTS) {
+        if (banned.pattern.test(line)) {
+          violations.push(violation(app.name, file, banned.rule, lineNo, banned.message, line))
+        }
+      }
+      // 逐行找遗留 prop（跳过 `.d.ts` 已在 collectFiles 过滤）
+      const match = LEGACY_PROP_RE.exec(line)
+      if (match) {
+        violations.push(
+          violation(
+            app.name,
+            file,
+            'api/legacy-prop',
+            lineNo,
+            `禁止底层风格 prop \`${match[1]}\`（换成 app-kit 统一词表）`,
+            line,
+          ),
+        )
+      }
+      if (ROW_RAW_RE.test(line)) {
+        violations.push(
+          violation(app.name, file, 'api/legacy-prop', lineNo, '禁止解包底层包装对象（row.raw 由组件内部消化）', line),
+        )
+      }
+    }
+  }
+}
+
+process.exit(report('component-audit（组件使用护栏）', violations, args, config))

package/lint/guardrails.config.schema.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "appkit-guardrails.config.json",
+  "description": "护栏配置：放在**应用包根**（即 `pnpm lint` 的 cwd），由 @manohub/app-kit/lint/*.mjs 读取。所有路径相对该目录。",
+  "type": "object",
+  "required": ["apps"],
+  "properties": {
+    "apps": {
+      "description": "被审计的应用列表。单应用仓写一条即可（dir 用 \".\"）。",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["dir"],
+        "properties": {
+          "dir": {
+            "type": "string",
+            "description": "应用目录，相对应用包根。"
+          },
+          "name": {
+            "type": "string",
+            "description": "报告里显示的应用名；缺省用 dir。"
+          },
+          "prefixes": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "该应用登记的选择器前缀（样式护栏规则 9）。`.app-container` 恒为允许项，不必登记。"
+          },
+          "pending": {
+            "type": "boolean",
+            "default": false,
+            "description": "存量挂起：为 true 时该应用仅产出基线报告，不计入退出码（迁移完成后置 false 即自动纳入门禁）。"
+          }
+        }
+      }
+    },
+    "srcGlobs": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "源码扫描范围（相对每个 app.dir）。默认 [\"src/**/*.ts\", \"src/**/*.tsx\"]。"
+    },
+    "styleGlobs": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "样式扫描范围。默认 [\"src/**/*.css\"]。"
+    },
+    "exemptionRegistry": {
+      "type": ["string", "null"],
+      "description": "设计还原豁免注册表（Markdown 表格）。文件头带 @figma-fidelity 且登记于此的文件，跳过视觉属性/裸元素/选择器前缀三类检查；!important 与自写 rem 仍然禁止。"
+    },
+    "contractDoc": {
+      "type": "string",
+      "description": "correction.doc 的锚点基址（指向 CONTRACT.md）。默认 node_modules/@manohub/app-kit/CONTRACT.md。"
+    },
+    "ignore": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "扫描时跳过的目录名。默认 [\"node_modules\", \"dist\"]。"
+    }
+  },
+  "additionalProperties": false,
+  "examples": [
+    {
+      "apps": [
+        { "dir": ".", "name": "sub-app", "prefixes": ["vm-", "app-container"], "pending": false }
+      ],
+      "srcGlobs": ["src/**/*.ts", "src/**/*.tsx"],
+      "styleGlobs": ["src/**/*.css"],
+      "exemptionRegistry": "docs/appkit-exemptions.md",
+      "contractDoc": "node_modules/@manohub/app-kit/CONTRACT.md",
+      "ignore": ["node_modules", "dist"]
+    }
+  ]
+}

package/lint/pre-commit.sample

@@ -0,0 +1,26 @@
+#!/bin/sh
+# app-kit 护栏 pre-commit 钩子样本：只检查**已改动文件**，目标 < 3 秒（否则人会在本机把它关掉）。
+#
+# 启用（不需要改 git 配置，默认 hooks 目录即可）：
+#   cp node_modules/@manohub/app-kit/lint/pre-commit.sample .git/hooks/pre-commit
+#   chmod +x .git/hooks/pre-commit
+#
+# 应用包不是仓库根时（monorepo，如 apps/sub-app），用环境变量指出包目录：
+#   APPKIT_APP_DIR=apps/sub-app   （可在 .git/hooks/pre-commit 里写死，或提交前 export）
+#
+# 说明：护栏以「应用包根」为 cwd 读取 appkit-guardrails.config.json；仓库根不存在该配置时
+# 必须给 APPKIT_APP_DIR，否则会以「未找到配置」失败（这是刻意为之：宁可报错，也不要静默跳过检查）。
+set -e
+
+AUDIT="node_modules/@manohub/app-kit/lint/run-all.mjs"
+
+if [ ! -f "$AUDIT" ]; then
+  echo "[guardrails] 未安装 @manohub/app-kit（找不到 $AUDIT），跳过检查"
+  exit 0
+fi
+
+if [ -n "$APPKIT_APP_DIR" ]; then
+  exec node "$AUDIT" --changed --cwd="$APPKIT_APP_DIR"
+fi
+
+exec node "$AUDIT" --changed

package/lint/run-all.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * run-all —— 三条护栏的统一入口（接入方只挂这一条，见 CONTRACT.md §8）。
+ *
+ * 并发跑 style / component / structure，汇总输出与退出码；支持 `--changed`（只跑改动文件，供 pre-commit）。
+ * 任一脚本报 error 即整体失败；`--json` 时输出聚合结果。
+ *
+ * 用法（接入方的 `package.json` 只挂前两条，另两条是排查单条时才用的）：
+ *   node node_modules/@manohub/app-kit/lint/run-all.mjs            # 全量（挂成 "lint"）
+ *   node node_modules/@manohub/app-kit/lint/run-all.mjs --changed   # 只跑改动文件（挂成 "lint:changed"）
+ *   node node_modules/@manohub/app-kit/lint/style-audit.mjs         # 单条排查：style / component / structure
+ *   node node_modules/@manohub/app-kit/lint/run-all.mjs --json
+ */
+import { spawn } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+import { parseArgs } from './shared.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const AUDITS = ['style-audit.mjs', 'component-audit.mjs', 'structure-audit.mjs']
+
+const args = parseArgs()
+const passthrough = process.argv.slice(2).filter((a) => a.startsWith('--app=') || a.startsWith('--cwd='))
+if (args.changed) passthrough.push('--changed')
+if (args.json) passthrough.push('--json')
+
+const runOne = (script) =>
+  new Promise((resolve) => {
+    const child = spawn(process.execPath, [join(HERE, script), ...passthrough], {
+      cwd: args.cwd,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    let stdout = ''
+    let stderr = ''
+    child.stdout.on('data', (d) => (stdout += d))
+    child.stderr.on('data', (d) => (stderr += d))
+    child.on('close', (code) => resolve({ script, code, stdout, stderr }))
+  })
+
+const started = Date.now()
+const results = await Promise.all(AUDITS.map(runOne))
+const elapsed = ((Date.now() - started) / 1000).toFixed(2)
+
+if (args.json) {
+  process.stdout.write(JSON.stringify({ audits: results.map((r) => ({ script: r.script, code: r.code })), elapsed }, null, 2) + '\n')
+} else {
+  for (const r of results) {
+    if (r.stdout) process.stdout.write(r.stdout)
+    if (r.stderr) process.stderr.write(r.stderr)
+  }
+  const failed = results.filter((r) => r.code !== 0)
+  process.stdout.write(
+    failed.length === 0
+      ? `✓ 护栏（三条）：全绿（${elapsed}s）\n`
+      : `✗ 护栏（三条）：${failed.map((f) => f.script).join(' / ')} 未通过（${elapsed}s）\n`,
+  )
+}
+
+process.exit(results.some((r) => r.code !== 0) ? 1 : 0)

package/lint/shared.mjs

@@ -0,0 +1,347 @@
+/**
+ * 护栏共享基建：配置加载 / 文件遍历 / 注释剥离 / 违规输出与 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
+}