@ultime/codecraft 1.4.0 → 1.6.0

package/src/cli.mjs

@@ -1,5 +1,6 @@
 import fs from 'node:fs'
 import path from 'node:path'
+import { spawnSync } from 'node:child_process'
 import { check } from './check.mjs'
 import { loadConfig, runGates } from './gates.mjs'
 import { buildPlan, summarizePlan } from './plan.mjs'
@@ -22,12 +23,15 @@ Options:
   --root <path>            Project root (default: cwd)
   --pack app|library|design-system|auto  Rule pack (default: auto)
   --config <path>          Config file (default: codecraft.config.json)
+  --changed                Only report findings in changed / untracked files
+  --since <ref>            Only report findings changed since a git ref (e.g. origin/main)
+  --exclude <glob>         Skip files when scanning (repeatable; e.g. "evals/fixtures/**")
   --no-gates               Skip gates in audit / plan
   --with-gates             Run configured gates in plan
   --fail-fast              Stop gates after the first failure
   --name <name>            Scaffold name (required with --apply)
   --apply                  Write the scaffold; existing paths are skipped
-  --format md|json         Output format (default: md)
+  --format md|json|sarif   Output format (default: md)
   --severity warn|error    Reported severity (default: warn)
   --ci                     Treat findings as errors
   --help, -h
@@ -106,9 +110,28 @@ export function main(argv) {
     return 0
   }
 
-  const result = check(root, { pack })
+  const result = check(root, {
+    pack,
+    boundaries: config.config.boundaries,
+    exclude: args.exclude,
+  })
+  let changed = null
+  let scoped = result.findings
+  if (args.changed || args.since) {
+    try {
+      changed = changedFiles(root, args.since)
+    } catch (error) {
+      console.error(`codecraft: ${error.message}`)
+      return 2
+    }
+    const files = new Set(changed)
+    scoped = scoped.filter((finding) => {
+      const file = finding.file.replace(/\\/g, '/')
+      return files.has(file) || [...files].some((candidate) => candidate.endsWith(`/${file}`))
+    })
+  }
   const severity = args.ci ? 'error' : args.severity
-  const findings = result.findings.map((finding) => ({ ...finding, severity }))
+  const findings = scoped.map((finding) => ({ ...finding, severity }))
   const filtered = applyIgnores(findings, config.config.ignore ?? [])
   const activeFindings = filtered.findings
   const warnings = []
@@ -127,8 +150,11 @@ export function main(argv) {
     root,
     config: config.file,
     severity,
-    rules: pack === 'app' ? ['A17', 'A21'] : ['A2', 'A11', 'A21'],
+    rules: pack === 'app' ? ['A6', 'A17', 'A21'] : ['A2', 'A6', 'A11', 'A21'],
     files: result.files,
+    scope: args.changed || args.since ? 'changed' : 'full',
+    changed: changed?.length ?? null,
+    exclude: args.exclude,
     findings: activeFindings.length,
     ignored: filtered.ignored.length,
     expired: filtered.expired.length,
@@ -161,6 +187,8 @@ export function main(argv) {
         2,
       ),
     )
