dsh-plugin-compat-check 0.1.0 → 0.1.2

package/kernel/lib/flow-values.mjs

@@ -0,0 +1,53 @@
+/** Small abstract values only; no inspected code is evaluated. */
+export function hasEvidence(value, seen = new Set()) {
+  if (!value || seen.has(value)) return false;
+  seen.add(value);
+  if (["context", "service", "method"].includes(value.kind)) return true;
+  if (value.kind === "proxy") return hasEvidence(value.target, seen);
+  return value.fields
+    ? [...value.fields.values()].some((v) => hasEvidence(v, seen))
+    : false;
+}
+export function hasProof(value, seen = new Set()) {
+  if (!value || seen.has(value)) return false;
+  seen.add(value);
+  if (value.kind === "proxy")
+    return (
+      !value.handler?.opaque &&
+      value.handler?.fields?.size === 0 &&
+      hasProof(value.target, seen)
+    );
+  if (value.kind === "context" || value.kind === "service")
+    return value.inferred === false && !value.state?.opaque;
+  if (value.kind === "method") return hasProof(value.receiver, seen);
+  return value.fields && !value.opaque
+    ? [...value.fields.values()].some((v) => hasProof(v, seen))
+    : false;
+}
+export function sameValue(a, b, depth = 0) {
+  if (a === b) return true;
+  if (!a || !b || a.kind !== b.kind || depth > 12) return false;
+  if (a.kind === "constant") return a.value === b.value;
+  // Mutable values are equal only when they share identity. Structural equality
+  // must never choose one object as the destination of a conditional write.
+  if (a.kind === "context" || a.kind === "service")
+    return (
+      a.kind === b.kind &&
+      a.service === b.service &&
+      a.inferred === b.inferred &&
+      !!a.state &&
+      a.state === b.state
+    );
+  if (a.kind === "method")
+    return (
+      a.service === b.service &&
+      a.method === b.method &&
+      sameValue(a.receiver, b.receiver, depth + 1)
+    );
+  return false;
+}
+export function mergedValue(values) {
+  return values.length && values.every((v) => sameValue(v, values[0]))
+    ? values[0]
+    : null;
+}

package/kernel/lib/observation.mjs

