@luolingp/request-doctor 0.11.0 → 0.12.0

package/lib/env-shape.js

@@ -0,0 +1,13 @@
+// 描述一个插件的兼容环境形态：薄垫片几个、真实旧版本几个。
+//
+// 单独成文件是为了让 version-repair 保持在行数上限内，也让这段逻辑能被直接测。
+import { classifyPackages, formatShape } from './env-verify.js';
+import { bareNameOf } from './compat.js';
+
+// @param {string} pluginDir - 插件在 profile 里的目录。
+// @param {object} entry - 审计条目，只需要它的 importMap。
+// @returns {string} 一句话，例如「薄垫片 4 个」或「真实旧版本 2 个（需重启）：…」。
+export function describeEnvironmentShape(pluginDir, entry) {
+  const names = Object.keys(entry.importMap ?? {}).map((spec) => bareNameOf(spec));
+  return formatShape(classifyPackages(pluginDir, names));
+}

package/lib/env-verify.js

@@ -1,160 +1,249 @@
-// 验证兼容环境真的能把插件要的东西交出来。
-//
-// 建完环境就假定成功是不够的：垫片写错一个导出名、目标文件读不出来，插件在加载那一刻
-// 就会崩，而修复流程还以为自己干得不错。这里把「插件要的每个符号，环境是否真能提供」
-// 逐条核对一遍，让问题在修复阶段暴露，而不是甩给用户。
-import { readFileSync, statSync } from 'node:fs';
-import { join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { bareNameOf, parseExportedNames } from './compat.js';
-
-// 一个插件图里最多缓存这么多个包的结果。运行时包不小，每次扫描都重新解析太费。
-const MAX_CACHE = 256;
-
-// 缓存键带文件签名，改动自然失效。键算错不会导致误判——只是多解析一次。
-const cache = new Map();
-
-// 文件签名，读不到用固定占位（表示"读不到"本身也是一种稳定状态）。
-function signatureOf(path) {
-  try {
-    const stat = statSync(path);
-    return `${stat.mtimeMs}:${stat.size}`;
-  } catch {
-    return 'unreadable';
-  }
-}
-
-// 从垫片里取出 `export * from "..."` / `export { ... } from "..."` 指向的 URL。
-//
-// 这里保留 URL 而不是立刻转成路径：转路径在有些平台上会失败（比如没有盘符的 Windows
-// 路径），那不代表垫片有问题，只说明这次核对不了。把"转换失败"和"没有目标"分开，
-// 才不会把能正常跑的环境误判成坏的。
-function targetUrlsOf(source) {
-  const urls = [];
-  const pattern = /\bfrom\s+"(file:[^"]+)"/g;
-  let match;
-  while ((match = pattern.exec(source)) !== null) urls.push(match[1]);
-  return urls;
-}
-
-// 读一个文件，读不到就返回 undefined。
-function readText(path) {
-  try {
-    return readFileSync(path, 'utf8');
-  } catch {
-    return undefined;
-  }
-}
-
-
-
-// 一个包的环境能否满足它需要的符号。
-//
-// 三种结果：provided（能提供）、missing（能读到目标但确实没有）、unverifiable（目标读不到，
-// 无从判断）。最后一种不算失败——运行时包常常装在归档里，普通读文件读不到是正常的。
-export function verifyPackage(pluginDir, name, symbols) {
-  const shimPath = join(pluginDir, 'node_modules', ...name.split('/'), 'index.js');
-  const shimSource = readText(shimPath);
-  if (shimSource === undefined) return { status: 'missing', detail: '没有垫片' };
-
-  // 垫片本身和它的目标都参与签名。这样运行时升级、垫片被改写都会自然失效，
-  // 而重复扫描同一个环境时不必再解析那个几百 KB 的运行时包。
-  const targets = targetUrlsOf(shimSource);
-  const targetPaths = targets.map((url) => {
-    try {
-      return fileURLToPath(url);
-    } catch {
-      return undefined;
-    }
-  });
-  const key = [shimPath, signatureOf(shimPath), ...targetPaths.map((path) => (path === undefined ? 'bad-url' : signatureOf(path)))].join('|');
-
-  const cached = cache.get(shimPath);
-  if (cached !== undefined && cached.key === key) return judge(cached.info, symbols);
-
-  const info = describeEnvironment(shimPath, shimSource, targetPaths);
-  if (cache.size >= MAX_CACHE && !cache.has(shimPath)) {
-    const oldest = cache.keys().next().value;
-    if (oldest !== undefined) cache.delete(oldest);
-  }
-  cache.set(shimPath, { key, info });
-  return judge(info, symbols);
-}
-
-// 把一个环境能提供的符号收齐。
-//
-// 有些包是 CommonJS 的（schemastery 就是），读不出 ESM 的导出清单。这时候退回按词边界
-// 搜源码——建环境那一侧本来就是这么做的，两边必须一致，否则一边说齐了、另一边说缺了，
-// 插件就会在「修好了」和「没修好」之间来回跳。
-function describeEnvironment(shimPath, shimSource, targetPaths) {
-  const shimNames = parseExportedNames(shimPath, (source) => readFileSync(source, 'utf8')) ?? [];
-  const targetNames = [];
-  const needles = [];
-  let readableTargets = 0;
-  for (const path of targetPaths) {
-    if (path === undefined) continue;
-    const source = readText(path);
-    if (source === undefined) continue;
-    readableTargets += 1;
-    const names = parseExportedNames(path, (file) => readFileSync(file, 'utf8'));
-    // 空清单同样不可信：CommonJS 包读出来就是空的。
-    if (names === undefined || names.length === 0) needles.push(source);
-    else targetNames.push(...names);
-  }
-  return { shimNames, targetNames, needles, readableTargets, hasTargets: targetPaths.length > 0 };
-}
-
-// 一个符号在环境里到底有没有。名字对不上时退回搜源码。
-function provides(info, symbol) {
-  if (info.shimNames.includes(symbol) || info.targetNames.includes(symbol)) return true;
-  const escaped = symbol.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  const pattern = new RegExp('\\b' + escaped + '\\b');
-  return info.needles.some((source) => pattern.test(source));
-}
-
-// 拿插件要的符号去对照环境能提供的，给出结论。
-function judge(info, symbols) {
-  const lacking = symbols.filter((symbol) => {
-    // default 必须由垫片自己写出来：`export *` 从不转发默认导出，
-    // 目标有 default 不等于插件拿得到。
-    if (symbol === 'default') return !info.shimNames.includes('default');
-    return !provides(info, symbol);
-  });
-
-  if (lacking.length === 0) return { status: 'provided' };
-  // 垫片指着的东西一个都读不到，这个环境是坏的：插件加载时自己也要读那些文件，
-  // 读不到就会崩。所以这里不能当「无法核对」放过去，要如实算作问题。
-  if (info.readableTargets === 0 && info.hasTargets) {
-    return { status: 'missing', detail: '垫片指向的文件一个都读不到，环境不可用' };
-  }
-  return { status: 'missing', detail: `缺 ${lacking.join(', ')}` };
-}
-
-// 核对整个环境。
-//
-// @param {object} input
-// @param {string} input.pluginDir - 插件目录。
-// @param {Map<string,string[]>} input.imports - 插件导入的包与符号。
-// @returns {{ok: boolean, problems: object[], unverified: object[]}}
-export function verifyEnvironment(input) {
-  const problems = [];
-  const unverified = [];
-  // 同一个包可能既从包根、也从子路径被导入。垫片只有一个，所以要按裸包名归组，
-  // 把两处的符号合起来核对，否则子路径那条会被当成一个没有垫片的包。
-  const groups = new Map();
-  for (const [specifier, symbols] of input.imports ?? new Map()) {
-    if (!specifier.startsWith('@deepseek-ai/')) continue;
-    const name = bareNameOf(specifier);
-    if (groups.has(name) === false) groups.set(name, new Set());
-    const set = groups.get(name);
-    for (const symbol of symbols ?? []) set.add(symbol);
-  }
-
-  for (const [name, symbols] of groups) {
-    if (symbols.size === 0) continue;
-    const result = verifyPackage(input.pluginDir, name, [...symbols]);
-    if (result.status === 'missing') problems.push({ name, detail: result.detail });
-    else if (result.status === 'unverifiable') unverified.push({ name, detail: result.detail });
-  }
-  return { ok: problems.length === 0, problems, unverified };
+// 验证兼容环境真的能把插件要的东西交出来。
+//
+// 建完环境就假定成功是不够的：垫片写错一个导出名、目标文件读不出来，插件在加载那一刻
+// 就会崩，而修复流程还以为自己干得不错。这里把「插件要的每个符号，环境是否真能提供」
+// 逐条核对一遍，让问题在修复阶段暴露，而不是甩给用户。
+import { readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { bareNameOf, parseExportedNames } from './compat.js';
+
+// 一个插件图里最多缓存这么多个包的结果。运行时包不小，每次扫描都重新解析太费。
+const MAX_CACHE = 256;
+
+// 缓存键带文件签名，改动自然失效。键算错不会导致误判——只是多解析一次。
+const cache = new Map();
+
+// 文件签名，读不到用固定占位（表示"读不到"本身也是一种稳定状态）。
+function signatureOf(path) {
+  try {
+    const stat = statSync(path);
+    return `${stat.mtimeMs}:${stat.size}`;
+  } catch {
+    return 'unreadable';
+  }
+}
+
+// 从垫片里取出 `export * from "..."` / `export { ... } from "..."` 指向的 URL。
+//
+// 这里保留 URL 而不是立刻转成路径：转路径在有些平台上会失败（比如没有盘符的 Windows
+// 路径），那不代表垫片有问题，只说明这次核对不了。把"转换失败"和"没有目标"分开，
+// 才不会把能正常跑的环境误判成坏的。
+function targetUrlsOf(source) {
+  const urls = [];
+  const pattern = /\bfrom\s+"(file:[^"]+)"/g;
+  let match;
+  while ((match = pattern.exec(source)) !== null) urls.push(match[1]);
+  return urls;
+}
+
+// 读一个文件，读不到就返回 undefined。
+function readText(path) {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch {
+    return undefined;
+  }
+}
+
+
+
+// 环境里装的是一整个真实旧版本（不是垫片）时怎么核对。
+//
+// 这种形态是给「当前运行时已经删掉的导出」准备的：垫片转发不过去，只能装旧版。
+// 所以这里不读垫片，读这个包自己的入口；读不到入口才算无法核对。
+function verifyRealPackage(dir, symbols) {
+  const manifest = readText(join(dir, 'package.json'));
+  if (manifest === undefined) return { status: 'missing', detail: '没有垫片，也没有包清单' };
+
+  let entry = join(dir, 'index.js');
+  try {
+    const parsed = JSON.parse(manifest);
+    const dot = parsed.exports?.['.'];
+    const target = typeof dot === 'string' ? dot : dot?.default;
+    if (typeof target === 'string') entry = join(dir, target);
+    else if (typeof parsed.main === 'string') entry = join(dir, parsed.main);
+  } catch {
+    // 清单读坏了就按 index.js 试，下面读不到会如实报出来。
+  }
+
+  const source = readText(entry);
+  if (source === undefined) return { status: 'unverifiable', detail: '入口读不到' };
+
+  const names = parseExportedNames(entry, (file) => readFileSync(file, 'utf8')) ?? [];
+  const info = {
+    shimNames: [],
+    targetNames: names,
+    // 导出清单读不出来（CommonJS 包）时退回搜源码，和建环境那一侧保持同一口径。
+    needles: names.length === 0 ? [source] : [],
+    readableTargets: 1,
+    hasTargets: true,
+  };
+
+  const lacking = symbols.filter((symbol) => {
+    if (symbol === 'default') {
+      return !(names.includes('default') || /\bexport\s+default\b/.test(source));
+    }
+    return !provides(info, symbol);
+  });
+  if (lacking.length === 0) return { status: 'provided', detail: '真实旧版本提供全部所需符号' };
+  return { status: 'missing', detail: '旧版本缺少 ' + lacking.join(', ') };
+}
+
+// 一个包的环境能否满足它需要的符号。
+//
+// 三种结果：provided（能提供）、missing（能读到目标但确实没有）、unverifiable（目标读不到，
+// 无从判断）。最后一种不算失败——运行时包常常装在归档里，普通读文件读不到是正常的。
+export function verifyPackage(pluginDir, name, symbols) {
+  const dir = join(pluginDir, 'node_modules', ...name.split('/'));
+  const shimPath = join(dir, 'index.js');
+  const shimSource = readText(shimPath);
+  if (shimSource === undefined) return verifyRealPackage(dir, symbols);
+
+  // 垫片本身和它的目标都参与签名。这样运行时升级、垫片被改写都会自然失效，
+  // 而重复扫描同一个环境时不必再解析那个几百 KB 的运行时包。
+  const targets = targetUrlsOf(shimSource);
+  const targetPaths = targets.map((url) => {
+    try {
+      return fileURLToPath(url);
+    } catch {
+      return undefined;
+    }
+  });
+  const key = [shimPath, signatureOf(shimPath), ...targetPaths.map((path) => (path === undefined ? 'bad-url' : signatureOf(path)))].join('|');
+
+  const cached = cache.get(shimPath);
+  if (cached !== undefined && cached.key === key) return judge(cached.info, symbols);
+
+  const info = describeEnvironment(shimPath, shimSource, targetPaths);
+  if (cache.size >= MAX_CACHE && !cache.has(shimPath)) {
+    const oldest = cache.keys().next().value;
+    if (oldest !== undefined) cache.delete(oldest);
+  }
+  cache.set(shimPath, { key, info });
+  return judge(info, symbols);
+}
+
+// 把一个环境能提供的符号收齐。
+//
+// 有些包是 CommonJS 的（schemastery 就是），读不出 ESM 的导出清单。这时候退回按词边界
+// 搜源码——建环境那一侧本来就是这么做的，两边必须一致，否则一边说齐了、另一边说缺了，
+// 插件就会在「修好了」和「没修好」之间来回跳。
+function describeEnvironment(shimPath, shimSource, targetPaths) {
+  const shimNames = parseExportedNames(shimPath, (source) => readFileSync(source, 'utf8')) ?? [];
+  const targetNames = [];
+  const needles = [];
+  let readableTargets = 0;
+  for (const path of targetPaths) {
+    if (path === undefined) continue;
+    const source = readText(path);
+    if (source === undefined) continue;
+    readableTargets += 1;
+    const names = parseExportedNames(path, (file) => readFileSync(file, 'utf8'));
+    // 空清单同样不可信：CommonJS 包读出来就是空的。
+    if (names === undefined || names.length === 0) needles.push(source);
+    else targetNames.push(...names);
+  }
+  return { shimNames, targetNames, needles, readableTargets, hasTargets: targetPaths.length > 0 };
+}
+
+// 一个符号在环境里到底有没有。名字对不上时退回搜源码。
+function provides(info, symbol) {
+  if (info.shimNames.includes(symbol) || info.targetNames.includes(symbol)) return true;
+  const escaped = symbol.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const pattern = new RegExp('\\b' + escaped + '\\b');
+  return info.needles.some((source) => pattern.test(source));
+}
+
+// 拿插件要的符号去对照环境能提供的，给出结论。
+function judge(info, symbols) {
+  const lacking = symbols.filter((symbol) => {
+    // default 必须由垫片自己写出来：`export *` 从不转发默认导出，
+    // 目标有 default 不等于插件拿得到。
+    if (symbol === 'default') return !info.shimNames.includes('default');
+    return !provides(info, symbol);
+  });
+
+  if (lacking.length === 0) return { status: 'provided' };
+  // 垫片指着的东西一个都读不到，这个环境是坏的：插件加载时自己也要读那些文件，
+  // 读不到就会崩。所以这里不能当「无法核对」放过去，要如实算作问题。
+  if (info.readableTargets === 0 && info.hasTargets) {
+    return { status: 'missing', detail: '垫片指向的文件一个都读不到，环境不可用' };
+  }
+  return { status: 'missing', detail: `缺 ${lacking.join(', ')}` };
+}
+
+// 兼容环境里每个包到底是哪种形态。
+//
+// 薄垫片：只有 index.js，转发到现行实现，改完立刻有效。
+// 真实旧版本：一整个包，用于当前运行时已经删掉的导出，改完必须重启才重新解析。
+// 两者后果不同，所以报告里要分开写，而不是笼统说「建了若干个环境」。
+export function classifyPackages(pluginDir, names) {
+  const shims = [];
+  const realVersions = [];
+  for (const name of names ?? []) {
+    const dir = join(pluginDir, 'node_modules', ...name.split('/'));
+    const manifest = readText(join(dir, 'package.json'));
+    if (manifest === undefined) {
+      // 连清单都没有：只有 index.js 的话，只可能是我们写的薄垫片。
+      if (readText(join(dir, 'index.js')) !== undefined) shims.push(name);
+      continue;
+    }
+    // 垫片也是完整的包（有自己的 package.json），靠描述里的标记认出来；
+    // 真实旧版本没有这个标记。
+    const isShim = manifest.includes('request-doctor compatibility environment');
+    if (isShim) shims.push(name);
+    else realVersions.push(name);
+  }
+  return { shims, realVersions };
+}
+
+// 报一句某个插件的兼容环境是怎么建的。
+//
+// 薄垫片转发到现行实现，立刻有效；真实旧版本用于已被删掉的导出，必须重启才重新解析。
+// 两种后果不同，报告里要分开写。
+export function describeCompat(pluginDir, item, packageVersion) {
+  const names = Object.keys(item.importMap ?? {}).map((spec) => bareNameOf(spec));
+  const shape = classifyPackages(pluginDir, names);
+  const parts = [];
+  if (shape.shims.length > 0) parts.push(`薄垫片 ${shape.shims.length} 个`);
+  if (shape.realVersions.length > 0) parts.push(`真实旧版本 ${shape.realVersions.length} 个（${shape.realVersions.join(', ')}）`);
+  const built = parts.length === 0 ? '无需建环境' : parts.join('，');
+  return `${packageVersion} given a ${item.runtimeVersion} compatibility environment：${built}；声明已对齐`;
+}
+// 把形态压成一行，给审计结论用。真实旧版本要重启才生效，所以必须标出来。
+export function formatShape(shape) {
+  if (shape.shims.length === 0 && shape.realVersions.length === 0) return '未建兼容环境';
+  const notes = [];
+  if (shape.shims.length > 0) notes.push(`薄垫片 ${shape.shims.length} 个`);
+  if (shape.realVersions.length > 0) notes.push(`真实旧版本 ${shape.realVersions.length} 个（需重启）：${shape.realVersions.join(', ')}`);
+  return notes.join('；');
 }
