@ultime/codecraft 0.0.0-stage → 1.0.1

package/src/cli.mjs

@@ -0,0 +1,384 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { check } from './check.mjs'
+import { loadConfig, runGates } from './gates.mjs'
+import { buildPlan, summarizePlan } from './plan.mjs'
+import { applyInitPlan, buildInitPlan } from './init.mjs'
+
+const PACKAGE = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+const VERSION = PACKAGE.version
+
+const HELP = `codecraft <command> [options]
+
+Commands:
+  check       Scan for boundary violations (default)
+  audit       check + configured gates; read-only report
+  plan        Read-only upgrade plan from findings
+  init        Scaffold an app or package (dry-run unless --apply)
+  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)
+  --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)
+  --severity warn|error    Reported severity (default: warn)
+  --ci                     Treat findings as errors
+  --help, -h
+  --version, -v
+
+Packs:
+  app            A17 / A21 — pages / components / behavior must not import external or generated;
+                 high-confidence secrets are always scanned
+  library        A2 / A11 / A21 — package boundaries, generated-file markers, secret scan
+  design-system  A2 / A11 / A21 — library rules + public docs must not reference internal docs
+`
+
+export function main(argv) {
+  const args = parseArgs(argv)
+  if (args.help) {
+    console.log(HELP)
+    return 0
+  }
+  if (args.version || args.command === 'version') {
+    console.log(VERSION)
+    return 0
+  }
+
+  const command = args.command || 'check'
+  if (!['check', 'audit', 'plan', 'init'].includes(command)) {
+    console.error(`codecraft: unknown command "${command}"`)
+    return 2
+  }
+
+  const root = path.resolve(process.cwd(), args.root)
+  if (!fs.existsSync(root)) {
+    console.error(`codecraft: root not found: ${root}`)
+    return 2
+  }
+
+  let config
+  try {
+    config = loadConfig(root, args.config)
+  } catch (error) {
+    console.error(`codecraft: ${error.message}`)
+    return 2
+  }
+
+  const pack = resolvePack(args.pack, config.config.pack, root)
+  if (!pack) {
+    console.error('codecraft: invalid config pack; expected app, library or auto')
+    return 2
+  }
+
+  if (command === 'init') {
+    if (args.apply && !args.name) {
+      console.error('codecraft: init --apply requires --name <name>')
+      return 2
+    }
+    const plan = buildInitPlan(root, pack === 'design-system' ? 'library' : pack, args.name)
+    const applied = args.apply ? applyInitPlan(root, plan) : null
+    const meta = {
+      version: VERSION,
+      mode: 'init',
+      pack,
+      root,
+      configFile: config.file,
+      name: args.name,
+      dryRun: !args.apply,
+      entries: plan.entries.length,
+      created: applied?.created.length ?? 0,
+      skipped: applied?.skipped.length ?? 0,
+    }
+    if (args.format === 'json') {
+      console.log(JSON.stringify({ ...meta, entries: plan.entries, config: plan.config, applied }, null, 2))
+    } else {
+      console.log(formatInit(meta, plan, applied))
+    }
+    return 0
+  }
+
+  const result = check(root, { pack })
+  const severity = args.ci ? 'error' : args.severity
+  const findings = result.findings.map((finding) => ({ ...finding, severity }))
+  const gates = shouldRunGates(command, args)
+    ? runGates(root, config.config.gates ?? [], { failFast: args.failFast })
+    : []
+  const plan = command === 'plan' ? buildPlan(findings) : []
+  const meta = {
+    version: VERSION,
+    mode: command,
+    pack,
+    root,
+    config: config.file,
+    severity,
+    rules: pack === 'app' ? ['A17', 'A21'] : ['A2', 'A11', 'A21'],
+    files: result.files,
+    findings: findings.length,
+    plan: plan.length,
+    gates: gates.length,
+  }
+
+  if (args.format === 'json') {
+    console.log(
+      JSON.stringify(
+        {
+          ...meta,
+          findings,
+          plan,
+          gates,
+          summary: {
+            files: result.files,
+            findings: findings.length,
+            plan: plan.length,
+            gates: gates.length,
+            gateFailures: gates.filter((gate) => gate.exitCode !== 0).length,
+          },
+        },
+        null,
+        2,
+      ),
+    )
+  } else if (command === 'plan') {
+    console.log(formatPlan(meta, findings, plan, gates))
+  } else {
+    console.log(formatReport(meta, findings, gates))
+  }
+
+  const failed = findings.some((finding) => finding.severity === 'error') || gates.some((gate) => gate.exitCode !== 0)
+  return failed ? 1 : 0
+}
+
+function shouldRunGates(command, args) {
+  if (args.noGates) return false
+  if (command === 'audit') return true
+  if (command === 'plan') return args.withGates
+  return false
+}
+
+function resolvePack(cliPack, configPack, root) {
+  if (cliPack !== 'auto') return cliPack
+  if (configPack && configPack !== 'auto') {
+    return ['app', 'library', 'design-system'].includes(configPack) ? configPack : null
+  }
+  return detectPack(root)
+}
+
+function parseArgs(argv) {
+  const args = {
+    command: '',
+    root: '.',
+    pack: 'auto',
+    config: '',
+    noGates: false,
+    withGates: false,
+    failFast: false,
+    name: '',
+    apply: false,
+    format: 'md',
+    severity: 'warn',
+    ci: false,
+    help: false,
+    version: false,
+  }
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === '--help' || arg === '-h') args.help = true
+    else if (arg === '--version' || arg === '-v') args.version = true
+    else if (arg === '--ci') args.ci = true
+    else if (arg === '--no-gates') args.noGates = true
+    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 === '--name') args.name = 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] ?? ''
+    else if (arg === '--format') args.format = argv[++i] ?? 'md'
+    else if (arg === '--severity') args.severity = argv[++i] ?? 'warn'
+    else if (!arg.startsWith('-') && !args.command) args.command = arg
+    else fail(`unknown option: ${arg}`)
+  }
+
+  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.severity !== 'warn' && args.severity !== 'error') {
+    fail(`invalid --severity: ${args.severity}`)
+  }
+
+  return args
+}
+
+function detectPack(root) {
+  if (isDir(path.join(root, 'apps')) || isDir(path.join(root, 'src', 'pages'))) return 'app'
+  if (isDir(path.join(root, 'packages'))) return 'library'
+  if (fs.existsSync(path.join(root, 'package.json'))) return 'library'
+  return 'app'
+}
+
+function fail(message) {
+  console.error(`codecraft: ${message}\n\n${HELP}`)
+  process.exit(2)
+}
+
+function formatReport(meta, findings, gates) {
+  const lines = header(meta)
+
+  if (!findings.length) {
+    lines.push('✓ 未发现边界问题。')
+  } else {
+    lines.push('## Findings', '', '| Rule | Severity | File | Line | Message |', '|---|---|---|---|---|')
+    for (const finding of findings) {
+      lines.push(row(finding))
+    }
+  }
+
+  lines.push(...gateLines(gates))
+  return lines.join('\n')
+}
+
+function formatPlan(meta, findings, plan, gates) {
+  const lines = header(meta)
+  lines.pop()
+  lines.push(`- Plan Items: ${plan.length}`, '')
+
+  if (!plan.length) {
+    lines.push('✓ 没有需要处理的问题；无需计划。')
+  } else {
+    lines.push('## Summary', '', '| Rule | Count |', '|---|---:|')
+    for (const item of summarizePlan(findings)) lines.push(`| ${item.rule} | ${item.count} |`)
+
+    lines.push(
+      '',
+      '## Plan',
+      '',
+      '| # | Rule | Severity | File | Line | Action | Verification |',
+      '|---|---|---|---|---|---|---|',
+    )
+    for (const item of plan) {
+      lines.push(
+        `| ${item.id} | ${item.rule} | ${item.severity} | ${item.file} | ${item.line} | ${escapeCell(item.action)} | \`${item.verification}\` |`,
+      )
+    }
+    lines.push('', '## Next', '', '- Apply in small batches; run `codecraft check` after each.')
+    lines.push('- No files were changed by this command.')
+  }
+
+  lines.push(...gateLines(gates))
+  return lines.join('\n')
+}
+
+function formatInit(meta, plan, applied) {
+  const lines = [
+    '# Codecraft Init',
+    '',
+    `- Version: ${meta.version}`,
+    `- Mode: init`,
+    `- Pack: ${meta.pack}`,
+    `- Root: ${meta.root}`,
+    `- Name: ${meta.name || '（placeholder）'}`,
+    `- Dry run: ${meta.dryRun}`,
+    `- Entries: ${meta.entries}`,
+  ]
+
+  if (applied) {
+    lines.push(`- Created: ${meta.created}`, `- Skipped: ${meta.skipped}`)
+  }
+
+  lines.push('', '## Directories', '', '| Path | Action |', '|---|---|')
+
+  for (const entry of plan.entries.filter((item) => item.type === 'dir')) {
+    lines.push(`| ${entry.path} | ${entry.action} |`)
+  }
+
+  lines.push('', '## Files', '', '| Path | Action |', '|---|---|')
+  for (const entry of plan.entries.filter((item) => item.type === 'file')) {
+    lines.push(`| ${entry.path} | ${entry.action} |`)
+  }
+
+  lines.push('', '## Config', '', '```json', JSON.stringify(plan.config, null, 2), '```')
+
+  if (applied) {
+    lines.push('', '## Appended', '', '- Existing paths are skipped; nothing was overwritten.')
+    if (applied.created.length) {
+      lines.push('', 'Created:', '')
+      for (const item of applied.created) lines.push(`- ${item}`)
+    }
+    if (applied.skipped.length) {
+      lines.push('', 'Skipped:', '')
+      for (const item of applied.skipped) lines.push(`- ${item}`)
+    }
+  }
+
+  lines.push(
+    '',
+    '## Next',
+    '',
+    meta.dryRun
+      ? '- Review the plan; nothing was written.'
+      : '- Run `codecraft check --pack <pack>` to confirm the boundary rules.',
+    meta.dryRun ? '- Re-run with `--apply --name <name>` to write the scaffold.' : '',
+  )
+
+  return lines.filter((line, index) => !(line === '' && lines[index - 1] === '')).join('\n')
+}
+
+function header(meta) {
+  return [
+    `# Codecraft ${title(meta.mode)}`,
+    '',
+    `- Version: ${meta.version}`,
+    `- Mode: ${meta.mode}`,
+    `- Pack: ${meta.pack}`,
+    `- Root: ${meta.root}`,
+    `- Config: ${meta.config ?? '（none）'}`,
+    `- Rules: ${meta.rules.join(' / ')}`,
+    `- Severity: ${meta.severity}`,
+    `- Files: ${meta.files}`,
+    `- Findings: ${meta.findings}`,
+    `- Gates: ${meta.gates}`,
+    '',
+  ]
+}
+
+function title(mode) {
+  if (mode === 'audit') return 'Audit'
+  if (mode === 'plan') return 'Plan'
+  return 'Check'
+}
+
+function row(finding) {
+  return `| ${finding.rule} | ${finding.severity} | ${finding.file} | ${finding.line} | ${escapeCell(finding.message)} |`
+}
+
+function gateLines(gates) {
+  if (!gates.length) return []
+  const lines = ['', '## Gates', '', '| Gate | Exit | Duration | Command |', '|---|---:|---:|---|']
+  for (const gate of gates) {
+    lines.push(`| ${gate.name} | ${gate.exitCode} | ${gate.durationMs}ms | \`${gate.command}\` |`)
+  }
+  for (const gate of gates.filter((item) => item.exitCode !== 0)) {
+    lines.push('', `### Gate: ${gate.name}（exit ${gate.exitCode}）`, '', '~~~text')
+    lines.push(gate.output || '(no output)')
+    lines.push('~~~')
+  }
+  return lines
+}
+
+function escapeCell(value) {
+  return value.replace(/\|/g, '\\|')
+}
+
+function isDir(target) {
+  try {
+    return fs.statSync(target).isDirectory()
+  } catch {
+    return false
+  }
+}

