kld-sdd 2.6.7 → 2.6.9

package/skywalk-sdd/ontology/naming-diagnose.cjs

@@ -0,0 +1,594 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const changeKey = require('./change-key.cjs');
+const modules = require('./modules.cjs');
+const sddConfig = require('./sdd-config.cjs');
+const activeChanges = require('./active-changes.cjs');
+const { parseFrontmatter } = require('./artifact-parser.cjs');
+const workspaceLayout = require('./workspace-layout.cjs');
+
+const STATUS = {
+  PASS: 'PASS',
+  FIXABLE: 'FIXABLE',
+  NEEDS_INPUT: 'NEEDS_INPUT',
+  FAIL: 'FAIL',
+  SKIP: 'SKIP',
+};
+
+function parseAffectedModules(lines) {
+  const result = [];
+  if (!lines.length || lines[0].trim() !== '---') return result;
+  let inList = false;
+  for (let index = 1; index < lines.length; index += 1) {
+    const line = lines[index].replace(/\r$/, '');
+    if (line.trim() === '---') break;
+    if (/^affected-modules:\s*$/i.test(line)) {
+      inList = true;
+      continue;
+    }
+    if (inList) {
+      const item = /^\s*-\s+(.+?)\s*$/.exec(line);
+      if (item) {
+        result.push(item[1].trim().toLowerCase());
+        continue;
+      }
+      if (/^\S/.test(line)) inList = false;
+    }
+  }
+  return result;
+}
+
+function readProposalFrontmatter(changeDir) {
+  const proposalPath = path.join(changeDir, 'proposal.md');
+  if (!fs.existsSync(proposalPath)) {
+    return { ok: false, message: `proposal.md 不存在: ${proposalPath}`, path: proposalPath };
+  }
+  const lines = fs.readFileSync(proposalPath, 'utf8').split(/\r?\n/);
+  const flat = parseFrontmatter(lines);
+  flat['affected-modules'] = parseAffectedModules(lines);
+  return {
+    ok: true,
+    path: proposalPath,
+    frontmatter: flat,
+  };
+}
+
+function detectEntryMode(projectRoot) {
+  const hasModules = fs.existsSync(path.join(projectRoot, 'modules.yaml'));
+  const hasOpenspecChanges = fs.existsSync(path.join(projectRoot, 'openspec', 'changes'));
+  const hasSddYaml = fs.existsSync(path.join(projectRoot, '.sdd.yaml'));
+  if (hasSddYaml && !hasOpenspecChanges) return 'code-repo';
+  if (hasModules || hasOpenspecChanges) return 'spec-repo';
+  if (hasSddYaml) return 'code-repo';
+  return 'unknown';
+}
+
+function checkHookInstalled(projectRoot) {
+  const hookPath = path.join(projectRoot, '.git', 'hooks', 'commit-msg');
+  const scriptPath = path.join(projectRoot, 'skywalk-sdd', 'git-hooks', 'commit-msg-sdd-trailer.cjs');
+  if (!fs.existsSync(path.join(projectRoot, '.git'))) {
+    return { status: STATUS.SKIP, message: '非 Git 仓库，跳过 Hook 检查' };
+  }
+  if (!fs.existsSync(scriptPath)) {
+    return {
+      status: STATUS.FIXABLE,
+      code: 'HOOK_SCRIPT_MISSING',
+      message: 'commit-msg 脚本未部署，可重新执行 kld-sdd-init 或手动复制模板',
+      fix: { type: 'deploy-hook-script' },
+    };
+  }
+  if (!fs.existsSync(hookPath)) {
+    return {
+      status: STATUS.FIXABLE,
+      code: 'HOOK_NOT_INSTALLED',
+      message: 'commit-msg Hook 未安装',
+      fix: { type: 'install-commit-msg-hook' },
+    };
+  }
+  const content = fs.readFileSync(hookPath, 'utf8');
+  if (!content.includes('commit-msg-sdd-trailer') && !content.includes('KLD SDD')) {
+    return {
+      status: STATUS.NEEDS_INPUT,
+      code: 'HOOK_UNKNOWN',
+      message: '已存在自定义 commit-msg Hook，需确认是否接入 SDD Trailer',
+    };
+  }
+  return { status: STATUS.PASS, message: 'commit-msg Hook 已安装' };
+}
+
+function diagnoseChangeNaming(projectRoot, changeName, registry) {
+  const changeDir = path.join(projectRoot, 'openspec', 'changes', changeName);
+  if (!fs.existsSync(changeDir)) {
+    return {
+      status: STATUS.FAIL,
+      code: 'CHANGE_DIR_MISSING',
+      message: `change 目录不存在: ${changeName}`,
+    };
+  }
+
+  const proposal = readProposalFrontmatter(changeDir);
+  if (!proposal.ok) {
+    return { status: STATUS.FAIL, code: 'PROPOSAL_MISSING', message: proposal.message };
+  }
+
+  const fm = proposal.frontmatter;
+  const title = fm.title || '';
+  const module = (fm.module || '').toLowerCase();
+  const key = (fm['change-key'] || '').toLowerCase();
+  const changeId = fm['change-id'] || '';
+  const affected = Array.isArray(fm['affected-modules']) ? fm['affected-modules'] : [];
+
+  const issues = [];
+  const legacy = !key && !module && !title;
+
+  if (legacy) {
+    return {
+      status: STATUS.PASS,
+      code: 'LEGACY_CHANGE',
+      message: '存量 change 缺少 change-key/title/module，归入未分类（兼容）',
+      legacy: true,
+      frontmatter: fm,
+    };
+  }
+
+  if (!title) issues.push({ status: STATUS.FAIL, code: 'TITLE_MISSING', message: 'proposal 缺少 title' });
+  if (!module) issues.push({ status: STATUS.FAIL, code: 'MODULE_MISSING', message: 'proposal 缺少 module' });
+  if (!key) issues.push({ status: STATUS.FAIL, code: 'CHANGE_KEY_MISSING', message: 'proposal 缺少 change-key' });
+  if (!changeId) issues.push({ status: STATUS.FAIL, code: 'CHANGE_ID_MISSING', message: 'proposal 缺少 change-id' });
+
+  if (key && key !== changeName.toLowerCase()) {
+    issues.push({
+      status: STATUS.FAIL,
+      code: 'CHANGE_KEY_DIR_MISMATCH',
+      message: `目录名与 change-key 不一致: ${changeName} vs ${key}`,
+    });
+  }
+
+  if (key) {
+    const registered = registry && registry.ok ? registry.codes : null;
+    const validated = changeKey.validate(key, { registeredModules: registered });
+    if (!validated.ok) {
+      issues.push({
+        status: STATUS.FAIL,
+        code: validated.code,
+        message: validated.message,
+      });
+    } else if (module && validated.parts.module !== module) {
+      issues.push({
+        status: STATUS.NEEDS_INPUT,
+        code: 'MODULE_PREFIX_CONFLICT',
+        message: `change-key 模块前缀 (${validated.parts.module}) 与 proposal module (${module}) 冲突`,
+      });
+    }
+  }
+
+  if (module && registry && registry.ok && !modules.hasModule(registry, module)) {
+    issues.push({
+      status: STATUS.NEEDS_INPUT,
+      code: 'MODULE_UNREGISTERED',
+      message: `module=${module} 未在 modules.yaml 注册`,
+      candidates: Object.keys(registry.modules),
+    });
+  }
+
+  if (module === changeKey.RESERVED_CROSS) {
+    const list = affected.filter(Boolean);
+    if (list.length < 2) {
+      issues.push({
+        status: STATUS.NEEDS_INPUT,
+        code: 'AFFECTED_MODULES_REQUIRED',
+        message: 'module=cross 时 affected-modules 至少需要两个已注册模块',
+      });
+    } else if (registry && registry.ok) {
+      for (const code of list) {
+        if (!modules.hasModule(registry, code)) {
+          issues.push({
+            status: STATUS.NEEDS_INPUT,
+            code: 'AFFECTED_MODULE_UNREGISTERED',
+            message: `affected-modules 含未注册模块: ${code}`,
+          });
+        }
+      }
+    }
+  }
+
+  if (key && changeId) {
+    const expected = `CHG-${key.toUpperCase()}`;
+    if (changeId !== expected && !/^CHG-/i.test(changeId)) {
+      issues.push({
+        status: STATUS.FAIL,
+        code: 'CHANGE_ID_FORMAT',
+        message: `change-id 必须以 CHG- 开头: ${changeId}`,
+      });
+    }
+    // 创建后 change-id 可与当前 key 解耦（迁移保留），仅在两者可派生且不一致时提示，不自动改
+    if (changeId !== expected && /^CHG-/i.test(changeId)) {
+      issues.push({
+        status: STATUS.PASS,
+        code: 'CHANGE_ID_IMMUTABLE',
+        message: `change-id 与当前 key 派生值不同（允许迁移保留）: ${changeId}`,
+      });
+    }
+  }
+
+  const hard = issues.filter((item) => item.status === STATUS.FAIL || item.status === STATUS.NEEDS_INPUT);
+  if (hard.length === 0) {
+    return {
+      status: STATUS.PASS,
+      message: 'Change 命名配置完整',
+      frontmatter: fm,
+      notes: issues,
+    };
+  }
+  const needsInput = hard.some((item) => item.status === STATUS.NEEDS_INPUT);
+  return {
+    status: needsInput ? STATUS.NEEDS_INPUT : STATUS.FAIL,
+    message: hard.map((item) => item.message).join('; '),
+    issues: hard,
+    frontmatter: fm,
+  };
+}
+
+function diagnoseSpecRepo(projectRoot, changeName) {
+  const checks = [];
+  const isGit = fs.existsSync(path.join(projectRoot, '.git'));
+  checks.push({
+    id: 'spec-git',
+    status: isGit ? STATUS.PASS : STATUS.FAIL,
+    message: isGit ? 'spec 仓库是 Git 仓库' : '当前目录不是 Git 仓库',
+  });
+
+  if (isGit) {
+    const remote = sddConfig.gitRemoteUrl(projectRoot);
+    checks.push({
+      id: 'spec-remote',
+      status: remote ? STATUS.PASS : STATUS.NEEDS_INPUT,
+      message: remote ? `remote 可识别: ${remote}` : '无法识别 git remote',
+      remote,
+    });
+  }
+
+  const registry = modules.loadModulesYaml(projectRoot);
+  checks.push({
+    id: 'modules-yaml',
+    status: registry.ok ? STATUS.PASS : (registry.code === modules.CODES.MISSING ? STATUS.NEEDS_INPUT : STATUS.FAIL),
+    message: registry.ok ? `modules.yaml 合法（${registry.codes.size} 个模块）` : registry.message,
+    registry,
+  });
+
+  let naming = null;
+  if (changeName) {
+    naming = diagnoseChangeNaming(projectRoot, changeName, registry.ok ? registry : null);
+    checks.push({
+      id: 'change-naming',
+      status: naming.status,
+      message: naming.message,
+      detail: naming,
+    });
+  } else {
+    checks.push({
+      id: 'change-naming',
+      status: STATUS.SKIP,
+      message: '未指定 --change，跳过命名一致性检查',
+    });
+  }
+
+  checks.push({
+    id: 'active-changes',
+    ...diagnoseActiveChanges(projectRoot, changeName),
+  });
+
+  // 单仓（openspec 与代码同仓）：Hook 装在本仓，应就地检查
+  if (isMonoRepoLayout(projectRoot)) {
+    checks.push({
+      id: 'commit-hook',
+      ...checkHookInstalled(projectRoot),
+    });
+    checks.push({
+      id: 'code-repo-association',
+      status: STATUS.PASS,
+      message: '单仓布局（.sdd.yaml layout: mono）：commit 写 Spec-Change，不写 Spec-Revision',
+    });
+    return {
+      mode: 'mono-repo',
+      checks,
+      summary: summarize(checks),
+    };
+  }
+
+  checks.push({
+    id: 'code-repo-association',
+    status: STATUS.SKIP,
+    message: '当前位于 spec 仓库：代码仓 .sdd.yaml / Hook 请在各代码仓库或工作目录诊断',
+  });
+
+  return {
+    mode: 'spec-repo',
+    checks,
+    summary: summarize(checks),
+  };
+}
+
+/**
+ * 单仓：openspec 与代码同仓，由 .sdd.yaml 的 layout: mono 显式声明。
+ * 不用启发式，否则独立的 spec 仓 clone 会被误判成单仓。
+ */
+function isMonoRepoLayout(projectRoot) {
+  return sddConfig.isMonoLayout(path.resolve(projectRoot));
+}
+
+/**
+ * sdd.config.yaml 活动变更登记表：存在性、格式、当前 change 是否登记、
+ * 以及已归档但仍登记的残留项（会被 Hook 误写成 Spec-Change）。
+ */
+function diagnoseActiveChanges(specRoot, changeName) {
+  const config = activeChanges.loadSddConfig(specRoot);
+
+  if (!config.ok) {
+    if (config.code === activeChanges.CODES.MISSING) {
+      return {
+        status: STATUS.FIXABLE,
+        code: config.code,
+        message: `${activeChanges.FILE_NAME} 不存在：代码仓无法获知活动 change，commit 将缺少 Spec-Change`,
+        fix: { type: 'deploy-sdd-config' },
+      };
+    }
+    return { status: STATUS.FAIL, code: config.code, message: config.message };
+  }
+
+  const stale = config.activeChanges.filter(
+    (entry) => !fs.existsSync(path.join(specRoot, 'openspec', 'changes', entry.changeKey)),
+  );
+  if (stale.length > 0) {
+    return {
+      status: STATUS.FIXABLE,
+      code: 'ACTIVE_CHANGE_STALE',
+      message: `登记项对应目录已不存在（应已归档）: ${stale.map((e) => e.changeKey).join(', ')}`,
+      fix: { type: 'remove-active-change', changes: stale.map((e) => e.changeKey) },
+      activeChanges: config.activeChanges,
+    };
+  }
+
+  if (changeName) {
+    const key = String(changeName).toLowerCase();
+    const registered = config.activeChanges.some((entry) => entry.changeKey === key);
+    if (!registered) {
+      return {
+        status: STATUS.FIXABLE,
+        code: 'ACTIVE_CHANGE_UNREGISTERED',
+        message: `当前 change 未登记到 ${activeChanges.FILE_NAME}: ${key}`,
+        fix: { type: 'register-active-change', change: key },
+        activeChanges: config.activeChanges,
+      };
+    }
+  }
+
+  return {
+    status: STATUS.PASS,
+    message: `活动变更登记表合法（${config.activeChanges.length} 个活动 change）`,
+    activeChanges: config.activeChanges,
+  };
+}
+
+function diagnoseWorkspaceRepos(workspaceRoot) {
+  const root = path.resolve(workspaceRoot);
+  const layout = workspaceLayout.detectWorkspaceLayout(root);
+  if (!layout.isWorkspace) {
+    return {
+      id: 'workspace-repos',
+      status: STATUS.SKIP,
+      message: '非工作区布局，跳过子仓发现',
+    };
+  }
+
+  const unattached = layout.codeRepos.filter((repo) => {
+    const hasYaml = fs.existsSync(path.join(repo.abs, '.sdd.yaml'));
+    const hasHook = fs.existsSync(path.join(repo.abs, '.git', 'hooks', 'commit-msg'));
+    return !hasYaml || !hasHook;
+  });
+
+  if (unattached.length === 0) {
+    return {
+      id: 'workspace-repos',
+      status: STATUS.PASS,
+      message: `工作区代码仓均已轻量接入（${layout.codeRepos.length}）`,
+      layout,
+      unattached: [],
+    };
+  }
+
+  return {
+    id: 'workspace-repos',
+    status: STATUS.NEEDS_INPUT,
+    message: `发现未接入代码仓: ${unattached.map((r) => r.name).join(', ')}。确认后执行 kld-sdd sync-repos`,
+    fix: { type: 'sync-repos', repos: unattached.map((r) => r.name) },
+    layout,
+    unattached,
+  };
+}
+
+function diagnoseCodeRepo(projectRoot) {
+  const checks = [];
+  const sddYaml = sddConfig.loadSddYaml(projectRoot);
+  checks.push({
+    id: 'sdd-yaml',
+    status: sddYaml.ok ? STATUS.PASS : (sddYaml.code === sddConfig.CODES.MISSING ? STATUS.NEEDS_INPUT : STATUS.FAIL),
+    message: sddYaml.ok ? `spec_repository=${sddYaml.spec_repository}` : sddYaml.message,
+    detail: sddYaml,
+  });
+
+  const context = sddConfig.resolveCodeRepoContext(projectRoot);
+  if (!context.specPath) {
+    checks.push({
+      id: 'spec-path',
+      status: STATUS.FIXABLE,
+      code: context.code,
+      message: context.message,
+      fix: { type: 'set-spec-path' },
+    });
+  } else if (context.code === sddConfig.CODES.REMOTE_MISMATCH) {
+    checks.push({
+      id: 'spec-path',
+      status: STATUS.PASS,
+      message: `本地路径有效: ${context.specPath} (${context.specPathSource})`,
+    });
+    checks.push({
+      id: 'remote-match',
+      status: STATUS.NEEDS_INPUT,
+      message: context.message,
+    });
+  } else if (!context.ok && context.code === sddConfig.CODES.SPEC_PATH_INVALID) {
+    checks.push({
+      id: 'spec-path',
+      status: STATUS.FAIL,
+      message: context.message,
+    });
+  } else {
+    checks.push({
+      id: 'spec-path',
+      status: STATUS.PASS,
+      message: `本地路径有效: ${context.specPath} (${context.specPathSource})`,
+    });
+    checks.push({
+      id: 'remote-match',
+      status: context.remoteMatches === false ? STATUS.NEEDS_INPUT : STATUS.PASS,
+      message: context.remoteMatches === false
+        ? context.message
+        : 'spec_repository 与本地 remote 一致或暂无可比对象',
+    });
+  }
+
+  checks.push({
+    id: 'commit-hook',
+    ...checkHookInstalled(projectRoot),
+  });
+
+  checks.push({
+    id: 'trailer-trace',
+    status: STATUS.SKIP,
+    message: 'Trailer 可追溯性：请对具体 commit 使用 diagnose-trailer（默认不扫描全历史）',
+  });
+
+  return {
+    mode: 'code-repo',
+    checks,
+    context,
+    summary: summarize(checks),
+  };
+}
+
+function summarize(checks) {
+  const counts = {
+    PASS: 0,
+    FIXABLE: 0,
+    NEEDS_INPUT: 0,
+    FAIL: 0,
+    SKIP: 0,
+  };
+  for (const item of checks) {
+    counts[item.status] = (counts[item.status] || 0) + 1;
+  }
+  let overall = STATUS.PASS;
+  if (counts.FAIL > 0) overall = STATUS.FAIL;
+  else if (counts.NEEDS_INPUT > 0) overall = STATUS.NEEDS_INPUT;
+  else if (counts.FIXABLE > 0) overall = STATUS.FIXABLE;
+  return { overall, counts };
+}
+
+function formatReport(result) {
+  const lines = [];
+  lines.push('多仓库关联配置');
+  lines.push(`入口: ${result.mode}`);
+  lines.push(`总体: ${result.summary.overall}`);
+  lines.push('');
+  for (const item of result.checks) {
+    lines.push(`${item.id}: ${item.status}`);
+    if (item.message) lines.push(`  ${item.message}`);
+  }
+  return lines.join('\n');
+}
+
+function diagnose(projectRoot, options = {}) {
+  const root = path.resolve(projectRoot || '.');
+  const mode = options.mode || detectEntryMode(root);
+
+  // 个人工作目录：优先做子仓发现
+  const layout = workspaceLayout.detectWorkspaceLayout(root);
+  if (layout.isWorkspace && mode !== 'code-repo') {
+    const checks = [];
+    checks.push(diagnoseWorkspaceRepos(root));
+    if (layout.specRepo) {
+      const specResult = diagnoseSpecRepo(layout.specRepo.abs, options.change);
+      checks.push(...specResult.checks.map((item) => ({ ...item, scope: 'spec-repo' })));
+    }
+    return {
+      mode: 'workspace',
+      checks,
+      layout,
+      summary: summarize(checks),
+    };
+  }
+
+  if (mode === 'code-repo') {
+    return diagnoseCodeRepo(root);
+  }
+  return diagnoseSpecRepo(root, options.change);
+}
+
+function diagnoseTrailer(specRoot, changeKeyValue, revision) {
+  const validated = changeKey.validate(changeKeyValue);
+  if (!validated.ok) {
+    return { ok: false, code: validated.code, message: validated.message };
+  }
+  if (!sddConfig.objectExists(specRoot, revision)) {
+    return {
+      ok: false,
+      code: 'REVISION_MISSING',
+      message: `Spec-Revision 在 spec 仓库中不存在: ${revision}`,
+    };
+  }
+  let treePath;
+  try {
+    treePath = execFileSync(
+      'git',
+      ['ls-tree', '-r', '--name-only', revision, `openspec/changes/${validated.normalized}/proposal.md`],
+      {
+        cwd: specRoot,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      },
+    ).trim();
+  } catch {
+    treePath = '';
+  }
+  if (!treePath) {
+    return {
+      ok: false,
+      code: 'CHANGE_MISSING_AT_REVISION',
+      message: `revision ${revision} 下不存在 openspec/changes/${validated.normalized}/proposal.md`,
+    };
+  }
+  return {
+    ok: true,
+    changeKey: validated.normalized,
+    revision,
+    proposalPath: treePath,
+  };
+}
+
+module.exports = {
+  STATUS,
+  detectEntryMode,
+  readProposalFrontmatter,
+  diagnoseChangeNaming,
+  diagnoseActiveChanges,
+  diagnoseWorkspaceRepos,
+  isMonoRepoLayout,
+  diagnose,
+  diagnoseTrailer,
+  formatReport,
+  summarize,
+};