dsh-plugin-compat-check 0.1.6 → 0.1.7

package/kernel/lib/report-service.mjs

@@ -2,19 +2,75 @@
 export class ReportService {
   constructor(
     compute,
-    { ttlMs = 300000, clock = Date.now, identity = null, watchMs = 5000 } = {},
+    {
+      ttlMs = 300000,
+      clock = Date.now,
+      identity = null,
+      watchMs = 5000,
+      maxTargets = 16,
+      idleMs = 600000,
+      onEvict = null,
+    } = {},
   ) {
+    if (
+      !Number.isSafeInteger(maxTargets) ||
+      maxTargets < 1 ||
+      maxTargets > 16 ||
+      !Number.isSafeInteger(idleMs) ||
+      idleMs < 1 ||
+      idleMs > 600000
+    )
+      throw new Error("Invalid cache budget");
+    this.maxTargets = maxTargets;
+    this.idleMs = idleMs;
+    this.onEvict = onEvict;
     this.compute = compute;
     this.ttlMs = ttlMs;
     this.clock = clock;
     this.identity = identity;
     this.watchMs = watchMs;
     this.states = new Map();
+    this.requestOrder = 0;
     this.disposed = false;
   }
+  alive(state) {
+    return !this.disposed && !state.retired;
+  }
+  evict(key) {
+    const state = this.states.get(key);
+    if (!state) return;
+    state.retired = true;
+    state.generation++;
+    clearTimeout(state.timer);
+    state.timer = null;
+    state.controller.abort();
+    this.states.delete(key);
+    state.report = null;
+    state.options = {};
+    state.identity = undefined;
+    state.publishedIdentity = undefined;
+    this.onEvict?.(key);
+  }
+  prune() {
+    for (const [key, state] of this.states)
+      if (this.clock() - state.lastUsed >= this.idleMs) this.evict(key);
+  }
   state(key) {
-    if (!this.states.has(key))
+    if (this.disposed) return undefined;
+    if (!this.states.has(key)) {
+      this.prune();
+      if (this.states.size >= this.maxTargets) {
+        const oldest = [...this.states].sort(
+          (a, b) => a[1].lastRequest - b[1].lastRequest,
+        )[0][0];
+        this.evict(oldest);
+      }
       this.states.set(key, {
+        key,
+        lastUsed: this.clock(),
+        lastRequest: ++this.requestOrder,
+        retired: false,
+        controller: new AbortController(),
         report: null,
         at: 0,
         inflight: null,
@@ -26,11 +82,13 @@ export class ReportService {
         options: {},
         timer: null,
       });
+    }
     return this.states.get(key);
   }
   invalidate(key, reason = "报告输入已变化，等待刷新") {
     if (this.disposed) return;
-    const state = this.state(key);
+    const state = this.states.get(key);
+    if (!state) return;
     state.generation++;
     state.stale = true;
     state.reason = reason;
@@ -41,10 +99,10 @@ export class ReportService {
     if (this.disposed || this.notifying) return;
     this.notifying = Promise.resolve()
       .then(async () => {
-        for (const state of this.states.values()) {
+        for (const state of [...this.states.values()]) {
           try {
             await this.observe(state);
-            if (!this.disposed && state.stale)
+            if (this.alive(state) && state.stale)
               void this.start(state, state.options);
           } catch {
             /* Keep the valid report and let the watchdog retry. */
@@ -56,12 +114,16 @@ export class ReportService {
       });
   }
   async observe(state) {
-    if (!this.identity || this.disposed) return;
+    if (!this.identity || !this.alive(state)) return;
     if (state.checking) return state.checking;
     state.checking = Promise.resolve()
-      .then(() => this.identity(state.options))
+      .then(() =>
+        this.alive(state)
+          ? this.identity(state.options, { signal: state.controller.signal })
+          : undefined,
+      )
       .then((identity) => {
-        if (this.disposed) return;
+        if (!this.alive(state)) return;
         if (state.identity !== undefined && state.identity !== identity) {
           state.generation++;
           state.stale = true;
@@ -71,7 +133,7 @@ export class ReportService {
         state.identity = identity;
       })
       .catch((error) => {
-        if (!this.disposed) {
+        if (this.alive(state)) {
           state.generation++;
           state.stale = true;
           state.error = error.message;
@@ -84,30 +146,37 @@ export class ReportService {
     return state.checking;
   }
   watch(state) {
-    if (!this.identity || state.watching || this.disposed) return;
+    if (state.watching || !this.alive(state)) 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);
+      if (!this.alive(state)) return;
+      state.timer = setTimeout(
+        async () => {
+          state.timer = null;
+          if (this.clock() - state.lastUsed >= this.idleMs) {
+            this.evict(state.key);
+            return;
+          }
+          try {
+            await this.observe(state);
+            if (
+              this.alive(state) &&
+              (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();
+        },
+        Math.min(this.watchMs, this.idleMs),
+      );
       state.timer.unref?.();
     };
     schedule();
   }
   start(state, options) {
-    if (this.disposed)
+    if (!this.alive(state))
       return Promise.resolve({
         ok: false,
         error: "Plugin generation disposed / 已卸载",
@@ -117,21 +186,26 @@ export class ReportService {
     let generation;
     state.inflight = Promise.resolve()
       .then(async () => {
+        if (!this.alive(state)) return { ok: false, error: "缓存目标已回收" };
         if (this.identity) await this.observe(state);
+        if (!this.alive(state)) return { ok: false, error: "缓存目标已回收" };
         generation = state.generation;
         let commit;
         const guard = {
+          signal: state.controller.signal,
           commit: (fn) => {
             commit = fn;
           },
           isCurrent: async () => {
-            if (this.disposed || generation !== state.generation) return false;
+            if (!this.alive(state) || 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;
+            if (!this.alive(state) || generation !== state.generation)
+              return false;
             await this.observe(state);
-            return !this.disposed && generation === state.generation;
+            return this.alive(state) && generation === state.generation;
           },
         };
         const out = await this.compute(options, guard);
@@ -156,7 +230,7 @@ export class ReportService {
         return out;
       })
       .catch((error) => {
-        if (!this.disposed) {
+        if (this.alive(state)) {
           state.error = error.message;
           state.stale = true;
         }
@@ -165,7 +239,7 @@ export class ReportService {
       .finally(() => {
         state.inflight = null;
         if (
-          !this.disposed &&
+          this.alive(state) &&
           generation !== undefined &&
           generation !== state.generation &&
           !state.error
@@ -177,7 +251,10 @@ export class ReportService {
   async get(key, options = {}, force = false) {
     if (this.disposed)
       return { ok: false, error: "Plugin generation disposed / 已卸载" };
+    this.prune();
     const state = this.state(key);
+    state.lastUsed = this.clock();
+    state.lastRequest = ++this.requestOrder;
     state.options = options;
     this.watch(state);
     const age = this.clock() - state.at;
@@ -188,7 +265,7 @@ export class ReportService {
       let out;
       for (let attempt = 0; attempt < 3; attempt++) {
         out = await this.start(state, options);
-        if (!out?.invalidated || this.disposed) return out;
+        if (!out?.invalidated || !this.alive(state)) return out;
       }
       return { ok: false, error: "报告输入持续变化，请稍后重试" };
     }
@@ -206,6 +283,13 @@ export class ReportService {
       },
     };
   }
+  ownsReport(report) {
+    return (
+      !this.disposed &&
+      !!report &&
+      [...this.states.values()].some((state) => state.report?.report === report)
+    );
+  }
   /** The immutable identity observed for this published report, including retained stale reports. */
   identityForReport(key, report) {
     const state = this.states.get(key);
@@ -217,8 +301,8 @@ export class ReportService {
   async isCurrent(key, report) {
     const state = this.states.get(key);
     const matches = () =>
-      !this.disposed &&
       state &&
+      this.alive(state) &&
       !state.stale &&
       !state.error &&
       state.report?.report === report;
@@ -231,10 +315,6 @@ export class ReportService {
   }
   dispose() {
     this.disposed = true;
-    for (const state of this.states.values()) {
-      clearTimeout(state.timer);
-      state.timer = null;
-      state.generation++;
-    }
+    for (const key of this.states.keys()) this.evict(key);
   }
 }

package/kernel/lib/report.mjs

@@ -1,19 +1,13 @@
-/**
- * 结论的**渲染**：给人看的表 + 给机器看的 JSON。
- *
- * ## 为什么单独一个文件
- *
- * 到 D1 为止，「一份结论」已经有三个消费方：CLI、对话工具、面板。
- * 它们各自的**呈现**不同（终端表 / 文本 / DOM），但**取值口径**必须完全一致 ——
- * 标签文案、排序、哪一类发现要标「疑似」、哪些"没发现"要额外解释。
- * 把这些放在一处，是为了让"面板说可用、工具说部分可用"这类分叉**在结构上不可能发生**。
- *
- * 它不做判定。判定在 `lib/verdict.mjs`；这里只把判定结果翻译成人话。
- */
+/** Shared report rendering for CLI, tools and UI; never changes verdict evidence. */
 
 import { TOOL_VERSION } from "./version.mjs";
 import path from "node:path";
-import { sealReportBody, createFailure, catalogLines } from "./contracts.mjs";
+import {
+  sealReportBody,
+  createFailure,
+  catalogLines,
+  terminalText,
+} from "./contracts.mjs";
 import { DISPOSITION } from "./verdict.mjs";
 import { describeDiff } from "./baseline.mjs";
 import { nextSteps } from "./finding-guidance.mjs";
@@ -31,6 +25,8 @@ const SEVERITY_LABEL = {
   degraded: "降级",
 };
 const CATEGORY_LABEL = {
+  "api-argument-invalid": "API参数不符",
+  "api-option-unsupported": "版本选项未支持",
   "host-service-missing": "宿主服务缺失",
   "host-method-missing": "宿主方法缺失",
   "unprovided-dependency": "依赖服务待确认",
@@ -55,7 +51,7 @@ export function render(result, opts) {
 
   if (result.error) {
     L.push(`结论: 无法判定 —— ${result.error}`);
-    return L.join("\n");
+    return L.map(terminalText).join("\n");
   }
 
   const meta = extract.report.manifests;
@@ -72,10 +68,10 @@ export function render(result, opts) {
         catalogLines(result.catalog).join("；") +
         (verdict.observation?.notes?.length
           ? "；采样说明：" +
-            verdict.observation.notes.join("；").replace(/\s+/g, " ")
+            verdict.observation.notes.map(terminalText).join("；")
           : ""),
     );
-    return L.join("\n");
+    return L.map(terminalText).join("\n");
   }
 
   L.push(
@@ -235,7 +231,7 @@ export function render(result, opts) {
     "      没有已验证调用仍可能存在服务依赖或客户端功能；调用核验、无发现和覆盖完整均不等于业务验收通过。",
   );
   L.push("      下一步是核实建议；本工具不会自动安装、升级或修改配置与源码。");
-  return L.join("\n");
+  return L.map(terminalText).join("\n");
 }
 
 export { VERDICT_LABEL, SEVERITY_LABEL, CATEGORY_LABEL };