kld-sdd 2.6.6 → 2.6.8

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

@@ -0,0 +1,297 @@
+'use strict';
+
+/**
+ * sdd.config.yaml —— spec 仓库根目录的活动变更登记表。
+ *
+ * 唯一职责：让所有已接入代码仓（经 sdd.specPath 读到同一份 spec clone）
+ * 拿到当前活动 change 的 key / 中文标题 / 摘要，供 AI 参考，
+ * 并供 commit-msg Hook 写入 Spec-Change Trailer（可多条）。
+ *
+ * 不承载：代码仓清单、路径 glob、CI 配置、本地绝对路径。
+ */
+
+const fs = require('fs');
+const path = require('path');
+const changeKey = require('./change-key.cjs');
+
+const FILE_NAME = 'sdd.config.yaml';
+
+const CODES = {
+  MISSING: 'SDD_CONFIG_MISSING',
+  FORMAT_INVALID: 'SDD_CONFIG_FORMAT_INVALID',
+  CHANGE_KEY_INVALID: 'SDD_CONFIG_CHANGE_KEY_INVALID',
+};
+
+const FIELD_ALIASES = {
+  'change-key': 'changeKey',
+  'change-id': 'changeId',
+  title: 'title',
+  module: 'module',
+  summary: 'summary',
+};
+
+function stripQuotes(value) {
+  const text = String(value == null ? '' : value).trim();
+  if (
+    (text.startsWith('"') && text.endsWith('"') && text.length >= 2) ||
+    (text.startsWith("'") && text.endsWith("'") && text.length >= 2)
+  ) {
+    return text.slice(1, -1);
+  }
+  return text;
+}
+
+function needsQuotes(value) {
+  return /^[\s]|[:#]|[\s]$/.test(value);
+}
+
+function quoteIfNeeded(value) {
+  const text = String(value == null ? '' : value);
+  if (!text) return '""';
+  if (needsQuotes(text)) return `"${text.replace(/"/g, '\\"')}"`;
+  return text;
+}
+
+/**
+ * Minimal parser for the constrained schema:
+ *
+ * version: 1
+ * active_changes:
+ *   - change-key: fi-260727-account-doc-head-create
+ *     change-id: CHG-FI-260727-ACCOUNT-DOC-HEAD-CREATE
+ *     title: 会计凭证头创建
+ *     module: fi
+ *     summary: 支持凭证头创建与校验
+ */
+function parseSddConfigYaml(text) {
+  const lines = String(text || '').split(/\r?\n/);
+  const activeChanges = [];
+  let version = null;
+  let inActive = false;
+  let current = null;
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const raw = lines[index];
+    const line = raw.replace(/#.*$/, '').replace(/\s+$/, '');
+    if (!line.trim()) continue;
+
+    const versionMatch = /^version:\s*(\d+)\s*$/.exec(line);
+    if (versionMatch) {
+      version = Number(versionMatch[1]);
+      inActive = false;
+      current = null;
+      continue;
+    }
+
+    if (/^active_changes:\s*(\[\s*\])?\s*$/.test(line)) {
+      inActive = true;
+      current = null;
+      continue;
+    }
+
+    if (!inActive) {
+      return {
+        ok: false,
+        code: CODES.FORMAT_INVALID,
+        message: `${FILE_NAME} 第 ${index + 1} 行无法解析: ${raw}`,
+      };
+    }
+
+    const itemMatch = /^ {2}-\s+([a-z-]+):\s*(.*)$/.exec(line);
+    if (itemMatch) {
+      const field = FIELD_ALIASES[itemMatch[1]];
+      if (!field) {
+        return {
+          ok: false,
+          code: CODES.FORMAT_INVALID,
+          message: `${FILE_NAME} 第 ${index + 1} 行存在未知字段: ${itemMatch[1]}`,
+        };
+      }
+      current = {};
+      current[field] = stripQuotes(itemMatch[2]);
+      activeChanges.push(current);
+      continue;
+    }
+
+    const fieldMatch = /^ {4}([a-z-]+):\s*(.*)$/.exec(line);
+    if (fieldMatch && current) {
+      const field = FIELD_ALIASES[fieldMatch[1]];
+      if (!field) {
+        return {
+          ok: false,
+          code: CODES.FORMAT_INVALID,
+          message: `${FILE_NAME} 第 ${index + 1} 行存在未知字段: ${fieldMatch[1]}`,
+        };
+      }
+      current[field] = stripQuotes(fieldMatch[2]);
+      continue;
+    }
+
+    return {
+      ok: false,
+      code: CODES.FORMAT_INVALID,
+      message: `${FILE_NAME} 第 ${index + 1} 行无法解析: ${raw}`,
+    };
+  }
+
+  if (version == null) {
+    return {
+      ok: false,
+      code: CODES.FORMAT_INVALID,
+      message: `${FILE_NAME} 缺少 version`,
+    };
+  }
+  if (version !== 1) {
+    return {
+      ok: false,
+      code: CODES.FORMAT_INVALID,
+      message: `不支持的 ${FILE_NAME} version: ${version}`,
+    };
+  }
+
+  for (const entry of activeChanges) {
+    if (!entry.changeKey) {
+      return {
+        ok: false,
+        code: CODES.FORMAT_INVALID,
+        message: `${FILE_NAME} 存在缺少 change-key 的条目`,
+      };
+    }
+    const validated = changeKey.validate(entry.changeKey);
+    if (!validated.ok) {
+      return {
+        ok: false,
+        code: CODES.CHANGE_KEY_INVALID,
+        message: `${FILE_NAME} change-key 不合规: ${validated.message}`,
+      };
+    }
+    entry.changeKey = validated.normalized;
+  }
+
+  return { ok: true, version, activeChanges };
+}
+
+function configPath(specRoot) {
+  return path.join(specRoot, FILE_NAME);
+}
+
+function loadSddConfig(specRoot) {
+  const filePath = configPath(specRoot);
+  if (!fs.existsSync(filePath)) {
+    return {
+      ok: false,
+      code: CODES.MISSING,
+      message: `${FILE_NAME} 不存在: ${filePath}`,
+      path: filePath,
+      activeChanges: [],
+    };
+  }
+  const parsed = parseSddConfigYaml(fs.readFileSync(filePath, 'utf8'));
+  return { ...parsed, path: filePath, activeChanges: parsed.activeChanges || [] };
+}
+
+function serializeSddConfig(activeChanges) {
+  const header = [
+    '# 活动变更登记表（spec 仓库根目录）',
+    '# 由 opsx-propose 隐式写入、opsx-archive 隐式移除，供代码仓 AI 与 commit-msg Hook 读取。',
+    '# 不登记代码仓清单、路径 glob 或 CI 配置。',
+    'version: 1',
+    '',
+    'active_changes:',
+  ];
+  if (!activeChanges || activeChanges.length === 0) {
+    return `${header.join('\n')}\n`;
+  }
+  const body = [];
+  for (const entry of activeChanges) {
+    body.push(`  - change-key: ${entry.changeKey}`);
+    if (entry.changeId) body.push(`    change-id: ${entry.changeId}`);
+    if (entry.title) body.push(`    title: ${quoteIfNeeded(entry.title)}`);
+    if (entry.module) body.push(`    module: ${entry.module}`);
+    if (entry.summary) body.push(`    summary: ${quoteIfNeeded(entry.summary)}`);
+  }
+  return `${header.concat(body).join('\n')}\n`;
+}
+
+function writeSddConfig(specRoot, activeChanges) {
+  const filePath = configPath(specRoot);
+  fs.writeFileSync(filePath, serializeSddConfig(activeChanges), 'utf8');
+  return { ok: true, path: filePath, count: activeChanges.length };
+}
+
+/**
+ * Upsert one active change (idempotent by change-key).
+ */
+function registerActiveChange(specRoot, entry) {
+  const validated = changeKey.validate(entry && entry.changeKey);
+  if (!validated.ok) {
+    return { ok: false, code: CODES.CHANGE_KEY_INVALID, message: validated.message };
+  }
+  const key = validated.normalized;
+
+  const existing = loadSddConfig(specRoot);
+  if (!existing.ok && existing.code !== CODES.MISSING) {
+    return existing;
+  }
+
+  const next = {
+    changeKey: key,
+    changeId: entry.changeId || changeKey.toChangeId(key),
+    title: entry.title || '',
+    module: entry.module || changeKey.parse(key).module,
+    summary: entry.summary || '',
+  };
+
+  const list = existing.activeChanges.slice();
+  const at = list.findIndex((item) => item.changeKey === key);
+  if (at >= 0) {
+    list[at] = { ...list[at], ...next };
+  } else {
+    list.push(next);
+  }
+
+  const written = writeSddConfig(specRoot, list);
+  return {
+    ok: true,
+    path: written.path,
+    registered: next,
+    activeChanges: list,
+    updated: at >= 0,
+  };
+}
+
+function removeActiveChange(specRoot, keyInput) {
+  const key = String(keyInput || '').trim().toLowerCase();
+  const existing = loadSddConfig(specRoot);
+  if (!existing.ok && existing.code !== CODES.MISSING) {
+    return existing;
+  }
+  const list = existing.activeChanges.filter((item) => item.changeKey !== key);
+  const removed = list.length !== existing.activeChanges.length;
+  if (removed) {
+    writeSddConfig(specRoot, list);
+  }
+  return { ok: true, removed, activeChanges: list, path: configPath(specRoot) };
+}
+
+/**
+ * Ordered change-keys for Spec-Change trailers (may be multiple).
+ */
+function activeChangeKeys(specRoot) {
+  const config = loadSddConfig(specRoot);
+  if (!config.ok) return [];
+  return config.activeChanges.map((entry) => entry.changeKey);
+}
+
+module.exports = {
+  FILE_NAME,
+  CODES,
+  parseSddConfigYaml,
+  serializeSddConfig,
+  loadSddConfig,
+  writeSddConfig,
+  registerActiveChange,
+  removeActiveChange,
+  activeChangeKeys,
+  configPath,
+};

package/skywalk-sdd/ontology/archive-package.cjs

@@ -101,26 +101,107 @@ function requiredText(value, field, owner) {
 }
 
 function normalizeExternalRefs(refs) {
+  const { normalize } = require('./external-key.cjs');
   if (!Array.isArray(refs)) return [];
   const seen = new Set();
   const result = [];
   for (const ref of refs) {
     const system = String(ref.system || ref.system_name || '').trim();
     const objectType = String(ref.object_type || ref.objectType || '').trim().toLowerCase();
-    const externalId = String(ref.external_id || ref.externalId || '').trim();
-    if (!system || !objectType || !externalId) continue;
+    const rawExternalId = String(ref.external_id || ref.externalId || '').trim();
+    if (!system || !objectType || !rawExternalId) continue;
+    const externalId = normalize(rawExternalId, objectType) || rawExternalId;
     const key = `${system}\0${objectType}\0${externalId}`;
     if (seen.has(key)) continue;
     seen.add(key);
-    result.push({
+    const entry = {
       system,
       object_type: objectType,
       external_id: externalId,
-    });
+    };
+    const rawFeatureId = ref.feature_id || ref.featureId;
+    if (rawFeatureId && objectType === 'requirement') {
+      entry.feature_id = normalize(String(rawFeatureId), 'feature') || String(rawFeatureId).trim();
+    }
+    result.push(entry);
   }
   return result;
 }
 
+function expandRequirementRefsWithFeatures(requirementRefs) {
+  const expanded = [];
+  for (const ref of requirementRefs) {
+    expanded.push(ref);
+    if (ref.object_type === 'requirement' && ref.feature_id) {
+      expanded.push({
+        system: ref.system,
+        object_type: 'feature',
+        external_id: ref.feature_id,
+      });
+    }
+  }
+  return normalizeExternalRefs(expanded);
+}
+
+function assertExternalKeyFinalGate(entities) {
+  const {
+    validate,
+    normalize,
+    parseScenario,
+    CODES,
+  } = require('./external-key.cjs');
+  const packageRequirementIds = new Set();
+  for (const entity of entities) {
+    for (const ref of entity.external_refs || []) {
+      if (ref.object_type === 'requirement') {
+        packageRequirementIds.add(normalize(ref.external_id, 'requirement'));
+      }
+    }
+  }
+  for (const entity of entities) {
+    const declaredFeatures = new Set();
+    const featureBindings = new Set();
+    for (const ref of entity.external_refs || []) {
+      const format = validate(ref.external_id, ref.object_type);
+      if (!format.ok) {
+        throw new Error(`${CODES.FORMAT_INVALID}: ${format.message} @ ${entity.anchor_id}`);
+      }
+      if (ref.feature_id) {
+        const featureFormat = validate(ref.feature_id, 'feature');
+        if (!featureFormat.ok) {
+          throw new Error(`${CODES.FORMAT_INVALID}: requirement.feature_id 不合规: ${featureFormat.message} @ ${entity.anchor_id}`);
+        }
+        declaredFeatures.add(normalize(ref.feature_id, 'feature'));
+      }
+      if (ref.object_type === 'feature') {
+        featureBindings.add(normalize(ref.external_id, 'feature'));
+      }
+      if (ref.object_type === 'scenario') {
+        const parts = parseScenario(ref.external_id);
+        if (!parts || !packageRequirementIds.has(parts.requirementId)) {
+          throw new Error(
+            `${CODES.SCOPE_MISMATCH}: 场景键 REQ 前缀不在同包 requirement 绑定集合中: ${ref.external_id} @ ${entity.anchor_id}`,
+          );
+        }
+      }
+    }
+    for (const featureId of featureBindings) {
+      if (!declaredFeatures.has(featureId)) {
+        throw new Error(
+          `${CODES.FEATURE_UNDECLARED}: feature 绑定无法与同实体 requirement.feature_id 配对: ${featureId} @ ${entity.anchor_id}`,
+        );
+      }
+    }
+    for (const featureId of declaredFeatures) {
+      if (!featureBindings.has(featureId)) {
+        throw new Error(
+          `${CODES.FEATURE_UNDECLARED}: requirement 申报了 feature_id 但缺少对应 feature 绑定: ${featureId} @ ${entity.anchor_id}`,
+        );
+      }
+    }
+  }
+}
+
 function canonicalEntity(archiveDir, entity, inheritedRequirementRefs = []) {
   const anchorId = requiredText(entity.anchor_id || entity.id, 'anchor_id', '本体实体').toUpperCase();
   const versionId = requiredText(
@@ -130,8 +211,15 @@ function canonicalEntity(archiveDir, entity, inheritedRequirementRefs = []) {
   ).toLowerCase();
   const entityType = requiredText(entity.type, 'type', anchorId);
   let externalRefs = normalizeExternalRefs(entity.external_refs || entity.externalRefs || []);
-  if (entityType === 'Capability' && inheritedRequirementRefs.length > 0) {
-    externalRefs = normalizeExternalRefs([...externalRefs, ...inheritedRequirementRefs]);
+  if (entityType === 'Capability') {
+    const requirementSources = [
+      ...externalRefs.filter((ref) => ref.object_type === 'requirement'),
+      ...inheritedRequirementRefs,
+    ];
+    externalRefs = normalizeExternalRefs([
+      ...externalRefs,
+      ...expandRequirementRefsWithFeatures(requirementSources),
+    ]);
   }
   return {
     anchor_id: anchorId,
@@ -237,6 +325,7 @@ function buildCanonicalFacts(archiveDir, snapshot, projectId, archiveId) {
   if (entities.length === 0) {
     throw new Error('archive-ontology.json 没有可导出的实体');
   }
+  assertExternalKeyFinalGate(entities);
   const entityByAnchor = new Map(entities.map((entity) => [entity.anchor_id, entity]));
   const warningCounts = new Map();
   const seenRelations = new Set();

package/skywalk-sdd/ontology/artifact-parser.cjs

@@ -201,15 +201,28 @@ function identityFromValues(values = {}) {
 
 function flushRequirementRef(requirementRefs, currentRef) {
   if (!currentRef) return null;
+  const { normalize, validate } = require('./external-key.cjs');
   const system = currentRef.system;
   const objectType = currentRef['object-type'] || currentRef.object_type;
   const externalId = currentRef['external-id'] || currentRef.external_id;
+  const featureId = currentRef['feature-id'] || currentRef.feature_id;
   if (system && objectType && externalId) {
-    requirementRefs.push({
+    const type = String(objectType).toLowerCase();
+    const entry = {
       system,
-      object_type: String(objectType).toLowerCase(),
-      external_id: externalId,
-    });
+      object_type: type,
+      external_id: normalize(externalId, type) || String(externalId).trim(),
+    };
+    if (featureId) {
+      const featureCheck = validate(featureId, 'feature');
+      if (!featureCheck.ok) {
+        entry.feature_id_invalid = featureCheck.message;
+        entry.feature_id_raw = featureId;
+      } else {
+        entry.feature_id = normalize(featureId, 'feature');
+      }
+    }
+    requirementRefs.push(entry);
   }
   return null;
 }
@@ -218,8 +231,10 @@ function parseStructuredFrontmatter(lines) {
   const flat = {};
   const requirementRefs = [];
   const continuity = {};
+  const numberingWaiver = {};
+  let numberingGate = false;
   if (!lines.length || lines[0].trim() !== '---') {
-    return { flat, requirementRefs, continuity };
+    return { flat, requirementRefs, continuity, numberingWaiver, numberingGate };
   }
   let section = null;
   let currentRef = null;
@@ -238,6 +253,13 @@ function parseStructuredFrontmatter(lines) {
       flat[section] = value;
       currentCap = null;
       if (section === 'continuity' && value) continuity.kind = value;
+      if (section === 'numbering-waiver') {
+        numberingGate = true;
+        if (value) numberingWaiver.reason = value;
+      }
+      if (section === 'requirement-refs') {
+        numberingGate = true;
+      }
       continue;
     }
 
@@ -253,6 +275,12 @@ function parseStructuredFrontmatter(lines) {
       continue;
     }
 
+    if (section === 'numbering-waiver' && nested) {
+      const key = nested[1].toLowerCase().replace(/-/g, '_');
+      numberingWaiver[key] = unwrapScalar(stripInlineYamlComment(nested[2]));
+      continue;
+    }
+
     if (section === 'continuity' && nested) {
       const key = nested[1].toLowerCase().replace(/-/g, '_');
       const value = unwrapScalar(stripInlineYamlComment(nested[2]));
@@ -280,7 +308,7 @@ function parseStructuredFrontmatter(lines) {
     }
   }
   flushRequirementRef(requirementRefs, currentRef);
-  return { flat, requirementRefs, continuity };
+  return { flat, requirementRefs, continuity, numberingWaiver, numberingGate };
 }
 
 function parseIdentityBlock(lines, startIndex, endIndex = lines.length) {
@@ -324,6 +352,8 @@ function parseProposal(target, file, lines, frontmatter) {
   target.proposalMode = String(mergedFrontmatter.mode || '').trim().toLowerCase();
   target.requirementRefs = structured.requirementRefs;
   target.continuity = structured.continuity;
+  target.numberingWaiver = structured.numberingWaiver || {};
+  target.numberingGate = Boolean(structured.numberingGate);
   const changeId = String(mergedFrontmatter['change-id'] || '').trim().toUpperCase();
   if (changeId) {
     addEntity(
@@ -355,9 +385,20 @@ function parseProposal(target, file, lines, frontmatter) {
     const capabilityId = match[1].toUpperCase();
     const identity = parseIdentityBlock(lines, index + 1);
     if (structured.requirementRefs.length > 0) {
+      const expanded = [];
+      for (const ref of structured.requirementRefs) {
+        expanded.push(ref);
+        if (ref.feature_id) {
+          expanded.push({
+            system: ref.system,
+            object_type: 'feature',
+            external_id: ref.feature_id,
+          });
+        }
+      }
       identity.external_refs = [
         ...(identity.external_refs || []),
-        ...structured.requirementRefs,
+        ...expanded,
       ];
     }
     const slug = unwrapScalar(match[2]);
@@ -683,6 +724,8 @@ function parseChangeArtifacts(projectRoot, changeName, options = {}) {
     profile: 'simple',
     proposalMode: '',
     requirementRefs: [],
+    numberingWaiver: {},
+    numberingGate: false,
     continuity: {},
     artifacts: [],
     files: files.map((file) => ({ path: file.relativePath, content_hash: file.contentHash })),