dsh-plugin-compat-check 0.1.0 → 0.1.2

package/kernel/lib/baseline.mjs

@@ -1,3 +1,4 @@
+import { validateBaseline } from "./contracts.mjs";
 /**
  * 基线：回答「**变了没有**」，以及变了多少、往哪个方向变。
  *
@@ -14,14 +15,14 @@
  *
  * ## 两条硬约束
  *
- * 1. **只写自己的状态目录**（Plan.md §2 第 1 题：插件严格只读之外的唯一例外）。
+ * 1. **只写自己的状态目录**（docs/Plan.md §1 与 §3 第 4 条：插件严格只读之外的唯一例外）。
  *    不联网、不外传 —— 「我装了哪些插件」是本机信息。
  * 2. **绝不把「没变」当成「没问题」。** 基线只回答差分；结论仍然来自判定引擎。
  *    两者混在一份输出里，会让人以为"没有变化"等于"兼容"。
  */
 
 /** 基线的存储版本：结构变了就要能识别出旧基线，而不是读出一个错的差分 */
-export const BASELINE_SCHEMA = 1;
+export const BASELINE_SCHEMA = 2;
 
 const has = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
 
@@ -35,7 +36,7 @@ const has = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
  * @param {object} verdict  buildVerdicts 的返回值
  * @param {string} dshVersion  当前 DSH 版本（它变了，方法级结论理应跟着变）
  */
