kld-sdd 2.5.0 → 2.5.2

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

@@ -0,0 +1,126 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { safeChangeName } = require('./artifact-parser.cjs');
+
+const DEFAULT_STALE_MS = 5 * 60 * 1000;
+
+function lockPaths(projectRoot, changeName) {
+  const root = path.resolve(projectRoot || process.cwd());
+  const safeName = safeChangeName(changeName);
+  const dir = path.join(root, 'skywalk-sdd', 'state', 'ontology', '.locks');
+  return {
+    dir,
+    file: path.join(dir, `${safeName}.lock`),
+  };
+}
+
+function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error && error.code === 'EPERM';
+  }
+}
+
+function readLock(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    return null;
+  }
+}
+
+function isStaleLock(lock, staleMs) {
+  if (!lock || !lock.created_at) return true;
+  const createdAt = Date.parse(lock.created_at);
+  if (!Number.isFinite(createdAt)) return true;
+  return Date.now() - createdAt > staleMs || !isProcessAlive(Number(lock.pid));
+}
+
+function lockedError(changeName, lock) {
+  const owner = lock && lock.pid ? `，持有进程 PID=${lock.pid}` : '';
+  const error = new Error(`Change 正在进行语义事务: ${changeName}${owner}`);
+  error.code = 'SEM_CHANGE_LOCKED';
+  error.lock = lock || null;
+  return error;
+}
+
+function acquireChangeLock(projectRoot, changeName, options = {}) {
+  const paths = lockPaths(projectRoot, changeName);
+  const staleMs = Math.max(1000, Number(options.staleMs || DEFAULT_STALE_MS));
+  fs.mkdirSync(paths.dir, { recursive: true });
+
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    const token = crypto.randomUUID();
+    const lock = {
+      schema_version: 'kld-sdd-change-lock/v1',
+      change: safeChangeName(changeName),
+      token,
+      pid: process.pid,
+      created_at: new Date().toISOString(),
+    };
+    let descriptor;
+    try {
+      descriptor = fs.openSync(paths.file, 'wx');
+      fs.writeFileSync(descriptor, JSON.stringify(lock, null, 2) + '\n', 'utf8');
+      fs.closeSync(descriptor);
+      return { ...lock, path: paths.file };
+    } catch (error) {
+      if (descriptor !== undefined) fs.closeSync(descriptor);
+      if (!error || error.code !== 'EEXIST') throw error;
+      const existing = readLock(paths.file);
+      if (attempt === 0 && isStaleLock(existing, staleMs)) {
+        fs.rmSync(paths.file, { force: true });
+        continue;
+      }
+      throw lockedError(changeName, existing);
+    }
+  }
+  throw lockedError(changeName, readLock(paths.file));
+}
+
+function assertChangeLock(lock) {
+  if (!lock || !lock.path || !lock.token) {
+    const error = new Error('缺少 Change 事务锁');
+    error.code = 'SEM_CHANGE_LOCK_REQUIRED';
+    throw error;
+  }
+  const current = readLock(lock.path);
+  if (!current || current.token !== lock.token || current.pid !== lock.pid) {
+    const error = new Error(`Change 事务锁已失效: ${lock.change || 'unknown'}`);
+    error.code = 'SEM_CHANGE_LOCK_LOST';
+    throw error;
+  }
+  return current;
+}
+
+function releaseChangeLock(lock) {
+  if (!lock || !lock.path || !lock.token) return false;
+  const current = readLock(lock.path);
+  if (!current || current.token !== lock.token) return false;
+  fs.rmSync(lock.path, { force: true });
+  return true;
+}
+
+function withChangeLock(projectRoot, changeName, options, action) {
+  const lock = acquireChangeLock(projectRoot, changeName, options);
+  try {
+    return action(lock);
+  } finally {
+    releaseChangeLock(lock);
+  }
+}
+
+module.exports = {
+  DEFAULT_STALE_MS,
+  lockPaths,
+  acquireChangeLock,
+  assertChangeLock,
+  releaseChangeLock,
+  withChangeLock,
+};

