dsh-plugin-compat-check 0.1.3 → 0.1.5

package/lib/finding-guidance.js

@@ -0,0 +1,73 @@
+// Generated from lib/finding-guidance.mjs; run node plugin/scripts/stage-contract.mjs
+/** Presentation-only follow-up checks. Never changes a finding or performs work. */
+export function nextSteps(finding) {
+  if (!finding || typeof finding !== "object") return [];
+  switch (finding.category) {
+    case "client-entry-missing":
+      return [
+        '检查该插件 package.json 的 dsh.client 与 exports["./client"] 客户端入口声明，并在实际安装制品中核对入口文件是否存在、可读且已随包交付。',
+        "把已装插件的精确版本与制品文件清单对照；如需作者处理，提供缺失入口的包内相对位置，不猜测修复版本。",
+        "补充同一目标的浏览器加载结果，并实际操作客户端功能、核验实际功能结果；静态入口发现不等于业务失败已实测。",
+      ];
+    case "declared-incompatible":
+      return [
+        "复核已装插件 package.json 的 engines.dsh 与官方 peerDependencies、字段格式及目标 DSH 版本；按报告所用声明策略核对生效字段。",
+        "只读核对目标 profile 的 compatibility.json 是否有该插件名、插件精确版本与目标 DSH 精确版本的记录；未观测或未授予不等于可自行添加豁免。",
+        "补充该目标的实际加载与功能结果；声明冲突不证明已经实际加载失败，豁免也不证明业务通过。",
+      ];
+    case "host-entry-inactive": {
+      const state = finding.evidence?.state;
+      const step =
+        state === "FAILED"
+          ? "定位该包对应的 FAILED loader 条目，先在本机查看失败原因与同次启动日志，核对导入、初始化失败发生在哪一步。"
+          : state === "PENDING"
+            ? "定位该包对应的 PENDING loader 条目，核对顶层必需 inject 与各依赖服务的提供者是否在同一宿主实际激活。"
+            : "在同一目标宿主重新读取该包映射的 loader 条目状态，核对条目身份、启用状态与采样时间，不从说明文本猜测状态。";
+      return [
+        step,
+        "补充同一 profile、DSH 版本和时间的服务观测及 loader 状态；LOADING、禁用或无法映射的条目不能代替 FAILED 或 PENDING 证据。",
+        "服务或条目状态恢复后仍需实际操作对应功能并核验结果；激活成功不能代替业务验收。",
+      ];
+    }
+    case "unprovided-dependency": {
+      const absent = finding.evidence?.status === "absent";
+      const steps = [
+        absent
+          ? "核对本次明确 absent 的服务观测是否属于同一 profile、DSH 版本与依赖作用域，并查看该服务的提供者是否实际激活。"
+          : "该依赖仍待确认：补充同一 profile、DSH 版本与有效采样时间的服务观测；省略键或未采样不能确认服务缺失，也不能确认插件挂起。",
+        finding.evidence?.hardInject === true
+          ? "在报告给出的源码位置检查顶层必需 inject 与激活前提，再对照实际 loader 状态；依赖声明本身不能证明已经挂起。"
+          : "在报告给出的源码位置区分可选或子作用域依赖与顶层硬依赖；不推断整个插件挂起，实际操作相关功能核验影响。",
+      ];
+      if (finding.evidence?.status === "unreadable")
+        steps.push(
+          "先在本机核对采样读取失败原因；只补安全的结构观测，不执行 getter 来消除未知。",
+        );
+      steps.push(
+        "核对服务提供者的包声明与实际运行状态；提供声明只是线索，不自动安装依赖或认定某包能提供该服务。",
+      );
+      return steps;
+    }
+    case "host-service-missing":
+      return [
+        "在报告给出的源码位置核对服务读取及必需 inject 的作用域，并确认 absent 观测绑定同一 profile、DSH 版本与采样时间。",
+        "核对该服务的实际提供者及 loader 状态，补充相关功能操作结果；服务缺失的推断影响不等于业务失败已实测。",
+      ];
+    case "host-method-missing":
+      return [
+        "在报告给出的文件与行号核对实际方法调用、Context 绑定及能力守卫，检查是否存在报告尚未识别的兜底。",
+        "补充同一目标服务的完整方法结构观测，区分目录线索、未采样方法与明确缺失；实际操作对应功能核验推断影响。",
+        "需要替代 API 时先查该目标版本的源码或官方契约并保留出处；本报告不猜测替代方法或修复版本。",
+      ];
+    case "declaration-mismatch":
+      return [
+        "对照已装插件的兼容声明、精确目标版本及报告中的具体 API 发现，分别核对声明范围与运行时证据。",
+        "在已有源码位置检查调用与守卫，并补充同一目标的服务观测和实际功能结果；声明放行不证明业务通过。",
+      ];
+    default:
+      return [
+        "先核对该发现的类别、依据、已有包内位置和目标版本；缺少位置或状态时保留待确认，不补造证据。",
+        "补充同一 profile、DSH 版本与采样时间的相关观测，再实际操作对应功能核验影响；不根据未知类别猜测修复。",
+      ];
+  }
+}