-export function snapshotForBaseline(verdict, dshVersion) {
+export function snapshotForBaseline(verdict, dshVersion, identity = {}) {
   const plugins = {};
   const names = Object.keys(verdict.plugins || {}).sort();
   for (const name of names) {
@@ -47,16 +48,28 @@ export function snapshotForBaseline(verdict, dshVersion) {
       // 发现按稳定键排序：顺序不该影响「变了没有」
       findings: (p.findings || [])
         .map((f) => ({
-          key: f.service ? (f.method ? `${f.service}.${f.method}` : f.service) : '(declaration)',
+          key: f.service
+            ? f.method
+              ? `${f.service}.${f.method}`
+              : f.service
+            : "(declaration)",
           category: f.category,
           severity: f.severity,
           certainty: f.certainty,
           location: f.location ? `${f.location.file}:${f.location.line}` : null,
         }))
-        .sort((a, b) => a.key.localeCompare(b.key) || a.category.localeCompare(b.category)),
+        .sort(
+          (a, b) =>
+            a.key.localeCompare(b.key) || a.category.localeCompare(b.category),
+        ),
     };
   }
-  return { schemaVersion: BASELINE_SCHEMA, dshVersion: dshVersion ?? null, plugins };
+  return {
+    schemaVersion: BASELINE_SCHEMA,
+    dshVersion: dshVersion ?? null,
+    identity: { mode: verdict.observation?.mode ?? "unspecified", ...identity },
+    plugins,
+  };
 }
 
 /** 结论档位的"好坏"序：用于判断某个变化是变好还是变差 */
@@ -86,24 +99,39 @@ export function diffAgainstBaseline(prev, next) {
     removed: [],
     worsened: [],
     improved: [],
+    updated: [],
   };
 
   if (!prev || prev.schemaVersion !== BASELINE_SCHEMA) {
     out.reason = prev
       ? `基线结构版本不匹配（存的 ${prev.schemaVersion}，当前认 ${BASELINE_SCHEMA}）`
-      : '还没有基线（这是第一次体检）';
+      : "还没有基线（这是第一次体检）";
+    return out;
+  }
+  if (
+    JSON.stringify(prev.identity || {}) !== JSON.stringify(next.identity || {})
+  ) {
+    out.reason =
+      "体检对象、采样方式或判定规则变了，不能将两次结果当成插件状态变化";
+    return out;
+  }
+  if (validateBaseline(prev).length || validateBaseline(next).length) {
+    out.reason = "基线内容结构或契约损坏，本次不做比较";
     return out;
   }
   out.comparable = true;
   out.dshVersionFrom = prev.dshVersion ?? null;
   out.dshVersionTo = next.dshVersion ?? null;
-  out.dshVersionChanged = (prev.dshVersion ?? null) !== (next.dshVersion ?? null);
+  out.dshVersionChanged =
+    (prev.dshVersion ?? null) !== (next.dshVersion ?? null);
 
   const a = prev.plugins || {};
   const b = next.plugins || {};
 
-  for (const name of Object.keys(a)) if (!has(b, name)) out.removed.push({ name, version: a[name].version });
-  for (const name of Object.keys(b)) if (!has(a, name)) out.added.push({ name, version: b[name].version });
+  for (const name of Object.keys(a))
+    if (!has(b, name)) out.removed.push({ name, version: a[name].version });
+  for (const name of Object.keys(b))
+    if (!has(a, name)) out.added.push({ name, version: b[name].version });
 
   for (const name of Object.keys(a)) {
     if (!has(b, name)) continue;
@@ -118,8 +146,36 @@ export function diffAgainstBaseline(prev, next) {
 
     const xk = new Set(x.findings.map((f) => `${f.key}|${f.category}`));
     const yk = new Set(y.findings.map((f) => `${f.key}|${f.category}`));
-    const newFindings = y.findings.filter((f) => !xk.has(`${f.key}|${f.category}`));
-    const goneFindings = x.findings.filter((f) => !yk.has(`${f.key}|${f.category}`));
+    const newFindings = y.findings.filter(
+      (f) => !xk.has(`${f.key}|${f.category}`),
+    );
+    const goneFindings = x.findings.filter(
+      (f) => !yk.has(`${f.key}|${f.category}`),
+    );
+    const severityRank = { degraded: 0, "feature-dead": 1, fatal: 2 };
+    const certaintyRank = { suspected: 0, certain: 1 };
+    const changes = y.findings
+      .map((f) => ({
+        from: x.findings.find(
+          (g) => g.key === f.key && g.category === f.category,
+        ),
+        to: f,
+      }))
+      .filter(
+        (c) =>
+          c.from &&
+          (c.from.severity !== c.to.severity ||
+            c.from.certainty !== c.to.certainty ||
+            c.from.location !== c.to.location),
+      );
+    const evidenceWorse = changes.some(
+      (c) =>
+        severityRank[c.to.severity] > severityRank[c.from.severity] ||
+        certaintyRank[c.to.certainty] > certaintyRank[c.from.certainty],
+    );
+    const evidenceBetter = changes.some(
+      (c) => severityRank[c.to.severity] < severityRank[c.from.severity],
+    );
 
     const entry = {
       name,
@@ -130,33 +186,40 @@ export function diffAgainstBaseline(prev, next) {
       verdictTo: y.verdict,
       newFindings,
       goneFindings,
+      changedFindings: changes,
     };
 
     // 变差：档位下降，或**新增了发现**（档位可能没动，例如两条降级变三条）。
     // 注意 `newFindings.length` 优先于档位判断 —— 档位相同但多了发现也是变差。
-    if (worseVerdict || newFindings.length > 0) {
+    if (worseVerdict || newFindings.length > 0 || evidenceWorse) {
       entry.reason = worseVerdict
         ? `结论从「${x.verdict}」变为「${y.verdict}」`
-        : `新增 ${newFindings.length} 条发现（档位未变）`
+        : evidenceWorse
+          ? "已有发现的严重度或证据确定性提高了"
+          : `新增 ${newFindings.length} 条发现（档位未变）`;
       out.worsened.push(entry);
       continue;
     }
-    if (betterVerdict || goneFindings.length > 0) {
+    if (betterVerdict || goneFindings.length > 0 || evidenceBetter) {
       entry.reason = betterVerdict
         ? `结论从「${x.verdict}」变为「${y.verdict}」`
-        : `少了 ${goneFindings.length} 条发现（档位未变）`
+        : evidenceBetter
+          ? "已有发现的严重度降低了"
+          : `少了 ${goneFindings.length} 条发现（档位未变）`;
       out.improved.push(entry);
       continue;
     }
     // 什么都没变，但版本动了 —— 这也是一条要说的事
-    if (versionChanged) {
-      entry.reason = '版本变了，但结论与发现都没变'
-      out.improved.push(entry);
+    if (versionChanged || changes.length) {
+      entry.reason = versionChanged
+        ? "版本变了，但结论未变"
+        : "发现的位置或证据改变了";
+      out.updated.push(entry);
     }
   }
 
   // 稳定排序：角标与列表的顺序不该随对象键顺序变化
-  for (const k of ['added', 'removed', 'worsened', 'improved']) {
+  for (const k of ["added", "removed", "worsened", "improved", "updated"]) {
     out[k].sort((p, q) => p.name.localeCompare(q.name));
   }
   return out;
@@ -165,7 +228,7 @@ export function diffAgainstBaseline(prev, next) {
 /**
  * 角标该显示什么。
  *
- * 规则：**任何变化都打**，并标明方向（Plan.md §2 第 5 题）。
+ * 规则：**任何变化都打**，并标明方向（docs/Plan.md §2.2）。
  * 只有"变差"才亮会漏掉"变好" —— 而"某个插件被修好了、你可以放心留着了"
  * 同样是用户需要知道的事。
  *
@@ -174,19 +237,27 @@ export function diffAgainstBaseline(prev, next) {
 export function badgeFor(diff) {
   if (!diff || !diff.comparable) {
     // 没有基线不是"没变化" —— 它意味着**还比不了**。角标不打，但要说清为什么。
-    return { show: false, text: null, direction: null, detail: diff ? diff.reason : '没有基线' };
+    return {
+      show: false,
+      text: null,
+      direction: null,
+      detail: diff ? diff.reason : "没有基线",
+    };
   }
   const w = diff.worsened.length;
   const b = diff.improved.length;
   const add = diff.added.length;
   const rm = diff.removed.length;
+  const updated = (diff.updated || []).length;
 
-  if (w === 0 && b === 0 && add === 0 && rm === 0) {
+  if (w === 0 && b === 0 && add === 0 && rm === 0 && updated === 0) {
     return {
-      show: false, text: null, direction: 'neutral',
+      show: false,
+      text: null,
+      direction: "neutral",
       detail: diff.dshVersionChanged
-        ? `DSH 从 ${diff.dshVersionFrom ?? '?'} 变为 ${diff.dshVersionTo ?? '?'}，但所有插件的结论都没变`
-        : '与上次相比没有任何变化',
+        ? `DSH 从 ${diff.dshVersionFrom ?? "?"} 变为 ${diff.dshVersionTo ?? "?"}，但所有插件的结论都没变`
+        : "与上次相比没有任何变化",
     };
   }
 
@@ -195,16 +266,19 @@ export function badgeFor(diff) {
   if (b) bits.push(`变好 ${b}`);
   if (add) bits.push(`新增 ${add}`);
   if (rm) bits.push(`移除 ${rm}`);
-  const direction = w > 0 && b > 0 ? 'mixed' : (w > 0 ? 'worse' : (b > 0 ? 'better' : 'neutral'));
-  const arrow = direction === 'worse' ? '↓' : (direction === 'better' ? '↑' : '•');
+  if (updated) bits.push(`更新 ${updated}`);
+  const direction =
+    w > 0 && b > 0 ? "mixed" : w > 0 ? "worse" : b > 0 ? "better" : "neutral";
+  const arrow =
+    direction === "worse" ? "↓" : direction === "better" ? "↑" : "•";
 
   return {
     show: true,
-    text: `${arrow} ${bits.join(' · ')}`,
+    text: `${arrow} ${bits.join(" · ")}`,
     direction,
     detail: diff.dshVersionChanged
-      ? `DSH 版本也从 ${diff.dshVersionFrom ?? '?'} 变成了 ${diff.dshVersionTo ?? '?'} —— 这常常是上面这些变化的原因`
-      : 'DSH 版本没变',
+      ? `DSH 版本也从 ${diff.dshVersionFrom ?? "?"} 变成了 ${diff.dshVersionTo ?? "?"} —— 这常常是上面这些变化的原因`
+      : "DSH 版本没变",
   };
 }
 
@@ -215,13 +289,14 @@ export function badgeFor(diff) {
  * 而坏消息被"另外还发现两个插件变好了"稀释掉，就等于没说。
  */
 export function describeDiff(diff) {
-  if (!diff || !diff.comparable) return diff ? diff.reason : '没有基线';
+  if (!diff || !diff.comparable) return diff ? diff.reason : "没有基线";
   const badge = badgeFor(diff);
   if (!badge.show) return badge.detail;
   const L = [badge.text];
   for (const e of diff.worsened) {
     L.push(`  ↓ ${e.name}@${e.versionFrom}→${e.versionTo}：${e.reason}`);
-    for (const f of e.newFindings) L.push(`      新增：${f.key} @ ${f.location || '—'}`);
+    for (const f of e.newFindings)
+      L.push(`      新增：${f.key} @ ${f.location || "—"}`);
   }
   for (const e of diff.improved) {
     L.push(`  ↑ ${e.name}：${e.reason}`);
@@ -229,5 +304,6 @@ export function describeDiff(diff) {
   }
   for (const e of diff.added) L.push(`  + ${e.name}@${e.version}`);
   for (const e of diff.removed) L.push(`  − ${e.name}@${e.version}`);
-  return L.join('\n');
+  for (const e of diff.updated || []) L.push(`  • ${e.name}：${e.reason}`);
+  return L.join("\n");
 }