@@ -0,0 +1,182 @@
+import path from "node:path";
+
+const object = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const samePath = (a, b) => path.resolve(a) === path.resolve(b);
+
+/** Legacy reports authorize only their explicit keys, never missing keys. */
+export function normalizeObservation(surface, target = {}) {
+  if (surface?.error) throw new Error(`Probe failed: ${String(surface.error)}`);
+  const root = Object.create(null),
+    notes = [];
+  if (surface === null || surface === undefined)
+    return { root, notes, bound: false, usable: false };
+  if (!object(surface) || !object(surface.root))
+    throw new Error("探针报告必须包含对象类型 root");
+  const bound = surface.observationVersion === 1;
+  if (
+    bound &&
+    ((target.profileId &&
+      (!surface.profileId || !samePath(surface.profileId, target.profileId))) ||
+      (target.dshVersion && surface.dshVersion !== target.dshVersion))
+  ) {
+    notes.push("探针的 profile/DSH 版本与体检对象不匹配，忽略运行时证据");
+    return { root, notes, bound, usable: false };
+  }
+  if (
+    bound &&
+    target.maxAgeMs &&
+    (!surface.probedAt ||
+      !Number.isFinite(Date.parse(surface.probedAt)) ||
+      Date.now() - Date.parse(surface.probedAt) > target.maxAgeMs)
+  ) {
+    notes.push("探针采样时间缺失或已过期，忽略运行时证据");
+    return { root, notes, bound, usable: false };
+  }
+  if (!bound)
+    notes.push(
+      "旧格式探针未绑定 profile/DSH 版本；仅使用显式记录的服务，不推断缺项",
+    );
+  for (const [name, info] of Object.entries(surface.root)) {
+    if (!object(info)) throw new Error(`探针服务 ${name} 的记录必须为对象`);
+    if (info.methods !== undefined && !object(info.methods))
+      throw new Error(`探针服务 ${name}.methods 必须为对象`);
+    const status =
+      info.error || info.status === "unreadable"
+        ? "unreadable"
+        : info.status === "unobserved"
+          ? "unobserved"
+          : info.present === true || info.status === "present"
+            ? "present"
+            : info.present === false || info.status === "absent"
+              ? "absent"
+              : "unobserved";
+    root[name] = {
+      status,
+      methods: Object.keys(info.methods || {}),
+      complete:
+        info.methods !== undefined &&
+        info.truncated !== true &&
+        info.namesComplete !== false &&
+        (info.namesComplete === true || info.complete !== false),
+      unknownMethods: Array.isArray(info.unknownMethods)
+        ? info.unknownMethods.filter((n) => typeof n === "string")
+        : [],
+      nonCallableMethods: Array.isArray(info.nonCallableMethods)
+        ? info.nonCallableMethods.filter((n) => typeof n === "string")
+        : [],
+      reason: info.error || null,
+    };
+  }
+  if (surface.entries?.note)
+    notes.push(`Loader 覆盖限制：${String(surface.entries.note)}`);
+  if (surface.entries?.unmapped?.length)
+    notes.push(
+      `Loader 有 ${surface.entries.unmapped.length} 个条目无法映射到包名`,
+    );
+  return {
+    root,
+    notes,
+    bound,
+    usable: true,
+    probedAt: surface.probedAt ?? null,
+    profileId: surface.profileId ?? null,
+    dshVersion: surface.dshVersion ?? null,
+  };
+}
+
+/** Shape inspection reads descriptors; it never invokes service getters. */
+export function serviceShape(
+  service,
+  { maxMethods = 200, maxDepth = 12 } = {},
+) {
+  const methods = {},
+    unknownMethods = [],
+    nonCallableMethods = [],
+    seen = new Set();
+  if (service === null || service === undefined)
+    return {
+      methods,
+      complete: false,
+      namesComplete: false,
+      truncated: false,
+      unknownMethods,
+      nonCallableMethods,
+    };
+  let obj = Object(service),
+    depth = 0,
+    truncated = false;
+  while (obj) {
+    if (depth++ >= maxDepth) {
+      truncated = true;
+      break;
+    }
+    for (const key of Object.getOwnPropertyNames(obj)) {
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const descriptor = Object.getOwnPropertyDescriptor(obj, key);
+      if (!descriptor) continue;
+      if (!("value" in descriptor)) {
+        unknownMethods.push(key);
+        continue;
+      }
+      if (typeof descriptor.value === "function") {
+        if (Object.keys(methods).length >= maxMethods) {
+          truncated = true;
+          continue;
+        }
+        Object.defineProperty(methods, key, {
+          value: "function",
+          enumerable: true,
+        });
+      } else if (descriptor.value !== null && descriptor.value !== undefined)
+        nonCallableMethods.push(key);
+    }
+    obj = Object.getPrototypeOf(obj);
+  }
+  return {
+    methods,
+    complete: !truncated && unknownMethods.length === 0,
+    namesComplete: !truncated,
+    truncated,
+    unknownMethods,
+    nonCallableMethods,
+  };
+}
+
+export function sampleServices(
+  ctx,
+  names,
+  { profileId = null, dshVersion = null } = {},
+) {
+  const root = Object.create(null);
+  for (const name of [...new Set(names)].sort()) {
+    try {
+      const value =
+        typeof ctx.get === "function" ? ctx.get(name, false) : ctx[name];
+      root[name] =
+        value === undefined
+          ? { present: false, status: "absent" }
+          : value === null
+            ? {
+                present: true,
+                status: "unreadable",
+                error:
+                  "Service value is null; dependency presence is not proven",
+              }
+            : { present: true, status: "present", ...serviceShape(value) };
+    } catch {
+      root[name] = {
+        status: "unreadable",
+        error: "Service structure could not be read",
+      };
+    }
+  }
+  return {
+    observationVersion: 1,
+    probedAt: new Date().toISOString(),
+    profileId,
+    dshVersion,
+    wanted: Object.keys(root),
+    root,
+  };
+}

package/kernel/lib/report-service.mjs

