@manohub/app-kit 0.1.0

package/lint/structure-audit.mjs

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+/**
+ * structure-audit —— 页面结构护栏（S1–S7 + 自绘竖直边框检查）。
+ *
+ *   S1 路由级页面必须用 AppShell
+ *   S2 AppShell.Header 必须传 title（或登记为自定义页头白名单）
+ *   S3 AppShell.Body 必须显式声明 mode
+ *   S4 禁原生 button/input/select/textarea 带 class 承载外观
+ *   S5 禁 h-screen / 100vh
+ *   S6 禁自绘页头与面板头类名（*titlebar* / *page-header* / *panel-head* / *nav-head*）
+ *   S7 面板 toolbar 表单控件 >3 → warn（建议上提 AppShell.Filter）；AppShell.Filter 与面板 toolbar 同时放字段 → warn
+ *   S8 用了 AppShell.Split 的应用，其 CSS 不应再出现竖直边框（分隔线由 Split 提供）→ warn
+ *   S9 分页与承载表格的容器错位（文件里有 AppPanel 却把 AppPagination 放 AppShell.Footer）→ warn
+ *
+ * 用法：node node_modules/@manohub/app-kit/lint/structure-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
+
+/** 路由级页面的判定：位于 views/pages 目录下的 tsx（弹窗组件在 components 下，不受 S1 约束）。 */
+const ROUTE_PAGE_RE = /(?:^|\/)(?:views|pages)\//
+/** 表单控件（S7 计数用）。 */
+const FORM_CONTROLS = /<(AppInput|AppSearchBox|AppSelect|AppDatePicker|AppTextarea|AppNumber)\b/g
+/** 自绘页头/面板头类名（S6）。 */
+const SELF_HEADER_RE = /(?:titlebar|title-bar|page-header|page-title|panel-head|panel-title|nav-head|nav-caption|grid-card|grid-wrap)/i
+/**
+ * 原生控件带 class（S4）。
+ *
+ * 含**无 `href` 的锚点**：`<a class=… onClick=…>` 是「按钮的伪装」（本仓踩过：行内操作 4 处、
+ * 移除列 3 处都靠它逃过检查）。带 `href` 的锚点是真链接（导航语义），不在本条范围内。
+ */
+const NATIVE_CONTROL_RE = /<(button|input|select|textarea)\b[^>]*\bclass\s*=|<a\b(?![^>]*\bhref\b)[^>]*\bclass\s*=/
+
+function violation(app, file, rule, line, message, snippet, severity = 'error') {
+  return makeViolation({ app, file: displayPath(cwd, file), rule, line, severity, message, snippet })
+}
+
+/** 取 `name={<...>}` / `name={render()}` 的整段文本（括号配平），用于计数面板 toolbar 里的控件。 */
+function extractAttrBlock(source, index, attrName) {
+  const at = source.indexOf(`${attrName}=`, index)
+  if (at < 0) return ''
+  let i = source.indexOf('{', at)
+  if (i < 0) return ''
+  let depth = 0
+  const start = i
+  for (; i < source.length; i++) {
+    if (source[i] === '{') depth += 1
+    else if (source[i] === '}') {
+      depth -= 1
+      if (depth === 0) return source.slice(start, i + 1)
+    }
+  }
+  return source.slice(start)
+}
+
+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)
+  const srcFiles = collectFiles(root, config, ['.ts', '.tsx'], config.srcGlobs)
+  let usesSplit = false
+  for (const file of srcFiles) {
+    if (changed) {
+      const rel = displayPath(cwd, file)
+      if (![...changed].some((c) => c === rel || c.endsWith(rel))) continue
+    }
+    const source = stripComments(readFileSync(file, 'utf8'))
+    const rel = displayPath(cwd, file)
+    const lines = source.split('\n')
+    const hasShell = /<AppShell\b/.test(source)
+    if (/<AppShell\.Split\b/.test(source)) usesSplit = true
+
+    // S1：路由级页面必须用 AppShell
+    if (ROUTE_PAGE_RE.test(rel) && file.endsWith('.tsx') && !hasShell) {
+      violations.push(violation(app.name, file, 'structure/no-shell', 1, '路由级页面必须使用 AppShell 承载结构', rel))
+    }
+    // S2 / S3
+    if (hasShell) {
+      const headerIdx = source.indexOf('<AppShell.Header')
+      if (headerIdx >= 0 && !/<AppShell\.Header[^>]*\btitle\s*=/.test(source)) {
+        violations.push(
+          violation(
+            app.name,
+            file,
+            'structure/header-title',
+            source.slice(0, headerIdx).split('\n').length,
+            'AppShell.Header 未传 title',
+            '<AppShell.Header',
+          ),
+        )
+      }
+      const bodyIdx = source.indexOf('<AppShell.Body')
+      if (bodyIdx >= 0 && !/<AppShell\.Body[^>]*\bmode\s*=/.test(source)) {
+        violations.push(
+          violation(
+            app.name,
+            file,
+            'structure/body-mode',
+            source.slice(0, bodyIdx).split('\n').length,
+            'AppShell.Body 未显式声明 mode',
+            '<AppShell.Body',
+          ),
+        )
+      }
+    }
+
+    // S7：面板 toolbar 字段数
+    let panelToolbarTotal = 0
+    let searchFrom = 0
+    while (true) {
+      const at = source.indexOf('<AppPanel', searchFrom)
+      if (at < 0) break
+      const block = extractAttrBlock(source, at, 'toolbar')
+      const count = (block.match(FORM_CONTROLS) ?? []).length
+      panelToolbarTotal += count
+      if (count > 3) {
+        violations.push(
+          violation(
+            app.name,
+            file,
+            'structure/toolbar-fields',
+            source.slice(0, at).split('\n').length,
+            `面板 toolbar 内表单控件 ${count} 个（上限 3）`,
+            block.slice(0, 120),
+            'warn',
+          ),
+        )
+      }
+      searchFrom = at + 10
+    }
+    if (panelToolbarTotal > 0 && /<AppShell\.Filter\b/.test(source)) {
+      violations.push(
+        violation(
+          app.name,
+          file,
+          'structure/toolbar-fields',
+          1,
+          '页面级 AppShell.Filter 与面板 toolbar 同时放了字段，请核对是否重复筛选',
+          rel,
+          'warn',
+        ),
+      )
+    }
+
+    // S4：原生控件带 class（含无 href 的锚点）
+    //
+    // **按整段源码扫，不逐行扫**：把 `<input` 与其 `class=` 拆成两行是常见排版
+    // （属性多时几乎必然如此），逐行正则会静默漏掉整条规则
+    // —— 本仓踩过：列编辑表格的 `<input`↵`class="vm-cell-input"` 一直没被报出来。
+    for (const match of source.matchAll(new RegExp(NATIVE_CONTROL_RE.source, 'g'))) {
+      const lineNo = source.slice(0, match.index).split('\n').length
+      violations.push(
+        violation(
+          app.name,
+          file,
+          'structure/native-control',
+          lineNo,
+          '不得用原生控件（含无 href 的锚点）承载外观/交互，控件一律用组件',
+          lines[lineNo - 1],
+        ),
+      )
+    }
+
+    // S5 / S6
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i]
+      const lineNo = i + 1
+      if (/h-screen|100vh/.test(line)) {
+        violations.push(violation(app.name, file, 'structure/viewport-height', lineNo, '禁用 h-screen / 100vh', line))
+      }
+      const cls = /(?:class|className)\s*=\s*["'`]([^"'`]*)["'`]/.exec(line)
+      if (cls && SELF_HEADER_RE.test(cls[1])) {
+        violations.push(
+          violation(
+            app.name,
+            file,
+            'structure/self-header',
+            lineNo,
+            `疑似自绘页头/面板头/表格框类名：${cls[1].trim()}（页头用 AppShell.Header、面板头用 AppPanel、表格框用 AppTable framed）`,
+            line,
+          ),
+        )
+      }
+    }
+
+    // S9：分页与承载表格的容器错位
+    // 文件里既有 AppPanel（说明存在区域级容器）又在 AppShell.Footer 里放 AppPagination
+    // → 提示核对：表格若在面板内，分页应放 AppPanel.Footer（表格与分页必须同容器）
+    if (/<AppPanel[\s>]/.test(source) && source.includes('AppShell.Footer')) {
+      let insideShellFooter = false
+      for (let i = 0; i < lines.length; i++) {
+        if (/<AppShell\.Footer/.test(lines[i])) insideShellFooter = true
+        if (insideShellFooter && /\bAppPagination\b/.test(lines[i])) {
+          violations.push(
+            violation(
+              app.name,
+              file,
+              'structure/pagination-scope',
+              i + 1,
+              '分页应与承载表格的容器同层：表格在 AppPanel 内时分页放 AppPanel.Footer，不要把区域列表的分页提到页面级 AppShell.Footer',
+              lines[i],
+              'warn',
+            ),
+          )
+          break
+        }
+        if (/<\/AppShell\.Footer>/.test(lines[i])) insideShellFooter = false
+      }
+    }
+  }
+
+  // S8：用了 Split 的应用不该再写竖直边框
+  if (usesSplit) {
+    for (const cssFile of collectFiles(root, config, ['.css'], config.styleGlobs)) {
+      if (changed) {
+        const rel = displayPath(cwd, cssFile)
+        if (![...changed].some((c) => c === rel || c.endsWith(rel))) continue
+      }
+      const lines = stripComments(readFileSync(cssFile, 'utf8')).split('\n')
+      for (let i = 0; i < lines.length; i++) {
+        if (/border-(?:right|left)\s*:/.test(lines[i])) {
+          violations.push(
+            violation(
+              app.name,
+              cssFile,
+              'structure/self-border',
+              i + 1,
+              '使用了 AppShell.Split，不应再自绘竖直边框（分隔线由 Split 提供）',
+              lines[i],
+              'warn',
+            ),
+          )
+        }
+      }
+    }
+  }
+}
+
+process.exit(report('structure-audit（页面结构护栏）', violations, args, config))

package/lint/style-audit.mjs

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+/**
+ * style-audit —— 样式护栏（应用侧只允许布局属性）。
+ *
+ * 规则（编号沿用方案 §16，新增 12）：
+ *   4  禁 `@import "tailwindcss..."` / `@tailwindcss*`
+ *   5  禁在应用侧定义令牌（`--*:`）与 `@theme`
+ *   6  禁视觉属性（color / background* / border-radius / box-shadow / font-* / fill / stroke）
+ *   7  禁 `!important`（唯一允许出现的位置是包内 farris-bridge.css，不在本审计范围内）
+ *   8  禁裸元素选择器与 `*`
+ *   9  选择器首段必须匹配登记前缀或 `.app-container`
+ *   10 禁书写 `.ak-*` 选择器（ak- 归 app-kit 所有）
+ *   11 禁 tsx 的 `class=` 里出现工具类形态字符串
+ *   12 禁自写 rem 尺寸（全仓统一 px 令牌，不跟随根字号 —— CONTRACT.md §9）
+ *
+ * 豁免：文件头含 `@figma-fidelity` 且登记在豁免注册表时，跳过规则 6 / 8 / 9
+ * （规则 4/5/7/10/11/12 仍然生效）。
+ *
+ * 用法：
+ *   node node_modules/@manohub/app-kit/lint/style-audit.mjs [--json] [--strict] [--changed] [--app=<name>]
+ * 配置：应用包根 appkit-guardrails.config.json
+ */
+import { readFileSync, existsSync } 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
+
+/** 视觉属性（规则 6）。布局属性一律不在列表内。 */
+const VISUAL_PROPS = [
+  'color',
+  'background',
+  'background-color',
+  'background-image',
+  'background-position',
+  'background-size',
+  'background-repeat',
+  'background-clip',
+  'border-radius',
+  'box-shadow',
+  'font',
+  'font-size',
+  'font-weight',
+  'font-family',
+  'font-style',
+  'line-height',
+  'fill',
+  'stroke',
+  'text-shadow',
+  'opacity',
+]
+
+/** 带色值的边框简写（规则 6）：值里出现色值字面量时违规。 */
+const BORDER_SHORTHAND = /^border(?:-(?:top|right|bottom|left))?(?:-(?:width|style|color))?$/
+
+/** 工具类形态（规则 11，窄口径，避免误伤业务类名）。 */
+const UTILITY_CLASS = /(?:^|\s)(?:p|m|px|py|mx|my|pt|pb|pl|pr|w|h|text|bg|border|rounded|gap|items|justify|leading|tracking)-(?:\[|\d|xs|sm|base|lg|xl|full|auto|center|none)/
+
+function violation(app, file, rule, line, message, snippet, severity = 'error') {
+  return makeViolation({ app, file: displayPath(cwd, file), rule, line, severity, message, snippet })
+}
+
+/** 该文件是否登记为设计还原豁免（跳过规则 6/8/9）。 */
+function isExempt(file, source) {
+  if (!config.exemptionRegistry) return false
+  if (!/@figma-fidelity/.test(source)) return false
+  const registry = join(cwd, config.exemptionRegistry)
+  if (!existsSync(registry)) return false
+  const text = readFileSync(registry, 'utf8')
+  return text.includes(displayPath(cwd, file)) || text.includes(file.split(/[\\/]/).pop())
+}
+
+function auditCss(app, file, source, out) {
+  const exempt = isExempt(file, source)
+  const lines = stripComments(source).split('\n')
+  const prefixes = app.prefixes ?? []
+  let selector = []
+  for (let i = 0; i < lines.length; i++) {
+    const rawLine = lines[i]
+    const line = rawLine.trim()
+    if (!line) continue
+    const lineNo = i + 1
+
+    // 规则 4：tailwind 引入
+    if (/@import\s+['"]tailwindcss|@tailwindcss/.test(line)) {
+      out.push(violation(app.name, file, 'style/tailwind', lineNo, '禁止引入 Tailwind', line))
+    }
+    // 规则 5：@theme / 令牌定义
+    if (/@theme/.test(line)) {
+      out.push(violation(app.name, file, 'style/token', lineNo, '禁止在应用侧定义 @theme', line))
+    }
+    if (/^\s*--[\w-]+\s*:/.test(rawLine) && !/[({]/.test(line)) {
+      out.push(violation(app.name, file, 'style/token', lineNo, '禁止在应用侧定义 CSS 令牌', line))
+    }
+
+    // 选择器（以 { 结尾或本行含 {）
+    const braceIdx = line.indexOf('{')
+    if (braceIdx >= 0) {
+      const head = line.slice(0, braceIdx).trim()
+      if (head) selector.push(head)
+      const first = selector.join(' ').split(',')[0].trim()
+      if (first) {
+        if (!exempt) {
+          // 规则 8：裸元素选择器 / *
+          const firstSeg = first.split(/[\s>+~]+/)[0]
+          const isBareElement = /^[a-zA-Z][a-zA-Z0-9-]*$/.test(firstSeg) || firstSeg.startsWith('*')
+          if (isBareElement) {
+            out.push(violation(app.name, file, 'style/bare-element', lineNo, `禁止裸元素选择器 \`${firstSeg}\``, first))
+          }
+          // 规则 9：首段必须匹配登记前缀
+          if (
+            prefixes.length > 0 &&
+            !isBareElement &&
+            !prefixes.some((p) => first.includes(p)) &&
+            !first.includes('.app-container')
+          ) {
+            out.push(
+              violation(app.name, file, 'style/prefix', lineNo, `选择器首段未匹配登记前缀（${prefixes.join(' / ')}）`, first),
+            )
+          }
+        }
+        // 规则 10：.ak-* 选择器
+        if (/\.ak-[\w-]/.test(first)) {
+          out.push(violation(app.name, file, 'style/ak-selector', lineNo, '禁止在应用侧书写 .ak-* 选择器', first))
+        }
+      }
+      if (line.includes('}')) selector = []
+      continue
+    }
+    if (line === '}') {
+      selector = []
+      continue
+    }
+
+    // 声明行
+    const decl = /^([\w-]+)\s*:\s*(.+?);?\s*$/.exec(line)
+    if (decl) {
+      const prop = decl[1].toLowerCase()
+      const value = decl[2]
+      if (/!important/.test(value)) {
+        out.push(violation(app.name, file, 'style/important', lineNo, '禁止 !important', line))
+      }
+      if (/\b\d*\.?\d+rem\b/.test(value)) {
+        out.push(violation(app.name, file, 'style/rem', lineNo, '禁止自写 rem 尺寸', line))
+      }
+      if (!exempt) {
+        // 规则 6：视觉属性（含带色值的 border 简写）一律走组件或 --ui-* 令牌
+        if (VISUAL_PROPS.includes(prop) || BORDER_SHORTHAND.test(prop)) {
+          out.push(violation(app.name, file, 'style/visual', lineNo, `禁止视觉属性 \`${prop}\``, line))
+        }
+      }
+    }
+  }
+}
+
+function auditSource(app, file, source, out) {
+  const lines = stripComments(source).split('\n')
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const lineNo = i + 1
+    if (/@import\s+['"]tailwindcss|from\s+['"]tailwindcss|@tailwindcss/.test(line)) {
+      out.push(violation(app.name, file, 'style/tailwind', lineNo, '禁止引入 Tailwind', line))
+    }
+    const classMatch = /(?:class|className)\s*=\s*["'`]([^"'`]*)["'`]/.exec(line)
+    if (classMatch && UTILITY_CLASS.test(classMatch[1])) {
+      out.push(violation(app.name, file, 'style/utility-class', lineNo, '禁止工具类形态字符串', line))
+    }
+  }
+}
+
+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)
+  const cssFiles = collectFiles(root, config, ['.css'], config.styleGlobs)
+  const srcFiles = collectFiles(root, config, ['.ts', '.tsx'], config.srcGlobs)
+  for (const file of [...cssFiles, ...srcFiles]) {
+    if (changed) {
+      const rel = displayPath(cwd, file)
+      if (![...changed].some((c) => c === rel || c.endsWith(rel))) continue
+    }
+    const source = readFileSync(file, 'utf8')
+    if (file.endsWith('.css')) auditCss(app, file, source, violations)
+    else auditSource(app, file, source, violations)
+  }
+}
+
+process.exit(report('style-audit（样式护栏）', violations, args, config))

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@manohub/app-kit",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "子应用统一骨架层：入口编排（createSubApp）、布局契约（AppShell）、页面组件、原子件、服务、样式底座。farris 被收敛在本包内部，对外只暴露标准 API。",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.iec.io/gsp-cloud-ds/dip/ibp/aihub/frontend-infra.git",
+    "directory": "packages/app-kit"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "lint",
+    "CONTRACT.md",
+    "README.md"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./entry": {
+      "types": "./dist/entry/index.d.ts",
+      "import": "./dist/entry/index.js"
+    },
+    "./styles.css": "./dist/styles/index.css",
+    "./reset.css": "./dist/styles/reset.css",
+    "./CONTRACT.md": "./CONTRACT.md",
+    "./lint/*": "./lint/*"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "node ../../scripts/clean-dist.mjs && vue-tsc -p tsconfig.build.json && vite build && node scripts/copy-styles.mjs",
+    "type-check": "vue-tsc --noEmit -p tsconfig.json",
+    "test:unit": "vitest run && node --test lint/__tests__/guardrails.spec.mjs",
+    "test:guardrails": "node --test lint/__tests__/guardrails.spec.mjs",
+    "test:watch": "vitest"
+  },
+  "peerDependencies": {
+    "@tanstack/vue-query": "^5.0.0",
+    "i18next": "^25.0.0",
+    "i18next-browser-languagedetector": "^8.0.0",
+    "i18next-vue": "^5.0.0",
+    "pinia": "^4.0.0",
+    "vue": "^3.5.0",
+    "vue-router": "^4.6.0"
+  },
+  "dependencies": {
+    "@farris/ui-vue": "^1.8.4",
+    "@manohub/icon": "workspace:^0.1.0"
+  },
+  "devDependencies": {
+    "@tanstack/vue-query": "catalog:",
+    "@vitejs/plugin-vue-jsx": "catalog:",
+    "i18next": "catalog:",
+    "i18next-browser-languagedetector": "catalog:",
+    "i18next-vue": "catalog:",
+    "jsdom": "^25.0.1",
+    "pinia": "catalog:",
+    "typescript": "catalog:",
+    "vite": "catalog:",
+    "vitest": "^3.2.7",
+    "vue": "catalog:",
+    "vue-router": "catalog:",
+    "vue-tsc": "catalog:"
+  }
+}