package/skywalk-sdd/ontology/cli.cjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path');
+const {
+  scanChange,
+  reconcileChange,
+  readWorkingState,
+  createArchiveSnapshot,
+} = require('./runtime.cjs');
+const { observeChangeArtifacts } = require('./artifact-observer.cjs');
+const { allocateIdentity } = require('./id.cjs');
+
+function parseArgs(argv) {
+  const result = { _: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (!value.startsWith('--')) {
+      result._.push(value);
+      continue;
+    }
+    const equal = value.indexOf('=');
+    if (equal >= 0) {
+      result[value.slice(2, equal)] = value.slice(equal + 1);
+    } else if (argv[index + 1] && !argv[index + 1].startsWith('--')) {
+      result[value.slice(2)] = argv[index + 1];
+      index += 1;
+    } else {
+      result[value.slice(2)] = true;
+    }
+  }
+  return result;
+}
+
+function summary(result) {
+  return {
+    change: result.state.change,
+    profile: result.profile,
+    valid: result.valid,
+    revision: result.revision,
+    changed: result.changed,
+    counts: result.counts,
+    paths: result.paths,
+    diagnostics: result.diagnostics,
+  };
+}
+
+function showHelp() {
+  console.log(`KLD-SDD Ontology Runtime
+
+用法:
+  node skywalk-sdd/ontology/cli.cjs scan      --project=. --change=<name> [--profile=auto|simple|full|strict]
+  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 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>
+  node skywalk-sdd/ontology/cli.cjs observe   --project=. --change=<name> [--interval=1500]
+  node skywalk-sdd/ontology/cli.cjs snapshot  --project=. --change=<name> --archive=<path>
+
+observe 只负责采集和同步；check/archive 前仍必须执行 reconcile。`);
+}
+
+function main(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+  const command = args._[0];
+  if (!command || command === 'help' || args.help) {
+    showHelp();
+    return;
+  }
+  if (command === 'identity') {
+    console.log(JSON.stringify(allocateIdentity(args), null, 2));
+    return;
+  }
+  const projectRoot = path.resolve(args.project || '.');
+  const changeName = args.change;
+  if (!changeName) throw new Error('缺少 --change 参数');
+  const profile = args.profile || 'auto';
+
+  if (command === 'scan') {
+    const result = scanChange(projectRoot, changeName, { profile });
+    console.log(JSON.stringify(summary({ ...result, changed: false, paths: undefined }), null, 2));
+    if (!result.valid) process.exitCode = 1;
+    return;
+  }
+  if (command === 'reconcile' || command === 'check') {
+    const result = reconcileChange(projectRoot, changeName, {
+      profile,
+      markPending: command === 'check',
+    });
+    console.log(JSON.stringify(summary(result), null, 2));
+    if (!result.valid) process.exitCode = 1;
+    return;
+  }
+  if (command === 'status') {
+    const state = readWorkingState(projectRoot, changeName);
+    if (!state) throw new Error(`不存在工作态本体实例: ${changeName}`);
+    console.log(JSON.stringify(state, null, 2));
+    return;
+  }
+  if (command === 'snapshot') {
+    if (!args.archive) throw new Error('snapshot 缺少 --archive 参数');
+    const snapshot = createArchiveSnapshot(projectRoot, changeName, path.resolve(args.archive));
+    console.log(JSON.stringify(snapshot, null, 2));
+    return;
+  }
+  if (command === 'observe') {
+    const observer = observeChangeArtifacts(projectRoot, changeName, {
+      profile,
+      pollIntervalMs: Number(args.interval || 1500),
+      onReconciled(result) {
+        console.log(JSON.stringify(summary(result)));
+      },
+      onError(error) {
+        console.error(`[ontology-observer] ${error.message}`);
+      },
+    });
+    console.log(JSON.stringify({ change: changeName, mode: observer.mode, change_dir: observer.changeDir }));
+    const close = () => {
+      observer.close();
+      process.exit(0);
+    };
+    process.once('SIGINT', close);
+    process.once('SIGTERM', close);
+    return;
+  }
+
+  throw new Error(`未知 ontology 命令: ${command}`);
+}
+
+if (require.main === module) {
+  try {
+    main();
+  } catch (error) {
+    console.error(`错误: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  parseArgs,
+  summary,
+  showHelp,
+  main,
+};

package/skywalk-sdd/ontology/effective-graph.cjs

@@ -0,0 +1,158 @@
+'use strict';
+
+const { DIAGNOSTIC_CODES } = require('./schema.cjs');
+
+function resolutionDiagnostic(code, message, item, suggestion = '') {
+  return {
+    code,
+    severity: 'error',
+    message,
+    file: item && item.source && item.source.file || '',
+    line: Number(item && item.source && item.source.line || 0),
+    entity_id: item && (item.anchor_id || item.from) || undefined,
+    suggestion: suggestion || undefined,
+  };
+}
+
+function sourceMatches(record, sourceRef, anchorId) {
+  const normalized = String(sourceRef || '').replace(/\\/g, '/');
+  if (!normalized) return false;
+  const expectedTail = `${record.source && record.source.file || ''}#${anchorId}`;
+  return normalized.includes(`/archive/${record.change}/`) && normalized.endsWith(expectedTail);
+}
+
+function relationSourceMatches(root, sourceRef) {
+  const normalized = String(sourceRef || '').replace(/\\/g, '/');
+  return Boolean(normalized && normalized.includes(`/archive/${root.change}/`));
+}
+
+function buildEffectiveGraph(currentFacts, identityCatalog) {
+  const catalog = identityCatalog || { records: [], factsByRoot: new Map() };
+  const currentEntities = (currentFacts.entities || []).filter((entity) => entity.delta_state !== 'removed');
+  const currentRelations = (currentFacts.relations || []).slice();
+  const effectiveEntities = currentEntities.map((entity) => ({ ...entity, generation_role: 'current' }));
+  const effectiveRelations = currentRelations.map((relation) => ({ ...relation, generation_role: 'current' }));
+  const inheritedResolutions = [];
+  const resolutionDiagnostics = [];
+  const resolvedRoots = new Map();
+
+  for (const reference of currentFacts.inherited_references || []) {
+    const matches = (catalog.records || []).filter((record) => (
+      record.scope === 'archive'
+      && record.anchor_id === reference.anchor_id
+      && record.entity_id === reference.entity_id
+      && record.version_id === reference.version_id
+      && record.content_hash === reference.source_version_hash
+      && sourceMatches(record, reference.source_ref, reference.anchor_id)
+    ));
+    if (matches.length !== 1) {
+      resolutionDiagnostics.push(resolutionDiagnostic(
+        DIAGNOSTIC_CODES.VERSION_LINEAGE_MISSING,
+        `unchanged 引用必须唯一解析到 confirmed Archive: ${reference.anchor_id}`,
+        reference,
+        matches.length > 1 ? '消除重复 Archive 版本，禁止任选候选' : '修正 archive scope、UUID、anchor、source 和内容哈希',
+      ));
+      continue;
+    }
+    const record = matches[0];
+    const root = catalog.factsByRoot && catalog.factsByRoot.get(record.root_key);
+    const historicalEntity = root && root.facts.entities.find((entity) => (
+      entity.id === reference.anchor_id && entity.version_id === reference.version_id
+    ));
+    if (!root || !historicalEntity) {
+      resolutionDiagnostics.push(resolutionDiagnostic(
+        DIAGNOSTIC_CODES.VERSION_LINEAGE_MISSING,
+        `confirmed Archive 缺少可投影实体: ${reference.anchor_id}`,
+        reference,
+      ));
+      continue;
+    }
+    effectiveEntities.push({
+      ...historicalEntity,
+      delta_state: 'unchanged',
+      generation_role: 'inherited',
+      inherited_from: {
+        change: record.change,
+        source_revision: record.source_revision,
+        source_ref: reference.source_ref,
+      },
+    });
+    resolvedRoots.set(reference.anchor_id, root);
+    inheritedResolutions.push({
+      kind: 'entity',
+      anchor_id: reference.anchor_id,
+      root_key: record.root_key,
+      source_revision: record.source_revision,
+    });
+  }
+
+  const entityIds = new Set(effectiveEntities.map((entity) => entity.id));
+  for (const inherited of currentFacts.inherited_relations || []) {
+    const candidateRoots = [...new Set([
+      resolvedRoots.get(inherited.from),
+      resolvedRoots.get(inherited.to),
+    ].filter(Boolean))];
+    const matches = [];
+    for (const root of candidateRoots) {
+      if (!relationSourceMatches(root, inherited.source_ref)) continue;
+      for (const relation of root.facts.relations || []) {
+        if (relation.type === inherited.type && relation.from === inherited.from && relation.to === inherited.to) {
+          matches.push({ root, relation });
+        }
+      }
+    }
+    if (matches.length !== 1 || !entityIds.has(inherited.from) || !entityIds.has(inherited.to)) {
+      resolutionDiagnostics.push(resolutionDiagnostic(
+        DIAGNOSTIC_CODES.INHERITED_RELATION_MISSING,
+        `继承关系必须唯一存在且两端都在 Effective Graph: ${inherited.from} -${inherited.type}-> ${inherited.to}`,
+        inherited,
+        '显式继承关系两端实体，并核对 confirmed Archive relation source',
+      ));
+      continue;
+    }
+    effectiveRelations.push({
+      ...matches[0].relation,
+      generation_role: 'inherited',
+      inherited_from: {
+        change: matches[0].root.change,
+        source_revision: matches[0].root.source_revision,
+        source_ref: inherited.source_ref,
+      },
+    });
+    inheritedResolutions.push({
+      kind: 'relation',
+      type: inherited.type,
+      from: inherited.from,
+      to: inherited.to,
+      root_key: matches[0].root.rootKey,
+      source_revision: matches[0].root.source_revision,
+    });
+  }
+
+  const seenEntities = new Set();
+  const uniqueEntities = effectiveEntities.filter((entity) => {
+    const key = `${entity.id}:${entity.version_id || ''}`;
+    if (seenEntities.has(key)) return false;
+    seenEntities.add(key);
+    return true;
+  });
+  const seenRelations = new Set();
+  const uniqueRelations = effectiveRelations.filter((relation) => {
+    const key = `${relation.type}:${relation.from}:${relation.to}`;
+    if (seenRelations.has(key)) return false;
+    seenRelations.add(key);
+    return true;
+  });
+
+  return {
+    ...currentFacts,
+    effective_entities: uniqueEntities,
+    effective_relations: uniqueRelations,
+    inherited_resolutions: inheritedResolutions,
+    resolution_diagnostics: resolutionDiagnostics,
+  };
+}
+
+module.exports = {
+  buildEffectiveGraph,
+};

package/skywalk-sdd/ontology/id.cjs

@@ -0,0 +1,126 @@
+'use strict';
+
+const crypto = require('crypto');
+const { ID_PREFIX_TYPES, entityTypeForId } = require('./schema.cjs');
+
+function normalizeSlug(value) {
+  const raw = String(value || '').trim();
+  const ascii = raw
+    .normalize('NFKD')
+    .toUpperCase()
+    .replace(/[^A-Z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .replace(/-{2,}/g, '-');
+  if (ascii) return ascii;
+  if (!raw) return 'UNSCOPED';
+  return `U${crypto.createHash('sha1').update(raw).digest('hex').slice(0, 8).toUpperCase()}`;
+}
+
+function normalizePrefix(prefix) {
+  const normalized = String(prefix || '').trim().toUpperCase();
+  if (!ID_PREFIX_TYPES[normalized]) {
+    throw new Error(`不支持的实体 ID 前缀: ${prefix}`);
+  }
+  return normalized;
+}
+
+function nextEntityId(prefix, scope, existingIds = []) {
+  const normalizedPrefix = normalizePrefix(prefix);
+  const normalizedScope = normalizeSlug(scope);
+  const matcher = new RegExp(`^${normalizedPrefix}-${normalizedScope}-(\\d+)$`, 'i');
+  let max = 0;
+  for (const value of existingIds) {
+    const match = String(value || '').trim().match(matcher);
+    if (!match) continue;
+    max = Math.max(max, Number(match[1]) || 0);
+  }
+  return `${normalizedPrefix}-${normalizedScope}-${String(max + 1).padStart(3, '0')}`;
+}
+
+function isValidEntityId(entityId, expectedType = '') {
+  const value = String(entityId || '').trim().toUpperCase();
+  if (!/^(?:CHG|CAP|STMT|AC|CON|DES|TASK|ART|SEC|SNAP)-[A-Z0-9]+(?:-[A-Z0-9]+)*$/.test(value)) {
+    return false;
+  }
+  if (expectedType && entityTypeForId(value) !== expectedType) {
+    return false;
+  }
+  return true;
+}
+
+function generateUuidV7(timestamp = Date.now()) {
+  const milliseconds = Number(timestamp);
+  if (!Number.isSafeInteger(milliseconds) || milliseconds < 0 || milliseconds > 0xffffffffffff) {
+    throw new Error(`UUIDv7 时间戳非法: ${timestamp}`);
+  }
+  const bytes = crypto.randomBytes(16);
+  let value = BigInt(milliseconds);
+  for (let index = 5; index >= 0; index -= 1) {
+    bytes[index] = Number(value & 0xffn);
+    value >>= 8n;
+  }
+  bytes[6] = (bytes[6] & 0x0f) | 0x70;
+  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 isValidUuid(value) {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(String(value || '').trim());
+}
+
+const isValidUuidV7 = isValidUuid;
+
+function allocateIdentity(options = {}) {
+  const deltaState = String(options.deltaState || options['delta-state'] || 'added').trim().toLowerCase();
+  const entityId = String(options.entityId || options['entity-id'] || '').trim().toLowerCase();
+  const versionId = String(options.versionId || options['version-id'] || '').trim().toLowerCase();
+  const predecessorVersionId = String(
+    options.predecessorVersionId || options['predecessor-version'] || '',
+  ).trim().toLowerCase();
+
+  if (!['added', 'modified', 'unchanged', 'removed'].includes(deltaState)) {
+    throw new Error(`不支持的 delta-state: ${deltaState}`);
+  }
+  if (deltaState === 'added') {
+    return {
+      entity_id: generateUuidV7(),
+      version_id: generateUuidV7(),
+      predecessor_version_id: null,
+      delta_state: deltaState,
+    };
+  }
+  if (!isValidUuid(entityId)) {
+    throw new Error(`${deltaState} 必须提供有效的 --entity-id`);
+  }
+  if (deltaState === 'unchanged') {
+    if (!isValidUuid(versionId)) {
+      throw new Error('unchanged 必须提供既有 --version-id');
+    }
+    return {
+      entity_id: entityId,
+      version_id: versionId,
+      predecessor_version_id: null,
+      delta_state: deltaState,
+    };
+  }
+  if (!isValidUuid(predecessorVersionId)) {
+    throw new Error(`${deltaState} 必须提供有效的 --predecessor-version`);
+  }
+  return {
+    entity_id: entityId,
+    version_id: generateUuidV7(),
+    predecessor_version_id: predecessorVersionId,
+    delta_state: deltaState,
+  };
+}
+
+module.exports = {
+  normalizeSlug,
+  nextEntityId,
+  isValidEntityId,
+  generateUuidV7,
+  isValidUuid,
+  isValidUuidV7,
+  allocateIdentity,
+};