kld-sdd 2.5.1 → 2.6.0

package/skywalk-sdd/ontology/identity-index.cjs

@@ -0,0 +1,287 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { parseChangeArtifacts } = require('./artifact-parser.cjs');
+const { normalizeFacts } = require('./normalizer.cjs');
+const { DIAGNOSTIC_CODES } = require('./schema.cjs');
+
+function catalogDiagnostic(code, message, context = {}) {
+  return {
+    code,
+    severity: context.severity || 'error',
+    message,
+    file: context.file || '',
+    line: Number(context.line || 0),
+    entity_id: context.entity_id || undefined,
+    suggestion: context.suggestion || undefined,
+  };
+}
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function identityRoots(projectRoot) {
+  const root = path.resolve(projectRoot || process.cwd());
+  const changesRoot = path.join(root, 'openspec', 'changes');
+  const candidates = [];
+  if (!fs.existsSync(changesRoot)) return candidates;
+
+  for (const entry of fs.readdirSync(changesRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.name === 'archive' || entry.name.startsWith('.')) continue;
+    candidates.push({
+      change: entry.name,
+      scope: 'active',
+      changeDir: path.join(changesRoot, entry.name),
+      rootKey: `active:${entry.name}`,
+    });
+  }
+
+  const archiveRoot = path.join(changesRoot, 'archive');
+  if (fs.existsSync(archiveRoot)) {
+    for (const entry of fs.readdirSync(archiveRoot, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name.includes('.staging-')) continue;
+      candidates.push({
+        change: entry.name,
+        scope: 'archive',
+        changeDir: path.join(archiveRoot, entry.name),
+        rootKey: `archive:${entry.name}`,
+      });
+    }
+  }
+
+  return candidates.sort((left, right) => left.changeDir.localeCompare(right.changeDir));
+}
+
+function validateArchiveCandidate(candidate, facts) {
+  const snapshotPath = path.join(candidate.changeDir, 'archive-ontology.json');
+  const manifestPath = path.join(candidate.changeDir, 'archive-manifest.json');
+  const snapshot = fs.existsSync(snapshotPath) ? readJson(snapshotPath) : null;
+  const manifest = fs.existsSync(manifestPath) ? readJson(manifestPath) : null;
+  const diagnostics = [];
+
+  if (!snapshot || snapshot.review_status !== 'confirmed' || !manifest) {
+    diagnostics.push(catalogDiagnostic(
+      DIAGNOSTIC_CODES.ARCHIVE_NOT_CONFIRMED,
+      `Archive 不能作为继承来源，缺少 confirmed snapshot 或 manifest: ${candidate.change}`,
+      { file: snapshotPath, suggestion: '通过 KLD-SDD Archive 两阶段事务重新归档，禁止手工伪造 confirmed' },
+    ));
+    return { eligible: false, snapshot, manifest, diagnostics };
+  }
+
+  const projectRoot = path.resolve(candidate.changeDir, '..', '..', '..', '..');
+  const declaredArchiveDir = manifest.archive_path
+    ? path.resolve(projectRoot, manifest.archive_path)
+    : '';
+  const expectedArchiveDir = path.resolve(candidate.expectedArchiveDir || candidate.changeDir);
+  if (!declaredArchiveDir || declaredArchiveDir !== expectedArchiveDir) {
+    diagnostics.push(catalogDiagnostic(
+      DIAGNOSTIC_CODES.ARCHIVE_REVISION_MISMATCH,
+      `Archive manifest 路径与实际目录不一致: ${candidate.change}`,
+      { file: manifestPath, suggestion: '通过 KLD-SDD Archive 事务重新生成 manifest，禁止复制旧 manifest 冒充新 Archive' },
+    ));
+    return { eligible: false, snapshot, manifest, diagnostics };
+  }
+
+  if (!snapshot.facts_hash || snapshot.facts_hash !== facts.facts_hash) {
+    diagnostics.push(catalogDiagnostic(
+      DIAGNOSTIC_CODES.ARCHIVE_REVISION_MISMATCH,
+      `Archive snapshot 与实际归档正文不一致: ${candidate.change}`,
+      { file: snapshotPath, suggestion: '重新解析归档正文并生成一致的 confirmed snapshot' },
+    ));
+    return { eligible: false, snapshot, manifest, diagnostics };
+  }
+
+  const artifactIndexPath = path.join(candidate.changeDir, 'artifact-index.json');
+  if (!fs.existsSync(artifactIndexPath)) {
+    diagnostics.push(catalogDiagnostic(
+      DIAGNOSTIC_CODES.ARCHIVE_NOT_CONFIRMED,
+      `Archive 缺少 change 目录下的 artifact-index.json: ${candidate.change}`,
+      { file: artifactIndexPath, suggestion: '通过 KLD-SDD reconcile/archive 在 change 目录生成工作态 JSON 后再归档' },
+    ));
+    return { eligible: false, snapshot, manifest, diagnostics };
+  }
+
+  if (manifest.schema_version === 'kld-sdd-archive-manifest/v2') {
+    const canonicalPath = path.join(
+      candidate.changeDir,
+      manifest.canonical_facts_path || 'canonical-facts.json',
+    );
+    if (!fs.existsSync(canonicalPath)) {
+      diagnostics.push(catalogDiagnostic(
+        DIAGNOSTIC_CODES.ARCHIVE_NOT_CONFIRMED,
+        `Archive v2 manifest 缺少 canonical facts: ${candidate.change}`,
+        { file: canonicalPath, suggestion: '运行 archive-docs 或 materializeArchivePackage 生成 canonical-facts.json' },
+      ));
+      return { eligible: false, snapshot, manifest, diagnostics };
+    }
+  }
+
+  return { eligible: true, snapshot, manifest, diagnostics };
+}
+
+function recordsFor(candidate, facts, sourceRevision) {
+  return facts.entities
+    .filter((entity) => entity.entity_id || entity.version_id)
+    .map((entity) => ({
+      change: candidate.change,
+      scope: candidate.scope,
+      root_key: candidate.rootKey,
+      change_dir: candidate.changeDir,
+      source_revision: sourceRevision || undefined,
+      anchor_id: entity.anchor_id || entity.id,
+      type: entity.type,
+      entity_id: entity.entity_id,
+      version_id: entity.version_id,
+      predecessor_version_id: entity.predecessor_version_id,
+      delta_state: entity.delta_state,
+      content_hash: entity.content_hash,
+      source: entity.source,
+    }));
+}
+
+function groupBy(records, field) {
+  const grouped = new Map();
+  for (const record of records) {
+    const value = record[field];
+    if (!value) continue;
+    if (!grouped.has(value)) grouped.set(value, []);
+    grouped.get(value).push(record);
+  }
+  return grouped;
+}
+
+function buildCatalogDiagnostics(records) {
+  const diagnostics = [];
+  const byEntityId = groupBy(records, 'entity_id');
+  const byVersionId = groupBy(records, 'version_id');
+  const byAnchor = groupBy(records, 'anchor_id');
+  const byPredecessor = groupBy(records, 'predecessor_version_id');
+
+  for (const [entityId, items] of byEntityId.entries()) {
+    const signatures = new Set(items.map((item) => `${item.anchor_id}|${item.type}`));
+    if (signatures.size > 1) {
+      diagnostics.push(catalogDiagnostic(
+        DIAGNOSTIC_CODES.ENTITY_IDENTITY_CONFLICT,
+        `历史集合中同一 entity-id 对应多个锚点或类型: ${entityId}`,
+        { entity_id: items[0].anchor_id, file: items[0].source && items[0].source.file },
+      ));
+    }
+  }
+
+  for (const [versionId, items] of byVersionId.entries()) {
+    const signatures = new Set(items.map((item) => `${item.entity_id}|${item.content_hash}`));
+    if (signatures.size > 1) {
+      diagnostics.push(catalogDiagnostic(
+        DIAGNOSTIC_CODES.VERSION_IDENTITY_CONFLICT,
+        `历史集合中同一 version-id 对应不同实体或内容: ${versionId}`,
+        { entity_id: items[0].anchor_id, file: items[0].source && items[0].source.file },
+      ));
+    }
+  }
+
+  for (const [anchorId, items] of byAnchor.entries()) {
+    const entityIds = new Set(items.map((item) => item.entity_id).filter(Boolean));
+    if (entityIds.size > 1) {
+      diagnostics.push(catalogDiagnostic(
+        DIAGNOSTIC_CODES.ENTITY_IDENTITY_CONFLICT,
+        `历史锚点被不同 entity-id 复用: ${anchorId}`,
+        { entity_id: anchorId, file: items[0].source && items[0].source.file },
+      ));
+    }
+  }
+
+  for (const [predecessorId, items] of byPredecessor.entries()) {
+    const successors = new Set(items.map((item) => item.version_id).filter(Boolean));
+    if (successors.size > 1) {
+      diagnostics.push(catalogDiagnostic(
+        DIAGNOSTIC_CODES.VERSION_LINEAGE_CONFLICT,
+        `历史集合中同一 predecessor 存在多个后继: ${predecessorId}`,
+        { entity_id: items[0].anchor_id, file: items[0].source && items[0].source.file },
+      ));
+    }
+  }
+
+  for (const record of records) {
+    if (!record.predecessor_version_id) continue;
+    const predecessors = byVersionId.get(record.predecessor_version_id) || [];
+    if (!predecessors.some((item) => item.entity_id === record.entity_id)) {
+      diagnostics.push(catalogDiagnostic(
+        DIAGNOSTIC_CODES.VERSION_LINEAGE_MISSING,
+        `历史版本 predecessor 不属于同一 entity 或不存在: ${record.anchor_id}`,
+        { entity_id: record.anchor_id, file: record.source && record.source.file },
+      ));
+    }
+  }
+
+  return diagnostics;
+}
+
+function buildIdentityCatalog(projectRoot, options = {}) {
+  const root = path.resolve(projectRoot || process.cwd());
+  const excluded = options.excludeChangeDir ? path.resolve(options.excludeChangeDir) : '';
+  const records = [];
+  const factsByRoot = new Map();
+  const diagnostics = [];
+
+  for (const candidate of identityRoots(root)) {
+    if (excluded && path.resolve(candidate.changeDir) === excluded) continue;
+    const facts = normalizeFacts(parseChangeArtifacts(root, candidate.change, {
+      changeDir: candidate.changeDir,
+      persistStructuralIdentities: false,
+    }));
+    let sourceRevision = '';
+    if (candidate.scope === 'archive') {
+      const archive = validateArchiveCandidate(candidate, facts);
+      diagnostics.push(...archive.diagnostics);
+      if (!archive.eligible) continue;
+      sourceRevision = archive.snapshot.source_revision || '';
+    }
+    factsByRoot.set(candidate.rootKey, {
+      ...candidate,
+      source_revision: sourceRevision || undefined,
+      facts,
+    });
+    records.push(...recordsFor(candidate, facts, sourceRevision));
+  }
+
+  records.sort((left, right) => (
+    String(left.entity_id || '').localeCompare(String(right.entity_id || ''))
+    || String(left.version_id || '').localeCompare(String(right.version_id || ''))
+    || String(left.change || '').localeCompare(String(right.change || ''))
+    || String(left.anchor_id || '').localeCompare(String(right.anchor_id || ''))
+  ));
+  diagnostics.push(...buildCatalogDiagnostics(records));
+  diagnostics.sort((left, right) => (
+    String(left.code || '').localeCompare(String(right.code || ''))
+    || String(left.file || '').localeCompare(String(right.file || ''))
+    || String(left.message || '').localeCompare(String(right.message || ''))
+  ));
+
+  return {
+    records,
+    factsByRoot,
+    byEntityId: groupBy(records, 'entity_id'),
+    byVersionId: groupBy(records, 'version_id'),
+    byAnchor: groupBy(records, 'anchor_id'),
+    byPredecessor: groupBy(records, 'predecessor_version_id'),
+    diagnostics,
+  };
+}
+
+function buildIdentityHistory(projectRoot, options = {}) {
+  return buildIdentityCatalog(projectRoot, options).records;
+}
+
+module.exports = {
+  identityRoots,
+  validateArchiveCandidate,
+  buildCatalogDiagnostics,
+  buildIdentityCatalog,
+  buildIdentityHistory,
+};

