dsh-plugin-compat-check 0.1.5 → 0.1.7

package/lib/finding-guidance.js

@@ -53,6 +53,12 @@ export function nextSteps(finding) {
         "在报告给出的源码位置核对服务读取及必需 inject 的作用域，并确认 absent 观测绑定同一 profile、DSH 版本与采样时间。",
         "核对该服务的实际提供者及 loader 状态，补充相关功能操作结果；服务缺失的推断影响不等于业务失败已实测。",
       ];
+    case "api-argument-invalid":
+    case "api-option-unsupported":
+      return [
+        "按源码位置核对选项类型、枚举、实际传值和精确目标版本，查阅 evidence 中固定源码及归档摘要；方法存在或能力守卫不证明参数有效。",
+        "在独立目标会话核验草稿保留、替换或追加；本项仅是静态参数风险，不证明业务失败，也不自动修改或提交草稿。",
+      ];
     case "host-method-missing":
       return [
         "在报告给出的文件与行号核对实际方法调用、Context 绑定及能力守卫，检查是否存在报告尚未识别的兜底。",

package/lib/local-request.js

@@ -0,0 +1,44 @@
+/** 本地信任栅栏：只有本机的 DSH 界面该读到这份数据。 */
+export function isTrustedRequest(req) {
+  try {
+    const header = (name) => {
+      const value = Object.entries(req.headers || {}).find(
+        ([key]) => key.toLowerCase() === name,
+      )?.[1];
+      if (value !== undefined && typeof value !== "string")
+        throw new Error("Invalid request header");
+      return value;
+    };
+    // A non-safelisted header also fences legacy browsers that omit both Origin
+    // and Fetch Metadata. It is a CSRF admission marker, never an auth secret.
+    if (header("x-dsh-compat-request") !== "1") return false;
+    const host = header("host") || "";
+    const origin = header("origin");
+    const hostOk = /^(127\.0\.0\.1|localhost|\[::1\])(:\d+)?$/i.test(host);
+    if (!hostOk) return false;
+    const peer = req.socket?.remoteAddress;
+    if (peer && !["127.0.0.1", "::1", "::ffff:127.0.0.1"].includes(peer))
+      return false;
+    const protocol = req.socket?.encrypted === true ? "https:" : "http:";
+    const expectedOrigin = new URL(`${protocol}//${host}`).origin;
+    const site = header("sec-fetch-site"),
+      mode = header("sec-fetch-mode"),
+      dest = header("sec-fetch-dest");
+    if (site !== undefined && site !== "same-origin") return false;
+    if (mode !== undefined && !["cors", "same-origin"].includes(mode))
+      return false;
+    if (dest !== undefined && !["", "empty"].includes(dest)) return false;
+    if (
+      origin !== undefined &&
+      (!/^https?:\/\/(127\.0\.0\.1|localhost|\[::1\])(:\d+)?$/i.test(origin) ||
+        new URL(origin).origin !== expectedOrigin)
+    )
+      return false;
+    const referer = header("referer");
+    if (referer !== undefined && new URL(referer).origin !== expectedOrigin)
+      return false;
+    return true;
+  } catch {
+    return false;
+  }
+}

package/lib/report-contract.js

@@ -9,6 +9,14 @@
 export const REPORT_SCHEMA = 1;
 export const REPORT_KIND = "plugin-compat-check/result";
 export const ENVELOPE_KIND = "plugin-compat-check/report";
+/** Escape untrusted single-line display text; callers supply layout newlines.
+ * JSON identities remain untouched. Visible escapes are safe to render again. */
+export function terminalText(value) {
+  return String(value).replace(
+    /[\x00-\x1f\x7f-\x9f\u061c\u200e\u200f\u2028-\u202e\u2066-\u2069]/g,
+    (c) => "\\u" + c.charCodeAt(0).toString(16).padStart(4, "0"),
+  );
+}
 /** Reviewed catalogue bytes, not a promise of plugin business compatibility.
  * Adding a version requires source verification, rule review and integration
  * evidence; extraction alone must never extend this list. */
@@ -23,6 +31,11 @@ export const CATALOG_REFERENCES = Object.freeze([
     file: "dsh-api-catalog-0.2.1-rc.2.json",
     sha256: "90b4ae484ebc6660c53e5c9ad14ba657581534b30e8222c636c759e19587f743",
   }),
+  Object.freeze({
+    version: "0.2.1-rc.3",
+    file: "dsh-api-catalog-0.2.1-rc.3.json",
+    sha256: "dd253bc418a787d881e402f3650857c2d8e7631b818927743a5f2b81104f25a5",
+  }),
 ]);
 export function describeCatalog({
   targetVersion = null,
@@ -103,7 +116,9 @@ function snapshotFinding(f) {
     text(f.category) &&
     severities.includes(f.severity) &&
     certainties.includes(f.certainty) &&
-    nullableText(f.location)
+    nullableText(f.location) &&
+    (f.entryId === undefined || nullableText(f.entryId)) &&
+    (f.column === undefined || integer(f.column))
   );
 }
 function checkedEntry(v) {

package/lib/upgrade-contract.js

@@ -3,6 +3,7 @@
 export const SUPPORTED_PREVIEW_VERSIONS = Object.freeze([
   "0.2.0-rc.2",
   "0.2.1-rc.2",
+  "0.2.1-rc.3",
 ]);
 const record = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
 const text = (x) => typeof x === "string" && x.length > 0;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-plugin-compat-check",
-  "version": "0.1.5",
-  "description": "Checks installed DSH plugins against the current DSH version, with source locations, runtime evidence and coverage limits. Includes a compatibility panel and agent tool.",
+  "version": "0.1.7",
+  "description": "Checks installed DSH plugins and previews upgrade risks, with source locations, dependency views, review records and evidence limits. Includes a panel and agent tool.",
   "license": "MIT",
   "type": "module",
   "main": "index.js",
@@ -33,7 +33,8 @@
     "THIRD_PARTY_NOTICES.md"
   ],
   "engines": {
-    "node": "^22.19.0 || >=24"
+    "node": "^22.19.0 || >=24",
+    "dsh": ">=0.2.0-rc.2"
   },
   "scripts": {
     "prepack": "node scripts/stage-skill.mjs && node scripts/stage-contract.mjs && node scripts/stage-kernel.mjs",
@@ -50,7 +51,10 @@
     "compatibility",
     "health-check",
     "cordis",
-    "agent-skills"
+    "agent-skills",
+    "static-analysis",
+    "dependency-analysis",
+    "upgrade"
   ],
   "repository": {
     "type": "git",
@@ -63,6 +67,7 @@
   },
   "dependencies": {
     "@babel/parser": "7.29.9",
-    "semver": "7.7.3"
+    "semver": "7.7.3",
+    "yaml": "2.9.1"
   }
 }