+// 核对整个环境。
+//
+// @param {object} input
+// @param {string} input.pluginDir - 插件目录。
+// @param {Map<string,string[]>} input.imports - 插件导入的包与符号。
+// @returns {{ok: boolean, problems: object[], unverified: object[]}}
+export function verifyEnvironment(input) {
+  const problems = [];
+  const unverified = [];
+  // 同一个包可能既从包根、也从子路径被导入。垫片只有一个，所以要按裸包名归组，
+  // 把两处的符号合起来核对，否则子路径那条会被当成一个没有垫片的包。
+  const groups = new Map();
+  for (const [specifier, symbols] of input.imports ?? new Map()) {
+    if (!specifier.startsWith('@deepseek-ai/')) continue;
+    const name = bareNameOf(specifier);
+    if (groups.has(name) === false) groups.set(name, new Set());
+    const set = groups.get(name);
+    for (const symbol of symbols ?? []) set.add(symbol);
+  }
+
+  for (const [name, symbols] of groups) {
+    if (symbols.size === 0) continue;
+    const result = verifyPackage(input.pluginDir, name, [...symbols]);
+    if (result.status === 'missing') problems.push({ name, detail: result.detail });
+    else if (result.status === 'unverifiable') unverified.push({ name, detail: result.detail });
+  }
+  return { ok: problems.length === 0, problems, unverified };
+}