+  } else if (args.format === 'sarif') {
+    console.log(formatSarif(meta, activeFindings))
   } else if (command === 'plan') {
     console.log(formatPlan(meta, activeFindings, plan, gates))
   } else {
@@ -200,6 +228,9 @@ function parseArgs(argv) {
     failFast: false,
     name: '',
     apply: false,
+    changed: false,
+    since: '',
+    exclude: [],
     format: 'md',
     severity: 'warn',
     ci: false,
@@ -216,6 +247,13 @@ function parseArgs(argv) {
     else if (arg === '--with-gates') args.withGates = true
     else if (arg === '--fail-fast') args.failFast = true
     else if (arg === '--apply') args.apply = true
+    else if (arg === '--changed') args.changed = true
+    else if (arg === '--since') args.since = argv[++i] ?? ''
+    else if (arg === '--exclude') {
+      const pattern = argv[++i] ?? ''
+      if (!pattern) fail('--exclude needs a path or glob (e.g. "evals/fixtures/**")')
+      args.exclude.push(pattern)
+    }
     else if (arg === '--name') args.name = argv[++i] ?? ''
     else if (arg === '--root') args.root = argv[++i] ?? '.'
     else if (arg === '--pack') args.pack = argv[++i] ?? 'auto'
@@ -227,7 +265,9 @@ function parseArgs(argv) {
   }
 
   if (!['app', 'library', 'design-system', 'auto'].includes(args.pack)) fail(`invalid --pack: ${args.pack}`)
-  if (args.format !== 'md' && args.format !== 'json') fail(`invalid --format: ${args.format}`)
+  if (args.format !== 'md' && args.format !== 'json' && args.format !== 'sarif') {
+    fail(`invalid --format: ${args.format}`)
+  }
   if (args.severity !== 'warn' && args.severity !== 'error') {
     fail(`invalid --severity: ${args.severity}`)
   }
@@ -235,6 +275,39 @@ function parseArgs(argv) {
   return args
 }
 
+function changedFiles(root, since) {
+  const top = git(root, ['rev-parse', '--show-toplevel'])
+  if (top == null) {
+    throw new Error('not a git repository; --changed / --since need git (run inside a git repo or drop the flag)')
+  }
+
+  const lists = [git(root, ['diff', '--name-only', '--diff-filter=ACMRT', 'HEAD'])]
+  if (since) lists.push(git(root, ['diff', '--name-only', '--diff-filter=ACMRT', `${since}...HEAD`]))
+  lists.push(git(root, ['ls-files', '--others', '--exclude-standard']))
+
+  const realRoot = fs.realpathSync(root)
+  const files = new Set()
+  for (const list of lists) {
+    if (!list) continue
+    for (const line of list.split('\n')) {
+      const file = line.trim()
+      if (!file) continue
+      const relative = path.relative(realRoot, path.resolve(top, file)).split(path.sep).join('/')
+      if (relative && !relative.startsWith('..')) files.add(relative)
+    }
+  }
+  return [...files]
+}
+
+function git(root, args) {
+  const result = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8' })
+  if (result.status !== 0) {
+    const message = (result.stderr || '').trim()
+    throw new Error(`git ${args.join(' ')} failed${message ? `: ${message}` : ''}`)
+  }
+  return result.stdout.trim()
+}
+
 export function detectPack(root) {
   if (isDir(path.join(root, 'apps'))) return 'app'
   if (hasAppMarkers(root)) return 'app'
@@ -256,13 +329,28 @@ const APP_FILE_MARKERS = [
   'src/app.config.ts',
   'taro.config.js',
   'taro.config.ts',
+  'vue.config.js',
+  'vue.config.ts',
 ]
 const APP_DEPS = ['nuxt', '@tarojs/taro', '@dcloudio/uni-app', 'uni-app', 'next']
+/** 单页 Web 应用入口；库的 demo 页通常不具备「框架依赖 + 入口 + html」三件套。 */
+const WEB_ENTRIES = [
+  'src/main.ts',
+  'src/main.js',
+  'src/main.tsx',
+  'src/main.jsx',
+  'src/index.ts',
+  'src/index.js',
+  'src/index.tsx',
+  'src/index.jsx',
+]
+const WEB_DEPS = ['vue', 'react', 'react-dom', 'react-scripts', 'svelte', 'solid-js', 'preact', '@angular/core']
 
 function hasAppMarkers(root) {
   if (APP_DIR_MARKERS.some((dir) => isDir(path.join(root, dir)))) return true
   if (APP_FILE_MARKERS.some((file) => isFile(path.join(root, file)))) return true
   if (hasUniAppFiles(root)) return true
+  if (hasWebEntry(root)) return true
   return hasAppDependency(root)
 }
 
@@ -282,6 +370,7 @@ function hasNestedApp(root) {
     if (APP_DIR_MARKERS.some((dir) => isDir(path.join(child, dir)))) return true
     if (APP_FILE_MARKERS.some((file) => isFile(path.join(child, file)))) return true
     if (hasUniAppFiles(child)) return true
+    if (hasWebEntry(child)) return true
     if (hasAppDependency(child)) return true
   }
   return false
@@ -294,14 +383,25 @@ function hasUniAppFiles(root) {
 }
 
 function hasAppDependency(root) {
+  return dependencyNames(root).some((dep) => APP_DEPS.includes(dep))
+}
+
+/** 框架依赖 + html + 入口；三者齐全才按单页应用处理，避免把带 demo 的库判成 app。 */
+function hasWebEntry(root) {
+  const html = isFile(path.join(root, 'index.html')) || isFile(path.join(root, 'public', 'index.html'))
+  if (!html) return false
+  if (!dependencyNames(root).some((dep) => WEB_DEPS.includes(dep))) return false
+  return WEB_ENTRIES.some((file) => isFile(path.join(root, file)))
+}
+
+function dependencyNames(root) {
   let manifest
   try {
     manifest = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'))
   } catch {
-    return false
+    return []
   }
-  const deps = { ...(manifest.dependencies ?? {}), ...(manifest.devDependencies ?? {}) }
-  return APP_DEPS.some((dep) => dep in deps)
+  return Object.keys({ ...(manifest.dependencies ?? {}), ...(manifest.devDependencies ?? {}) })
 }
 
 function isFile(target) {
@@ -317,6 +417,55 @@ function fail(message) {
   process.exit(2)
 }
 
+function formatSarif(meta, findings) {
+  const rules = meta.rules.map((id) => ({
+    id,
+    name: SARIF_RULES[id]?.name ?? id,
+    shortDescription: { text: SARIF_RULES[id]?.short ?? id },
+  }))
+  return JSON.stringify(
+    {
+      $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+      version: '2.1.0',
+      runs: [
+        {
+          tool: {
+            driver: {
+              name: 'codecraft',
+              informationUri: 'https://github.com/ultime-space/skills',
+              version: meta.version,
+              rules,
+            },
+          },
+          results: findings.map((finding) => ({
+            ruleId: finding.rule,
+            level: finding.severity === 'error' ? 'error' : 'warning',
+            message: { text: finding.message },
+            locations: [
+              {
+                physicalLocation: {
+                  artifactLocation: { uri: finding.file.replace(/\\/g, '/') },
+                  region: { startLine: finding.line },
+                },
+              },
+            ],
+          })),
+        },
+      ],
+    },
+    null,
+    2,
+  )
+}
+
+const SARIF_RULES = {
+  A2: { name: 'DependencyDirection', short: 'Dependencies must point inward' },
+  A6: { name: 'EmptyCatch', short: 'Empty catch swallows failures' },
+  A11: { name: 'GeneratedReadOnly', short: 'Generated files must be read-only and marked' },
+  A17: { name: 'ExternalBoundary', short: 'Internal layers must not import external or generated types' },
+  A21: { name: 'SecretScan', short: 'No secrets or internal paths in repository' },
+}
+
 function formatReport(meta, findings, ignored, expired, gates) {
   const lines = header(meta)
 
@@ -457,6 +606,7 @@ function header(meta) {
     `- Pack: ${meta.pack}`,
     `- Root: ${meta.root}`,
     `- Config: ${meta.config ?? '（none）'}`,
+    `- Exclude: ${meta.exclude?.length ? meta.exclude.join(', ') : '（none）'}`,
     `- Rules: ${meta.rules.join(' / ')}`,
     `- Severity: ${meta.severity}`,
     `- Files: ${meta.files}`,

package/src/gates.mjs

@@ -27,7 +27,34 @@ export function loadConfig(root, configPath) {
     }
   }
 
-  return { file, config: { ...config, ignore: validateIgnore(config.ignore, file) } }
+  return {
+    file,
+    config: {
+      ...config,
+      ignore: validateIgnore(config.ignore, file),
+      ...(config.boundaries ? { boundaries: validateBoundaries(config.boundaries, file) } : {}),
+    },
+  }
+}
+
+function validateBoundaries(value, file) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`invalid config ${file}: "boundaries" must be an object with external / generated arrays`)
+  }
+  const boundaries = {}
+  for (const key of ['external', 'generated']) {
+    if (value[key] == null) continue
+    if (!Array.isArray(value[key])) {
+      throw new Error(`invalid config ${file}: boundaries.${key} must be an array of import prefixes or globs`)
+    }
+    boundaries[key] = value[key].map((item) => {
+      if (typeof item !== 'string' || !item.trim()) {
+        throw new Error(`invalid config ${file}: boundaries.${key} entries must be non-empty strings`)
+      }
+      return item.trim()
+    })
+  }
+  return boundaries
 }
 
 export function runGates(root, gates, options = {}) {

package/src/plan.mjs

@@ -1,6 +1,7 @@
 const ACTIONS = {
   A2: 'Declare the workspace dependency in package.json, or remove the import; if shared, move it to a lower-layer package.',
   A4: 'Move the external import to a Wrapper/API module; expose an internal type to the caller.',
+  A6: 'Return a Result or handle the error; never swallow it in an empty catch.',
   A11: "Regenerate the file from source and add a 'do not edit' marker; if it is not generated, move it out of generated paths.",
   A17: 'Move the external import to a Wrapper/API module; expose an internal type to the caller.',
 }
@@ -8,6 +9,7 @@ const ACTIONS = {
 const VERIFY = {
   A2: 'codecraft check --pack library',
   A4: 'codecraft check --pack app',
+  A6: 'codecraft check',
   A11: 'codecraft check --pack library',
   A17: 'codecraft check --pack app',
 }

package/templates/README.md

@@ -6,6 +6,8 @@
 |---|---|
 | `app/` | 应用骨架：`README.md` + `package.json` |
 | `library/` | 包骨架：`README.md` + `CHANGELOG.md` + `compat.md` + `package.json` |
+| `architecture-report.md` | 代码架构分析报告模板（Agent 输出用，不是 init 骨架） |
 
 - 目录结构由 `src/init.mjs` 定义，模板只提供文件内容。
-- 页面 / 组件 / Wrapper 的单文件形态见 `docs/01-family-cards.md`，不单独出模板：不同框架的写法差异大于共性。
+- `architecture-report.md` 只被 `scenarios/architecture-report.md` 引用，不参与 `init`。
+- 页面 / 组件 / Wrapper的单文件形态见 `docs/01-family-cards.md`，不单独出模板：不同框架的写法差异大于共性。

package/templates/architecture-report.md

@@ -0,0 +1,97 @@
+# <项目 / 模块> 代码架构分析报告（Codecraft）
+
+> 模式：Audit / Plan，只读 · 日期：YYYY-MM-DD · 仓库：`<repo>` · 分支：`<branch>` · HEAD：`<sha>`
+> 范围：`<目录 / 包>` · 规则版本：Codecraft `<version>`
+> 只读声明：未改代码、未起服务。未执行：`<typecheck / build / 单测>`。
+> 边界：本文只讨论代码架构；业务能力、角色、业务流程、领域规则不在范围。
+
+## 1. 结论与置信度
+
+- 一句话结论：
+- 置信度：High / Medium / Low（依据：静态 + 人工抽样 + 关键路径）
+- 最高风险：
+- 最需要先做的决定：
+
+## 2. 范围与方法
+
+| 项 | 内容 |
+|---|---|
+| 范围 | |
+| 已执行 | |
+| 未执行 | |
+| 覆盖边界 | |
+| 判定口径 | |
+
+## 3. 架构现状
+
+### 3.1 系统与容器
+
+| 单元 | 职责 | 运行时 / 部署 | 外部依赖 |
+|---|---|---|---|
+| | | | |
+
+### 3.2 模块与依赖
+
+| 模块 / 包 | 职责 | 允许依赖 | 禁止依赖 | 证据 |
+|---|---|---|---|---|
+| | | | | |
+
+- 依赖方向：
+- 边界与内外分离：
+- 公共 API / 内部实现：
+
+### 3.3 关键链路
+
+| 链路 | 入口 | 关键节点 | 失败模式 | 证据 |
+|---|---|---|---|---|
+| 请求 | | | | |
+| 状态 | | | | |
+| 错误 | | | | |
+| 数据 | | | | |
+| 生成 | | | | |
+
+## 4. A1–A21 判定
+
+| ID | 判定 | 证据 | 局限 |
+|---|---|---|---|
+| A1 | pass / pass（静态）/ warn / fail / na | `path:line` 或命令 | |
+| … | | | |
+
+- 一致性检查：
+- `codecraft check` 结果：`files / findings / 覆盖范围`
+- A17 / A21 盲区：
+
+## 5. 风险与技术债
+
+| 优先级 | 问题 | 证据 | 影响 | 建议 |
+|---|---|---|---|---|
+| P0 | | | | |
+| P1 | | | | |
+| P2 | | | | |
+| P3 | | | | |
+
+## 6. 演进计划
+
+| 阶段 | 内容 | 可回滚 | 验收 |
+|---|---|---|---|
+| 0 | | | |
+| 1 | | | |
+| 2 | | | |
+
+- 不写时间估算。
+- 每阶段一个可验收的垂直切片。
+
+## 7. 未知项与待确认
+
+| # | 问题 | 为什么无法确认 | 需要谁 / 什么证据 |
+|---|---|---|---|
+| 1 | | | |
+
+## 8. 附录：证据与命令
+
+```bash
+# 本次执行的检查
+```
+
+- 相关文件：
+- 相关文档：

package/adapters/claude/SKILL.md

@@ -1,42 +0,0 @@
----
-name: codecraft
-description: 面向 JS/TS 的代码规范与架构设计（Codecraft）。默认 Web 前端，Node 后端可复用结构规则；用于审计、架构设计、重构评审、规范检查与脚手架。
----
-
-# Codecraft（代码手艺）
-
-> 方向：JS/TS（默认前端）。后端只复用结构规则；Page / Component 等前端族不套用到后端。
-
-## 先读
-
-1. 项目 `AGENTS.md` / `rules/`
-2. `../../docs/00-constitution.md`
-3. 只读相关族卡：`../../docs/01-family-cards.md`
-4. 设计架构时：`../../docs/06-architecture.md`
-5. 需要选型时：`../../docs/05-patterns.md`
-6. 选场景：`../../scenarios/`
-
-## 模式
-
-- **Audit（审计）**：只读，出报告。
-- **Plan（计划）**：只读，出架构 / 升级计划。
-- **Apply（执行）**：改代码 + 跑门禁。
-
-## 工作流
-
-1. 判定任务属于哪个场景。
-2. 只读相关族卡，不要一次加载全部。
-3. 先出计划；Apply 前确认范围。
-4. 跑项目验证命令；不能跑要说明原因。
-5. 按 `../../prompts/output.md` 输出。
-
-## 禁止
-
-- Audit / Plan 模式改文件。
-- 把业务逻辑放进 Transport 或 Page。
-- 内部代码 import `external/` 或生成类型。
-- 手改生成物。
-- 写敏感信息；发现即停止、脱敏、提示轮换。
-- 安全红线登记例外。
-
-规则正文只在 `docs/`；本文件只做入口。

package/adapters/trae/SKILL.md

@@ -1,42 +0,0 @@
----
-name: codecraft
-description: 面向 JS/TS 的代码规范与架构设计（Codecraft）。默认 Web 前端，Node 后端可复用结构规则；用于审计、架构设计、重构评审、规范检查与脚手架。
----
-
-# Codecraft（代码手艺）
-
-> 方向：JS/TS（默认前端）。后端只复用结构规则；Page / Component 等前端族不套用到后端。
-
-## 先读
-
-1. 项目 `AGENTS.md` / `rules/`
-2. `../../docs/00-constitution.md`
-3. 只读相关族卡：`../../docs/01-family-cards.md`
-4. 设计架构时：`../../docs/06-architecture.md`
-5. 需要选型时：`../../docs/05-patterns.md`
-6. 选场景：`../../scenarios/`
-
-## 模式
-
-- **Audit（审计）**：只读，出报告。
-- **Plan（计划）**：只读，出架构 / 升级计划。
-- **Apply（执行）**：改代码 + 跑门禁。
-
-## 工作流
-
-1. 判定任务属于哪个场景。
-2. 只读相关族卡，不要一次加载全部。
-3. 先出计划；Apply 前确认范围。
-4. 跑项目验证命令；不能跑要说明原因。
-5. 按 `../../prompts/output.md` 输出。
-
-## 禁止
-
-- Audit / Plan 模式改文件。
-- 把业务逻辑放进 Transport 或 Page。
-- 内部代码 import `external/` 或生成类型。
-- 手改生成物。
-- 写敏感信息；发现即停止、脱敏、提示轮换。
-- 安全红线登记例外。
-
-规则正文只在 `docs/`；本文件只做入口。