package/src/gates.mjs

@@ -0,0 +1,67 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+export function loadConfig(root, configPath) {
+  const file = configPath ? path.resolve(root, configPath) : path.join(root, 'codecraft.config.json')
+
+  if (!fs.existsSync(file)) return { file: null, config: {} }
+
+  let config
+  try {
+    config = JSON.parse(fs.readFileSync(file, 'utf8'))
+  } catch (error) {
+    throw new Error(`invalid config ${file}: ${error.message}`)
+  }
+
+  if (config.gates != null && !Array.isArray(config.gates)) {
+    throw new Error(`invalid config ${file}: "gates" must be an array`)
+  }
+
+  for (const gate of config.gates ?? []) {
+    if (!gate || typeof gate.run !== 'string' || !gate.run.trim()) {
+      throw new Error(`invalid config ${file}: each gate needs a "run" string`)
+    }
+  }
+
+  return { file, config }
+}
+
+export function runGates(root, gates, options = {}) {
+  if (!Array.isArray(gates)) throw new Error('gates must be an array')
+  const results = []
+  for (const gate of gates) {
+    const result = runGate(root, gate)
+    results.push(result)
+    if (options.failFast && result.exitCode !== 0) break
+  }
+  return results
+}
+
+function runGate(root, gate) {
+  const name = typeof gate.name === 'string' && gate.name.trim() ? gate.name.trim() : gate.run
+  const startedAt = Date.now()
+  const result = spawnSync(gate.run, {
+    cwd: root,
+    shell: true,
+    encoding: 'utf8',
+    timeout: Number.isFinite(gate.timeoutMs) ? gate.timeoutMs : 120000,
+    env: { ...process.env, CI: '1' },
+    maxBuffer: 10 * 1024 * 1024,
+  })
+  const durationMs = Date.now() - startedAt
+  const output = tail([result.error?.message, result.stdout, result.stderr].filter(Boolean).join('\n').trim(), 40, 4000)
+
+  return {
+    name,
+    command: gate.run,
+    exitCode: result.status ?? 1,
+    durationMs,
+    output,
+  }
+}
+
+function tail(text, maxLines, maxChars) {
+  const sliced = text.split('\n').slice(-maxLines).join('\n')
+  return sliced.length > maxChars ? sliced.slice(-maxChars) : sliced
+}

