@ultime/codecraft 1.3.0 → 1.5.0

package/src/cli.mjs

@@ -1,11 +1,11 @@
 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'
 import { applyInitPlan, buildInitPlan } from './init.mjs'
 import { applyIgnores } from './ignore.mjs'
-import { applyInstallPlan, buildInstallPlan, listAgents, loadAgents, parseAgents } from './install.mjs'
 
 const PACKAGE = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
 const VERSION = PACKAGE.version
@@ -17,25 +17,21 @@ Commands:
   audit       check + configured gates; read-only report
   plan        Read-only upgrade plan from findings
   init        Scaffold an app or package (dry-run unless --apply)
-  install     Install the skill into agent skills directories
   version     Print version
 
 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)
-  --agent <name>[,<name>]  Install target (default: auto; see --list-agents)
-  --list-agents            List registered agents, paths and detection
-  --global                 Install into the home directory
-  --dest <path>            Explicit destination (relative to root / home), e.g. .trae-cn/skills
-  --force                  Replace an existing codecraft skill directory
-  --dry-run                Show the install plan without writing
+  --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
@@ -60,7 +56,7 @@ export function main(argv) {
   }
 
   const command = args.command || 'check'
-  if (!['check', 'audit', 'plan', 'init', 'install'].includes(command)) {
+  if (!['check', 'audit', 'plan', 'init'].includes(command)) {
     console.error(`codecraft: unknown command "${command}"\n  next: run codecraft --help`)
     return 2
   }
@@ -71,59 +67,6 @@ export function main(argv) {
     return 2
   }
 
-  if (args.listAgents) {
-    try {
-      const agents = listAgents(root, { global: args.global })
-      if (args.format === 'json') {
-        console.log(JSON.stringify({ version: VERSION, agents }, null, 2))
-      } else {
-        console.log(formatAgents(agents))
-      }
-      return 0
-    } catch (error) {
-      console.error(`codecraft: ${error.message}`)
-      return 2
-    }
-  }
-
-  if (command === 'install') {
-    let agents
-    let registry
-    try {
-      registry = loadAgents(root, { global: args.global })
-      agents = parseAgents(args.agent, [...registry.keys()])
-    } catch (error) {
-      console.error(`codecraft: ${error.message}`)
-      return 2
-    }
-    try {
-      const plan = buildInstallPlan(root, { agents, global: args.global, dest: args.dest, registry })
-      const applied = args.dryRun ? null : applyInstallPlan(plan, { force: args.force })
-      const meta = {
-        version: VERSION,
-        mode: 'install',
-        root,
-        scope: args.global ? 'global' : 'project',
-        agent: args.agent,
-        dest: args.dest || null,
-        dryRun: args.dryRun,
-        targets: plan.length,
-        created: applied?.created.length ?? 0,
-        replaced: applied?.replaced.length ?? 0,
-        skipped: applied?.skipped.length ?? 0,
-      }
-      if (args.format === 'json') {
-        console.log(JSON.stringify({ ...meta, plan, applied }, null, 2))
-      } else {
-        console.log(formatInstall(meta, plan, applied))
-      }
-      return plan.length ? 0 : 1
-    } catch (error) {
-      console.error(`codecraft: ${error.message}`)
-      return 1
-    }
-  }
-
   let config
   try {
     config = loadConfig(root, args.config)
@@ -167,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 = []
@@ -188,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,
@@ -222,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 {
@@ -261,12 +228,9 @@ function parseArgs(argv) {
     failFast: false,
     name: '',
     apply: false,
-    agent: 'auto',
-    global: false,
-    dest: '',
-    force: false,
-    dryRun: false,
-    listAgents: false,
+    changed: false,
+    since: '',
+    exclude: [],
     format: 'md',
     severity: 'warn',
     ci: false,
@@ -283,13 +247,14 @@ 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 === '--global') args.global = true
-    else if (arg === '--force') args.force = true
-    else if (arg === '--dry-run') args.dryRun = true
-    else if (arg === '--list-agents') args.listAgents = 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 === '--agent') args.agent = argv[++i] ?? 'auto'
-    else if (arg === '--dest') args.dest = argv[++i] ?? ''
     else if (arg === '--root') args.root = argv[++i] ?? '.'
     else if (arg === '--pack') args.pack = argv[++i] ?? 'auto'
     else if (arg === '--config') args.config = argv[++i] ?? ''
@@ -300,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}`)
   }
@@ -308,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'
@@ -329,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)
 }
 
@@ -355,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
@@ -367,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) {
@@ -390,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)
 
@@ -521,67 +597,6 @@ function formatInit(meta, plan, applied) {
   return lines.filter((line, index) => !(line === '' && lines[index - 1] === '')).join('\n')
 }
 
-function formatAgents(agents) {
-  const lines = [
-    '# Codecraft Agents',
-    '',
-    `- Version: ${VERSION}`,
-    '',
-    '| Name | Source | Project | Global | Detected |',
-    '|---|---|---|---|---|',
-  ]
-  for (const agent of agents) {
-    const detected =
-      [agent.detected.project ? 'project' : '', agent.detected.global ? 'global' : ''].filter(Boolean).join(', ') ||
-      '—'
-    lines.push(`| ${agent.name} | ${agent.source} | ${agent.project} | ${agent.global} | ${detected} |`)
-  }
-  return lines.join('\n')
-}
-
-function formatInstall(meta, plan, applied) {
-  const lines = [
-    '# Codecraft Install',
-    '',
-    `- Version: ${meta.version}`,
-    `- Mode: install`,
-    `- Scope: ${meta.scope}`,
-    `- Agent: ${meta.agent}`,
-    `- Root: ${meta.root}`,
-    `- Dest: ${meta.dest ?? '（auto）'}`,
-    `- Dry run: ${meta.dryRun}`,
-    `- Targets: ${meta.targets}`,
-  ]
-
-  if (applied) {
-    lines.push(
-      `- Created: ${meta.created}`,
-      `- Replaced: ${meta.replaced}`,
-      `- Skipped: ${meta.skipped}`,
-    )
-  }
-
-  if (!plan.length) {
-    lines.push('', '未找到可安装的目标；请用 `--agent` 指定，或先创建 agent 配置目录。')
-  } else {
-    lines.push('', '## Plan', '', '| Agent | Target | Action |', '|---|---|---|')
-    for (const entry of plan) {
-      lines.push(`| ${entry.agent} | ${entry.target} | ${entry.action} |`)
-    }
-  }
-
-  lines.push(
-    '',
-    '## Next',
-    '',
-    meta.dryRun
-      ? '- Re-run without `--dry-run` to write the skill.'
-      : '- Restart the agent or reload skills；然后说：`用 Codecraft 审计本项目，只读，不改文件。`',
-  )
-
-  return lines.join('\n')
-}
-
 function header(meta) {
   return [
     `# Codecraft ${title(meta.mode)}`,
@@ -591,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/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/`；本文件只做入口。