package/skywalk-sdd/ontology/normalizer.cjs

@@ -0,0 +1,107 @@
+'use strict';
+
+const crypto = require('crypto');
+const { SCHEMA_VERSION } = require('./schema.cjs');
+
+function compareText(left, right) {
+  return String(left || '').localeCompare(String(right || ''));
+}
+
+function stableRelationId(relation) {
+  return `${relation.type}:${relation.from_entity_id || relation.from}:${relation.to_entity_id || relation.to}`;
+}
+
+function normalizeFacts(parsed) {
+  const entities = (parsed.entities || []).map((entity) => ({
+    ...entity,
+    id: String(entity.id || '').trim().toUpperCase(),
+    anchor_id: String(entity.anchor_id || entity.id || '').trim().toUpperCase(),
+    entity_id: String(entity.entity_id || '').trim().toLowerCase() || undefined,
+    version_id: String(entity.version_id || '').trim().toLowerCase() || undefined,
+    predecessor_version_id: String(entity.predecessor_version_id || '').trim().toLowerCase() || undefined,
+    delta_state: String(entity.delta_state || '').trim().toLowerCase() || undefined,
+  })).sort((left, right) => (
+    compareText(left.id, right.id)
+    || compareText(left.type, right.type)
+    || compareText(left.source && left.source.file, right.source && right.source.file)
+    || Number((left.source && left.source.line) || 0) - Number((right.source && right.source.line) || 0)
+  ));
+
+  const seenRelations = new Set();
+  const relations = [];
+  const identityByAnchor = new Map();
+  for (const entity of entities) {
+    if (!identityByAnchor.has(entity.id) && entity.entity_id) {
+      identityByAnchor.set(entity.id, entity.entity_id);
+    }
+  }
+  for (const reference of parsed.inheritedReferences || []) {
+    const anchorId = String(reference.anchor_id || '').toUpperCase();
+    const entityId = String(reference.entity_id || '').toLowerCase();
+    if (anchorId && entityId && !identityByAnchor.has(anchorId)) {
+      identityByAnchor.set(anchorId, entityId);
+    }
+  }
+  for (const input of parsed.relations || []) {
+    const relation = {
+      ...input,
+      from: String(input.from || '').trim().toUpperCase(),
+      to: String(input.to || '').trim().toUpperCase(),
+    };
+    relation.from_entity_id = identityByAnchor.get(relation.from);
+    relation.to_entity_id = identityByAnchor.get(relation.to);
+    relation.id = stableRelationId(relation);
+    const sourceKey = `${relation.id}:${relation.source && relation.source.file}:${relation.source && relation.source.line}`;
+    if (seenRelations.has(sourceKey)) continue;
+    seenRelations.add(sourceKey);
+    relations.push(relation);
+  }
+  relations.sort((left, right) => (
+    compareText(left.id, right.id)
+    || compareText(left.source && left.source.file, right.source && right.source.file)
+    || Number((left.source && left.source.line) || 0) - Number((right.source && right.source.line) || 0)
+  ));
+
+  const diagnostics = (parsed.diagnostics || []).slice().sort((left, right) => (
+    compareText(left.code, right.code)
+    || compareText(left.file, right.file)
+    || Number(left.line || 0) - Number(right.line || 0)
+  ));
+
+  const facts = {
+    schema_version: SCHEMA_VERSION,
+    change: parsed.changeName,
+    change_id: parsed.changeId || undefined,
+    profile: parsed.profile,
+    proposal_mode: parsed.proposalMode || undefined,
+    artifacts: (parsed.artifacts || []).slice().sort((left, right) => compareText(left.path, right.path)),
+    files: (parsed.files || []).slice().sort((left, right) => compareText(left.path, right.path)),
+    entities,
+    relations,
+    inherited_references: (parsed.inheritedReferences || []).map((reference) => ({
+      ...reference,
+      anchor_id: String(reference.anchor_id || '').toUpperCase(),
+      entity_id: String(reference.entity_id || '').toLowerCase() || undefined,
+      version_id: String(reference.version_id || '').toLowerCase() || undefined,
+      delta_state: String(reference.delta_state || '').toLowerCase() || undefined,
+    })).sort((left, right) => compareText(left.anchor_id, right.anchor_id)),
+    inherited_relations: (parsed.inheritedRelations || []).map((relation) => ({
+      ...relation,
+      type: String(relation.type || '').trim(),
+      from: String(relation.from || '').trim().toUpperCase(),
+      to: String(relation.to || '').trim().toUpperCase(),
+    })).sort((left, right) => (
+      compareText(left.type, right.type)
+      || compareText(left.from, right.from)
+      || compareText(left.to, right.to)
+    )),
+    diagnostics,
+  };
+  facts.facts_hash = crypto.createHash('sha256').update(JSON.stringify(facts)).digest('hex');
+  return facts;
+}
+
+module.exports = {
+  stableRelationId,
+  normalizeFacts,
+};