kld-sdd 2.5.2 → 2.6.0

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

@@ -0,0 +1,489 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { generateUuidV7 } = require('./id.cjs');
+
+const PRODUCER_VERSION = require('../../package.json').version;
+const PRODUCER = `kld-sdd@${PRODUCER_VERSION}`;
+const MANIFEST_SCHEMA_VERSION = 'kld-sdd-archive-manifest/v2';
+const CANONICAL_FACTS_SCHEMA_VERSION = 'kld-sdd-canonical-facts/v1';
+const CONVERSION_REPORT_SCHEMA_VERSION = 'kld-sdd-conversion-report/v1';
+const PROJECT_IDENTITY_SCHEMA_VERSION = 'kld-sdd-project-identity/v1';
+const MANIFEST_PATH = 'archive-manifest.json';
+const ONTOLOGY_PATH = 'archive-ontology.json';
+const CANONICAL_FACTS_PATH = 'canonical-facts.json';
+const CONVERSION_REPORT_PATH = 'conversion-report.json';
+const PACKAGE_SUFFIXES = new Set(['.md', '.json', '.jsonl', '.yaml', '.yml']);
+
+function sha256(content) {
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function atomicWrite(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+  fs.writeFileSync(tempPath, content);
+  fs.renameSync(tempPath, filePath);
+}
+
+function writeJson(filePath, value) {
+  const bytes = Buffer.from(`${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  atomicWrite(filePath, bytes);
+  return bytes;
+}
+
+function toPosix(value) {
+  return String(value || '').replace(/\\/g, '/');
+}
+
+function safePackagePath(value) {
+  const input = toPosix(value).trim();
+  if (!input || input.startsWith('/') || /^[A-Za-z]:\//.test(input) || input.includes('\0')) {
+    throw new Error(`Archive Package 路径不安全: ${value}`);
+  }
+  const normalized = path.posix.normalize(input);
+  if (normalized !== input || normalized === '..' || normalized.startsWith('../')) {
+    throw new Error(`Archive Package 路径不规范: ${value}`);
+  }
+  return normalized;
+}
+
+function ensureProjectIdentity(projectRoot) {
+  const identityPath = path.join(projectRoot, 'skywalk-sdd', 'project-identity.json');
+  if (fs.existsSync(identityPath)) {
+    const existing = readJson(identityPath);
+    if (existing.schema_version !== PROJECT_IDENTITY_SCHEMA_VERSION || !existing.project_id) {
+      throw new Error(`项目身份文件格式非法: ${identityPath}`);
+    }
+    return existing;
+  }
+  const identity = {
+    schema_version: PROJECT_IDENTITY_SCHEMA_VERSION,
+    project_id: `urn:kld:sdd:project:${generateUuidV7()}`,
+    created_at: new Date().toISOString(),
+  };
+  writeJson(identityPath, identity);
+  return identity;
+}
+
+function sourceWithVerifiedHash(archiveDir, source, ownerAnchor, forceOwnerAnchor) {
+  const declared = source && typeof source === 'object' ? source : {};
+  const relativePath = safePackagePath(declared.file);
+  const absolutePath = path.resolve(archiveDir, relativePath);
+  const relativeCheck = toPosix(path.relative(archiveDir, absolutePath));
+  if (relativeCheck !== relativePath || !fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isFile()) {
+    throw new Error(`本体来源文件不在 Archive Package 中: ${relativePath} (${ownerAnchor})`);
+  }
+  const line = Number(declared.line || 0);
+  return {
+    artifact_type: String(declared.artifact_type || 'unknown').trim().toLowerCase(),
+    file: relativePath,
+    ...(Number.isInteger(line) && line > 0 ? { line } : {}),
+    anchor_id: forceOwnerAnchor
+      ? ownerAnchor
+      : String(declared.anchor_id || ownerAnchor).trim().toUpperCase(),
+    content_hash: `sha256:${sha256(fs.readFileSync(absolutePath))}`,
+  };
+}
+
+function requiredText(value, field, owner) {
+  const normalized = String(value || '').trim();
+  if (!normalized) {
+    throw new Error(`${owner} 缺少 ${field}`);
+  }
+  return normalized;
+}
+
+function canonicalEntity(archiveDir, entity) {
+  const anchorId = requiredText(entity.anchor_id || entity.id, 'anchor_id', '本体实体').toUpperCase();
+  const versionId = requiredText(
+    entity.entity_version_id || entity.version_id,
+    'entity_version_id/version_id',
+    anchorId,
+  ).toLowerCase();
+  return {
+    anchor_id: anchorId,
+    type: requiredText(entity.type, 'type', anchorId),
+    name: String(entity.name || anchorId).trim(),
+    entity_id: requiredText(entity.entity_id, 'entity_id', anchorId).toLowerCase(),
+    entity_version_id: versionId,
+    predecessor_version_id: entity.predecessor_version_id
+      ? String(entity.predecessor_version_id).trim().toLowerCase()
+      : null,
+    delta_state: String(entity.delta_state || 'added').trim().toLowerCase(),
+    content_hash: requiredText(entity.content_hash, 'content_hash', anchorId),
+    fact_kind: 'semantic',
+    assertion_type: 'asserted',
+    review_status: 'confirmed',
+    generation_role: entity.generation_role || 'current',
+    ...(entity.inherited_from ? { inherited_from: entity.inherited_from } : {}),
+    attributes: entity.attributes && typeof entity.attributes === 'object' ? entity.attributes : {},
+    source: sourceWithVerifiedHash(archiveDir, entity.source, anchorId, true),
+  };
+}
+
+function normalizeRelationDirection(type, fromAnchor, toAnchor, entityByAnchor) {
+  if (type !== 'constrains') {
+    return { type: type === 'acceptedBy' ? 'verifiedBy' : type, fromAnchor, toAnchor };
+  }
+  const fromType = entityByAnchor.get(fromAnchor)?.type;
+  const toType = entityByAnchor.get(toAnchor)?.type;
+  if (fromType === 'Constraint' && toType === 'SpecificationStatement') {
+    return { type: 'constrainedBy', fromAnchor: toAnchor, toAnchor: fromAnchor };
+  }
+  if (fromType === 'SpecificationStatement' && toType === 'Constraint') {
+    return { type: 'constrainedBy', fromAnchor, toAnchor };
+  }
+  throw new Error(`constrains 关系方向无法归一化: ${fromAnchor} -> ${toAnchor}`);
+}
+
+function canonicalRelation(archiveDir, relation, entityByAnchor, warningCounts) {
+  const originalType = requiredText(relation.type, 'type', '本体关系');
+  const originalFrom = requiredText(relation.from, 'from', originalType).toUpperCase();
+  const originalTo = requiredText(relation.to, 'to', originalType).toUpperCase();
+  const normalized = normalizeRelationDirection(originalType, originalFrom, originalTo, entityByAnchor);
+  if (normalized.type !== originalType || normalized.fromAnchor !== originalFrom) {
+    const warningKey = `${originalType}->${normalized.type}`;
+    warningCounts.set(warningKey, (warningCounts.get(warningKey) || 0) + 1);
+  }
+  const fromEntity = entityByAnchor.get(normalized.fromAnchor);
+  const toEntity = entityByAnchor.get(normalized.toAnchor);
+  if (!fromEntity || !toEntity) {
+    throw new Error(
+      `关系端点不在 canonical snapshot 中: ${normalized.fromAnchor} -${normalized.type}-> ${normalized.toAnchor}`,
+    );
+  }
+  const assertionType = String(relation.assertion_type || 'asserted').trim().toLowerCase();
+  const reviewStatus = assertionType === 'suggested' ? 'pending' : 'confirmed';
+  const relationKey = `${normalized.type}:${fromEntity.entity_id}:${toEntity.entity_id}`;
+  const output = {
+    type: normalized.type,
+    from_entity_id: fromEntity.entity_id,
+    to_entity_id: toEntity.entity_id,
+    assertion_type: assertionType,
+    fact_kind: 'semantic',
+    review_status: reviewStatus,
+    generation_role: relation.generation_role || 'current',
+    ...(relation.inherited_from ? { inherited_from: relation.inherited_from } : {}),
+    source: sourceWithVerifiedHash(archiveDir, relation.source, relationKey, false),
+  };
+  if (assertionType === 'inferred') {
+    output.rule_id = requiredText(relation.rule_id, 'rule_id', relationKey);
+    output.generator = relation.generator || 'kld-sdd';
+    output.generator_version = relation.generator_version || PRODUCER_VERSION;
+  } else if (relation.rule_id) {
+    output.rule_id = relation.rule_id;
+  }
+  if (assertionType === 'suggested') {
+    output.generator = requiredText(relation.generator, 'generator', relationKey);
+    output.generator_version = requiredText(relation.generator_version, 'generator_version', relationKey);
+    if (!Number.isFinite(relation.confidence)) {
+      throw new Error(`${relationKey} 缺少 suggested confidence`);
+    }
+    output.confidence = relation.confidence;
+    output.support_evidence = Array.isArray(relation.support_evidence) ? relation.support_evidence : [];
+    output.opposition_evidence = Array.isArray(relation.opposition_evidence) ? relation.opposition_evidence : [];
+  }
+  return output;
+}
+
+function buildCanonicalFacts(archiveDir, snapshot, projectId, archiveId) {
+  if (snapshot.review_status !== 'confirmed') {
+    throw new Error('archive-ontology.json 必须是 confirmed 快照');
+  }
+  const changeId = requiredText(snapshot.change_id, 'change_id', 'archive-ontology.json');
+  const entities = (snapshot.entities || [])
+    .map((entity) => canonicalEntity(archiveDir, entity))
+    .sort((left, right) => (
+      left.anchor_id.localeCompare(right.anchor_id)
+      || left.entity_version_id.localeCompare(right.entity_version_id)
+    ));
+  if (entities.length === 0) {
+    throw new Error('archive-ontology.json 没有可导出的实体');
+  }
+  const entityByAnchor = new Map(entities.map((entity) => [entity.anchor_id, entity]));
+  const warningCounts = new Map();
+  const seenRelations = new Set();
+  const relations = [];
+  for (const relation of snapshot.relations || []) {
+    const converted = canonicalRelation(archiveDir, relation, entityByAnchor, warningCounts);
+    const key = `${converted.type}:${converted.from_entity_id}:${converted.to_entity_id}`;
+    if (seenRelations.has(key)) {
+      warningCounts.set('duplicate-relation-removed', (warningCounts.get('duplicate-relation-removed') || 0) + 1);
+      continue;
+    }
+    seenRelations.add(key);
+    relations.push(converted);
+  }
+  relations.sort((left, right) => (
+    left.type.localeCompare(right.type)
+    || left.from_entity_id.localeCompare(right.from_entity_id)
+    || left.to_entity_id.localeCompare(right.to_entity_id)
+  ));
+  const warnings = [...warningCounts.entries()]
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([type, count]) => `${type}: ${count}`);
+  return {
+    canonicalFacts: {
+      schema_version: CANONICAL_FACTS_SCHEMA_VERSION,
+      producer: PRODUCER,
+      project_id: projectId,
+      archive_id: archiveId,
+      change_id: changeId,
+      profile: requiredText(snapshot.profile, 'profile', 'archive-ontology.json').toLowerCase(),
+      review_status: 'confirmed',
+      facts_hash: requiredText(snapshot.facts_hash, 'facts_hash', 'archive-ontology.json'),
+      source_revision: snapshot.source_revision,
+      snapshot_id: snapshot.snapshot_id,
+      entities,
+      relations,
+    },
+    warnings,
+  };
+}
+
+function collectPackageFilePaths(archiveDir) {
+  const files = [];
+  function walk(currentDir) {
+    for (const entry of fs.readdirSync(currentDir, { withFileTypes: true })) {
+      if (entry.name.startsWith('.')) continue;
+      const absolutePath = path.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        walk(absolutePath);
+      } else if (entry.isFile()) {
+        const relativePath = safePackagePath(toPosix(path.relative(archiveDir, absolutePath)));
+        if (relativePath === MANIFEST_PATH) continue;
+        if (!PACKAGE_SUFFIXES.has(path.posix.extname(relativePath).toLowerCase())) continue;
+        files.push(relativePath);
+      }
+    }
+  }
+  walk(archiveDir);
+  return files.sort((left, right) => left.localeCompare(right));
+}
+
+function dosTimestamp(isoValue) {
+  const parsed = new Date(isoValue || '');
+  const date = Number.isNaN(parsed.getTime()) ? new Date() : parsed;
+  const year = Math.min(2107, Math.max(1980, date.getUTCFullYear()));
+  const month = date.getUTCMonth() + 1;
+  const day = date.getUTCDate();
+  const hours = date.getUTCHours();
+  const minutes = date.getUTCMinutes();
+  const seconds = Math.floor(date.getUTCSeconds() / 2);
+  return {
+    time: (hours << 11) | (minutes << 5) | seconds,
+    date: ((year - 1980) << 9) | (month << 5) | day,
+  };
+}
+
+let crcTable;
+function crc32(content) {
+  if (!crcTable) {
+    crcTable = Array.from({ length: 256 }, (_, index) => {
+      let value = index;
+      for (let bit = 0; bit < 8; bit += 1) {
+        value = (value & 1) ? (0xedb88320 ^ (value >>> 1)) : (value >>> 1);
+      }
+      return value >>> 0;
+    });
+  }
+  let value = 0xffffffff;
+  for (const byte of content) {
+    value = crcTable[(value ^ byte) & 0xff] ^ (value >>> 8);
+  }
+  return (value ^ 0xffffffff) >>> 0;
+}
+
+function storedZipEntry(name, content, timestamp, offset) {
+  const nameBytes = Buffer.from(name, 'utf8');
+  const checksum = crc32(content);
+  const local = Buffer.alloc(30);
+  local.writeUInt32LE(0x04034b50, 0);
+  local.writeUInt16LE(20, 4);
+  local.writeUInt16LE(0x0800, 6);
+  local.writeUInt16LE(0, 8);
+  local.writeUInt16LE(timestamp.time, 10);
+  local.writeUInt16LE(timestamp.date, 12);
+  local.writeUInt32LE(checksum, 14);
+  local.writeUInt32LE(content.length, 18);
+  local.writeUInt32LE(content.length, 22);
+  local.writeUInt16LE(nameBytes.length, 26);
+  local.writeUInt16LE(0, 28);
+
+  const central = Buffer.alloc(46);
+  central.writeUInt32LE(0x02014b50, 0);
+  central.writeUInt16LE(20, 4);
+  central.writeUInt16LE(20, 6);
+  central.writeUInt16LE(0x0800, 8);
+  central.writeUInt16LE(0, 10);
+  central.writeUInt16LE(timestamp.time, 12);
+  central.writeUInt16LE(timestamp.date, 14);
+  central.writeUInt32LE(checksum, 16);
+  central.writeUInt32LE(content.length, 20);
+  central.writeUInt32LE(content.length, 24);
+  central.writeUInt16LE(nameBytes.length, 28);
+  central.writeUInt16LE(0, 30);
+  central.writeUInt16LE(0, 32);
+  central.writeUInt16LE(0, 34);
+  central.writeUInt16LE(0, 36);
+  central.writeUInt32LE(0, 38);
+  central.writeUInt32LE(offset, 42);
+  return {
+    local: Buffer.concat([local, nameBytes, content]),
+    central: Buffer.concat([central, nameBytes]),
+  };
+}
+
+function writeArchiveZip(archiveDir, packagePath, manifest) {
+  const filePaths = [MANIFEST_PATH, ...(manifest.files || []).map((item) => item.path)];
+  if (filePaths.length > 0xffff) {
+    throw new Error(`Archive Package 文件数超过 ZIP32 上限: ${filePaths.length}`);
+  }
+  const timestamp = dosTimestamp(manifest.created_at);
+  const localParts = [];
+  const centralParts = [];
+  let offset = 0;
+  for (const declaredPath of filePaths) {
+    const relativePath = safePackagePath(declaredPath);
+    const content = fs.readFileSync(path.join(archiveDir, relativePath));
+    if (content.length > 0xffffffff) {
+      throw new Error(`Archive Package 单文件超过 ZIP32 上限: ${relativePath}`);
+    }
+    const entry = storedZipEntry(relativePath, content, timestamp, offset);
+    localParts.push(entry.local);
+    centralParts.push(entry.central);
+    offset += entry.local.length;
+  }
+  const centralDirectory = Buffer.concat(centralParts);
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(0x06054b50, 0);
+  end.writeUInt16LE(0, 4);
+  end.writeUInt16LE(0, 6);
+  end.writeUInt16LE(filePaths.length, 8);
+  end.writeUInt16LE(filePaths.length, 10);
+  end.writeUInt32LE(centralDirectory.length, 12);
+  end.writeUInt32LE(offset, 16);
+  end.writeUInt16LE(0, 20);
+  atomicWrite(packagePath, Buffer.concat([...localParts, centralDirectory, end]));
+  return packagePath;
+}
+
+function materializeArchivePackage(options = {}) {
+  const projectRoot = path.resolve(options.projectRoot || process.cwd());
+  const archiveDir = path.resolve(requiredText(options.archiveDir, 'archiveDir', 'Archive Package'));
+  const committedArchiveDir = path.resolve(options.archivePath || archiveDir);
+  const ontologyPath = path.join(archiveDir, ONTOLOGY_PATH);
+  if (!fs.existsSync(ontologyPath)) {
+    throw new Error(`缺少 ${ONTOLOGY_PATH}: ${archiveDir}`);
+  }
+  const snapshot = readJson(ontologyPath);
+  const projectIdentity = ensureProjectIdentity(projectRoot);
+  const changeId = requiredText(snapshot.change_id, 'change_id', ONTOLOGY_PATH);
+  const archiveId = `urn:kld:sdd:archive:${sha256(
+    `${projectIdentity.project_id}\n${changeId}\n${snapshot.facts_hash}`,
+  )}`;
+  const { canonicalFacts, warnings } = buildCanonicalFacts(
+    archiveDir,
+    snapshot,
+    projectIdentity.project_id,
+    archiveId,
+  );
+  const canonicalPath = path.join(archiveDir, CANONICAL_FACTS_PATH);
+  const canonicalBytes = writeJson(canonicalPath, canonicalFacts);
+
+  const conversionReport = {
+    schema_version: CONVERSION_REPORT_SCHEMA_VERSION,
+    producer: PRODUCER,
+    source_file: ONTOLOGY_PATH,
+    source_schema: String(snapshot.schema_version || 'unknown'),
+    target_file: CANONICAL_FACTS_PATH,
+    target_schema: CANONICAL_FACTS_SCHEMA_VERSION,
+    status: 'converted',
+    entity_count: canonicalFacts.entities.length,
+    relation_count: canonicalFacts.relations.length,
+    warnings,
+  };
+  writeJson(path.join(archiveDir, CONVERSION_REPORT_PATH), conversionReport);
+
+  const existingManifestPath = path.join(archiveDir, MANIFEST_PATH);
+  const existingManifest = fs.existsSync(existingManifestPath)
+    ? readJson(existingManifestPath)
+    : {};
+  const createdAt = options.archivedAt
+    || existingManifest.created_at
+    || existingManifest.archived_at
+    || new Date().toISOString();
+  const filePaths = collectPackageFilePaths(archiveDir);
+  const files = filePaths.map((relativePath) => ({
+    path: relativePath,
+    content_hash: `sha256:${sha256(fs.readFileSync(path.join(archiveDir, relativePath)))}`,
+  }));
+  const archiveRelativePath = toPosix(path.relative(projectRoot, committedArchiveDir));
+  const manifest = {
+    schema_version: MANIFEST_SCHEMA_VERSION,
+    producer: PRODUCER,
+    project_id: projectIdentity.project_id,
+    archive_id: archiveId,
+    change_id: changeId,
+    content_hash: `sha256:${sha256(canonicalBytes)}`,
+    canonical_facts_path: CANONICAL_FACTS_PATH,
+    conversion_report_path: CONVERSION_REPORT_PATH,
+    created_at: createdAt,
+    files,
+    change: options.changeName || snapshot.change || path.basename(committedArchiveDir),
+    archived_at: createdAt,
+    reason: options.reason || existingManifest.reason || '变更已完成实施',
+    method: options.method || existingManifest.method || 'skywalk-full-spec-archive',
+    source_path: options.sourcePath || existingManifest.source_path || '',
+    archive_path: archiveRelativePath,
+    copied_specs: Array.isArray(options.copiedSpecs)
+      ? options.copiedSpecs
+      : (existingManifest.copied_specs || []),
+    evidence_events_path: options.evidenceEventsPath === undefined
+      ? (existingManifest.evidence_events_path || null)
+      : options.evidenceEventsPath,
+  };
+  writeJson(existingManifestPath, manifest);
+
+  const packagePath = options.packagePath === false
+    ? ''
+    : path.resolve(options.packagePath || `${committedArchiveDir}.zip`);
+  if (packagePath) {
+    writeArchiveZip(archiveDir, packagePath, manifest);
+  }
+  return {
+    manifest,
+    conversion_report: conversionReport,
+    manifest_path: existingManifestPath,
+    canonical_facts_path: canonicalPath,
+    conversion_report_path: path.join(archiveDir, CONVERSION_REPORT_PATH),
+    package_path: packagePath,
+  };
+}
+
+module.exports = {
+  PRODUCER_VERSION,
+  PRODUCER,
+  MANIFEST_SCHEMA_VERSION,
+  CANONICAL_FACTS_SCHEMA_VERSION,
+  CONVERSION_REPORT_SCHEMA_VERSION,
+  PROJECT_IDENTITY_SCHEMA_VERSION,
+  MANIFEST_PATH,
+  ONTOLOGY_PATH,
+  CANONICAL_FACTS_PATH,
+  CONVERSION_REPORT_PATH,
+  sha256,
+  safePackagePath,
+  ensureProjectIdentity,
+  buildCanonicalFacts,
+  collectPackageFilePaths,
+  writeArchiveZip,
+  materializeArchivePackage,
+};

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

@@ -97,6 +97,31 @@ function validateArchiveCandidate(candidate, facts) {
     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 };
 }