package/scripts/prepublish-check.mjs

@@ -1,26 +1,5 @@
 #!/usr/bin/env node
-/**
- * `prepublishOnly` 钩子 —— 发布前把两类**不可挽回**的错误挡在门外。
- *
- * ## 为什么必须有它
- *
- * npm 发布是**公开且近乎不可撤回**的。而有两类错误一旦发出去就只能靠发新版弥补：
- *
- * ① **版本号与内核不一致**。版本的真源是 `lib/version.mjs`，但 `package.json`
- *    只能写字面量（npm 只认字面量）。改了一处忘了另一处，发布出去的就是
- *    「包的版本是 A、它自己 `--version` 报 B」—— 而这恰恰是这次发布的**主题**
- *    （见 docs/Plan.md §1、§6：「单版本」）。
- *
- * ② **测试没过就发**。`npm publish` 默认**不跑测试**。测试没过的包发出去，
- *    用户拿到的是我们已知有问题的版本，而他还以为那是"刚发布的最新版"。
- *
- * ## 为什么不用 `npm test` 那种写法
- *
- * 这个包发布时人在**仓库里**（`plugin/` 的上一级就是仓库根），
- * 所以能直接跑仓库的测试套件。但 `files` 字段里不含 `test/` ——
- * 也就是说这个脚本**不能**假设测试文件在包内，必须从仓库根跑。
- * 这正是"发布时必须从仓库检出里发"这条约束的技术原因。
- */
+/** Local-only publication gate: source checkout, consistent version, successful tests and document checks. Never publishes. */
 
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';

