kld-sdd 2.7.8 → 2.8.1

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

@@ -0,0 +1,507 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { parseChangeArtifacts } = require('./artifact-parser.cjs');
+const { normalizeFacts } = require('./normalizer.cjs');
+const { resolveChangeDir } = require('./runtime.cjs');
+const { resolveRuntimeMetadata } = require('../runtime-metadata.cjs');
+const { ensureDir, readJsonSafe, writeJsonAtomic } = require('../lib/shared.cjs');
+const { DIAGNOSTIC_CODES } = require('./schema.cjs');
+const { isValidUuid } = require('./id.cjs');
+
+const SPEC_ONTOLOGY_SCHEMA_VERSION = 'kld-sdd-spec-ontology/v1';
+const LEGACY_MAPPING_SCHEMA_VERSION = 'kld-sdd-legacy-identity-mapping/v1';
+const SPEC_ONTOLOGY_PATH = 'spec-ontology.json';
+const LEGACY_MAPPING_PATH = 'ontology/legacy-mapping.json';
+const RUNTIME_METADATA = resolveRuntimeMetadata();
+
+const TYPE_MAP = Object.freeze({
+  BusinessObject: 'BusinessObject',
+  Capability: 'Capability',
+  AcceptanceCriterion: 'Scenario',
+  Constraint: 'Rule',
+  SpecificationStatement: 'SpecPattern',
+});
+
+const RELATION_MAP = Object.freeze({
+  contains: 'contains',
+  usesObject: 'usesObject',
+  acceptedBy: 'verifiedByScenario',
+  verifiedBy: 'verifiedByScenario',
+  constrainedBy: 'constrainedBy',
+  constrains: 'constrainedBy',
+});
+
+// 工具升级后新增的身份、归档和任务校验。历史稿上传遇到这些诊断时旁路物化，
+// 由上传流程自动消解，不把整包失败交回给使用者。
+const LEGACY_TOLERATED_CODES = Object.freeze([
+  DIAGNOSTIC_CODES.UUID_MISSING,
+  DIAGNOSTIC_CODES.UUID_INVALID,
+  DIAGNOSTIC_CODES.ID_MISSING,
+  DIAGNOSTIC_CODES.ID_INVALID,
+  DIAGNOSTIC_CODES.ID_DUPLICATE,
+  DIAGNOSTIC_CODES.DELTA_STATE_INVALID,
+  DIAGNOSTIC_CODES.SOURCE_MISSING,
+  DIAGNOSTIC_CODES.VERSION_LINEAGE_MISSING,
+  DIAGNOSTIC_CODES.ENTITY_IDENTITY_CONFLICT,
+  DIAGNOSTIC_CODES.VERSION_IDENTITY_CONFLICT,
+  DIAGNOSTIC_CODES.INHERITED_SOURCE_MISMATCH,
+  DIAGNOSTIC_CODES.INHERITED_RELATION_MISSING,
+  DIAGNOSTIC_CODES.ARCHIVE_NOT_CONFIRMED,
+  DIAGNOSTIC_CODES.ARCHIVE_REVISION_MISMATCH,
+  DIAGNOSTIC_CODES.TASK_DEPENDENCY_CYCLE,
+  DIAGNOSTIC_CODES.TASK_DEPENDENCY_LAYER_GAP,
+  DIAGNOSTIC_CODES.TASK_DEPENDENCY_MISSING_EDGE,
+  DIAGNOSTIC_CODES.STMT_WITHOUT_AC,
+  DIAGNOSTIC_CODES.STMT_WITHOUT_DESIGN,
+  DIAGNOSTIC_CODES.DESIGN_WITHOUT_TASK,
+  DIAGNOSTIC_CODES.AC_WITHOUT_STMT,
+  DIAGNOSTIC_CODES.TASK_WITHOUT_UPSTREAM,
+]);
+
+// Check 对用户隐藏并自行处理的工具诊断。需求、设计、任务之间的覆盖缺口不在此列。
+const CHECK_TOOL_CODES = Object.freeze([
+  DIAGNOSTIC_CODES.UUID_MISSING,
+  DIAGNOSTIC_CODES.UUID_INVALID,
+  DIAGNOSTIC_CODES.ID_MISSING,
+  DIAGNOSTIC_CODES.ID_INVALID,
+  DIAGNOSTIC_CODES.ID_DUPLICATE,
+  DIAGNOSTIC_CODES.DELTA_STATE_INVALID,
+  DIAGNOSTIC_CODES.SOURCE_MISSING,
+  DIAGNOSTIC_CODES.VERSION_LINEAGE_MISSING,
+  DIAGNOSTIC_CODES.ENTITY_IDENTITY_CONFLICT,
+  DIAGNOSTIC_CODES.VERSION_IDENTITY_CONFLICT,
+  DIAGNOSTIC_CODES.INHERITED_SOURCE_MISMATCH,
+  DIAGNOSTIC_CODES.INHERITED_RELATION_MISSING,
+  DIAGNOSTIC_CODES.ARCHIVE_NOT_CONFIRMED,
+  DIAGNOSTIC_CODES.ARCHIVE_REVISION_MISMATCH,
+]);
+
+function sha256(value) {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+function splitCheckDiagnostics(diagnostics = []) {
+  const tool = [];
+  const product = [];
+  for (const item of diagnostics || []) {
+    if (item && item.severity === 'error' && CHECK_TOOL_CODES.includes(item.code)) tool.push(item);
+    else product.push(item);
+  }
+  return {
+    tool_diagnostics: tool,
+    product_diagnostics: product,
+    product_valid: product.every((item) => !item || item.severity !== 'error'),
+  };
+}
+
+function classifyLegacyDiagnostics(diagnostics = []) {
+  const blocking = (diagnostics || []).filter((item) => item && item.severity === 'error');
+  const tolerated = blocking.filter((item) => LEGACY_TOLERATED_CODES.includes(item.code));
+  const rejected = blocking.filter((item) => !LEGACY_TOLERATED_CODES.includes(item.code));
+  return {
+    blocking,
+    tolerated,
+    rejected,
+    legacyCompatible: blocking.length > 0 && rejected.length === 0,
+  };
+}
+
+// 同一份 Markdown 反复物化时用于判断“已审核本体是否仍对应当前正文”。
+function specOntologyContentSignature(payload) {
+  const entities = (payload?.entities || [])
+    .map((entity) => `${entity.anchor_id}:${entity.content_hash}`)
+    .sort();
+  const relations = (payload?.relations || [])
+    .map((relation) => `${relation.type}:${relation.source?.anchor_id || ''}:${relation.source?.content_hash || ''}`)
+    .sort();
+  return JSON.stringify({ entities, relations });
+}
+
+function withOntologyHash(payload) {
+  const result = { ...payload };
+  delete result.ontology_hash;
+  result.ontology_hash = `sha256:${sha256(JSON.stringify(result))}`;
+  return result;
+}
+
+function deterministicUuid(seed) {
+  const bytes = Buffer.from(sha256(String(seed)).slice(0, 32), 'hex');
+  bytes[6] = (bytes[6] & 0x0f) | 0x50;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = bytes.toString('hex');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+function normalizedText(value) {
+  return String(value || '').trim();
+}
+
+function normalizedAnchor(entity) {
+  return normalizedText(entity.anchor_id || entity.id).toUpperCase();
+}
+
+function semanticKeyFor(entity) {
+  const ontologyType = TYPE_MAP[entity.type];
+  const external = (entity.external_refs || []).find((ref) => (
+    ref && ref.system && ref.object_type && ref.external_id
+  ));
+  if (external) {
+    return `${ontologyType.toLowerCase()}:${normalizedText(external.system).toLowerCase()}`
+      + `:${normalizedText(external.object_type).toLowerCase()}:${normalizedText(external.external_id)}`;
+  }
+  return `${ontologyType.toLowerCase()}:${normalizedAnchor(entity).toLowerCase()}`;
+}
+
+function normalizeSource(source = {}) {
+  const line = Number(source.line || 0);
+  return {
+    artifact_type: normalizedText(source.artifact_type || 'unknown').toLowerCase(),
+    file: normalizedText(source.file),
+    ...(Number.isInteger(line) && line > 0 ? { line } : {}),
+    anchor_id: normalizedText(source.anchor_id).toUpperCase(),
+    ...(source.content_hash ? { content_hash: normalizedText(source.content_hash) } : {}),
+  };
+}
+
+function compatibilityMode(facts, selectedEntities) {
+  if (selectedEntities.length === 0) return 'EVIDENCE_ONLY';
+  const complete = selectedEntities.every((entity) => entity.entity_id && entity.version_id);
+  const sourceSchema = normalizedText(facts.schema_version);
+  if (complete && sourceSchema === SPEC_ONTOLOGY_SCHEMA_VERSION) return 'NATIVE';
+  if (complete) return 'ADAPTED_V2';
+  return 'LEGACY_MATERIALIZED';
+}
+
+function identityFor(entity, projectId, semanticKey, options = {}) {
+  const declaredEntityId = normalizedText(entity.entity_id).toLowerCase();
+  const declaredVersionId = normalizedText(entity.entity_version_id || entity.version_id).toLowerCase();
+  const declaredUsable = isValidUuid(declaredEntityId) && isValidUuid(declaredVersionId);
+  const contentHash = normalizedText(entity.content_hash) || `sha256:${sha256(JSON.stringify(entity))}`;
+  if (!options.repairLegacy || declaredUsable) {
+    return {
+      entity_id: declaredEntityId || deterministicUuid(`${projectId}\n${semanticKey}`),
+      entity_version_id: declaredVersionId || deterministicUuid(`${declaredEntityId || semanticKey}\n${contentHash}`),
+      identity_origin: declaredUsable ? 'declared' : 'derived_legacy',
+      repaired: false,
+    };
+  }
+  return {
+    entity_id: deterministicUuid(`${projectId}\n${semanticKey}`),
+    entity_version_id: deterministicUuid(`${projectId}\n${semanticKey}\n${contentHash}`),
+    identity_origin: 'derived_legacy',
+    repaired: true,
+    repair_reason: declaredEntityId || declaredVersionId ? 'invalid_declared_uuid' : 'missing_uuid',
+  };
+}
+
+function buildSpecOntology(facts, options = {}) {
+  const projectId = normalizedText(options.projectId || facts.project_id || 'urn:kld:sdd:project:unconfigured');
+  const selected = (facts.entities || []).filter((entity) => TYPE_MAP[entity.type]);
+  const mode = options.compatibilityMode || compatibilityMode(facts, selected);
+  const reviewStatus = options.reviewStatus
+    || (mode === 'LEGACY_MATERIALIZED' || mode === 'EVIDENCE_ONLY' ? 'pending' : 'confirmed');
+  const baseKeys = selected.map(semanticKeyFor);
+  const keyCounts = new Map();
+  for (const key of baseKeys) keyCounts.set(key, (keyCounts.get(key) || 0) + 1);
+  const warnings = [];
+  const entities = [];
+  const identityMap = [];
+  const entityByAnchor = new Map();
+
+  for (let index = 0; index < selected.length; index += 1) {
+    const sourceEntity = selected[index];
+    const anchor = normalizedAnchor(sourceEntity);
+    const baseKey = baseKeys[index];
+    const source = normalizeSource(sourceEntity.source);
+    const semanticKey = keyCounts.get(baseKey) > 1
+      ? `${baseKey}@${normalizedText(source.file).toLowerCase() || 'source'}#${index + 1}`
+      : baseKey;
+    if (keyCounts.get(baseKey) > 1) {
+      warnings.push(`LEGACY_DUPLICATE_ANCHOR: ${baseKey} 已按来源路径拆成独立事实，上传不再等待人工合并`);
+    }
+    const repairLegacy = mode === 'LEGACY_MATERIALIZED';
+    let identity = identityFor(sourceEntity, projectId, semanticKey, { repairLegacy });
+    if (repairLegacy && entities.some((item) => item.entity_id === identity.entity_id)) {
+      identity = {
+        entity_id: deterministicUuid(`${projectId}\n${semanticKey}\n${index}`),
+        entity_version_id: deterministicUuid(`${projectId}\n${semanticKey}\n${index}\nversion`),
+        identity_origin: 'derived_legacy',
+        repaired: true,
+        repair_reason: 'entity_id_conflict',
+      };
+    }
+    if (repairLegacy && entities.some((item) => item.entity_version_id === identity.entity_version_id)) {
+      identity = {
+        ...identity,
+        entity_version_id: deterministicUuid(`${identity.entity_id}\n${semanticKey}\n${index}\nversion`),
+        identity_origin: 'derived_legacy',
+        repaired: true,
+        repair_reason: identity.repair_reason || 'version_id_conflict',
+      };
+    }
+    if (identity.repaired) {
+      warnings.push(`LEGACY_IDENTITY_REPAIRED: ${anchor} ${identity.repair_reason}`);
+    }
+    const declaredPredecessor = normalizedText(sourceEntity.predecessor_version_id);
+    const predecessor = repairLegacy || !isValidUuid(declaredPredecessor) ? null : declaredPredecessor;
+    const ontologyEntity = {
+      semantic_key: semanticKey,
+      type: TYPE_MAP[sourceEntity.type],
+      name: normalizedText(sourceEntity.name || anchor),
+      summary: normalizedText(
+        sourceEntity.attributes?.description
+        || sourceEntity.attributes?.summary
+        || sourceEntity.name
+        || anchor,
+      ),
+      anchor_id: anchor,
+      entity_id: identity.entity_id,
+      entity_version_id: identity.entity_version_id,
+      identity_origin: identity.identity_origin,
+      predecessor_version_id: predecessor,
+      content_hash: normalizedText(sourceEntity.content_hash),
+      review_status: reviewStatus,
+      publication_status: reviewStatus === 'confirmed' ? 'publishable' : 'candidate',
+      attributes: {
+        legacy_type: sourceEntity.type,
+        ...(sourceEntity.attributes && typeof sourceEntity.attributes === 'object'
+          ? sourceEntity.attributes : {}),
+      },
+      ...(Array.isArray(sourceEntity.external_refs) && sourceEntity.external_refs.length > 0
+        ? { external_refs: sourceEntity.external_refs } : {}),
+      source,
+    };
+    entities.push(ontologyEntity);
+    entityByAnchor.set(anchor, ontologyEntity);
+    identityMap.push({
+      anchor_id: anchor,
+      semantic_key: semanticKey,
+      entity_id: identity.entity_id,
+      entity_version_id: identity.entity_version_id,
+      identity_origin: identity.identity_origin,
+      source,
+    });
+  }
+
+  const relations = [];
+  const seenRelations = new Set();
+  for (const sourceRelation of facts.relations || []) {
+    let from = entityByAnchor.get(normalizedText(sourceRelation.from).toUpperCase());
+    let to = entityByAnchor.get(normalizedText(sourceRelation.to).toUpperCase());
+    let type = RELATION_MAP[sourceRelation.type];
+    if (!from || !to || !type) continue;
+    if (sourceRelation.type === 'constrains') {
+      [from, to] = [to, from];
+    }
+    const key = `${type}:${from.semantic_key}:${to.semantic_key}`;
+    if (seenRelations.has(key)) continue;
+    seenRelations.add(key);
+    relations.push({
+      type,
+      from_semantic_key: from.semantic_key,
+      to_semantic_key: to.semantic_key,
+      from_entity_id: from.entity_id,
+      to_entity_id: to.entity_id,
+      assertion_type: normalizedText(sourceRelation.assertion_type || 'asserted').toLowerCase(),
+      review_status: reviewStatus,
+      source: normalizeSource(sourceRelation.source),
+    });
+  }
+
+  if (mode === 'LEGACY_MATERIALIZED') {
+    warnings.unshift('LEGACY_IDENTITIES_DERIVED: 历史文档未被改写，身份已物化到旁路映射，发布前需要审核');
+  } else if (mode === 'EVIDENCE_ONLY') {
+    warnings.unshift('NO_STRUCTURED_ONTOLOGY_FACTS: 仅作为可追溯证据入库，不自动发布本体事实');
+  }
+
+  const payload = {
+    schema_version: SPEC_ONTOLOGY_SCHEMA_VERSION,
+    producer: RUNTIME_METADATA.producer,
+    project_id: projectId,
+    ...(options.archiveId ? { archive_id: options.archiveId } : {}),
+    change: normalizedText(facts.change),
+    change_id: normalizedText(facts.change_id) || null,
+    source_schema: normalizedText(facts.schema_version || 'legacy-markdown'),
+    source_facts_hash: normalizedText(facts.facts_hash) || null,
+    compatibility_mode: mode,
+    review_status: reviewStatus,
+    publication_eligible: reviewStatus === 'confirmed' && mode !== 'EVIDENCE_ONLY',
+    entities,
+    relations,
+    identity_map: identityMap,
+    warnings: [...new Set(warnings)],
+  };
+  return withOntologyHash(payload);
+}
+
+function validateSpecOntology(payload) {
+  const errors = [];
+  const warnings = [];
+  if (!payload || payload.schema_version !== SPEC_ONTOLOGY_SCHEMA_VERSION) {
+    errors.push(`schema_version 必须为 ${SPEC_ONTOLOGY_SCHEMA_VERSION}`);
+  }
+  if (!payload?.project_id) errors.push('缺少 project_id');
+  if (!Array.isArray(payload?.entities)) errors.push('entities 必须是数组');
+  if (!Array.isArray(payload?.relations)) errors.push('relations 必须是数组');
+  const keys = new Set();
+  const ids = new Set();
+  for (const entity of payload?.entities || []) {
+    if (!entity.semantic_key) errors.push('实体缺少 semantic_key');
+    if (keys.has(entity.semantic_key)) errors.push(`semantic_key 重复: ${entity.semantic_key}`);
+    keys.add(entity.semantic_key);
+    if (!entity.entity_id || !entity.entity_version_id) {
+      errors.push(`实体缺少内部身份: ${entity.semantic_key || entity.anchor_id}`);
+    }
+    ids.add(entity.entity_id);
+    if (!Object.values(TYPE_MAP).includes(entity.type)) {
+      errors.push(`不支持的本体类型: ${entity.type || '(empty)'}`);
+    }
+  }
+  for (const relation of payload?.relations || []) {
+    if (!keys.has(relation.from_semantic_key) || !keys.has(relation.to_semantic_key)) {
+      errors.push(`关系端点不存在: ${relation.from_semantic_key} -${relation.type}-> ${relation.to_semantic_key}`);
+    }
+  }
+  const identityByKey = new Map((payload?.identity_map || []).map((item) => [item.semantic_key, item]));
+  for (const entity of payload?.entities || []) {
+    const identity = identityByKey.get(entity.semantic_key);
+    if (!identity) {
+      errors.push(`identity_map 缺少实体: ${entity.semantic_key}`);
+    } else if (identity.entity_id !== entity.entity_id || identity.entity_version_id !== entity.entity_version_id) {
+      errors.push(`identity_map 与实体身份不一致: ${entity.semantic_key}`);
+    }
+  }
+  if (payload?.publication_eligible === true) {
+    if (payload.review_status !== 'confirmed') errors.push('可发布本体的 review_status 必须为 confirmed');
+    for (const entity of payload?.entities || []) {
+      if (entity.review_status !== 'confirmed' || entity.publication_status !== 'publishable') {
+        errors.push(`可发布实体状态不完整: ${entity.semantic_key}`);
+      }
+    }
+    for (const relation of payload?.relations || []) {
+      if (relation.review_status !== 'confirmed') {
+        errors.push(`可发布关系尚未确认: ${relation.from_semantic_key} -${relation.type}-> ${relation.to_semantic_key}`);
+      }
+    }
+  }
+  if (payload?.ontology_hash && withOntologyHash(payload).ontology_hash !== payload.ontology_hash) {
+    errors.push('ontology_hash 与内容不一致');
+  }
+  if (payload?.compatibility_mode === 'LEGACY_MATERIALIZED') {
+    warnings.push('历史产物已兼容物化，只有审核后才能发布为 current 事实');
+  }
+  return { valid: errors.length === 0, errors, warnings, counts: { entities: keys.size, identities: ids.size, relations: payload?.relations?.length || 0 } };
+}
+
+function approveSpecOntologyFile(filePath, options = {}) {
+  const resolved = path.resolve(filePath);
+  const payload = readJsonSafe(resolved);
+  if (!payload) throw new Error(`无法读取 Spec 本体文件: ${resolved}`);
+  const validation = validateSpecOntology(payload);
+  if (!validation.valid) {
+    throw new Error(`Spec 本体审核前校验失败: ${validation.errors.join('; ')}`);
+  }
+  if (payload.compatibility_mode === 'EVIDENCE_ONLY' || payload.entities.length === 0) {
+    throw new Error('EVIDENCE_ONLY 产物没有足够结构化事实，不能直接发布');
+  }
+  const collisions = (payload.warnings || []).filter((warning) => warning.startsWith('SEMANTIC_KEY_COLLISION:'));
+  if (collisions.length > 0 && !options.allowCollisions) {
+    throw new Error(`仍有 semantic_key 冲突，需先完成合并判断: ${collisions.join('; ')}`);
+  }
+  const approved = withOntologyHash({
+    ...payload,
+    review_status: 'confirmed',
+    publication_eligible: true,
+    entities: payload.entities.map((entity) => ({
+      ...entity,
+      review_status: 'confirmed',
+      publication_status: 'publishable',
+    })),
+    relations: payload.relations.map((relation) => ({
+      ...relation,
+      review_status: 'confirmed',
+    })),
+    warnings: [
+      ...(payload.warnings || []).filter((warning) => (
+        !warning.startsWith('LEGACY_IDENTITIES_DERIVED:')
+        && !warning.startsWith('SEMANTIC_KEY_COLLISION:')
+      )),
+      'LEGACY_IDENTITIES_REVIEWED: 旁路身份和语义键已审核，可发布为 current 事实',
+    ],
+  });
+  writeJsonAtomic(resolved, approved);
+  return {
+    file: resolved,
+    payload: approved,
+    validation: validateSpecOntology(approved),
+  };
+}
+
+function resolveProjectIdentity(projectRoot) {
+  const identityPath = path.join(projectRoot, 'skywalk-sdd', 'project-identity.json');
+  const identity = readJsonSafe(identityPath);
+  if (identity?.project_id) return { projectId: identity.project_id, configured: true, identityPath };
+  return {
+    projectId: `urn:kld:sdd:project:local:${sha256(path.resolve(projectRoot)).slice(0, 16)}`,
+    configured: false,
+    identityPath,
+  };
+}
+
+function materializeChangeSpecOntology(projectRoot, changeName, options = {}) {
+  const root = path.resolve(projectRoot || process.cwd());
+  const changeDir = options.changeDir ? path.resolve(options.changeDir) : resolveChangeDir(root, changeName);
+  const facts = normalizeFacts(parseChangeArtifacts(root, changeName, {
+    changeDir,
+    persistStructuralIdentities: false,
+  }));
+  const projectIdentity = resolveProjectIdentity(root);
+  let payload = buildSpecOntology(facts, {
+    projectId: options.projectId || projectIdentity.projectId,
+    compatibilityMode: options.compatibilityMode,
+    reviewStatus: options.reviewStatus,
+  });
+  if (!projectIdentity.configured) {
+    payload.warnings.unshift('PROJECT_ID_UNCONFIGURED: 可先在本地物化，上传前通过 opsx-kb-config 绑定 Space');
+  }
+  payload = withOntologyHash(payload);
+  const outputPath = path.resolve(options.outputPath || path.join(changeDir, 'ontology', SPEC_ONTOLOGY_PATH));
+  const mappingPath = path.resolve(options.mappingPath || path.join(changeDir, LEGACY_MAPPING_PATH));
+  ensureDir(path.dirname(outputPath));
+  ensureDir(path.dirname(mappingPath));
+  writeJsonAtomic(outputPath, payload);
+  writeJsonAtomic(mappingPath, {
+    schema_version: LEGACY_MAPPING_SCHEMA_VERSION,
+    project_id: payload.project_id,
+    change: payload.change,
+    compatibility_mode: payload.compatibility_mode,
+    mappings: payload.identity_map,
+  });
+  return {
+    payload,
+    validation: validateSpecOntology(payload),
+    output_path: outputPath,
+    mapping_path: mappingPath,
+  };
+}
+
+module.exports = {
+  SPEC_ONTOLOGY_SCHEMA_VERSION,
+  LEGACY_MAPPING_SCHEMA_VERSION,
+  SPEC_ONTOLOGY_PATH,
+  LEGACY_MAPPING_PATH,
+  TYPE_MAP,
+  LEGACY_TOLERATED_CODES,
+  deterministicUuid,
+  semanticKeyFor,
+  classifyLegacyDiagnostics,
+  splitCheckDiagnostics,
+  specOntologyContentSignature,
+  buildSpecOntology,
+  validateSpecOntology,
+  approveSpecOntologyFile,
+  materializeChangeSpecOntology,
+};

package/skywalk-sdd/ontology/workspace-layout.cjs

@@ -3,6 +3,10 @@
 const fs = require('fs');
 const path = require('path');
 
+// spec 判据的唯一真相源。spec-detect 对 workspace-layout 的依赖是惰性（函数内
+// require），故此处顶层 require 不构成循环依赖。
+const specDetect = require('./spec-detect.cjs');
+
 const WORKSPACE_FILE = '.sdd-workspace.yaml';
 const IGNORE_DIR_NAMES = new Set([
   'node_modules',
@@ -24,19 +28,19 @@ function isGitRepo(dir) {
   return fs.existsSync(path.join(dir, '.git'));
 }
 
+/**
+ * 是否像 SDD spec 包裹包。
+ *
+ * ⚠️ 判据已收敛到 `spec-detect.cjs#isSpecCandidate`（全仓唯一判据入口），
+ * 本函数保留仅为向后兼容既有调用点，**不得再在此处新增判据**。
+ *
+ * 语义（与 spec-detect 一致）：
+ * - 四结构齐全（modules.yaml + sdd.config.yaml + openspec/changes
+ *   + openspec/specs/overview.md）→ 命中，**不看目录名**
+ * - 目录名 `*-sdd-specs` → 命中（含预填空壳，由 tier 排序决定取舍）
+ */
 function looksLikeSpecRepo(dir) {
-  const name = path.basename(dir).toLowerCase();
-  // 命名约定：*-sdd-specs 目录名直接命中
-  if (/-sdd-specs$/.test(name) || name.endsWith('sdd-specs')) return true;
-  // 结构判据（四项同时满足）：
-  // modules.yaml（模块登记）+ sdd.config.yaml（活动变更登记）
-  // + openspec/changes（变更结构）+ openspec/specs/overview.md（全局契约）
-  return (
-    fs.existsSync(path.join(dir, 'modules.yaml'))
-    && fs.existsSync(path.join(dir, 'sdd.config.yaml'))
-    && fs.existsSync(path.join(dir, 'openspec', 'changes'))
-    && fs.existsSync(path.join(dir, 'openspec', 'specs', 'overview.md'))
-  );
+  return specDetect.isSpecCandidate(dir);
 }
 
 function listChildGitRepos(workspaceRoot) {
@@ -88,7 +92,6 @@ function detectWorkspaceLayout(workspaceRoot = process.cwd()) {
     rootIsGit,
     specRepo: spec,
     codeRepos,
-    allChildGitRepos: children,
   };
 }
 
@@ -164,7 +167,25 @@ function writeWorkspaceFile(workspaceRoot, layout) {
     '',
   ];
   const filePath = path.join(workspaceRoot, WORKSPACE_FILE);
-  fs.writeFileSync(filePath, lines.join('\n'), 'utf8');
+  if (fs.existsSync(filePath)) {
+    // sync-repos 只追加新仓；既有行、注释、自定义字段和暂时离线的仓库保留。
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const saved = parseWorkspaceYaml(raw);
+    if (!saved.spec_path || path.resolve(workspaceRoot, saved.spec_path) !== path.resolve(workspaceRoot, specRel)) {
+      throw new Error('已有多仓清单的 Spec 指向不一致，请先核对配置');
+    }
+    const known = new Set(saved.code_repos.map(rel => path.resolve(workspaceRoot, rel.replace(/^(["'])(.*)\1$/, '$2'))));
+    const additions = codeRels.filter(rel => !known.has(path.resolve(workspaceRoot, rel)));
+    if (!additions.length) return filePath;
+    const newline = raw.includes('\r\n') ? '\r\n' : '\n';
+    const existing = raw.split(/\r?\n/);
+    const header = existing.findIndex(line => /^code_repos:\s*(?:#.*)?$/.test(line));
+    if (header < 0) throw new Error('已有多仓清单缺少 code_repos 列表，请先修复配置');
+    existing.splice(header + 1, 0, ...additions.map(rel => `  - ${rel}`));
+    fs.writeFileSync(filePath, existing.join(newline), 'utf8');
+  } else {
+    fs.writeFileSync(filePath, lines.join('\n'), 'utf8');
+  }
   return filePath;
 }
 
@@ -228,6 +249,22 @@ function findNestedSpecPackage(parentDir) {
   );
 }
 
+/**
+ * 取候选来源的中文标签；未知来源原样返回。
+ *
+ * ⚠️ 标签表与候选枚举均已收敛到 `spec-detect.cjs`（唯一真相源）：
+ * - 枚举用 `detectSpecCandidates` / `detectSpecCandidatesWithGit`
+ * - 标签用 `spec-detect#specSourceLabel`
+ *
+ * 本模块曾另有一份 `listSpecCandidates`（多出一个 'workspace' 来源标签），
+ * 现已删除 —— 它只是给「扫描已能找到的同一个目录」换个标签，对候选集合
+ * 无增量，反而造成「同一目录两种来源说法」。判据强度统一由候选的 `tier`
+ * 承载（0=显式声明 / 1=四结构 / 2=名称含空壳）。
+ */
+function specSourceLabel(source) {
+  return specDetect.specSourceLabel(source);
+}
+
 /**
  * 确保父目录下存在统一的 SDD 包裹包目录。
  * @param {{ name?: string, initGit?: boolean }} options
@@ -278,18 +315,29 @@ function ensureSpecPackage(parentDir, options = {}) {
   return { name, abs, created: !existed, isGit };
 }
 
+/**
+ * 公开 API —— 只导出「有跨模块消费者」的符号。
+ *
+ * 刻意不导出（函数体保留，模块内部使用）：
+ * - `WORKSPACE_FILE`    仅本模块 loadWorkspaceFile / writeWorkspaceFile 使用
+ * - `listChildGitRepos` 仅 detectWorkspaceLayout 使用
+ * - `parseWorkspaceYaml` 仅 loadWorkspaceFile 使用
+ *
+ * 标签表 `SPEC_SOURCE_LABELS` 已迁至 `spec-detect.cjs`（唯一真相源），
+ * 本模块仅转发 `specSourceLabel()`；如需直接读表请从 spec-detect 引入。
+ *
+ * 如需外部使用请重新加入本表，而不是依赖 `module.exports` 的隐式宽松。
+ */
 module.exports = {
-  WORKSPACE_FILE,
   isGitRepo,
   looksLikeSpecRepo,
-  listChildGitRepos,
   listChildDirectories,
   detectWorkspaceLayout,
-  parseWorkspaceYaml,
   loadWorkspaceFile,
   writeWorkspaceFile,
   findNewCodeRepos,
   deriveSpecPackageName,
   findNestedSpecPackage,
+  specSourceLabel,
   ensureSpecPackage,
 };