@@ -0,0 +1,55 @@
+/** Single flight per target; retain the last valid report on failed refresh. */
+export class ReportService {
+  constructor(compute, { ttlMs = 300000, clock = Date.now } = {}) {
+    this.compute = compute;
+    this.ttlMs = ttlMs;
+    this.clock = clock;
+    this.states = new Map();
+  }
+  state(key) {
+    if (!this.states.has(key))
+      this.states.set(key, {
+        report: null,
+        at: 0,
+        inflight: null,
+        error: null,
+      });
+    return this.states.get(key);
+  }
+  start(state, options) {
+    if (state.inflight) return state.inflight;
+    state.inflight = Promise.resolve()
+      .then(() => this.compute(options))
+      .then((out) => {
+        if (out?.ok === true) {
+          state.report = out;
+          state.at = this.clock();
+          state.error = null;
+        } else state.error = out?.error || "体检未产生有效报告";
+        return out;
+      })
+      .catch((error) => {
+        state.error = error.message;
+        return { ok: false, error: state.error };
+      })
+      .finally(() => {
+        state.inflight = null;
+      });
+    return state.inflight;
+  }
+  async get(key, options = {}, force = false) {
+    const state = this.state(key),
+      age = this.clock() - state.at;
+    if (force || !state.report) return this.start(state, options);
+    if (age > this.ttlMs) this.start(state, options);
+    return {
+      ...state.report,
+      cache: {
+        hit: true,
+        ageMs: age,
+        refreshing: !!state.inflight,
+        refreshError: state.error,
+      },
+    };
+  }
+}

package/kernel/lib/report.mjs