package/lib/restart-notice.js

@@ -0,0 +1,21 @@
+// 「需要重启」的判定。
+//
+// 兼容环境的两种形态后果不同：
+// - 薄垫片：转发到现行实现，改完立刻有效；
+// - 真实旧版本：文件已经换好，但这个进程多半缓存过那次失败的导入，ESM 不会重新解析。
+//
+// 第二种只能重启，所以要明确告诉用户，而不是反复重试或报成环境失败。
+
+const MISSING_EXPORT = /does not provide an export named '([^']+)'/;
+
+// 从失败明细里认出「缺导出」这种情况，并把它记成一条待重启提示。
+export function noteRestart(deps, name, detail) {
+  const missing = MISSING_EXPORT.exec(detail);
+  if (missing === null) return false;
+  const symbol = missing[1];
+  const hint = `${name} 已经装好需要的旧版本，但这个进程不会重新解析 ${symbol}，重启 DSH 后即可生效`;
+  const box = deps.diagnostics.diagnostics;
+  box.restartRequired = [...(box.restartRequired ?? []), { name, symbol, hint }];
+  deps.record('restart-required', hint);
+  return true;
+}

package/lib/verdict-report.js

@@ -0,0 +1,37 @@
+// 讲清某个插件为什么被拦下。
+//
+// 审计把判定、理由、缺的符号都记在诊断里，平时只在整轮扫描的输出里一闪而过。
+// 装不上的人真正想问的就是「为什么」，所以要能直接查。
+
+// @param {string} name - 插件包名。
+// @param {object} deps - 组合根传进来的依赖，只需要 diagnostics。
+// @returns {{kind: string, text: string}} 命令结果。
+export function explainVerdict(name, deps) {
+  if (name === '') return { kind: 'error', text: 'usage: /doctor why <包名>' };
+  const audited = deps.diagnostics?.versionScan?.audited ?? [];
+  const hit = audited.find((item) => item.name === name);
+  if (hit === undefined) return { kind: 'error', text: missingText(name, audited) };
+  return { kind: 'success', text: reportLines(hit).join('\n') };
+}
+
+// 一条一条拼出结论：判定、理由、缺的符号、环境，最后给一句能照做的建议。
+function reportLines(hit) {
+  const lines = [`${hit.name}@${hit.version}：${hit.verdict}`];
+  for (const reason of hit.reasons ?? []) lines.push(`  ${reason}`);
+  if ((hit.missing ?? []).length > 0) lines.push(`  缺符号：${hit.missing.join(', ')}`);
+  if (hit.environment !== undefined) lines.push(`  环境：${hit.environment}`);
+  lines.push(advice(hit.verdict));
+  return lines;
+}
+
+// 没查到这个插件时说清楚现状，顺便列出已经审计过谁。
+function missingText(name, audited) {
+  if (audited.length === 0) return `没有 ${name} 的审计结论：还没有扫描结果，先执行 /doctor 或等下一轮扫描`;
+  return `没有 ${name} 的审计结论。已审计的插件：${audited.map((item) => item.name).join(', ')}`;
+}
+
+// 结论后面跟一句能直接照做的话。
+function advice(verdict) {
+  if (verdict === 'compatible') return '  结论：可以装。装不上就是管理器那边的检查没过，用 /doctor install 走本插件的路径。';
+  return '  结论：要修得先让它要的东西能被提供；缺符号时本插件会尝试装入插件声明的旧版本。';
+}