package/src/init.mjs

@@ -0,0 +1,98 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+const TEMPLATES = new URL('../templates/', import.meta.url)
+
+export function buildInitPlan(root, pack, name = '') {
+  const appName = name || '<app>'
+  const packageName = name || '<package>'
+  const id = toPackageId(name)
+  const entries = []
+
+  const add = (rel, type, content) => {
+    const abs = path.join(root, rel)
+    entries.push({
+      path: rel,
+      type,
+      action: fs.existsSync(abs) ? 'exists' : 'create',
+      ...(content == null ? {} : { content }),
+    })
+  }
+
+  const fill = (target, vars) => render(template(pack, target), vars)
+
+  if (pack === 'library') {
+    add('packages', 'dir')
+    add(`packages/${packageName}`, 'dir')
+    add(`packages/${packageName}/src`, 'dir')
+    add(`packages/${packageName}/tests`, 'dir')
+    const vars = { name: packageName, id }
+    add(`packages/${packageName}/README.md`, 'file', fill('README.md', vars))
+    add(`packages/${packageName}/CHANGELOG.md`, 'file', fill('CHANGELOG.md', vars))
+    add(`packages/${packageName}/compat.md`, 'file', fill('compat.md', vars))
+    add(`packages/${packageName}/package.json`, 'file', fill('package.json', vars))
+  } else {
+    add('apps', 'dir')
+    add(`apps/${appName}`, 'dir')
+    add(`apps/${appName}/src`, 'dir')
+    add(`apps/${appName}/src/pages`, 'dir')
+    add(`apps/${appName}/src/components`, 'dir')
+    add(`apps/${appName}/src/behavior`, 'dir')
+    add(`apps/${appName}/src/api`, 'dir')
+    add(`apps/${appName}/src/adapters`, 'dir')
+    add(`apps/${appName}/src/types`, 'dir')
+    add(`apps/${appName}/src/external`, 'dir')
+    const vars = { name: appName, id }
+    add(`apps/${appName}/README.md`, 'file', fill('README.md', vars))
+    add(`apps/${appName}/package.json`, 'file', fill('package.json', vars))
+  }
+
+  add('docs', 'dir')
+  const config = { pack, gates: [] }
+  add('codecraft.config.json', 'file', `${JSON.stringify(config, null, 2)}\n`)
+
+  return { pack, name, entries, config }
+}
+
+export function applyInitPlan(root, plan) {
+  const created = []
+  const skipped = []
+
+  for (const entry of plan.entries) {
+    const abs = path.join(root, entry.path)
+    if (entry.action === 'exists') {
+      skipped.push(entry.path)
+      continue
+    }
+    if (entry.type === 'dir') {
+      fs.mkdirSync(abs, { recursive: true })
+    } else {
+      fs.mkdirSync(path.dirname(abs), { recursive: true })
+      fs.writeFileSync(abs, entry.content ?? '')
+    }
+    created.push(entry.path)
+  }
+
+  return { created, skipped }
+}
+
+function template(pack, rel) {
+  try {
+    return fs.readFileSync(new URL(`${pack}/${rel}`, TEMPLATES), 'utf8')
+  } catch {
+    return ''
+  }
+}
+
+function render(text, vars) {
+  return text.replace(/\{\{(\w+)\}\}/g, (_, key) => vars[key] ?? '')
+}
+
+function toPackageId(name) {
+  if (!name) return '<package>'
+  return name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}

