kld-sdd 2.6.6 → 2.6.8

package/skywalk-sdd/ontology/change-key.cjs

@@ -0,0 +1,241 @@
+'use strict';
+
+/**
+ * Change Key grammar for multi-repo association.
+ * Authority: 本体架构设计方案/10-最小化多仓库关联与变更命名方案.md §2.1 / §2.2
+ */
+
+const CHANGE_KEY_REGEX = /^([a-z][a-z0-9]{1,7})-([0-9]{6})-([a-z0-9]+(?:-[a-z0-9]+)*)$/;
+const MODULE_CODE_REGEX = /^[a-z][a-z0-9]{1,7}$/;
+const SLUG_REGEX = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const SLUG_MAX_LEN = 48;
+const RESERVED_CROSS = 'cross';
+
+const CODES = {
+  FORMAT_INVALID: 'CHANGE_KEY_FORMAT_INVALID',
+  DATE_INVALID: 'CHANGE_KEY_DATE_INVALID',
+  MODULE_INVALID: 'CHANGE_KEY_MODULE_INVALID',
+  SLUG_INVALID: 'CHANGE_KEY_SLUG_INVALID',
+  CONFLICT: 'CHANGE_KEY_CONFLICT',
+};
+
+function pad2(value) {
+  return String(value).padStart(2, '0');
+}
+
+function formatYymmdd(date = new Date()) {
+  const year = date.getFullYear() % 100;
+  const month = date.getMonth() + 1;
+  const day = date.getDate();
+  return `${pad2(year)}${pad2(month)}${pad2(day)}`;
+}
+
+function isValidCalendarYymmdd(yymmdd) {
+  if (!/^[0-9]{6}$/.test(String(yymmdd || ''))) return false;
+  const year = 2000 + Number(yymmdd.slice(0, 2));
+  const month = Number(yymmdd.slice(2, 4));
+  const day = Number(yymmdd.slice(4, 6));
+  if (month < 1 || month > 12 || day < 1 || day > 31) return false;
+  const dt = new Date(year, month - 1, day);
+  return (
+    dt.getFullYear() === year &&
+    dt.getMonth() === month - 1 &&
+    dt.getDate() === day
+  );
+}
+
+function normalizeSlug(raw) {
+  if (raw == null) return '';
+  let slug = String(raw)
+    .trim()
+    .toLowerCase()
+    .replace(/[_\s.]+/g, '-')
+    .replace(/[^a-z0-9-]/g, '')
+    .replace(/-+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  if (slug.length > SLUG_MAX_LEN) {
+    slug = slug.slice(0, SLUG_MAX_LEN).replace(/-+$/g, '');
+  }
+  return slug;
+}
+
+function normalizeModule(raw) {
+  if (raw == null) return '';
+  return String(raw).trim().toLowerCase();
+}
+
+function parse(changeKey) {
+  const key = String(changeKey || '').trim().toLowerCase();
+  const match = CHANGE_KEY_REGEX.exec(key);
+  if (!match) return null;
+  return {
+    changeKey: key,
+    module: match[1],
+    yymmdd: match[2],
+    slug: match[3],
+  };
+}
+
+function validate(changeKey, options = {}) {
+  const key = String(changeKey || '').trim();
+  if (!key) {
+    return { ok: false, code: CODES.FORMAT_INVALID, message: 'change-key 为空' };
+  }
+  if (key !== key.toLowerCase()) {
+    return {
+      ok: false,
+      code: CODES.FORMAT_INVALID,
+      message: `change-key 必须全小写: ${changeKey}`,
+    };
+  }
+  if (/[_\s.]/.test(key) || key.includes('--')) {
+    return {
+      ok: false,
+      code: CODES.FORMAT_INVALID,
+      message: `change-key 禁止下划线、空格、点号或连续连字符: ${changeKey}`,
+    };
+  }
+  if (!CHANGE_KEY_REGEX.test(key)) {
+    return {
+      ok: false,
+      code: CODES.FORMAT_INVALID,
+      message: `change-key 格式不合规: ${changeKey}`,
+    };
+  }
+  const parts = parse(key);
+  if (!parts) {
+    return {
+      ok: false,
+      code: CODES.FORMAT_INVALID,
+      message: `change-key 无法解析: ${changeKey}`,
+    };
+  }
+  if (!isValidCalendarYymmdd(parts.yymmdd)) {
+    return {
+      ok: false,
+      code: CODES.DATE_INVALID,
+      message: `change-key 日期不是真实日历日: ${parts.yymmdd}`,
+    };
+  }
+  if (parts.slug.length > SLUG_MAX_LEN) {
+    return {
+      ok: false,
+      code: CODES.SLUG_INVALID,
+      message: `slug 超过 ${SLUG_MAX_LEN} 字符: ${parts.slug}`,
+    };
+  }
+  const registeredModules = options.registeredModules;
+  if (registeredModules && typeof registeredModules.has === 'function') {
+    if (!registeredModules.has(parts.module)) {
+      return {
+        ok: false,
+        code: CODES.MODULE_INVALID,
+        message: `模块代号未注册: ${parts.module}`,
+      };
+    }
+  } else if (Array.isArray(registeredModules)) {
+    if (!registeredModules.includes(parts.module)) {
+      return {
+        ok: false,
+        code: CODES.MODULE_INVALID,
+        message: `模块代号未注册: ${parts.module}`,
+      };
+    }
+  }
+  return { ok: true, code: null, message: null, normalized: key, parts };
+}
+
+function toChangeId(changeKey) {
+  const result = validate(changeKey);
+  if (!result.ok) {
+    throw new Error(result.message);
+  }
+  return `CHG-${result.normalized.toUpperCase()}`;
+}
+
+function buildChangeKey(moduleCode, slug, options = {}) {
+  const module = normalizeModule(moduleCode);
+  const normalizedSlug = normalizeSlug(slug);
+  const yymmdd = options.yymmdd || formatYymmdd(options.date || new Date());
+
+  if (!MODULE_CODE_REGEX.test(module)) {
+    return {
+      ok: false,
+      code: CODES.MODULE_INVALID,
+      message: `模块代号不合规: ${moduleCode}`,
+    };
+  }
+  if (!SLUG_REGEX.test(normalizedSlug)) {
+    return {
+      ok: false,
+      code: CODES.SLUG_INVALID,
+      message: `slug 不合规: ${slug} → ${normalizedSlug}`,
+    };
+  }
+  if (!isValidCalendarYymmdd(yymmdd)) {
+    return {
+      ok: false,
+      code: CODES.DATE_INVALID,
+      message: `日期不是真实日历日: ${yymmdd}`,
+    };
+  }
+
+  let candidate = `${module}-${yymmdd}-${normalizedSlug}`;
+  const existing = options.existingKeys || new Set();
+  const existingSet = existing instanceof Set
+    ? existing
+    : new Set(Array.from(existing || []).map((item) => String(item).toLowerCase()));
+
+  if (!existingSet.has(candidate)) {
+    const checked = validate(candidate, options);
+    if (!checked.ok) return checked;
+    return {
+      ok: true,
+      changeKey: candidate,
+      changeId: toChangeId(candidate),
+      module,
+      yymmdd,
+      slug: normalizedSlug,
+    };
+  }
+
+  for (let suffix = 2; suffix <= 99; suffix += 1) {
+    candidate = `${module}-${yymmdd}-${normalizedSlug}-${suffix}`;
+    if (existingSet.has(candidate)) continue;
+    const checked = validate(candidate, options);
+    if (!checked.ok) return checked;
+    return {
+      ok: true,
+      changeKey: candidate,
+      changeId: toChangeId(candidate),
+      module,
+      yymmdd,
+      slug: `${normalizedSlug}-${suffix}`,
+      collided: true,
+      suffix,
+    };
+  }
+
+  return {
+    ok: false,
+    code: CODES.CONFLICT,
+    message: `无法为 ${module}-${yymmdd}-${normalizedSlug} 分配可用序号`,
+  };
+}
+
+module.exports = {
+  CHANGE_KEY_REGEX,
+  MODULE_CODE_REGEX,
+  SLUG_REGEX,
+  SLUG_MAX_LEN,
+  RESERVED_CROSS,
+  CODES,
+  formatYymmdd,
+  isValidCalendarYymmdd,
+  normalizeSlug,
+  normalizeModule,
+  parse,
+  validate,
+  toChangeId,
+  buildChangeKey,
+};

package/skywalk-sdd/ontology/cli.cjs

@@ -10,6 +10,13 @@ const {
 } = require('./runtime.cjs');
 const { observeChangeArtifacts } = require('./artifact-observer.cjs');
 const { allocateIdentity } = require('./id.cjs');
+const externalKey = require('./external-key.cjs');
+const changeKey = require('./change-key.cjs');
+const modules = require('./modules.cjs');
+const namingDiagnose = require('./naming-diagnose.cjs');
+const listChanges = require('./list-changes.cjs');
+const sddConfig = require('./sdd-config.cjs');
+const activeChanges = require('./active-changes.cjs');
 
 function parseArgs(argv) {
   const result = { _: [] };
@@ -53,6 +60,16 @@ function showHelp() {
   node skywalk-sdd/ontology/cli.cjs identity  --delta-state=added
   node skywalk-sdd/ontology/cli.cjs identity  --delta-state=modified --entity-id=<uuid> --predecessor-version=<uuid>
   node skywalk-sdd/ontology/cli.cjs identity  --delta-state=unchanged --entity-id=<uuid> --version-id=<uuid>
+  node skywalk-sdd/ontology/cli.cjs external-key --validate <id> --type <requirement|feature|scenario>
+  node skywalk-sdd/ontology/cli.cjs change-key --validate <key>
+  node skywalk-sdd/ontology/cli.cjs change-key --generate --module=<code> --slug=<slug> [--date=yymmdd]
+  node skywalk-sdd/ontology/cli.cjs modules --validate [--project=.]
+  node skywalk-sdd/ontology/cli.cjs diagnose-naming [--project=.] [--change=<key>] [--mode=spec-repo|code-repo]
+  node skywalk-sdd/ontology/cli.cjs list-changes [--project=.] [--json]
+  node skywalk-sdd/ontology/cli.cjs link-spec --path=<spec-clone> [--project=.]
+  node skywalk-sdd/ontology/cli.cjs active-change --register --change=<key> [--title=] [--summary=] [--module=]
+  node skywalk-sdd/ontology/cli.cjs active-change --remove --change=<key>
+  node skywalk-sdd/ontology/cli.cjs active-change --list [--json]
   node skywalk-sdd/ontology/cli.cjs reconcile --project=. --change=<name> [--profile=...]
   node skywalk-sdd/ontology/cli.cjs check     --project=. --change=<name> [--profile=...]
   node skywalk-sdd/ontology/cli.cjs status    --project=. --change=<name>
@@ -73,6 +90,143 @@ function main(argv = process.argv.slice(2)) {
     console.log(JSON.stringify(allocateIdentity(args), null, 2));
     return;
   }
+  if (command === 'external-key') {
+    const id = args.validate || args._[1];
+    const type = args.type || args.t;
+    if (!id || !type) {
+      throw new Error('用法: external-key --validate <id> --type <requirement|feature|scenario>');
+    }
+    const result = externalKey.validate(id, type);
+    console.log(JSON.stringify({
+      ok: result.ok,
+      code: result.code,
+      message: result.message,
+      normalized: externalKey.normalize(id, type),
+      objectType: String(type).toLowerCase(),
+    }, null, 2));
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+  if (command === 'change-key') {
+    if (args.generate || args._[1] === 'generate') {
+      const projectRoot = path.resolve(args.project || '.');
+      const registry = modules.loadModulesYaml(projectRoot);
+      const existing = listChanges.listActiveChanges(projectRoot);
+      const built = changeKey.buildChangeKey(args.module, args.slug, {
+        yymmdd: args.date || args.yymmdd,
+        existingKeys: existing,
+        registeredModules: registry.ok ? registry.codes : null,
+      });
+      console.log(JSON.stringify(built, null, 2));
+      if (!built.ok) process.exitCode = 1;
+      return;
+    }
+    const key = args.validate || args._[1];
+    if (!key) throw new Error('用法: change-key --validate <key> | --generate --module= --slug=');
+    const projectRoot = path.resolve(args.project || '.');
+    const registry = modules.loadModulesYaml(projectRoot);
+    const result = changeKey.validate(key, {
+      registeredModules: registry.ok ? registry.codes : null,
+    });
+    console.log(JSON.stringify({
+      ok: result.ok,
+      code: result.code,
+      message: result.message,
+      normalized: result.normalized || null,
+      changeId: result.ok ? changeKey.toChangeId(result.normalized) : null,
+      parts: result.parts || null,
+    }, null, 2));
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+  if (command === 'modules') {
+    const projectRoot = path.resolve(args.project || '.');
+    const result = modules.loadModulesYaml(projectRoot);
+    console.log(JSON.stringify({
+      ok: result.ok,
+      code: result.code || null,
+      message: result.message || null,
+      path: result.path,
+      version: result.version || null,
+      modules: result.modules || null,
+    }, null, 2));
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+  if (command === 'diagnose-naming') {
+    const projectRoot = path.resolve(args.project || '.');
+    const result = namingDiagnose.diagnose(projectRoot, {
+      change: args.change,
+      mode: args.mode,
+    });
+    if (args.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(namingDiagnose.formatReport(result));
+      console.log('');
+      console.log(JSON.stringify(result.summary, null, 2));
+    }
+    if (result.summary.overall === 'FAIL') process.exitCode = 1;
+    return;
+  }
+  if (command === 'list-changes') {
+    const projectRoot = path.resolve(args.project || '.');
+    const result = listChanges.groupChanges(projectRoot);
+    if (args.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(listChanges.formatGroupedText(result) || '(无活动 change)');
+    }
+    return;
+  }
+  if (command === 'link-spec') {
+    const projectRoot = path.resolve(args.project || '.');
+    const specPath = args.path || args._[1];
+    if (!specPath) throw new Error('用法: link-spec --path=<spec-clone> [--project=.]');
+    const result = sddConfig.setSpecPath(projectRoot, specPath);
+    console.log(JSON.stringify(result, null, 2));
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+  if (command === 'active-change') {
+    const specRoot = path.resolve(args.project || '.');
+    if (args.list || args._[1] === 'list') {
+      const config = activeChanges.loadSddConfig(specRoot);
+      if (args.json) {
+        console.log(JSON.stringify(config, null, 2));
+      } else if (!config.ok) {
+        console.log(config.message);
+      } else if (config.activeChanges.length === 0) {
+        console.log('(无活动 change)');
+      } else {
+        for (const entry of config.activeChanges) {
+          console.log(`● ${entry.title || '(无标题)'}`);
+          console.log(`  ${entry.changeKey}${entry.module ? `  [${entry.module}]` : ''}`);
+          if (entry.summary) console.log(`  ${entry.summary}`);
+        }
+      }
+      if (!config.ok && config.code !== activeChanges.CODES.MISSING) process.exitCode = 1;
+      return;
+    }
+    const key = args.change || args._[1];
+    if (!key) throw new Error('用法: active-change --register|--remove --change=<key> [--project=<spec>]');
+    if (args.remove) {
+      const result = activeChanges.removeActiveChange(specRoot, key);
+      console.log(JSON.stringify(result, null, 2));
+      if (!result.ok) process.exitCode = 1;
+      return;
+    }
+    const result = activeChanges.registerActiveChange(specRoot, {
+      changeKey: key,
+      changeId: args['change-id'] || args.changeId,
+      title: args.title,
+      module: args.module,
+      summary: args.summary,
+    });
+    console.log(JSON.stringify(result, null, 2));
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
   const projectRoot = path.resolve(args.project || '.');
   const changeName = args.change;
   if (!changeName) throw new Error('缺少 --change 参数');

package/skywalk-sdd/ontology/external-key.cjs

@@ -0,0 +1,159 @@
+'use strict';
+
+/**
+ * External key grammar for requirement / feature / scenario.
+ * Authority: kb-sdd docs/superpowers/specs/2026-07-24-external-numbering-kb-sdd-design.md §2.
+ * Regex and normalization MUST stay byte-for-byte aligned with kb-sdd ExternalKeyFormat.java.
+ */
+
+const REGEX = {
+  requirement: /^REQ-[A-Z][A-Z0-9]{1,7}-[0-9]{4}-[0-9]{3,6}$/,
+  feature: /^FEAT-[A-Z][A-Z0-9]{1,7}-[0-9]{3,6}$/,
+  scenario: /^REQ-[A-Z][A-Z0-9]{1,7}-[0-9]{4}-[0-9]{3,6}:SCN-[a-z0-9]+(-[a-z0-9]+)*-[0-9]{3}$/,
+};
+
+const SCENARIO_PARTS =
+  /^(REQ-[A-Z][A-Z0-9]{1,7}-[0-9]{4}-[0-9]{3,6}):SCN-([a-z0-9]+(?:-[a-z0-9]+)*)-([0-9]{3})$/;
+
+const SLUG_MAX_LEN = 40;
+const SCENARIO_KEY_MAX_LEN = 120;
+const SCN_SEQ_MAX = 999;
+
+const CODES = {
+  FORMAT_INVALID: 'EXTERNAL_KEY_FORMAT_INVALID',
+  SCOPE_MISMATCH: 'EXTERNAL_KEY_SCOPE_MISMATCH',
+  FEATURE_UNDECLARED: 'EXTERNAL_KEY_FEATURE_UNDECLARED',
+  SEQ_REUSED: 'EXTERNAL_KEY_SEQ_REUSED',
+  WAIVER_ACTIVE: 'NUMBERING_WAIVER_ACTIVE',
+};
+
+function normalizeObjectType(objectType) {
+  if (objectType == null || String(objectType).trim() === '') return null;
+  return String(objectType).trim().toLowerCase();
+}
+
+function normalize(id, objectType) {
+  if (id == null) return null;
+  const trimmed = String(id).trim();
+  if (!trimmed) return trimmed;
+  const type = normalizeObjectType(objectType);
+  if (type === 'scenario') {
+    const colon = trimmed.indexOf(':');
+    if (colon < 0) return trimmed.toUpperCase();
+    const reqPart = trimmed.slice(0, colon).trim().toUpperCase();
+    const rest = trimmed.slice(colon + 1).trim();
+    if (/^scn-/i.test(rest)) {
+      const afterScn = rest.slice(4);
+      const lastDash = afterScn.lastIndexOf('-');
+      if (lastDash > 0) {
+        const slug = afterScn.slice(0, lastDash).toLowerCase();
+        const seq = afterScn.slice(lastDash + 1);
+        return `${reqPart}:SCN-${slug}-${seq}`;
+      }
+    }
+    return `${reqPart}:${rest.toLowerCase()}`;
+  }
+  return trimmed.toUpperCase();
+}
+
+function validate(id, objectType) {
+  const type = normalizeObjectType(objectType);
+  if (!type || !REGEX[type]) {
+    return {
+      ok: false,
+      code: CODES.FORMAT_INVALID,
+      message: `未知 object_type，无法校验编号: ${objectType}`,
+    };
+  }
+  const normalized = normalize(id, type);
+  if (!normalized) {
+    return { ok: false, code: CODES.FORMAT_INVALID, message: 'external_id 为空' };
+  }
+  if (!REGEX[type].test(normalized)) {
+    return {
+      ok: false,
+      code: CODES.FORMAT_INVALID,
+      message: `编号格式不合规 (${type}): ${id} → ${normalized}`,
+    };
+  }
+  if (type === 'scenario') {
+    const parts = parseScenario(normalized);
+    if (!parts) {
+      return {
+        ok: false,
+        code: CODES.FORMAT_INVALID,
+        message: `场景键无法解析: ${normalized}`,
+      };
+    }
+    if (parts.slug.length > SLUG_MAX_LEN) {
+      return {
+        ok: false,
+        code: CODES.FORMAT_INVALID,
+        message: `场景 SLUG 超过 ${SLUG_MAX_LEN} 字符: ${parts.slug}`,
+      };
+    }
+    if (normalized.length > SCENARIO_KEY_MAX_LEN) {
+      return {
+        ok: false,
+        code: CODES.FORMAT_INVALID,
+        message: `场景键总长超过 ${SCENARIO_KEY_MAX_LEN} 字符`,
+      };
+    }
+  }
+  return { ok: true, code: null, message: null, normalized };
+}
+
+function parseScenario(key) {
+  const normalized = normalize(key, 'scenario');
+  if (!normalized) return null;
+  const match = SCENARIO_PARTS.exec(normalized);
+  if (!match) return null;
+  return {
+    requirementId: match[1],
+    slug: match[2],
+    seq: Number(match[3]),
+  };
+}
+
+function composeScenario(reqId, slug, seq) {
+  const req = normalize(reqId, 'requirement');
+  const normalizedSlug = String(slug || '').trim().toLowerCase();
+  const n = Number(seq);
+  if (!Number.isInteger(n) || n < 1 || n > SCN_SEQ_MAX) {
+    throw new Error(`SCN 序号必须在 1..${SCN_SEQ_MAX} 之间: ${seq}`);
+  }
+  const composed = `${req}:SCN-${normalizedSlug}-${String(n).padStart(3, '0')}`;
+  const result = validate(composed, 'scenario');
+  if (!result.ok) throw new Error(result.message);
+  return composed;
+}
+
+function nextScenarioSeq(reqId, usedKeys) {
+  const req = normalize(reqId, 'requirement');
+  let max = 0;
+  for (const key of usedKeys || []) {
+    const parts = parseScenario(key);
+    if (!parts) continue;
+    if (parts.requirementId === req) {
+      max = Math.max(max, parts.seq);
+    }
+  }
+  if (max >= SCN_SEQ_MAX) {
+    throw new Error(`SCN 序号已用尽 (999)，请回需求管理系统拆分需求: ${req}`);
+  }
+  return max + 1;
+}
+
+module.exports = {
+  REGEX,
+  CODES,
+  SLUG_MAX_LEN,
+  SCENARIO_KEY_MAX_LEN,
+  SCN_SEQ_MAX,
+  normalize,
+  validate,
+  parseScenario,
+  composeScenario,
+  nextScenarioSeq,
+  normalizeObjectType,
+};

package/skywalk-sdd/ontology/list-changes.cjs

@@ -0,0 +1,110 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const modules = require('./modules.cjs');
+const { readProposalFrontmatter } = require('./naming-diagnose.cjs');
+
+function listActiveChanges(projectRoot) {
+  const changesDir = path.join(projectRoot, 'openspec', 'changes');
+  if (!fs.existsSync(changesDir)) return [];
+
+  return fs.readdirSync(changesDir)
+    .filter((name) => {
+      if (name === 'archive' || name.startsWith('.')) return false;
+      const full = path.join(changesDir, name);
+      return fs.statSync(full).isDirectory();
+    })
+    .sort();
+}
+
+function describeChange(projectRoot, changeName, registry) {
+  const changeDir = path.join(projectRoot, 'openspec', 'changes', changeName);
+  const proposal = readProposalFrontmatter(changeDir);
+  const fm = proposal.ok ? proposal.frontmatter : {};
+  const moduleCode = (fm.module || '').toLowerCase();
+  const title = fm.title || '';
+  const changeKey = (fm['change-key'] || '').toLowerCase() || changeName;
+  const affected = Array.isArray(fm['affected-modules']) ? fm['affected-modules'] : [];
+  const legacy = !fm.module && !fm.title && !fm['change-key'];
+
+  let groupCode = 'uncategorized';
+  let groupName = '未分类';
+  if (!legacy && moduleCode) {
+    groupCode = moduleCode;
+    groupName = modules.getModuleName(registry, moduleCode) || moduleCode;
+  }
+
+  return {
+    changeKey,
+    directory: changeName,
+    title: title || changeName,
+    module: moduleCode || null,
+    affectedModules: affected,
+    changeId: fm['change-id'] || null,
+    legacy,
+    groupCode,
+    groupName,
+    hasProposal: proposal.ok,
+  };
+}
+
+function groupChanges(projectRoot) {
+  const registry = modules.loadModulesYaml(projectRoot);
+  const names = listActiveChanges(projectRoot);
+  const items = names.map((name) => describeChange(projectRoot, name, registry.ok ? registry : null));
+
+  const groups = new Map();
+  for (const item of items) {
+    if (!groups.has(item.groupCode)) {
+      groups.set(item.groupCode, {
+        code: item.groupCode,
+        name: item.groupName,
+        changes: [],
+      });
+    }
+    groups.get(item.groupCode).changes.push(item);
+  }
+
+  const ordered = [];
+  if (registry.ok) {
+    for (const code of Object.keys(registry.modules)) {
+      if (groups.has(code)) ordered.push(groups.get(code));
+    }
+  }
+  for (const [code, group] of groups.entries()) {
+    if (!ordered.find((item) => item.code === code)) {
+      ordered.push(group);
+    }
+  }
+
+  return {
+    registryOk: registry.ok,
+    modulesPath: registry.path || path.join(projectRoot, 'modules.yaml'),
+    groups: ordered,
+    changes: items,
+  };
+}
+
+function formatGroupedText(result) {
+  const lines = [];
+  for (const group of result.groups) {
+    lines.push(`${group.name} (${group.code})`);
+    for (const change of group.changes) {
+      lines.push(`  ● ${change.title}`);
+      lines.push(`    ${change.changeKey}`);
+      if (change.module === 'cross' && change.affectedModules.length) {
+        lines.push(`    affected: ${change.affectedModules.join(', ')}`);
+      }
+    }
+    lines.push('');
+  }
+  return lines.join('\n').trimEnd();
+}
+
+module.exports = {
+  listActiveChanges,
+  describeChange,
+  groupChanges,
+  formatGroupedText,
+};