dsh-plugin-compat-check 0.1.4 → 0.1.5

package/kernel/lib/report-identity-worker.mjs

@@ -0,0 +1,153 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { parentPort, workerData } from "node:worker_threads";
+const hash = createHash("sha256");
+const add = (value) => hash.update(JSON.stringify(value) + "\n");
+let remaining = 50000,
+  directories = 10000;
+const services = new Set(),
+  manifests = [];
+function metadata(file) {
+  if (--remaining < 0) throw Error("缓存身份文件预算超限，等待后续刷新");
+  const stat = fs.statSync(file);
+  add([
+    file,
+    fs.realpathSync(file),
+    stat.size,
+    stat.mtimeMs,
+    stat.ctimeMs,
+    stat.ino,
+    stat.mode,
+  ]);
+  return stat;
+}
+function smallFile(file, limit = 1024 * 1024) {
+  let fd;
+  try {
+    metadata(file);
+    // Open nonblocking before inspecting the same descriptor. A swapped
+    // symlink or FIFO cannot turn the following bounded read into a host hang.
+    fd = fs.openSync(
+      file,
+      fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK || 0),
+    );
+    const stat = fs.fstatSync(fd);
+    if (!stat.isFile() || stat.size > limit)
+      throw Error("缓存身份输入不是预算内普通文件");
+    const buffer = Buffer.alloc(limit + 1),
+      length = fs.readSync(fd, buffer, 0, buffer.length, 0);
+    if (length > limit) throw Error("缓存身份输入超过读取预算");
+    const bytes = buffer.subarray(0, length);
+    add(bytes.toString("base64"));
+    return bytes;
+  } catch (error) {
+    if (error.code === "ENOENT" || error.code === "ENOTDIR") {
+      add([file, "missing"]);
+      return null;
+    }
+    throw error;
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+function walk(root) {
+  const seen = new Set(),
+    queue = [root],
+    canonical = fs.realpathSync(root);
+  while (queue.length) {
+    if (--directories < 0) throw Error("缓存身份目录预算超限，等待后续刷新");
+    const dir = queue.pop(),
+      real = fs.realpathSync(dir);
+    if (
+      seen.has(real) ||
+      (real !== canonical && !real.startsWith(canonical + path.sep))
+    )
+      continue;
+    seen.add(real);
+    for (const entry of fs.readdirSync(dir).sort()) {
+      const file = path.join(dir, entry);
+      let stat;
+      try {
+        stat = metadata(file);
+      } catch (error) {
+        if (error.code === "ENOENT") {
+          add([file, "missing"]);
+          continue;
+        }
+        throw error;
+      }
+      if (stat.isDirectory()) queue.push(file);
+    }
+  }
+}
+try {
+  const { nodeModules, files = [], context = {} } = workerData;
+  add(context);
+  metadata(nodeModules);
+  for (const name of fs.readdirSync(nodeModules).sort()) {
+    const bases = name.startsWith("@")
+      ? fs
+          .readdirSync(path.join(nodeModules, name))
+          .sort()
+          .map((n) => path.join(name, n))
+      : [name];
+    for (const base of bases) {
+      const root = path.join(nodeModules, base);
+      let bytes;
+      try {
+        bytes = smallFile(path.join(root, "package.json"), 65536);
+      } catch (error) {
+        if (remaining < 0) throw error;
+        add([root, "unreadable-manifest", error.code || error.message]);
+        continue;
+      }
+      if (!bytes) continue;
+      let manifest;
+      try {
+        manifest = JSON.parse(bytes);
+      } catch {
+        continue;
+      }
+      if (
+        !manifest ||
+        typeof manifest !== "object" ||
+        Array.isArray(manifest) ||
+        !("dsh" in manifest) ||
+        String(manifest.name || "").startsWith("@deepseek-ai/")
+      )
+        continue;
+      manifests.push({ name: manifest.name });
+      const inject = manifest.inject;
+      for (const name of Array.isArray(inject)
+        ? inject
+        : inject && typeof inject === "object"
+          ? [
+              ...(Array.isArray(inject.required) ? inject.required : []),
+              ...(Array.isArray(inject.optional) ? inject.optional : []),
+            ]
+          : [])
+        if (typeof name === "string") services.add(name);
+      walk(root);
+    }
+  }
+  for (const file of files.filter(Boolean)) {
+    const bytes = smallFile(file, 8 * 1024 * 1024);
+    if (bytes && path.basename(file).startsWith("dsh-api-catalog"))
+      try {
+        for (const name of Object.keys(JSON.parse(bytes).host || {}))
+          services.add(name);
+      } catch {}
+  }
+  parentPort.postMessage({
+    ok: true,
+    value: {
+      digest: hash.digest("hex"),
+      services: [...services].sort(),
+      manifests,
+    },
+  });
+} catch (error) {
+  parentPort.postMessage({ ok: false, error: error.message });
+}

package/kernel/lib/report-identity.mjs

@@ -0,0 +1,15 @@
+import { runWorkerTask } from "./worker-analysis.mjs";
+/** Bounded metadata walk runs off the host thread and never imports plugin code. */
+export function reportIdentity(inputs) {
+  return runWorkerTask(
+    new URL("./report-identity-worker.mjs", import.meta.url),
+    inputs,
+    {
+      timeoutMs: 5000,
+      resourceLimits: {
+        maxOldGenerationSizeMb: 128,
+        maxYoungGenerationSizeMb: 16,
+      },
+    },
+  );
+}

package/kernel/lib/report-service.mjs

@@ -1,10 +1,16 @@
-/** Single flight per target; retain the last valid report on failed refresh. */
+/** Single flight per canonical target; keep valid reports while inputs refresh. */
 export class ReportService {
-  constructor(compute, { ttlMs = 300000, clock = Date.now } = {}) {
+  constructor(
+    compute,
+    { ttlMs = 300000, clock = Date.now, identity = null, watchMs = 5000 } = {},
+  ) {
     this.compute = compute;
     this.ttlMs = ttlMs;
     this.clock = clock;
+    this.identity = identity;
+    this.watchMs = watchMs;
     this.states = new Map();
+    this.disposed = false;
   }
   state(key) {
     if (!this.states.has(key))
@@ -13,43 +19,222 @@ export class ReportService {
         at: 0,
         inflight: null,
         error: null,
+        generation: 0,
+        stale: false,
+        identity: undefined,
+        checking: null,
+        options: {},
+        timer: null,
       });
     return this.states.get(key);
   }
+  invalidate(key, reason = "报告输入已变化，等待刷新") {
+    if (this.disposed) return;
+    const state = this.state(key);
+    state.generation++;
+    state.stale = true;
+    state.reason = reason;
+    state.error = null;
+    if (!state.inflight) void this.start(state, state.options);
+  }
+  notify() {
+    if (this.disposed || this.notifying) return;
+    this.notifying = Promise.resolve()
+      .then(async () => {
+        for (const state of this.states.values()) {
+          try {
+            await this.observe(state);
+            if (!this.disposed && state.stale)
+              void this.start(state, state.options);
+          } catch {
+            /* Keep the valid report and let the watchdog retry. */
+          }
+        }
+      })
+      .finally(() => {
+        this.notifying = null;
+      });
+  }
+  async observe(state) {
+    if (!this.identity || this.disposed) return;
+    if (state.checking) return state.checking;
+    state.checking = Promise.resolve()
+      .then(() => this.identity(state.options))
+      .then((identity) => {
+        if (this.disposed) return;
+        if (state.identity !== undefined && state.identity !== identity) {
+          state.generation++;
+          state.stale = true;
+          state.reason = "报告输入已变化，等待刷新";
+          state.error = null;
+        }
+        state.identity = identity;
+      })
+      .catch((error) => {
+        if (!this.disposed) {
+          state.generation++;
+          state.stale = true;
+          state.error = error.message;
+        }
+        throw error;
+      })
+      .finally(() => {
+        state.checking = null;
+      });
+    return state.checking;
+  }
+  watch(state) {
+    if (!this.identity || state.watching || this.disposed) return;
+    state.watching = true;
+    const schedule = () => {
+      if (this.disposed) return;
+      state.timer = setTimeout(async () => {
+        state.timer = null;
+        try {
+          await this.observe(state);
+          if (
+            !this.disposed &&
+            (state.stale || this.clock() - state.at > this.ttlMs)
+          )
+            void this.start(state, state.options);
+        } catch {
+          /* Expose observation errors and retry at the next bounded tick. */
+        }
+        schedule();
+      }, this.watchMs);
+      state.timer.unref?.();
+    };
+    schedule();
+  }
   start(state, options) {
+    if (this.disposed)
+      return Promise.resolve({
+        ok: false,
+        error: "Plugin generation disposed / 已卸载",
+      });
     if (state.inflight) return state.inflight;
+    state.options = options;
+    let generation;
     state.inflight = Promise.resolve()
-      .then(() => this.compute(options))
-      .then((out) => {
+      .then(async () => {
+        if (this.identity) await this.observe(state);
+        generation = state.generation;
+        let commit;
+        const guard = {
+          commit: (fn) => {
+            commit = fn;
+          },
+          isCurrent: async () => {
+            if (this.disposed || generation !== state.generation) return false;
+            // A watchdog observation may have sampled before computation
+            // finished. Drain it, then start a fresh check for this commit.
+            if (state.checking) await state.checking;
+            if (this.disposed || generation !== state.generation) return false;
+            await this.observe(state);
+            return !this.disposed && generation === state.generation;
+          },
+        };
+        const out = await this.compute(options, guard);
+        if (!(await guard.isCurrent()))
+          return {
+            ok: false,
+            invalidated: true,
+            error: "报告输入已变化，正在重新检查",
+          };
         if (out?.ok === true) {
+          commit?.();
           state.report = out;
+          state.publishedIdentity = state.identity;
           state.at = this.clock();
           state.error = null;
-        } else state.error = out?.error || "体检未产生有效报告";
+          state.stale = false;
+          state.reason = null;
+        } else {
+          state.error = out?.error || "体检未产生有效报告";
+          state.stale = true;
+        }
         return out;
       })
       .catch((error) => {
-        state.error = error.message;
-        return { ok: false, error: state.error };
+        if (!this.disposed) {
+          state.error = error.message;
+          state.stale = true;
+        }
+        return { ok: false, error: error.message };
       })
       .finally(() => {
         state.inflight = null;
+        if (
+          !this.disposed &&
+          generation !== undefined &&
+          generation !== state.generation &&
+          !state.error
+        )
+          void this.start(state, state.options);
       });
     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);
+    if (this.disposed)
+      return { ok: false, error: "Plugin generation disposed / 已卸载" };
+    const state = this.state(key);
+    state.options = options;
+    this.watch(state);
+    const age = this.clock() - state.at;
+    if (force || !state.report) {
+      // A force request can join a background flight which was superseded
+      // while extracting. Wait for the replacement generation, with a bound
+      // for continuously changing inputs rather than publishing old success.
+      let out;
+      for (let attempt = 0; attempt < 3; attempt++) {
+        out = await this.start(state, options);
+        if (!out?.invalidated || this.disposed) return out;
+      }
+      return { ok: false, error: "报告输入持续变化，请稍后重试" };
+    }
+    if ((state.stale && !state.error) || age > this.ttlMs)
+      void this.start(state, options);
     return {
       ...state.report,
       cache: {
         hit: true,
         ageMs: age,
         refreshing: !!state.inflight,
+        stale: state.stale,
         refreshError: state.error,
+        reason: state.reason || null,
       },
     };
   }
+  /** The immutable identity observed for this published report, including retained stale reports. */
+  identityForReport(key, report) {
+    const state = this.states.get(key);
+    return state?.report?.report === report
+      ? state.publishedIdentity
+      : undefined;
+  }
+  /** Validate a sidecar edit against the published report without recomputing or advancing its baseline. */
+  async isCurrent(key, report) {
+    const state = this.states.get(key);
+    const matches = () =>
+      !this.disposed &&
+      state &&
+      !state.stale &&
+      !state.error &&
+      state.report?.report === report;
+    if (!matches()) return false;
+    const generation = state.generation;
+    if (state.checking) await state.checking;
+    if (!matches() || generation !== state.generation) return false;
+    await this.observe(state);
+    return matches() && generation === state.generation;
+  }
+  dispose() {
+    this.disposed = true;
+    for (const state of this.states.values()) {
+      clearTimeout(state.timer);
+      state.timer = null;
+      state.generation++;
+    }
+  }
 }

package/kernel/lib/report.mjs

@@ -13,9 +13,11 @@
 
 import { TOOL_VERSION } from "./version.mjs";
 import path from "node:path";
-import { sealReportBody, createFailure } from "./contracts.mjs";
+import { sealReportBody, createFailure, catalogLines } from "./contracts.mjs";
 import { DISPOSITION } from "./verdict.mjs";
 import { describeDiff } from "./baseline.mjs";
+import { nextSteps } from "./finding-guidance.mjs";
+import { buildDependencyGraph } from "./dependency-graph.mjs";
 
 const VERDICT_LABEL = {
   ok: "可用",
@@ -31,7 +33,7 @@ const SEVERITY_LABEL = {
 const CATEGORY_LABEL = {
   "host-service-missing": "宿主服务缺失",
   "host-method-missing": "宿主方法缺失",
-  "unprovided-dependency": "无人提供的依赖",
+  "unprovided-dependency": "依赖服务待确认",
   "declaration-mismatch": "声明与实测不符",
   "declared-incompatible": "版本声明不支持",
   "host-entry-inactive": "宿主条目未激活",
@@ -63,7 +65,15 @@ export function render(result, opts) {
   if (opts.quiet) {
     const q = verdict.summary;
     L.push(
-      `结论: ${VERDICT_LABEL.ok} ${q.ok}    ${VERDICT_LABEL.partial} ${q.partial}    ${VERDICT_LABEL.broken} ${q.broken}`,
+      `结论: ${VERDICT_LABEL.ok} ${q.ok}    ${VERDICT_LABEL.partial} ${q.partial}    ${VERDICT_LABEL.broken} ${q.broken}` +
+        (q.limited ? `    覆盖有限 ${q.limited}` : "") +
+        (q.vacuousOk ? `    其中 ${q.vacuousOk} 个无已验证调用` : "") +
+        "；" +
+        catalogLines(result.catalog).join("；") +
+        (verdict.observation?.notes?.length
+          ? "；采样说明：" +
+            verdict.observation.notes.join("；").replace(/\s+/g, " ")
+          : ""),
     );
     return L.join("\n");
   }
@@ -71,6 +81,7 @@ export function render(result, opts) {
   L.push(
     `插件数: ${meta.length}    有运行时面: ${result.inputs.hasRuntimeSurface ? "是" : "否（方法级结论降为「疑似」）"}`,
   );
+  L.push(...catalogLines(result.catalog));
   L.push("");
   for (const note of verdict.observation?.notes || [])
     L.push(`采样说明: ${note}`);
@@ -82,7 +93,7 @@ export function render(result, opts) {
   L.push(
     `结论: ${VERDICT_LABEL.ok} ${s.ok}    ${VERDICT_LABEL.partial} ${s.partial}    ${VERDICT_LABEL.broken} ${s.broken}` +
       (s.vacuousOk
-        ? `    （其中 ${s.vacuousOk} 个「可用」是空洞的：它没有任何可检查的依赖）`
+        ? `    （其中 ${s.vacuousOk} 个「可用」没有已验证调用，不等于业务通过）`
         : ""),
   );
   L.push("");
@@ -122,9 +133,16 @@ export function render(result, opts) {
   for (const name of names) {
     const p = verdict.plugins[name];
     L.push(
-      `${VERDICT_LABEL[p.verdict]}  ${name}@${p.version}${p.vacuous ? "   [空洞的结论：无可检查对象]" : ""}`,
+      `${VERDICT_LABEL[p.verdict]}  ${name}@${p.version}${p.vacuous ? "   [无已验证调用]" : ""}`,
     );
     if (opts.quiet) continue;
+    if (p.coverage) {
+      L.push(
+        `     证据覆盖: ${p.coverage.status === "complete" ? "完整" : "有限"}；已验证调用 ${p.coverage.verifiedCalls}`,
+      );
+      for (const note of p.coverage.limitations)
+        L.push(`       覆盖限制: ${note}`);
+    }
     for (const f of p.findings) {
       const api = f.service
         ? f.method
@@ -132,7 +150,7 @@ export function render(result, opts) {
           : f.service
         : "(声明)";
       const loc = f.location ? `${f.location.file}:${f.location.line}` : "-";
-      const cert = f.certainty === "certain" ? "" : " [疑似]";
+      const cert = f.certainty === "certain" ? " [确定]" : " [疑似]";
       L.push(
         `     ${SEVERITY_LABEL[f.severity] ?? f.severity} / ${CATEGORY_LABEL[f.category] ?? f.category}${cert}  ${api}  @ ${loc}`,
       );
@@ -142,12 +160,11 @@ export function render(result, opts) {
       // 标出来，用户才知道哪一句可以去核实。
       if (f.impact) {
         L.push(
-          f.impactBasis === "inferred"
-            ? `       影响（推断，非实测）: ${f.impact}`
-            : `       影响: ${f.impact}`,
+          `       影响${f.impactBasis === "measured" ? "（实测）" : f.impactBasis === "inferred" ? "（推断，非实测）" : "（依据未提供）"}: ${f.impact}`,
         );
       }
       if (f.basis) L.push(`       依据: ${f.basis}`);
+      for (const step of nextSteps(f)) L.push(`       下一步: ${step}`);
     }
     // 「没报」和「报了」一样要能审：过滤与弃权是结论的一部分。
     const cs = p.clientSide || [];
@@ -169,13 +186,55 @@ export function render(result, opts) {
       );
   }
 
+  const graph = buildDependencyGraph({
+    extraction: result.extract,
+    verdict,
+    entries: result.entryStates,
+  });
+  const relations = graph.edges.filter((edge) => edge.kind === "dependency");
+  const nodeNames = new Map(graph.nodes.map((node) => [node.id, node.name]));
+  const requirement = {
+    required: "必需",
+    optional: "可选",
+    subcontext: "子作用域",
+    unknown: "必需性未知",
+  };
+  L.push("");
+  L.push(
+    `依赖关系: 服务依赖 ${relations.length}；潜在声明环 ${graph.cycles.length}${graph.coverage.truncated ? "；关系/传播已截断" : ""}`,
+  );
+  for (const edge of relations.slice(0, 20)) {
+    const candidates = graph.edges.filter(
+      (candidate) =>
+        candidate.kind === "candidate-provider" &&
+        candidate.service === edge.service &&
+        (candidate.side === edge.side || candidate.side === "unknown"),
+    );
+    L.push(
+      `  ${nodeNames.get(edge.from)} → ${edge.service} [${edge.side}/${requirement[edge.requirement]}]；候选提供者：${candidates.map((candidate) => `${nodeNames.get(candidate.from)}（${candidate.side}）`).join("、") || "未定位（不等于宿主缺失）"}`,
+    );
+  }
+  if (relations.length > 20)
+    L.push(
+      `  文本仅列出前 20 条依赖；完整的本次关系见 JSON/面板（仍受图预算限制）。`,
+    );
+  L.push(
+    "  提供声明仅为候选；同端路径及环只表示潜在影响，不证明实际挂起或失败；client 包 inject 不当作 host 服务。",
+  );
+  for (const reason of graph.coverage.reasons)
+    L.push(`  关系覆盖限制: ${reason}`);
+
   L.push("");
   L.push(
-    "说明: 「疑似」= 没有运行时面、只能靠官方目录推断（那份目录是契约目录，不是运行时面）。",
+    "说明: 确定（certain）表示当前证据足以支持该条发现，可来自明确静态事实或合格运行时观测；疑似（suspected）表示当前证据不足以确定该条发现。",
+  );
+  L.push(
+    "      impactBasis=measured/inferred 分别表示影响有对应实测依据/影响由证据推断；确定发现不等于影响已实测。官方目录不是运行时面，未观测不等于缺失。",
   );
   L.push(
-    "      假阳性会让用户去做不必要的处置，所以判不准时一律降级，而不是升格成确定。",
+    "      没有已验证调用仍可能存在服务依赖或客户端功能；调用核验、无发现和覆盖完整均不等于业务验收通过。",
   );
+  L.push("      下一步是核实建议；本工具不会自动安装、升级或修改配置与源码。");
   return L.join("\n");
 }
 
@@ -211,6 +270,7 @@ export function toJSON(result) {
         }
       : null,
     dshVersion: result.verdict.dshVersion,
+    ...(result.catalog ? { catalog: result.catalog } : {}),
     summary: result.verdict.summary,
     observation: {
       ...result.verdict.observation,
@@ -219,6 +279,11 @@ export function toJSON(result) {
         : null,
     },
     plugins: result.verdict.plugins,
+    dependencyGraph: buildDependencyGraph({
+      extraction: result.extract,
+      verdict: result.verdict,
+      entries: result.entryStates,
+    }),
     extraction: {
       scanComplete: report.scanComplete,
       diagnostics: report.diagnostics,

package/kernel/lib/source-analysis.mjs

@@ -79,8 +79,10 @@ export function analyzeSources(
   const sites = [],
     bindings = [],
     dependencies = [],
+    provideSites = [],
     diagnostics = [],
     subContexts = [];
+  const provideSiteKeys = new Set();
   let scopeId = 0,
     invocationCount = 0,
     constantCalls = 0;
@@ -586,6 +588,24 @@ export function analyzeSources(
         sides: [...(activeSides || sides)],
       });
     };
+    const provide = (service, node) => {
+      provided.add(service);
+      mention(service);
+      const sides = [...(activeSides || fileSides[file] || ["unknown"])];
+      const site = {
+        service,
+        file,
+        line: node.loc?.start.line ?? 1,
+        start: node.start,
+        end: node.end,
+        sides,
+      };
+      const key = JSON.stringify([service, file, site.start, sides]);
+      if (!provideSiteKeys.has(key)) {
+        provideSiteKeys.add(key);
+        provideSites.push(site);
+      }
+    };
     const literalNames = (node, scope) => {
       node = unwrap(node);
       if (node?.type === "Identifier")
@@ -1383,8 +1403,7 @@ export function analyzeSources(
               );
           if (provideNames.has(field))
             for (const s of literalNames(node.init, scope)) {
-              provided.add(s);
-              mention(s);
+              provide(s, node);
             }
         }
         return;
@@ -1529,8 +1548,7 @@ export function analyzeSources(
             dependency(name, "descriptor-inject", node);
         if (node.type === "AssignmentExpression" && slot.key === "provide")
           for (const name of literalNames(node.right, scope)) {
-            provided.add(name);
-            mention(name);
+            provide(name, node);
           }
         return;
       }
@@ -1729,8 +1747,7 @@ export function analyzeSources(
             operation === "provide" &&
             constant(node.arguments[0], scope, guards) !== null
           ) {
-            provided.add(constant(node.arguments[0], scope, guards));
-            mention(constant(node.arguments[0], scope, guards));
+            provide(constant(node.arguments[0], scope, guards), node);
           }
           if (operation === "inject") {
             const injected = literalNames(node.arguments[0], scope);
@@ -1900,6 +1917,7 @@ export function analyzeSources(
     serviceFiles,
     sites,
     provided,
+    provideSites,
     bindings,
     dependencies,
     diagnostics,

package/kernel/lib/upgrade-capture-worker.mjs

@@ -0,0 +1,20 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parentPort, workerData } from "node:worker_threads";
+import { captureUpgradeInputOwned } from "./upgrade-input.mjs";
+
+try {
+  const { nm, limits, root } = workerData;
+  const selected = path.resolve(nm);
+  const installed =
+    path.basename(selected) !== "node_modules" &&
+    fs.existsSync(path.join(selected, "node_modules"))
+      ? path.join(selected, "node_modules")
+      : selected;
+  parentPort.postMessage({
+    ok: true,
+    value: captureUpgradeInputOwned(installed, limits, root),
+  });
+} catch (error) {
+  parentPort.postMessage({ ok: false, error: error.message });
+}