package/src/plan.mjs

@@ -0,0 +1,35 @@
+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.',
+  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.',
+}
+
+const VERIFY = {
+  A2: 'codecraft check --pack library',
+  A4: 'codecraft check --pack app',
+  A11: 'codecraft check --pack library',
+  A17: 'codecraft check --pack app',
+}
+
+export function buildPlan(findings) {
+  return findings.map((finding, index) => ({
+    id: `P${index + 1}`,
+    rule: finding.rule,
+    severity: finding.severity,
+    file: finding.file,
+    line: finding.line,
+    action: ACTIONS[finding.rule] ?? 'Review and fix according to the code constitution.',
+    verification: VERIFY[finding.rule] ?? 'codecraft check',
+  }))
+}
+
+export function summarizePlan(findings) {
+  const counts = new Map()
+  for (const finding of findings) {
+    counts.set(finding.rule, (counts.get(finding.rule) ?? 0) + 1)
+  }
+  return [...counts.entries()]
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([rule, count]) => ({ rule, count }))
+}

package/templates/README.md

@@ -0,0 +1,11 @@
+# Templates
+
+`init --apply` 使用的项目骨架。占位符：`{{name}}`（展示名）/ `{{id}}`（package.json 名）。
+
+| 目录 | 内容 |
+|---|---|
+| `app/` | 应用骨架：`README.md` + `package.json` |
+| `library/` | 包骨架：`README.md` + `CHANGELOG.md` + `compat.md` + `package.json` |
+
+- 目录结构由 `src/init.mjs` 定义，模板只提供文件内容。
+- 页面 / 组件 / Wrapper 的单文件形态见 `docs/01-family-cards.md`，不单独出模板：不同框架的写法差异大于共性。