package/scripts/stage-contract.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 /** Keep host/browser presentation artifacts byte-reproducible from pure sources. */
 import fs from "node:fs";
+import { format, resolveConfig } from "prettier";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 const plugin = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."),
@@ -94,6 +95,12 @@ for (const item of [
       source,
   ]);
 }
+// Format the complete generated artifact at its canonical generation boundary.
+// A formatted client must remain byte-identical on every subsequent check.
+next = await format(next, {
+  ...(await resolveConfig(client)),
+  filepath: client,
+});
 outputs.unshift([client, next]);
 for (const [file, value] of outputs) {
   if (fs.existsSync(file) && fs.readFileSync(file, "utf8") === value) continue;

package/skill/SKILL.md

@@ -15,13 +15,13 @@ description: 当用户询问已安装DSH插件是否适配当前版本、升级
 
 ## 升级前对比
 
-用户要比较当前与目标版本时，已注册工具优先调用 `compat_check({"upgradeTo":"0.2.1-rc.2"})`，需要时指定实际 `profile`；当前版本由运行宿主解析，读取返回的 `upgradePreview`，普通 `report`、baseline/cache为null。没有工具时使用仓库 CLI 的独立预检模式，先明确 profile、当前精确版本和目标精确版本，再运行：
+用户要比较当前与目标版本时，已注册工具优先调用 `compat_check({"upgradeTo":"0.2.1-rc.3"})`，需要时指定实际 `profile`；当前版本由运行宿主解析，读取返回的 `upgradePreview`，普通 `report`、baseline/cache为null。没有工具时使用仓库 CLI 的独立预检模式，先明确 profile、当前精确版本和目标精确版本，再运行：
 
 ```bash
-node <repo>/bin/compat-check.mjs --nm <profile或node_modules目录> --dsh-version 0.2.0-rc.2 --upgrade-to 0.2.1-rc.2 --json
+node <repo>/bin/compat-check.mjs --nm <profile或node_modules目录> --dsh-version 0.2.1-rc.2 --upgrade-to 0.2.1-rc.3 --json
 ```
 
-此模式的 `--dsh-version` 是**当前精确版本**，`--upgrade-to` 是目标精确版本；当前已认证目录仅为 `0.2.0-rc.2` 和 `0.2.1-rc.2`。未知版本或版本范围返回 `status=unsupported-version`、退出3并标明未认证，不能用邻近目录替代。普通文本输出省略 `--json`；此模式不接受 `--quiet`、探针/启动参数、规则/目录覆盖、基线参数或故障报告，可带无操作的 `--no-baseline`。
+此模式的 `--dsh-version` 是**当前精确版本**，`--upgrade-to` 是目标精确版本；当前已认证目录仅为 `0.2.0-rc.2`、`0.2.1-rc.2`、`0.2.1-rc.3`。未知版本或版本范围返回 `status=unsupported-version`、退出3并标明未认证，不能用邻近目录替代。普通文本输出省略 `--json`；此模式不接受 `--quiet`、探针/启动参数、规则/目录覆盖、基线参数或故障报告，可带无操作的 `--no-baseline`。
 
 JSON 使用独立的 `schemaVersion=1 / kind=plugin-compat-check/upgrade-preview`；读取 `currentReport`、`targetReport`、带插件身份的 `changes`、`summary` 与 `limitations`。它对**同一份已安装制品**做静态版本对比：不执行插件、不启动或升级宿主，不读取旁置/环境探针、profile豁免、基线或缓存，也不写状态。新增/恶化风险含致命项时退出2，其余新增/恶化风险退出1，无新增/恶化风险退出0；输入/扫描失败或未认证版本为3。保留提取不完整、coverage/vacuous和客户端未验证限制；0仍可能有未变化的旧问题。差异是目录与声明策略下的预测，不能据此认定升级后业务通过，也不能代替目标宿主的运行时与业务验收。
 
@@ -29,7 +29,7 @@ JSON 使用独立的 `schemaVersion=1 / kind=plugin-compat-check/upgrade-preview
 
 普通报告的`dependencyGraph`只解释依赖和潜在传播：保留host/client/未知端、必需/可选/子作用域、候选提供者、loader禁用/未知状态及覆盖预算。提供声明不是实际提供证明，环或路径不是实测故障；不跨端补造提供者，不因未找到候选就说宿主缺服务，也不据此自动装包。
 
-HTTP/tool envelope的`reviews`是独立人工记录，四种状态为pending/reviewed/false-positive/fixed。已复核、误报或已修复不消除内核发现、不隐藏新风险、不改变退出码/基线，也不授予compatibility豁免。记录绑定报告发布时的源码身份、目标/观察路径/模式、插件/DSH精确版本、工具/规则/目录及finding证据；变化后的needs-review必须重新核实，不能沿用旧误报/修复。只能按用户明确处置意图保存状态与依据，不因读到发现就自动标记已处理。坏文件/超限或busy须转述，不能覆盖或清空记录；进程崩溃可能留下.lock/.reviews-*.tmp，刷新不自动回收，确认没有任何保存任务后才可清理已核实孤立的lock/tmp，保留JSON和基线。
+HTTP/tool envelope的`reviews`是独立人工记录，四种状态为pending/reviewed/false-positive/fixed。已复核、误报或已修复不消除内核发现、不隐藏新风险、不改变退出码/基线，也不授予compatibility豁免。记录绑定报告发布时的源码身份、目标/观察路径/模式、插件/DSH精确版本、工具/规则/目录及finding证据；变化后的needs-review必须重新核实，不能沿用旧误报/修复。只能按用户明确处置意图保存状态与依据，不因读到发现就自动标记已处理。坏文件/超限或busy须转述，不能覆盖或清空记录。基线与人工记录的崩溃孤锁须按仓库`docs/guide.md#本地状态锁恢复`操作：运行`node <repo>/bin/recover-lock.mjs <确切.lock路径>`检查，再用本次token显式确认。只有同用户/主机且系统证明持有PID不存在时才恢复；不按年龄、PID复用或“没有保存任务”猜测，不递归清理JSON、临时文件或恢复保护锁。旧/损坏基线保留原件，不比较或自动覆盖。
 
 可选功能健康执行器仅在仓库`tools/functional-health.mjs`；默认review只审阅声明。普通兼容检查、健康记录导入及作者提供清单均不构成执行授权；不得自动添加执行开关。仅在用户已明确授权所选制品的安装、宿主/插件执行及HTTP/DOM测量后运行，必要时使用Chrome。声明与本地USTAR制品须校验SHA-256、包名/精确版本及DSH精确版本，预算为32项、请求/导航3秒、HTTP响应64KiB、整轮180秒；不接受作者脚本或跳过身份检查。私有profile不是OS沙箱，安装可能联网，不能借用用户账户/模型配置。
 
@@ -91,7 +91,7 @@ report_status=$?
 
 ## 输出怎么读
 
-下面是当前仓库源码对固定合成夹具的可复现输出，运行命令为 `node bin/compat-check.mjs --nm test/fixtures/labels --dsh-version 0.2.1-rc.2 --no-baseline`，预期退出2。它用于解释报告字段，不代表真实插件业务验收；当前版本为0.1.5，历史输出不追改。
+下面是当前仓库源码对固定合成夹具的可复现输出，运行命令为 `node bin/compat-check.mjs --nm test/fixtures/labels --dsh-version 0.2.1-rc.2 --no-baseline`，预期退出2。它用于解释报告字段，不代表真实插件业务验收；工具版本为0.1.7，实际发布与验收状态见仓库docs/current-state.json。
 
 ```text
 插件数: 4    有运行时面: 否（方法级结论降为「疑似」）
@@ -99,7 +99,7 @@ report_status=$?
 参考目录：0.2.1-rc.2 · SHA-256：90b4ae484ebc6660c53e5c9ad14ba657581534b30e8222c636c759e19587f743
 目录认证范围：0.2.1-rc.2；仅核验内置目录字节及对应精确版本的集成；不代表业务验收或运行时观测。
 
-工具版本: 0.1.5    证据覆盖有限: 4 个插件
+工具版本: 0.1.7    证据覆盖有限: 4 个插件
 结论: 可用 2    部分可用 1    不兼容 1    （其中 2 个「可用」没有已验证调用，不等于业务通过）
 
 不兼容  @label/broken-client@1.0.0
@@ -157,8 +157,7 @@ report_status=$?
     但没有观测浏览器中的实际失败；方法缺失案例也可能依据运行时方法面和源码调用点，
     推断「用户可能失去什么功能」。不要把这个方法案例当成所有发现都已有运行时观测。
     **转述时必须保留这个限定**，不要说成"确定会消失"。
-    实测有过一条 certain 级假阳性：工具说「设置页会消失」，而作者把能力检测写在了
-    一个辅助函数里、早就兜住了，还 log 了降级行为。
+    能力helper的静态支持有边界；不能把旧提取器的历史误报当成当前规则或完整覆盖证明。
   - 只有显式`impactBasis=measured`且有对应观测，才按实测转述，例如明确记录的loader FAILED/PENDING。缺少字段或没有标注“推断”均不能当成实测；损坏报告应报工具错误。
 - **转述结论时带上 `--version` 报出的工具版本**（`--json` 里是 `toolVersion`）。
   同一个插件在「规则表还没覆盖这个方法」和「已经覆盖」的两个版本下，
@@ -204,16 +203,18 @@ CI 里可以直接用：`0` 过，`1`/`2` 按你的策略处理，`3` 是**工
 - 报结论时**给出可核对的依据**。API源码发现引用真实`file:line`；没有源码位置的loader/声明事实说明包身份及观测或声明来源，不补造行号。
 
 
-0.1.1：`root` 缺项是未采样，不能称为不存在；`coverage.status=limited` 与 `vacuous` 必须转述。现代探针绑定 profile/DSH/采样时间；旧报告明确标为未绑定。解析、读取、资源上限等诊断会限制覆盖，完整性不足不更新基线。当前统计见仓库 `docs/current-state.json`；npm 包是插件，CLI 从仓库使用，根依赖尚未就绪时在授权范围内运行 `npm ci --ignore-scripts`。显式安装检查会执行目标插件，临时 profile 不是不可信代码隔离沙箱。
+`root` 缺项是未采样，不能称为不存在；`coverage.status=limited` 与 `vacuous` 必须转述。现代探针绑定 profile/DSH/采样时间；旧报告明确标为未绑定。解析、读取、资源上限等诊断会限制覆盖，完整性不足不更新基线。当前统计见仓库 `docs/current-state.json`；npm 包是插件，CLI 从仓库使用，根依赖尚未就绪时在授权范围内运行 `npm ci --ignore-scripts`。显式安装检查会执行目标插件，临时 profile 不是不可信代码隔离沙箱。
 
-0.1.3按目标DSH分流声明：从0.2.1-rc.1起优先自有`engines.dsh`，仅缺失该字段时回退官方peer；更旧目标保留旧peer规则与engines建议。非法字段、空/非法范围会报告风险；peer的workspace:^/~/*按当前DSH精确版本处理，engines的workspace不获放行。声明冲突为declared-incompatible及推断影响，不能写成实际加载失败；宿主也可能跳过不兼容bundle后继续启动。历史npm0.1.2使用旧算法；判断实际行为先核对安装包版本，是否公开发布以registry和Plan记录为准。
+声明按目标DSH分流：从0.2.1-rc.1起优先自有`engines.dsh`，仅缺失该字段时回退官方peer；更旧目标保留旧peer规则与engines建议。非法字段、空/非法范围会报告风险；peer的workspace:^/~/*按当前DSH精确版本处理，engines的workspace不获放行。声明冲突为declared-incompatible及推断影响，不能写成实际加载失败；宿主也可能跳过不兼容bundle后继续启动。历史npm0.1.2使用旧算法；判断实际行为先核对安装包版本，是否公开发布以registry和Plan记录为准。
 
-0.1.3的真实rc.2 UI入口为“更多 → 设置 → 内置插件 → 兼容性”。2026-10-18完整tgz/私有宿主/真实Chrome显示报告，禁用后路由移除、重启用后恢复且仅一个标签；自报注册不等于实际渲染。10月17日标签未显示的历史记录本次未复现，原因未定；有限回归不认证所有插件业务功能。HMR会撤销自有注册、计时器和诊断handle，在途任务卸载后不得写基线或返回新成功报告；分析worker仍受原预算回收，不宣称立即终止。
+DSH 0.2.1-rc.3的UI入口为“左下角账号菜单 → 设置 → 内置插件 → 兼容性”。HMR撤销自有注册、计时器及诊断handle，卸载后不得发布新成功或写基线；worker按预算回收，不承诺立即停止。历史现场证据与当前源码分别核验，见仓库docs/current-state.json。
 
 只读目标node_modules同级的独立`compatibility.json`，形如`{"sample@1.0.0":["0.2.1-rc.2"]}`。只有插件名、插件精确版本与DSH精确版本全匹配才豁免范围冲突；不使用包内兼容声明代替授权。无效记录整条忽略（其它有效记录仍用）并限制覆盖；缺文件为空豁免，可读性/JSON错误、非普通文件或超过64KiB则豁免未观测。不得代用户写豁免，豁免不绕过非法字段，也不证明API或业务成功。
 
-普通体检中，CLI的`--dsh-version`及probe-boot采集值、宿主自己的DSH版本用于目录选择：DSH≥0.2.1-rc.2使用独立rc.2目录，其余/未知使用旧0.2.0-rc.2目录，显式`--catalog`优先。未知版本不猜声明，未来DSH未经认证。单独文件probe不自动补目标版本，需给`--dsh-version`。目录不等于运行时面。当前契约/验收/后续见仓库docs/Plan.md，统计见docs/current-state.json；公开安装以npm registry为准。
+普通体检中，CLI的`--dsh-version`及probe-boot采集值、宿主自己的DSH版本用于目录选择：DSH≥0.2.1-rc.3使用独立rc.3目录，≥0.2.1-rc.2使用rc.2目录，其余/未知使用旧0.2.0-rc.2目录，显式`--catalog`优先。未知版本不猜声明，未来DSH未经认证。单独文件probe不自动补目标版本，需给`--dsh-version`。目录不等于运行时面。当前契约/验收/后续见仓库docs/Plan.md，统计见docs/current-state.json；公开安装以npm registry为准。
 
 普通报告另有 `catalog`：目标版本、参考目录版本、SHA-256、selection、verified、certifiedVersions及warning。转述时同时给出目标与目录身份；fallback/override、未知身份和未认证提示不得省略，verified仅表示内置目录与已验收精确版本匹配，不是业务认证。内置目录摘要不符、同名插件重复安装（含alias及不同版本）会明确无法判定，不允许转述为无冲突；普通报告失败不推进基线。仓库YAML修复仅涉及锁文件等工具依赖，不属于npm插件运行时依赖。新目录治理流程见仓库 `docs/maintaining.md#api目录候选审查`。
 
 对observationVersion=1探针始终校验采样时间：未来偏差最多5分钟（含边界），缺失/非法或超限时撤回该文件的服务及loader证据，不推断FAILED/PENDING或确定方法缺失；普通体检另保留24小时有效期及profile/DSH绑定。转述observation.notes中的原因，保留静态发现和待验证项，不修正原采样时间、不把时钟异常当插件不兼容；修复时钟/重采样后再显式刷新。旧未绑定报告仍只使用显式键，不能补造绑定。仓库CI依赖安全工具不属于npm运行时功能。
+
+rc.3三处“更多”按全局面板/会话视图/右侧工具区分；浏览进入主插件列表，创建仅追加Cordis草稿，不发送。`startSession`复用空白会话；指定preset隔离，`whenDraftExists`默认keep并优先于旧clearPreviousDraft。入口折叠不等于未激活；名称目录没有变化也不证明行为相同。rc.3模型列表发现使用凭据门控，首次可等待/失败回退；不要为体检访问生产/models或发送模型请求。