kld-sdd 2.6.6 → 2.6.8

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

@@ -0,0 +1,335 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const CODES = {
+  MISSING: 'SDD_YAML_MISSING',
+  FORMAT_INVALID: 'SDD_YAML_FORMAT_INVALID',
+  SPEC_PATH_MISSING: 'SDD_SPEC_PATH_MISSING',
+  SPEC_PATH_INVALID: 'SDD_SPEC_PATH_INVALID',
+  REMOTE_MISMATCH: 'SDD_SPEC_REMOTE_MISMATCH',
+};
+
+const LAYOUTS = {
+  MULTI: 'multi',
+  MONO: 'mono',
+};
+
+function stripYamlQuotes(value) {
+  const text = String(value == null ? '' : value).trim();
+  if (
+    (text.startsWith('"') && text.endsWith('"')) ||
+    (text.startsWith("'") && text.endsWith("'"))
+  ) {
+    return text.slice(1, -1);
+  }
+  return text;
+}
+
+/**
+ * Minimal parser for .sdd.yaml，两种布局：
+ *
+ * 多仓（默认）：spec 是另一个 clone
+ *   version: 1
+ *   spec_repository: git@host:group/repo.git
+ *
+ * 单仓：openspec 与代码同仓，无外部 spec 可指
+ *   version: 1
+ *   layout: mono
+ */
+function parseSddYaml(text) {
+  const lines = String(text || '').split(/\r?\n/);
+  let version = null;
+  let specRepository = null;
+  let layout = null;
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const raw = lines[index];
+    const line = raw.replace(/#.*$/, '').trim();
+    if (!line) continue;
+
+    const versionMatch = /^version:\s*(\d+)\s*$/.exec(line);
+    if (versionMatch) {
+      version = Number(versionMatch[1]);
+      continue;
+    }
+
+    const layoutMatch = /^layout:\s*(.+?)\s*$/.exec(line);
+    if (layoutMatch) {
+      const value = stripYamlQuotes(layoutMatch[1]).toLowerCase();
+      if (value !== LAYOUTS.MONO && value !== LAYOUTS.MULTI) {
+        return {
+          ok: false,
+          code: CODES.FORMAT_INVALID,
+          message: `.sdd.yaml layout 只能是 mono 或 multi，实际: ${value}`,
+        };
+      }
+      layout = value;
+      continue;
+    }
+
+    const repoMatch = /^spec_repository:\s*(.+?)\s*$/.exec(line);
+    if (repoMatch) {
+      specRepository = stripYamlQuotes(repoMatch[1]);
+      continue;
+    }
+
+    return {
+      ok: false,
+      code: CODES.FORMAT_INVALID,
+      message: `.sdd.yaml 第 ${index + 1} 行无法解析: ${raw}`,
+    };
+  }
+
+  if (version == null) {
+    return { ok: false, code: CODES.FORMAT_INVALID, message: '.sdd.yaml 缺少 version' };
+  }
+  if (version !== 1) {
+    return {
+      ok: false,
+      code: CODES.FORMAT_INVALID,
+      message: `不支持的 .sdd.yaml version: ${version}`,
+    };
+  }
+  const resolvedLayout = layout || LAYOUTS.MULTI;
+  // 单仓没有外部 spec 仓库可指，spec_repository 可省略
+  if (resolvedLayout === LAYOUTS.MULTI && !specRepository) {
+    return {
+      ok: false,
+      code: CODES.FORMAT_INVALID,
+      message: '.sdd.yaml 缺少 spec_repository（单仓请写 layout: mono）',
+    };
+  }
+
+  return {
+    ok: true,
+    version,
+    layout: resolvedLayout,
+    spec_repository: specRepository || '',
+  };
+}
+
+function loadSddYaml(codeRepoRoot) {
+  const filePath = path.join(codeRepoRoot, '.sdd.yaml');
+  if (!fs.existsSync(filePath)) {
+    return {
+      ok: false,
+      code: CODES.MISSING,
+      message: `.sdd.yaml 不存在: ${filePath}`,
+      path: filePath,
+    };
+  }
+  const parsed = parseSddYaml(fs.readFileSync(filePath, 'utf8'));
+  if (!parsed.ok) return { ...parsed, path: filePath };
+  return { ...parsed, path: filePath };
+}
+
+/** 单仓声明：.sdd.yaml 显式写了 layout: mono */
+function isMonoLayout(repoRoot) {
+  const loaded = loadSddYaml(repoRoot);
+  return loaded.ok && loaded.layout === LAYOUTS.MONO;
+}
+
+function gitConfig(cwd, key) {
+  try {
+    return execFileSync('git', ['config', '--local', '--get', key], {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return '';
+  }
+}
+
+function gitRemoteUrl(cwd, remote = 'origin') {
+  try {
+    return execFileSync('git', ['remote', 'get-url', remote], {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return '';
+  }
+}
+
+function normalizeRemoteUrl(url) {
+  if (!url) return '';
+  let value = String(url).trim().replace(/\\/g, '/');
+  value = value.replace(/\.git$/i, '');
+  const sshMatch = /^git@([^:]+):(.+)$/.exec(value);
+  if (sshMatch) {
+    return `${sshMatch[1].toLowerCase()}/${sshMatch[2].replace(/^\/+/, '').toLowerCase()}`;
+  }
+  const schemeMatch = /^https?:\/\/([^/]+)\/(.+)$/i.exec(value);
+  if (schemeMatch) {
+    return `${schemeMatch[1].toLowerCase()}/${schemeMatch[2].replace(/^\/+/, '').toLowerCase()}`;
+  }
+  return value.toLowerCase();
+}
+
+function remotesMatch(left, right) {
+  const a = normalizeRemoteUrl(left);
+  const b = normalizeRemoteUrl(right);
+  return Boolean(a && b && a === b);
+}
+
+function resolveSpecPath(codeRepoRoot, env = process.env) {
+  const fromEnv = env.KLD_SDD_SPEC_PATH && String(env.KLD_SDD_SPEC_PATH).trim();
+  if (fromEnv) {
+    return {
+      ok: true,
+      source: 'env',
+      path: path.resolve(fromEnv),
+    };
+  }
+
+  const fromGit = gitConfig(codeRepoRoot, 'sdd.specPath');
+  if (fromGit) {
+    return {
+      ok: true,
+      source: 'git-config',
+      path: path.resolve(fromGit),
+    };
+  }
+
+  return {
+    ok: false,
+    code: CODES.SPEC_PATH_MISSING,
+    message: '未找到 spec clone 路径。请设置 KLD_SDD_SPEC_PATH 或 git config --local sdd.specPath <path>',
+  };
+}
+
+function validateSpecPath(specPath) {
+  if (!specPath || !fs.existsSync(specPath)) {
+    return {
+      ok: false,
+      code: CODES.SPEC_PATH_INVALID,
+      message: `spec 路径不存在: ${specPath}`,
+    };
+  }
+  if (!fs.existsSync(path.join(specPath, '.git'))) {
+    return {
+      ok: false,
+      code: CODES.SPEC_PATH_INVALID,
+      message: `spec 路径不是 Git 仓库: ${specPath}`,
+    };
+  }
+  return { ok: true, path: specPath };
+}
+
+function setSpecPath(codeRepoRoot, specPath) {
+  const absolute = path.resolve(specPath);
+  const valid = validateSpecPath(absolute);
+  if (!valid.ok) return valid;
+  execFileSync('git', ['config', '--local', 'sdd.specPath', absolute], {
+    cwd: codeRepoRoot,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  return { ok: true, path: absolute };
+}
+
+function resolveCodeRepoContext(codeRepoRoot, env = process.env) {
+  const sddYaml = loadSddYaml(codeRepoRoot);
+  const specPathResult = resolveSpecPath(codeRepoRoot, env);
+  if (!specPathResult.ok) {
+    return {
+      ok: false,
+      code: specPathResult.code,
+      message: specPathResult.message,
+      sddYaml,
+      specPath: null,
+    };
+  }
+
+  const pathValid = validateSpecPath(specPathResult.path);
+  if (!pathValid.ok) {
+    return {
+      ok: false,
+      code: pathValid.code,
+      message: pathValid.message,
+      sddYaml,
+      specPath: specPathResult.path,
+      specPathSource: specPathResult.source,
+    };
+  }
+
+  const result = {
+    ok: true,
+    sddYaml,
+    specPath: pathValid.path,
+    specPathSource: specPathResult.source,
+    specRemote: gitRemoteUrl(pathValid.path),
+  };
+
+  if (sddYaml.ok && result.specRemote) {
+    result.remoteMatches = remotesMatch(sddYaml.spec_repository, result.specRemote);
+    if (!result.remoteMatches) {
+      result.ok = false;
+      result.code = CODES.REMOTE_MISMATCH;
+      result.message = `.sdd.yaml spec_repository 与本地 spec remote 不一致: ${sddYaml.spec_repository} vs ${result.specRemote}`;
+    }
+  }
+
+  return result;
+}
+
+function gitHeadSha(repoRoot) {
+  try {
+    return execFileSync('git', ['rev-parse', 'HEAD'], {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return '';
+  }
+}
+
+function gitWorkingTreeClean(repoRoot) {
+  try {
+    const status = execFileSync('git', ['status', '--porcelain'], {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    return status === '';
+  } catch {
+    return false;
+  }
+}
+
+function objectExists(repoRoot, sha) {
+  if (!sha) return false;
+  try {
+    execFileSync('git', ['cat-file', '-e', `${sha}^{commit}`], {
+      cwd: repoRoot,
+      stdio: ['ignore', 'ignore', 'ignore'],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  CODES,
+  LAYOUTS,
+  parseSddYaml,
+  isMonoLayout,
+  loadSddYaml,
+  gitConfig,
+  gitRemoteUrl,
+  normalizeRemoteUrl,
+  remotesMatch,
+  resolveSpecPath,
+  validateSpecPath,
+  setSpecPath,
+  resolveCodeRepoContext,
+  gitHeadSha,
+  gitWorkingTreeClean,
+  objectExists,
+};

package/skywalk-sdd/ontology/traceability-validator.cjs

@@ -453,8 +453,94 @@ function validateContinuityAndExternalRefs(facts, diagnostics, options = {}) {
     }
   }
 
+  const {
+    validate,
+    normalize,
+    parseScenario,
+  } = require('./external-key.cjs');
+
+  // 仅当 frontmatter 显式出现 requirement-refs / numbering-waiver 时启用入场门禁
+  // （新模板默认带 requirement-refs；旧夹具无该节则不强制）
+  const numberingDeclared = Boolean(facts.numbering_gate)
+    || (facts.numbering_waiver && typeof facts.numbering_waiver === 'object');
+  const requirementRefs = Array.isArray(facts.requirement_refs) ? facts.requirement_refs : [];
+  const waiverReason = String(
+    (facts.numbering_waiver && (facts.numbering_waiver.reason || facts.numbering_waiver.Reason)) || '',
+  ).trim();
+  if (numberingDeclared) {
+    if (requirementRefs.length === 0 && !waiverReason) {
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.CONTINUITY_DECISION_REQUIRED,
+        'error',
+        '缺少格式合规的 requirement-refs，且未提供 numbering-waiver.reason',
+        {
+          file: 'proposal.md',
+          suggestion: '申报 REQ 号，或填写 numbering-waiver.reason（探索性/纯内部重构）',
+        },
+      ));
+    }
+    if (requirementRefs.length === 0 && waiverReason) {
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.NUMBERING_WAIVER_ACTIVE,
+        'warning',
+        `编号豁免生效：${waiverReason}（本轮不种桥）`,
+        { file: 'proposal.md' },
+      ));
+    }
+    if (requirementRefs.length > 0 && waiverReason) {
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.EXTERNAL_KEY_FORMAT_INVALID,
+        'error',
+        'numbering-waiver 与非空 requirement-refs 互斥',
+        { file: 'proposal.md', suggestion: '清空其一' },
+      ));
+    }
+  }
+
+  const declaredReqIds = new Set();
+  const featureByReq = new Map();
+  for (const ref of requirementRefs) {
+    const objectType = String(ref.object_type || 'requirement').toLowerCase();
+    const format = validate(ref.external_id, objectType);
+    if (!format.ok) {
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.EXTERNAL_KEY_FORMAT_INVALID,
+        'error',
+        format.message,
+        { file: 'proposal.md', suggestion: '回需求管理系统核实/换发编号，禁止改写' },
+      ));
+      continue;
+    }
+    const normalizedReq = normalize(ref.external_id, objectType);
+    if (objectType === 'requirement') {
+      declaredReqIds.add(normalizedReq);
+      if (ref.feature_id_invalid) {
+        diagnostics.push(diagnostic(
+          DIAGNOSTIC_CODES.EXTERNAL_KEY_FORMAT_INVALID,
+          'error',
+          `feature-id 不合规: ${ref.feature_id_invalid}`,
+          { file: 'proposal.md', suggestion: '回需求管理系统核实 FEAT 号，禁止静默丢弃' },
+        ));
+      } else if (ref.feature_id) {
+        if (featureByReq.has(normalizedReq) && featureByReq.get(normalizedReq) !== ref.feature_id) {
+          diagnostics.push(diagnostic(
+            DIAGNOSTIC_CODES.EXTERNAL_KEY_FEATURE_UNDECLARED,
+            'error',
+            `同一 Change 内同一 REQ 申报了多个 feature-id: ${normalizedReq}`,
+            { file: 'proposal.md' },
+          ));
+        }
+        featureByReq.set(normalizedReq, normalize(ref.feature_id, 'feature'));
+      }
+    }
+  }
+
   const bindingKeys = new Map();
+  const scenarioKeysInChange = new Set();
+  const removedScenarioKeys = new Set();
   for (const entity of facts.entities || []) {
+    const declaredFeatures = new Set();
+    const featureBindings = new Set();
     for (const ref of entity.external_refs || []) {
       const objectType = String(ref.object_type || '').toLowerCase();
       const allowedTypes = allowed[objectType];
@@ -475,6 +561,59 @@ function validateContinuityAndExternalRefs(facts, diagnostics, options = {}) {
           { ...sourceContext(entity), entity_id: entity.id },
         ));
       }
+      const format = validate(ref.external_id, objectType);
+      if (!format.ok) {
+        diagnostics.push(diagnostic(
+          DIAGNOSTIC_CODES.EXTERNAL_KEY_FORMAT_INVALID,
+          'error',
+          `${format.message} (${entity.id})`,
+          {
+            ...sourceContext(entity),
+            entity_id: entity.id,
+            suggestion: '编号不合规回需求系统换发；场景键回 opsx-spec 修正',
+          },
+        ));
+      }
+      if (ref.feature_id) {
+        const featureFormat = validate(ref.feature_id, 'feature');
+        if (!featureFormat.ok) {
+          diagnostics.push(diagnostic(
+            DIAGNOSTIC_CODES.EXTERNAL_KEY_FORMAT_INVALID,
+            'error',
+            `requirement.feature_id 不合规: ${featureFormat.message} (${entity.id})`,
+            { ...sourceContext(entity), entity_id: entity.id },
+          ));
+        } else {
+          declaredFeatures.add(normalize(ref.feature_id, 'feature'));
+        }
+      }
+      if (objectType === 'feature') {
+        featureBindings.add(normalize(ref.external_id, 'feature'));
+      }
+      if (objectType === 'scenario') {
+        const normalizedScenario = normalize(ref.external_id, 'scenario');
+        const parts = parseScenario(normalizedScenario);
+        if (parts && declaredReqIds.size > 0 && !declaredReqIds.has(parts.requirementId)) {
+          diagnostics.push(diagnostic(
+            DIAGNOSTIC_CODES.EXTERNAL_KEY_SCOPE_MISMATCH,
+            'error',
+            `场景键 REQ 前缀不在 frontmatter requirement-refs 申报集合: ${normalizedScenario}`,
+            { ...sourceContext(entity), entity_id: entity.id },
+          ));
+        }
+        if (scenarioKeysInChange.has(normalizedScenario)) {
+          diagnostics.push(diagnostic(
+            DIAGNOSTIC_CODES.EXTERNAL_KEY_SEQ_REUSED,
+            'error',
+            `本 Change 内 SCN 键重复: ${normalizedScenario}`,
+            { ...sourceContext(entity), entity_id: entity.id },
+          ));
+        }
+        scenarioKeysInChange.add(normalizedScenario);
+        if (String(entity.delta_state || '').toLowerCase() === 'removed') {
+          removedScenarioKeys.add(normalizedScenario);
+        }
+      }
       const key = `${ref.system}|${objectType}|${ref.external_id}|${entity.anchor_id || entity.id}`;
       const prior = bindingKeys.get(key);
       if (prior && prior !== entity.entity_id) {
@@ -492,6 +631,42 @@ function validateContinuityAndExternalRefs(facts, diagnostics, options = {}) {
         bindingKeys.set(key, entity.entity_id);
       }
     }
+    for (const featureId of featureBindings) {
+      if (!declaredFeatures.has(featureId)) {
+        diagnostics.push(diagnostic(
+          DIAGNOSTIC_CODES.EXTERNAL_KEY_FEATURE_UNDECLARED,
+          'error',
+          `feature 绑定无法与同实体 requirement.feature_id 配对: ${featureId} (${entity.id})`,
+          { ...sourceContext(entity), entity_id: entity.id },
+        ));
+      }
+    }
+    for (const featureId of declaredFeatures) {
+      if (!featureBindings.has(featureId)) {
+        diagnostics.push(diagnostic(
+          DIAGNOSTIC_CODES.EXTERNAL_KEY_FEATURE_UNDECLARED,
+          'error',
+          `requirement 申报了 feature_id 但缺少对应 feature 绑定: ${featureId} (${entity.id})`,
+          { ...sourceContext(entity), entity_id: entity.id },
+        ));
+      }
+    }
+  }
+
+  for (const entity of facts.entities || []) {
+    if (String(entity.delta_state || '').toLowerCase() === 'removed') continue;
+    for (const ref of entity.external_refs || []) {
+      if (String(ref.object_type || '').toLowerCase() !== 'scenario') continue;
+      const key = normalize(ref.external_id, 'scenario');
+      if (removedScenarioKeys.has(key) && String(entity.delta_state || '').toLowerCase() !== 'removed') {
+        diagnostics.push(diagnostic(
+          DIAGNOSTIC_CODES.EXTERNAL_KEY_SEQ_REUSED,
+          'error',
+          `复用了 removed 墓碑 SCN 号: ${key}`,
+          { ...sourceContext(entity), entity_id: entity.id },
+        ));
+      }
+    }
   }
 }