package/templates/app/README.md

@@ -0,0 +1,28 @@
+# {{name}}
+
+> 应用骨架。边界约定见 codecraft 宪法 A4（单一收口）/ A17（内外分离）。
+
+## 目录
+
+| 目录 | 职责 |
+|---|---|
+| `src/pages` | 页面：一个页面一个编排入口，只编排 |
+| `src/components` | 展示与交互组件；原语薄、业务组件按域 |
+| `src/behavior` | 页面无关行为（hooks / composables） |
+| `src/api` | 请求收口；唯一可接触 `external/` 的层 |
+| `src/adapters` | 平台适配（请求 / 存储 / 路由 / 导出） |
+| `src/types` | 内部类型：通用层与业务层 |
+| `src/external` | 外部契约（后端 / 第三方）原文或生成物 |
+
+## 规则
+
+- `pages / components / behavior` 不 import `external/` 或 `generated/`。
+- 外部类型只在 `api` / `adapters` 内转成内部类型。
+- 鉴权失效、错误提示、分页各一处收口。
+- 状态用联合类型；非法状态不可表示。
+
+## 验证
+
+```bash
+codecraft check --pack app
+```

package/templates/app/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "{{id}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "check": "codecraft check --pack app"
+  }
+}

package/templates/library/CHANGELOG.md

@@ -0,0 +1,3 @@
+# Changelog
+
+## Unreleased

package/templates/library/README.md

@@ -0,0 +1,26 @@
+# {{name}}
+
+> 代码包骨架。边界约定见 codecraft 宪法 A2（依赖向内）/ A11（生成物只读）。
+
+## 结构
+
+| 路径 | 职责 |
+|---|---|
+| `src/` | 实现；对外只暴露 public contract |
+| `tests/` | 测试：契约 / 单元 |
+| `compat.md` | 兼容矩阵：支持范围与不可用能力 |
+| `CHANGELOG.md` | 版本变更 |
+
+## 规则
+
+- 不 import 上层应用（`apps/`）。
+- 不通过相对路径逃出自身目录。
+- 依赖必须写进 `package.json`。
+- 生成物必须有「勿手改 / 派生」标记。
+- 破坏性变更升 major；发布不覆盖。
+
+## 验证
+
+```bash
+codecraft check --pack library
+```

package/templates/library/compat.md

@@ -0,0 +1,5 @@
+# 兼容矩阵
+
+| 依赖 / 平台 | 支持范围 | 不可用能力 | 说明 |
+|---|---|---|---|
+| — | — | — | 待填写 |

package/templates/library/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "{{id}}",
+  "version": "0.0.0",
+  "private": true,
+  "files": [
+    "src"
+  ],
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "check": "codecraft check --pack library"
+  }
+}