kld-sdd 2.7.8 → 2.8.0

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

@@ -3,6 +3,8 @@
 const fs = require('fs');
 const path = require('path');
 const { execFileSync } = require('child_process');
+// spec 判据的唯一真相源（spec-detect 对本模块的依赖是惰性，不构成循环）
+const specDetect = require('./spec-detect.cjs');
 
 const CODES = {
   MISSING: 'SDD_YAML_MISSING',
@@ -156,12 +158,18 @@ function resolveMonoSpecRoot(repoRoot) {
   return root;
 }
 
+/**
+ * 目录内容是否"像 spec 包"（任一产物标记存在）。
+ *
+ * ⚠️ 判据已收敛到 `spec-detect.cjs#hasSpecPackageContent`（全仓唯一判据入口）。
+ * 本函数保留仅为向后兼容既有调用点。
+ *
+ * 语义：仅用于用户**显式给定**路径的校验（`validateSpecPath` 的
+ * allowNestedPackage 分支）。不可用于检测 —— 单仓代码仓根可能有 modules.yaml
+ * 而无 openspec，仅凭内容无法区分。
+ */
 function looksLikeSpecPackageContent(dir) {
-  return (
-    fs.existsSync(path.join(dir, 'modules.yaml'))
-    || fs.existsSync(path.join(dir, 'sdd.config.yaml'))
-    || fs.existsSync(path.join(dir, 'openspec', 'changes'))
-  );
+  return specDetect.hasSpecPackageContent(dir);
 }
 
 function gitConfig(cwd, key) {
@@ -176,6 +184,25 @@ function gitConfig(cwd, key) {
   }
 }
 
+/**
+ * 删除 git config --local sdd.specPath（卸载用）。
+ * 配置项不存在时视为成功（幂等）。
+ */
+function unsetSpecPath(codeRepoRoot) {
+  if (!gitConfig(codeRepoRoot, 'sdd.specPath')) {
+    return { ok: true, removed: false };
+  }
+  try {
+    execFileSync('git', ['config', '--local', '--unset', 'sdd.specPath'], {
+      cwd: codeRepoRoot,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch (error) {
+    return { ok: false, message: `无法删除 git config sdd.specPath: ${error.message}` };
+  }
+  return { ok: true, removed: true };
+}
+
 function gitRemoteUrl(cwd, remote = 'origin') {
   try {
     return execFileSync('git', ['remote', 'get-url', remote], {
@@ -374,6 +401,7 @@ module.exports = {
   resolveSpecPath,
   validateSpecPath,
   setSpecPath,
+  unsetSpecPath,
   resolveCodeRepoContext,
   gitHeadSha,
   gitWorkingTreeClean,

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

@@ -0,0 +1,421 @@
+'use strict';
+
+/**
+ * spec 目录识别 —— **唯一判据入口**。
+ *
+ * 本模块只回答两个问题，不负责定位（定位在 resolve-spec-root.cjs）：
+ *
+ *   1. 「这个目录是不是 spec 包？」        → classifySpecDir / isSpecCandidate
+ *   2. 「候选有哪些、优先级如何？」        → detectSpecCandidates
+ *
+ * 为什么需要分级而不是单一布尔值：两类调用方的松紧要求本来就不同。
+ *
+ * - **检测**（"这个目录是不是当前项目的 spec 仓"）→ 严，避免误报。
+ *   例：`sddmult-sdd-specs` 是个只有 .git 的空壳，若仅凭目录名就认定，
+ *   会被当成 spec 包采纳（init 往里灌内容、sync-repos 把它的路径写进代码仓
+ *   git config）。故名称判定必须附带"至少一项 SDD 产物"。
+ * - **校验**（"用户显式给的路径能不能当 spec 用"）→ 宽，接受半成品。
+ *   例：`--skip-openspec` 时 `openspec/changes` 永不创建，四结构必然不齐，
+ *   但包裹包是合法的。
+ *
+ * 因此不是"同一个布尔值到处用"，而是**同一个函数返回等级，调用方按需取阈值**。
+ *
+ * 等级（tier 越小优先级越高）：
+ *
+ * | tier | 来源            | 判据                                              |
+ * |------|-----------------|---------------------------------------------------|
+ * | 0    | 显式声明        | `.sdd-spec-root` / `git config` / `.sdd.yaml mono` |
+ * |      |                 | / `.sdd-workspace.yaml spec_path`                  |
+ * | 1    | 四结构齐全      | modules.yaml + sdd.config.yaml + openspec/changes |
+ * |      |                 | + openspec/specs/overview.md                       |
+ * | 2    | 目录名          | `*-sdd-specs`（**含预填空壳**：用户先建目录后填充） |
+ * | —    | 非候选          | 无结构证据且目录名不匹配                           |
+ *
+ * 依赖方向：本模块是叶子节点，加载期不 require 任何其它 ontology 模块
+ * （需要 sdd-config / workspace-layout 时在函数内惰性 require），
+ * 因此 workspace-layout / resolve-spec-root / sdd-config 都可以安全依赖它。
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/** tier 常量 */
+const TIER = Object.freeze({
+  /** 显式声明：.sdd-spec-root / git config sdd.specPath / .sdd.yaml layout: mono */
+  DECLARED: 0,
+  /** 四结构齐全 */
+  STRUCTURE: 1,
+  /** 目录名 `*-sdd-specs`（含预填空壳） */
+  NAME: 2,
+});
+
+/**
+ * 四结构标记 —— tier 1 判据，**四项必须同时满足**。
+ *
+ * 与"名称判定"的关键区别：四结构不看目录名，因此用户自定义命名的包裹包
+ * （如 `erp-specs`）只要内容齐全也能被识别。
+ */
+const SPEC_STRUCTURE_MARKS = Object.freeze([
+  'modules.yaml',
+  'sdd.config.yaml',
+  'openspec/changes',
+  'openspec/specs/overview.md',
+]);
+
+/**
+ * 半成品标记 —— 用于「显式给定路径」的宽松校验（任一满足即可）。
+ *
+ * 为什么比四结构宽：`--skip-openspec` 下 `openspec/changes` 永不创建
+ *（openspec init 是唯一创建者），但包裹包合法。此判据只用于
+ * `validateSpecPath({ allowNestedPackage: true })` —— 路径是用户显式给的，
+ * 只需确认"内容像 spec 包"，无需确认"是不是当前项目的 spec 仓"。
+ */
+const SPEC_ARTIFACT_MARKS = Object.freeze([
+  'modules.yaml',
+  'sdd.config.yaml',
+  'openspec/changes',
+]);
+
+/**
+ * 候选来源的中文标签（供 init / uninstall / sync-repos 展示，唯一真相源）。
+ *
+ * **来源表示「怎么找到的」，判据强度由候选的 `tier` 字段承载**：
+ * - hint / git / mono  显式声明（权威）
+ * - workspace          工作区探测（子仓目录被识别为 spec 包）
+ * - scan               裸目录扫描命中（结构或命名，具体见 `evidence`）
+ *
+ * ⚠️ 历史文案 `workspace: '工作区探测：子仓结构判据命中'` 有误 —— 该来源
+ * 实际也可能由**目录名** `*-sdd-specs` 命中（空壳子仓即如此）。故标签不再
+ * 声称具体判据，避免与 `tier` 冲突。
+ */
+const SPEC_SOURCE_LABELS = Object.freeze({
+  hint: '权威：.sdd-spec-root 指向',
+  git: '权威：git config sdd.specPath',
+  mono: '权威：.sdd.yaml layout: mono',
+  'workspace-yaml': '权威：.sdd-workspace.yaml spec_path',
+  scan: '推测：目录内容或命名命中',
+});
+
+/** tier 内来源优先级（数值越小越靠前） */
+const SOURCE_RANK = Object.freeze({
+  hint: 0,
+  git: 1,
+  mono: 2,
+  'workspace-yaml': 3,
+  scan: 4,
+});
+
+/**
+ * 目录名是否符合 `*-sdd-specs` 命名约定。
+ *
+ * 单独导出是因为「名称命中」与「结构命中」是两个不同强度的证据，
+ * 调用方有时需要区分（如提示文案、诊断）。
+ *
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function isSpecDirName(dir) {
+  if (!dir) return false;
+  const name = path.basename(path.resolve(dir)).toLowerCase();
+  return /-sdd-specs$/.test(name) || name.endsWith('sdd-specs');
+}
+
+/** 列出实际存在的标记（相对路径用 posix 形式，便于展示与断言） */
+function listExistingMarks(dir, marks) {
+  return marks.filter((mark) => {
+    try {
+      return fs.existsSync(path.join(dir, ...mark.split('/')));
+    } catch {
+      return false;
+    }
+  });
+}
+
+/**
+ * 对目录做分级判定 —— **本模块的核心，全仓唯一的 spec 判据**。
+ *
+ * @param {string} dir 候选目录
+ * @returns {{tier: number, source: 'structure'|'name', evidence: string[]}|null}
+ *          null 表示不是 spec 候选
+ */
+function classifySpecDir(dir) {
+  if (!dir) return null;
+  const abs = path.resolve(dir);
+  let st;
+  try {
+    st = fs.statSync(abs);
+  } catch {
+    return null;
+  }
+  if (!st.isDirectory()) return null;
+
+  // tier 1：四结构齐全（不看目录名 —— 支持用户自定义命名）
+  const structure = listExistingMarks(abs, SPEC_STRUCTURE_MARKS);
+  if (structure.length === SPEC_STRUCTURE_MARKS.length) {
+    return { tier: TIER.STRUCTURE, source: 'structure', evidence: structure };
+  }
+
+  // tier 2：目录名命中。**空壳（evidence 为空）仍是候选** ——
+  // 典型场景是用户预建目录待填充；由调用方按 tier 排序决定取舍。
+  if (!isSpecDirName(abs)) return null;
+  return {
+    tier: TIER.NAME,
+    source: 'name',
+    evidence: listExistingMarks(abs, SPEC_ARTIFACT_MARKS),
+  };
+}
+
+/**
+ * 严格判据：是否可作为 spec 候选（检测用）。
+ *
+ * 与历史 `looksLikeSpecRepo` 语义等价 —— 名称命中**或**四结构齐全。
+ * 保留"名称即命中"是刻意的：空壳 `*-sdd-specs` 是预填场景，必须入选。
+ *
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function isSpecCandidate(dir) {
+  return classifySpecDir(dir) !== null;
+}
+
+/**
+ * 校验判据：目录是否可作为 kb-state.json 的宿主 / spec 根。
+ *
+ * 比 `isSpecCandidate` 多一条 `openspec/` 兜底 —— 半成品包裹包
+ * （`--skip-openspec` 产物，只有 openspec/ 目录树）也是合法的 spec 根。
+ *
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function isSpecPackageRoot(dir) {
+  if (!dir) return false;
+  const abs = path.resolve(dir);
+  if (classifySpecDir(abs)) return true;
+  try {
+    return fs.existsSync(path.join(abs, 'openspec'));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 宽松判据：目录内容是否"像 spec 包"（任一产物标记存在）。
+ *
+ * 仅用于用户**显式给定**路径的校验（`validateSpecPath` 的 allowNestedPackage）。
+ * 不可用于检测 —— 单仓代码仓根可能有 modules.yaml 而无 openspec。
+ *
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function hasSpecPackageContent(dir) {
+  if (!dir) return false;
+  const abs = path.resolve(dir);
+  try {
+    if (!fs.statSync(abs).isDirectory()) return false;
+  } catch {
+    return false;
+  }
+  return listExistingMarks(abs, SPEC_ARTIFACT_MARKS).length > 0;
+}
+
+/** 向上逐级读取 `.sdd-spec-root` 指针（内容为相对路径） */
+function resolveHintUpward(anchorRoot) {
+  let current = path.resolve(anchorRoot);
+  const stop = path.parse(current).root;
+  for (;;) {
+    const hintPath = path.join(current, '.sdd-spec-root');
+    if (fs.existsSync(hintPath)) {
+      try {
+        const rel = String(fs.readFileSync(hintPath, 'utf8') || '')
+          .trim()
+          .split(/\r?\n/)[0]
+          .trim();
+        if (rel) {
+          const abs = path.resolve(current, rel);
+          if (fs.existsSync(abs)) return abs;
+        }
+      } catch { /* 指针损坏：继续向上，不阻断 */ }
+    }
+    if (current === stop) break;
+    current = path.dirname(current);
+  }
+  return null;
+}
+
+/** 向上逐级查找 `.sdd.yaml` 的 `layout: mono` 声明 */
+function resolveMonoUpward(anchorRoot) {
+  let current = path.resolve(anchorRoot);
+  const stop = path.parse(current).root;
+  for (;;) {
+    try {
+      const sddConfig = require('./sdd-config.cjs');
+      if (sddConfig.isMonoLayout(current)) {
+        const resolved = sddConfig.resolveMonoSpecRoot(current);
+        if (resolved && fs.existsSync(resolved)) return resolved;
+      }
+    } catch { /* sdd-config 不可用时跳过该来源 */ }
+    if (current === stop) break;
+    current = path.dirname(current);
+  }
+  return null;
+}
+
+/**
+ * 向上逐级查找 `.sdd-workspace.yaml` 的 `spec_path` 声明（多仓布局）。
+ *
+ * 与 `resolveMonoUpward` 的区别：`.sdd.yaml layout: mono` 描述**单仓内**的包裹包，
+ * `.sdd-workspace.yaml` 描述**多仓工作区**的编排（spec 是兄弟目录的独立 Git 仓）。
+ * 二者都是显式声明，属权威来源。
+ *
+ * 解析委托 `workspace-layout.parseWorkspaceYaml`（唯一解析实现），避免此处
+ * 再写一遍正则 —— 历史上 skills 的 `opsx-consistency-check/scripts.cjs` 就是
+ * 自己解析该文件，导致「权威链不认这个来源、技能自己认」的不一致。
+ *
+ * @param {string} anchorRoot 搜索起点
+ * @returns {string|null} spec 根绝对路径；未声明 / 指向不存在时 null
+ */
+function resolveWorkspaceYamlUpward(anchorRoot) {
+  let current = path.resolve(anchorRoot);
+  const stop = path.parse(current).root;
+  for (;;) {
+    try {
+      const workspaceLayout = require('./workspace-layout.cjs');
+      const loaded = workspaceLayout.loadWorkspaceFile(current);
+      if (loaded.ok && loaded.data && loaded.data.spec_path) {
+        // spec_path 相对清单所在目录解析（清单是工作区级文件）
+        const abs = path.resolve(current, loaded.data.spec_path);
+        if (fs.existsSync(abs)) return abs;
+      }
+    } catch { /* 解析异常：继续向上，不阻断 */ }
+    if (current === stop) break;
+    current = path.dirname(current);
+  }
+  return null;
+}
+
+/**
+ * 枚举 spec 候选集合，按优先级排序。
+ *
+ * 这是 init / uninstall / sync-repos 三个 CLI 场景**共用**的入口：
+ * 三处都要求「多候选时让用户单选」，故必须返回集合而非单值。
+ *
+ * 来源与 tier：
+ * - hint / git / mono          → tier 0（显式声明，权威）
+ * - 子仓 / 子目录 / 根自身命中  → tier 1（四结构）或 tier 2（名称）
+ *
+ * 排序：tier 升序 → 来源优先级 → 名称升序（保证输出稳定、可断言）。
+ *
+ * @param {string} anchorRoot 探测起点（工作目录 / 工作区根）
+ * @param {{gitSpecPath?: string, includeRoot?: boolean}} [options]
+ *        gitSpecPath 由调用方读取后传入，避免本模块反向依赖 sdd-config 的 git 逻辑
+ * @returns {Array<{abs: string, name: string, source: string, tier: number, evidence: string[]}>}
+ */
+function detectSpecCandidates(anchorRoot, options = {}) {
+  const root = path.resolve(anchorRoot || process.cwd());
+  const includeRoot = options.includeRoot !== false;
+  const out = [];
+  const seen = new Set();
+
+  const push = (candidate, source, tier, evidence) => {
+    if (!candidate) return;
+    const abs = path.resolve(candidate);
+    if (seen.has(abs)) return;
+    let st;
+    try {
+      st = fs.statSync(abs);
+    } catch {
+      return;
+    }
+    if (!st.isDirectory()) return;
+    seen.add(abs);
+    out.push({
+      abs,
+      name: path.basename(abs),
+      source,
+      tier,
+      evidence: evidence || [],
+    });
+  };
+
+  // ── tier 0：显式声明（权威）──────────────────────────────
+  push(resolveHintUpward(root), 'hint', TIER.DECLARED, ['.sdd-spec-root']);
+  push(options.gitSpecPath, 'git', TIER.DECLARED, ['git config sdd.specPath']);
+  push(resolveMonoUpward(root), 'mono', TIER.DECLARED, ['.sdd.yaml layout: mono']);
+  push(resolveWorkspaceYamlUpward(root), 'workspace-yaml', TIER.DECLARED,
+    ['.sdd-workspace.yaml spec_path']);
+
+  // ── tier 1/2：结构 / 名称判据扫描（来源统一记 'scan'）──────
+  // 判据强度由 `tier` 承载，来源只表示「怎么找到的」，不表示判据类型 ——
+  // 否则 UI 无法解释「同一来源却强度不同」。具体命中判据见 `evidence`。
+  const pushClassified = (dir) => {
+    const classified = classifySpecDir(dir);
+    if (!classified) return;
+    push(dir, 'scan', classified.tier, classified.evidence);
+  };
+
+  // 根自身
+  if (includeRoot) pushClassified(root);
+
+  // 一级子目录（含非 Git 目录 —— 单仓包裹包不是独立 Git）
+  try {
+    const workspaceLayout = require('./workspace-layout.cjs');
+    for (const child of workspaceLayout.listChildDirectories(root)) {
+      pushClassified(child.abs);
+    }
+  } catch { /* workspace-layout 不可用时退化为仅根目录 */ }
+
+  out.sort((a, b) => {
+    if (a.tier !== b.tier) return a.tier - b.tier;
+    const rankA = SOURCE_RANK[a.source] ?? 99;
+    const rankB = SOURCE_RANK[b.source] ?? 99;
+    if (rankA !== rankB) return rankA - rankB;
+    return a.name.localeCompare(b.name);
+  });
+
+  return out;
+}
+
+/**
+ * 枚举候选集合，并自动读取 `git config --local sdd.specPath` 作为 tier 0 来源。
+ *
+ * 这是 CLI 三个场景（init / uninstall / sync-repos）**共用的唯一枚举入口**。
+ * 历史上 init 与 uninstall 各写了一份完全相同的实现（都只是「读 git config
+ * 后调 listSpecCandidates」），本函数把它收敛为一处。
+ *
+ * 为什么 git 读取放在这里而不是让调用方传入：读取逻辑需要 sdd-config，
+ * 而 sdd-config 顶层 require 本模块 —— 放在函数内惰性 require 可避免加载期
+ * 循环依赖（本模块顶层只依赖 fs/path）。
+ *
+ * @param {string} anchorRoot 探测起点（工作目录 / 工作区根）
+ * @returns {Array<{abs: string, name: string, source: string, tier: number, evidence: string[]}>}
+ */
+function detectSpecCandidatesWithGit(anchorRoot) {
+  const root = path.resolve(anchorRoot || process.cwd());
+  let gitSpecPath = '';
+  try {
+    gitSpecPath = require('./sdd-config.cjs').gitConfig(root, 'sdd.specPath') || '';
+  } catch { /* 非 Git 仓或 git 不可用：跳过该来源 */ }
+  return detectSpecCandidates(root, { gitSpecPath });
+}
+
+/** 取候选来源的中文标签；未知来源原样返回 */
+function specSourceLabel(source) {
+  return SPEC_SOURCE_LABELS[source] || source || '未知来源';
+}
+
+module.exports = {
+  TIER,
+  SPEC_STRUCTURE_MARKS,
+  SPEC_ARTIFACT_MARKS,
+  SPEC_SOURCE_LABELS,
+  SOURCE_RANK,
+  isSpecDirName,
+  classifySpecDir,
+  isSpecCandidate,
+  isSpecPackageRoot,
+  hasSpecPackageContent,
+  resolveWorkspaceYamlUpward,
+  detectSpecCandidates,
+  detectSpecCandidatesWithGit,
+  specSourceLabel,
+};