package/lib/finding-review.js

@@ -0,0 +1,339 @@
+// Generated from lib/finding-review.mjs; run node plugin/scripts/stage-contract.mjs
+/** Browser-safe manual-review contract. Reviews never modify canonical findings. */
+export const REVIEW_STATUS_LABELS = Object.freeze({
+  pending: "待确认",
+  reviewed: "已复核",
+  "false-positive": "误报",
+  fixed: "已修复",
+  "needs-review": "待重审",
+});
+export const REVIEW_LIMITS = Object.freeze({
+  fileBytes: 1024 * 1024,
+  records: 1000,
+  note: 4000,
+  findings: 5000,
+  identityBytes: 128 * 1024,
+});
+const object = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
+const hash = (x) => typeof x === "string" && /^[a-f0-9]{64}$/.test(x);
+const safe = (x) =>
+  typeof x === "string" &&
+  !/[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/u.test(
+    x,
+  );
+function fail(message) {
+  throw Object.assign(new Error(message), { code: "REVIEW_INVALID" });
+}
+export function stableIdentity(value) {
+  const seen = new Set();
+  let nodes = 0;
+  function visit(x, depth = 0) {
+    if (++nodes > 50000 || depth > 30) fail("Review identity exceeds limits");
+    if (x === null || typeof x === "string" || typeof x === "boolean") return x;
+    if (typeof x === "number" && Number.isFinite(x)) return x;
+    if (typeof x !== "object" || seen.has(x)) fail("Invalid review identity");
+    seen.add(x);
+    const out = Array.isArray(x)
+      ? x.map((v) => visit(v, depth + 1))
+      : Object.fromEntries(
+          Object.keys(x)
+            .sort()
+            .filter((k) => x[k] !== undefined)
+            .map((k) => [k, visit(x[k], depth + 1)]),
+        );
+    seen.delete(x);
+    return out;
+  }
+  const result = JSON.stringify(visit(value));
+  if (result.length > REVIEW_LIMITS.identityBytes)
+    fail("Review identity exceeds limits");
+  return result;
+}
+export function validateReviewInput(input) {
+  if (
+    !object(input) ||
+    Object.keys(input).sort().join(",") !== "contextToken,findingId,note,status"
+  )
+    fail("Invalid review fields");
+  if (!hash(input.contextToken) || !hash(input.findingId))
+    fail("Invalid review context or finding ID");
+  if (
+    !Object.hasOwn(REVIEW_STATUS_LABELS, input.status) ||
+    input.status === "needs-review"
+  )
+    fail("Invalid manual review status");
+  if (!safe(input.note) || input.note.length > REVIEW_LIMITS.note)
+    fail("Invalid review note");
+  if (input.status !== "pending" && !input.note.trim())
+    fail("Review note is required");
+  return {
+    contextToken: input.contextToken,
+    findingId: input.findingId,
+    status: input.status,
+    note: input.note.trim(),
+  };
+}
+export function validateReviewDocument(doc) {
+  if (
+    !object(doc) ||
+    Object.keys(doc).sort().join(",") !== "records,revision,schemaVersion" ||
+    doc.schemaVersion !== 1 ||
+    !hash(doc.revision) ||
+    !Array.isArray(doc.records) ||
+    doc.records.length > REVIEW_LIMITS.records
+  )
+    fail("Invalid review storage");
+  const seen = new Set();
+  for (const record of doc.records) {
+    if (
+      !object(record) ||
+      Object.keys(record).sort().join(",") !==
+        "findingId,identity,lineage,note,pluginName,pluginVersion,status,updatedAt"
+    )
+      fail("Invalid review record");
+    validateReviewInput({
+      contextToken: doc.revision,
+      findingId: record.findingId,
+      status: record.status,
+      note: record.note,
+    });
+    if (
+      !safe(record.pluginName) ||
+      !record.pluginName ||
+      record.pluginName.length > 500 ||
+      !safe(record.pluginVersion) ||
+      !record.pluginVersion ||
+      record.pluginVersion.length > 200 ||
+      typeof record.identity !== "string" ||
+      record.identity.length > REVIEW_LIMITS.identityBytes ||
+      typeof record.lineage !== "string" ||
+      record.lineage.length > 2000 ||
+      !Number.isFinite(Date.parse(record.updatedAt)) ||
+      seen.has(record.findingId)
+    )
+      fail("Invalid review record identity");
+    const binding = JSON.parse(record.identity);
+    if (
+      !object(binding) ||
+      !object(binding.scope) ||
+      !object(binding.finding) ||
+      binding.pluginName !== record.pluginName ||
+      binding.pluginVersion !== record.pluginVersion ||
+      !safe(binding.finding.category) ||
+      !binding.finding.category ||
+      [
+        "profileId",
+        "originalPath",
+        "mode",
+        "toolVersion",
+        "dshVersion",
+        "rulesIdentity",
+        "catalogIdentity",
+        "sourceIdentity",
+      ].some((key) => !safe(binding.scope[key]) || !binding.scope[key]) ||
+      stableIdentity(binding) !== record.identity ||
+      stableIdentity([
+        record.pluginName,
+        binding.finding.category,
+        binding.finding.service ?? null,
+        binding.finding.method ?? null,
+      ]) !== record.lineage
+    )
+      fail("Invalid review binding");
+    seen.add(record.findingId);
+  }
+  return doc;
+}
+/** Validate an optional API sidecar without trusting it to be a renderable review. */
+export function validateReviewEnvelope(value, report) {
+  try {
+    const keys = (x, want) =>
+      object(x) && Object.keys(x).sort().join(",") === want;
+    const text = (x, max) => safe(x) && x.length > 0 && x.length <= max;
+    const note = (x) => safe(x) && x.length <= REVIEW_LIMITS.note;
+    const manual = (x) =>
+      Object.hasOwn(REVIEW_STATUS_LABELS, x) && x !== "needs-review";
+    const record = (r, summary = false) =>
+      keys(
+        r,
+        summary
+          ? "findingId,note,noteTruncated,pluginName,pluginVersion,status,updatedAt"
+          : "findingId,note,pluginName,pluginVersion,status,updatedAt",
+      ) &&
+      hash(r.findingId) &&
+      text(r.pluginName, 500) &&
+      text(r.pluginVersion, 200) &&
+      manual(r.status) &&
+      note(r.note) &&
+      (r.status === "pending" ||
+        r.note.trim().length > 0 ||
+        (summary && r.noteTruncated)) &&
+      text(r.updatedAt, 40) &&
+      Number.isFinite(Date.parse(r.updatedAt)) &&
+      (!summary ||
+        (typeof r.noteTruncated === "boolean" && r.note.length <= 200));
+    if (
+      !keys(value, "contextToken,error,history,items,revision,schemaVersion") ||
+      value.schemaVersion !== 1 ||
+      !Array.isArray(value.items) ||
+      value.items.length > REVIEW_LIMITS.findings ||
+      !Array.isArray(value.history) ||
+      value.history.length > REVIEW_LIMITS.records ||
+      !(value.error === null || text(value.error, 4000))
+    )
+      return false;
+    if (value.error && value.contextToken === null && value.revision === null)
+      return value.items.length === 0 && value.history.length === 0;
+    if (!hash(value.contextToken) || !hash(value.revision)) return false;
+    const seenSlots = new Set(),
+      seenHistory = new Set();
+    for (const item of value.items) {
+      if (
+        !keys(
+          item,
+          "findingId,findingIndex,history,historyCount,note,pluginName,pluginVersion,record,reviewReason,status",
+        ) ||
+        !hash(item.findingId) ||
+        !text(item.pluginName, 500) ||
+        !text(item.pluginVersion, 200) ||
+        !Number.isSafeInteger(item.findingIndex) ||
+        item.findingIndex < 0 ||
+        !Object.hasOwn(REVIEW_STATUS_LABELS, item.status) ||
+        !note(item.note) ||
+        !Array.isArray(item.history) ||
+        item.history.length > 3 ||
+        !Number.isSafeInteger(item.historyCount) ||
+        item.historyCount < item.history.length ||
+        item.historyCount > REVIEW_LIMITS.records ||
+        !(item.reviewReason === null || text(item.reviewReason, 4000))
+      )
+        return false;
+      const slot = JSON.stringify([item.pluginName, item.findingIndex]);
+      if (seenSlots.has(slot)) return false;
+      seenSlots.add(slot);
+      if (report) {
+        const plugin = report.plugins?.[item.pluginName];
+        if (
+          !plugin ||
+          plugin.version !== item.pluginVersion ||
+          !Array.isArray(plugin.findings) ||
+          item.findingIndex >= plugin.findings.length
+        )
+          return false;
+      }
+      if (item.record !== null) {
+        if (
+          !record(item.record) ||
+          item.record.findingId !== item.findingId ||
+          item.record.pluginName !== item.pluginName ||
+          item.record.pluginVersion !== item.pluginVersion ||
+          item.record.status !== item.status ||
+          item.record.note !== item.note
+        )
+          return false;
+      } else if (
+        item.note !== "" ||
+        !["pending", "needs-review"].includes(item.status)
+      )
+        return false;
+      if (
+        item.status === "needs-review" &&
+        (!item.historyCount || !item.reviewReason)
+      )
+        return false;
+      if (item.historyCount > 0 && !item.reviewReason) return false;
+      const local = new Set();
+      for (const previous of item.history) {
+        if (
+          !record(previous, true) ||
+          previous.findingId === item.findingId ||
+          previous.pluginName !== item.pluginName ||
+          local.has(previous.findingId)
+        )
+          return false;
+        local.add(previous.findingId);
+      }
+    }
+    for (const previous of value.history) {
+      if (!record(previous) || seenHistory.has(previous.findingId))
+        return false;
+      seenHistory.add(previous.findingId);
+    }
+    if (report) {
+      let count = 0;
+      for (const plugin of Object.values(report.plugins || {})) {
+        if (!Array.isArray(plugin.findings)) return false;
+        count += plugin.findings.length;
+      }
+      if (count !== value.items.length) return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+/** Exact identity includes evidence; lineage only offers old records as review history. */
+export function combineReviews(
+  context,
+  records,
+  { revision = "0".repeat(64), error = null } = {},
+) {
+  const byId = new Map(),
+    byLineage = new Map(),
+    currentIds = new Set(context.findings.map((f) => f.findingId));
+  const publicRecord = (r) => ({
+    findingId: r.findingId,
+    pluginName: r.pluginName,
+    pluginVersion: r.pluginVersion,
+    status: r.status,
+    note: r.note,
+    updatedAt: r.updatedAt,
+  });
+  for (const record of records) {
+    byId.set(record.findingId, record);
+    if (!byLineage.has(record.lineage)) byLineage.set(record.lineage, []);
+    byLineage.get(record.lineage).push(record);
+  }
+  const items = context.findings.map((entry) => {
+    const exact = byId.get(entry.findingId);
+    const record =
+      exact?.identity === entry.identity ? publicRecord(exact) : null;
+    const previous = byLineage.get(entry.lineage) || [];
+    const historyCount = previous.length - (exact ? 1 : 0);
+    // Keep row summaries bounded; the independent history retains each full note once.
+    const history = [];
+    for (let i = previous.length - 1; i >= 0 && history.length < 3; i--) {
+      if (previous[i].findingId === entry.findingId) continue;
+      const old = publicRecord(previous[i]);
+      history.push({
+        ...old,
+        note: old.note.slice(0, 200),
+        noteTruncated: old.note.length > 200,
+      });
+    }
+    return {
+      findingId: entry.findingId,
+      pluginName: entry.pluginName,
+      pluginVersion: entry.pluginVersion,
+      findingIndex: entry.findingIndex,
+      status: record?.status || (historyCount ? "needs-review" : "pending"),
+      note: record?.note || "",
+      record,
+      history,
+      historyCount,
+      reviewReason: historyCount
+        ? "插件源码或版本、规则、目录、工具、观察目标或发现证据已变化；旧处置仅供参考，需要重新核实。"
+        : null,
+    };
+  });
+  return {
+    schemaVersion: 1,
+    contextToken: context.contextToken,
+    revision,
+    error,
+    items,
+    history: records
+      .filter((r) => !currentIds.has(r.findingId))
+      .map(publicRecord),
+  };
+}