@@ -0,0 +1,237 @@
+/**
+ * 结论的**渲染**：给人看的表 + 给机器看的 JSON。
+ *
+ * ## 为什么单独一个文件
+ *
+ * 到 D1 为止，「一份结论」已经有三个消费方：CLI、对话工具、面板。
+ * 它们各自的**呈现**不同（终端表 / 文本 / DOM），但**取值口径**必须完全一致 ——
+ * 标签文案、排序、哪一类发现要标「疑似」、哪些"没发现"要额外解释。
+ * 把这些放在一处，是为了让"面板说可用、工具说部分可用"这类分叉**在结构上不可能发生**。
+ *
+ * 它不做判定。判定在 `lib/verdict.mjs`；这里只把判定结果翻译成人话。
+ */
+
+import { TOOL_VERSION } from "./version.mjs";
+import path from "node:path";
+import { sealReportBody, createFailure } from "./contracts.mjs";
+import { DISPOSITION } from "./verdict.mjs";
+import { describeDiff } from "./baseline.mjs";
+
+const VERDICT_LABEL = {
+  ok: "可用",
+  partial: "部分可用",
+  broken: "不兼容",
+  unknown: "未知",
+};
+const SEVERITY_LABEL = {
+  fatal: "致命",
+  "feature-dead": "功能失效",
+  degraded: "降级",
+};
+const CATEGORY_LABEL = {
+  "host-service-missing": "宿主服务缺失",
+  "host-method-missing": "宿主方法缺失",
+  "unprovided-dependency": "无人提供的依赖",
+  "declaration-mismatch": "声明与实测不符",
+  "declared-incompatible": "版本声明不支持",
+  "host-entry-inactive": "宿主条目未激活",
+  "client-entry-missing": "客户端入口不可交付",
+};
+
+/** 在终端里对齐中英文混排用的显示宽度（东亚字符按 2 列算） */
+const pad = (s, n) => {
+  const w = [...String(s)].reduce(
+    (a, c) => a + (c.charCodeAt(0) > 0x2e80 ? 2 : 1),
+    0,
+  );
+  return String(s) + " ".repeat(Math.max(0, n - w));
+};
+
+export function render(result, opts) {
+  const L = [];
+  const { verdict, extract } = result;
+
+  if (result.error) {
+    L.push(`结论: 无法判定 —— ${result.error}`);
+    return L.join("\n");
+  }
+
+  const meta = extract.report.manifests;
+  // `--quiet` 只输出那一条总结论。真实 profile 上有 21 个插件、每个几行，
+  // 而这个开关的用途是「脚本里只要一个信号」—— 它必须真的安静，而不是「安静一点」。
+  // （本会话里已经踩过一次死参数：.sh 的 --json 被解析却从没被用过。）
+  if (opts.quiet) {
+    const q = verdict.summary;
+    L.push(
+      `结论: ${VERDICT_LABEL.ok} ${q.ok}    ${VERDICT_LABEL.partial} ${q.partial}    ${VERDICT_LABEL.broken} ${q.broken}`,
+    );
+    return L.join("\n");
+  }
+
+  L.push(
+    `插件数: ${meta.length}    有运行时面: ${result.inputs.hasRuntimeSurface ? "是" : "否（方法级结论降为「疑似」）"}`,
+  );
+  L.push("");
+  for (const note of verdict.observation?.notes || [])
+    L.push(`采样说明: ${note}`);
+  L.push(
+    `工具版本: ${TOOL_VERSION}${verdict.summary.limited ? `    证据覆盖有限: ${verdict.summary.limited} 个插件` : ""}`,
+  );
+
+  const s = verdict.summary;
+  L.push(
+    `结论: ${VERDICT_LABEL.ok} ${s.ok}    ${VERDICT_LABEL.partial} ${s.partial}    ${VERDICT_LABEL.broken} ${s.broken}` +
+      (s.vacuousOk
+        ? `    （其中 ${s.vacuousOk} 个「可用」是空洞的：它没有任何可检查的依赖）`
+        : ""),
+  );
+  L.push("");
+
+  // ── 与上次比 ──
+  // 放在结论之后、逐插件之前：用户先要知道"整体变了没有"，再决定看细节。
+  // 而且**「没有变化」也要说出来** —— 沉默会让人以为没检查，或者以为坏消息被藏起来了。
+  if (result.baseline) {
+    const b = result.baseline;
+    L.push("与上次相比:");
+    // ⚠️ `note` 优先于 `badge.detail`。当基线**读不出来**时，diff 会退化成
+    // 「还没有基线（这是第一次体检）」—— 两种完全不同的事得到同一句话：
+    // 一种是"你没跑过"，另一种是"你的基线坏了"。后者必须说出来，
+    // 否则用户会以为没有变化，继续用着已经变坏的环境。
+    if (b.note) {
+      L.push(`  ${b.note}`);
+    } else if (b.badge && b.badge.show) {
+      L.push(`${b.badge.text}`);
+      for (const line of describeDiff(b.diff).split("\n").slice(1))
+        L.push(line);
+    } else {
+      L.push(`  ${(b.badge && b.badge.detail) || "没有可比基线"}`);
+    }
+    if (b.writeError) L.push(`  ⚠️ ${b.writeError}`);
+    L.push(`  基线: ${b.file}${b.wrote ? "" : "（本次未写入）"}`);
+    L.push("");
+  }
+
+  const names = Object.keys(verdict.plugins).sort((a, b) => {
+    const rank = { broken: 0, partial: 1, unknown: 2, ok: 3 };
+    return (
+      rank[verdict.plugins[a].verdict] - rank[verdict.plugins[b].verdict] ||
+      a.localeCompare(b)
+    );
+  });
+
+  for (const name of names) {
+    const p = verdict.plugins[name];
+    L.push(
+      `${VERDICT_LABEL[p.verdict]}  ${name}@${p.version}${p.vacuous ? "   [空洞的结论：无可检查对象]" : ""}`,
+    );
+    if (opts.quiet) continue;
+    for (const f of p.findings) {
+      const api = f.service
+        ? f.method
+          ? `${f.service}.${f.method}`
+          : f.service
+        : "(声明)";
+      const loc = f.location ? `${f.location.file}:${f.location.line}` : "-";
+      const cert = f.certainty === "certain" ? "" : " [疑似]";
+      L.push(
+        `     ${SEVERITY_LABEL[f.severity] ?? f.severity} / ${CATEGORY_LABEL[f.category] ?? f.category}${cert}  ${api}  @ ${loc}`,
+      );
+      // ⚠️ 「事实」和「推断」必须**看得出来不一样** —— 一次实测的假阳性
+      // （`dshmarket` 的"设置页会消失"，而作者把能力检测写在了辅助函数里）说明：
+      // `basis` 那条链是量出来的，而 `impact` 是我们读出来的，两者可信度不同。
+      // 标出来，用户才知道哪一句可以去核实。
+      if (f.impact) {
+        L.push(
+          f.impactBasis === "inferred"
+            ? `       影响（推断，非实测）: ${f.impact}`
+            : `       影响: ${f.impact}`,
+        );
+      }
+      if (f.basis) L.push(`       依据: ${f.basis}`);
+    }
+    // 「没报」和「报了」一样要能审：过滤与弃权是结论的一部分。
+    const cs = p.clientSide || [];
+    if (cs.length)
+      L.push(
+        `     客户端半边（命令行测不到，需界面验证）: ${cs.map((c) => c.service).join(", ")}`,
+      );
+    const filtered = p.filtered || [];
+    if (filtered.length)
+      L.push(
+        `     已过滤（判为噪音/有兜底）: ${filtered.map((x) => `${x.service}${x.method ? "." + x.method : ""}`).join(", ")}`,
+      );
+    const noCalls = Object.values(p.resolved || {}).filter(
+      (c) => c.disposition === DISPOSITION.NO_CALLS,
+    );
+    if (noCalls.length)
+      L.push(
+        `     无证据可判（只出现名字，没有调用点）: ${noCalls.map((c) => c.service).join(", ")}`,
+      );
+  }
+
+  L.push("");
+  L.push(
+    "说明: 「疑似」= 没有运行时面、只能靠官方目录推断（那份目录是契约目录，不是运行时面）。",
+  );
+  L.push(
+    "      假阳性会让用户去做不必要的处置，所以判不准时一律降级，而不是升格成确定。",
+  );
+  return L.join("\n");
+}
+
+export { VERDICT_LABEL, SEVERITY_LABEL, CATEGORY_LABEL };
+
+/** 机器可读形态：保留完整结论，但把 extract 换成一个摘要（原始输出可能几 MB） */
+export function toJSON(result) {
+  // ⚠️ 报错路径也要带版本：用户拿一份 `{error: ...}` 来问的时候，
+  // "哪一版工具没跑成"同样是他要的第一个信息。
+  if (result.error)
+    return createFailure(result.error, {
+      toolVersion: TOOL_VERSION,
+      inputs: result.inputs,
+    });
+  const report = result.extract.report;
+  return sealReportBody({
+    schemaVersion: 1,
+    // 「这份结论是哪一版工具给的」。`dshVersion` 是**被体检的对象**的版本，
+    // 与这一条是两件事 —— 少了它就等于结论无法追溯（见 lib/version.mjs 的注释）。
+    toolVersion: TOOL_VERSION,
+    inputs: result.inputs,
+    // 差分与角标也带上：面板/对话工具/CLI 必须看同一件事，
+    // 否则「面板说没变、CLI 说变差了」这种分叉就会发生。
+    baseline: result.baseline
+      ? {
+          ...result.baseline,
+          file: result.baseline.file,
+          wrote: result.baseline.wrote,
+          note: result.baseline.note,
+          writeError: result.baseline.writeError ?? null,
+          diff: result.baseline.diff,
+          badge: result.baseline.badge,
+        }
+      : null,
+    dshVersion: result.verdict.dshVersion,
+    summary: result.verdict.summary,
+    observation: {
+      ...result.verdict.observation,
+      profileId: result.verdict.observation.profileId
+        ? path.resolve(result.verdict.observation.profileId)
+        : null,
+    },
+    plugins: result.verdict.plugins,
+    extraction: {
+      scanComplete: report.scanComplete,
+      diagnostics: report.diagnostics,
+      manifests: report.manifests,
+      services: report.services,
+      fallbackPackages: report.fallbackPackages,
+      siteTotal: (report.callSites || []).length,
+      provenanceCounts: Object.fromEntries(
+        Object.entries(result.extract.provenance.packages).map(([k, v]) => [
+          k,
+          v.counts,
+        ]),
+      ),
+    },
+  });
+}