dsh-plugin-manager-companion 0.1.0

package/dist/diagnostics.d.ts

@@ -0,0 +1,332 @@
+/**
+ * 诊断引擎 — 对本地 DSH 环境做五层只读分析（环境控制台的核心）。
+ *
+ * 归属：A 类·重写（旧 src/analyze.ts 只作**检测清单**意图参考，未复制任何代码）。
+ * 旧实现参考：dsh-web-plugin-manager/src/analyze.ts（检测哪些问题）、
+ *   src/installFlow.ts#qualityIssues（安装前质量门的检查面）。
+ *   旧扫描器是"正则 + 手工剥注释"：被注释掉的 new Service(ctx, 'x') 会被算成真实注册（误报），
+ *   字符串里的 from 'x' 会被算成 import，正则字面量里的双斜杠会把整行代码当注释吞掉（漏报）。
+ *   本模块改为**逐字符词法扫描**：只在代码位置识别 import/export/require 关键字与调用实参，
+ *   注释与字符串字面量在词法阶段就被跳过，行号由扫描器直接给出，不做事后回找。
+ * 官方复用：@deepseek-ai/dsh-app-boot 的 loadProfileDirectory / composeEntries
+ *   （patch 层栈与合并语义的唯一权威口径）、@deepseek-ai/dsh-host-plugin-inventory
+ *   （运行时 fiber 事实，经 official.ts 的 readRuntimeInventory 降级封装）、
+ *   Node 的 createRequire 真实解析（只用于判定"能解析"；判定"不能解析"走文件与 exports 探测）。
+ *
+ * 解析根（2026-09-19 修复的误报根因）：一个 profile 只装自己的依赖，官方包（@deepseek-ai/*）
+ *   与 bundle 本体都不在 profile 的 node_modules 里，它们由**安装锚点**提供。只按
+ *   profile 目录解析会把官方包的每一行都判成孤儿（实测干净环境 163 条 orphan-row 全部是误报）。
+ *   因此解析根纳入 ctx.get('profileContext').installAnchor，口径与官方 profile.ts 的
+ *   packageDirFromAnchor 一致：createRequire(anchor).resolve.paths(name)，先 realpath 锚点
+ *   （pnpm 的 bin shim 路径不是安装目录的兄弟目录，不 realpath 会一个包都解析不到）。
+ *   锚点拿不到时退回 profile 解析并在 skipped 里如实说明，绝不静默当成"包不存在"。
+ * 前提检查：旧实现的前提是"官方只有只读清单，所以诊断必须自己扫 patch 文本、自己猜绑定关系"。
+ *   0.1.6 之后该前提消失：官方提供 composeEntries（与 boot 同一次 applyEntryPatches 调用）与
+ *   readPluginInventory。自己再实现一遍 patch 合并只会与官方漂移，因此事实来源是
+ *   **官方优先、静态兜底、缺失记 skipped**，绝不假装健康。
+ *
+ * 五层，逐层独立可跳过（能力缺失时写入 report.skipped 并给原因）：
+ *   L1 dependency  — import 图 × package.json 声明 × loader 提供项
+ *   L2 composition — patch 层栈的行 id / 禁用 / 孤立行（只读，保留原始行号）
+ *   L3 runtime     — loader fiber 相位 + 源码注册名冲突
+ *   L4 consistency — 官方 inventory × 本地 manifest
+ *   L5 ecosystem   — 市场索引（默认关闭；本模块只留最小骨架，索引归市场模块）
+ *
+ * 本模块不写任何文件、不调 pnpm、不注册服务。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { CompanionConfig, DiagnosticsConfig } from './settings.ts';
+import type { DiagnosticGroup, DiagnosticIssue, DiagnosticReport, EnvironmentInfo } from './types.ts';
+/**
+ * 官方包里允许作为**普通 dependencies** 声明的那几个。
+ *
+ * 理由（沿用前身仓库审计结论，此处只记录事实）：这两个包的模块身份不敏感——
+ * schemastery 的校验错误走 Symbol.for('ValidationError') 全局符号，schema 本身是纯闭包；
+ * cosmokit 是无模块级可变状态的工具集。其余 @deepseek-ai/* 一旦以普通依赖落进 profile，
+ * pnpm 会装出第二份拷贝，loader 从 profile 目录解析官方行时就会用到它，
+ * 唯一符号与类身份随之分裂，运行时报 "Cannot read properties of undefined" 这类错。
+ */
+export declare const OFFICIAL_DEP_ALLOWED: ReadonlySet<string>;
+/**
+ * 说明符是否由 loader / 平台提供（不需要在包里声明）。
+ * @param spec - 裸说明符。
+ * @returns 是否由平台提供。
+ */
+export declare function isLoaderProvided(spec: string): boolean;
+/**
+ * 本模块会产出的修复动作标识（host 端据此分派，是闭集）。
+ *
+ * wire 契约见 src/types.ts 的 DiagnosticFix.action（那里是 string）；
+ * host 的 switch 应当覆盖全部取值。
+ */
+export type DiagnosticFixAction = 'remove-duplicate-row' | 'enable-row' | 'remove-official-copy' | 'remove-row' | 'install-provider' | 'install-dependency' | 'disable-row';
+/** 一次源码扫描给出的命名注册点。 */
+export interface RegistrationHit {
+    readonly name: string;
+    readonly file: string;
+    readonly line: number;
+}
+/** import / require / re-export 的一处说明符。 */
+export interface ScannedImport {
+    readonly spec: string;
+    readonly file: string;
+    readonly line: number;
+    readonly kind: 'static' | 'dynamic' | 're-export' | 'require';
+}
+/** 一个包完整扫描的结果。 */
+export interface PackageScan {
+    readonly imports: readonly ScannedImport[];
+    readonly services: readonly RegistrationHit[];
+    readonly injects: readonly RegistrationHit[];
+    readonly tools: readonly RegistrationHit[];
+    readonly sections: readonly RegistrationHit[];
+    readonly routes: readonly RegistrationHit[];
+    readonly entryFiles: readonly string[];
+    readonly filesScanned: number;
+    /** 命中上限时为 true（结果不完整，调用方必须如实标注）。 */
+    readonly truncated: boolean;
+    /** 无法扫描时的原因（没有入口、manifest 不可读等）。 */
+    readonly reason?: string;
+}
+/**
+ * 诊断目标环境：EnvironmentInfo 加上可选的安装锚点。
+ *
+ * 锚点不是"环境的事实"而是**启动这次诊断的 dsh 安装**的事实，所以调用方可以在环境对象上
+ * 原样透传（EnvironmentInfo 兼容这个类型）；不传时引擎自己从 ctx.get('profileContext') 取。
+ * 两种来源都没有时按"没有锚点"处理并记 skipped，绝不静默当成"包不存在"。
+ */
+export interface DiagnosticTargetEnvironment extends EnvironmentInfo {
+    /** 启动这次诊断的 dsh 安装的 package.json 绝对路径（官方 ProfileContext.installAnchor）。 */
+    readonly installAnchor?: string;
+}
+/**
+ * 对一个环境做完整诊断。
+ *
+ * 五层依次执行，任何一层失败只影响它自己：该层的失败原因写进 report.skipped，
+ * 其余层照常产出。函数本身不抛错——诊断工具把异常抛给 UI 只能得到白屏。
+ *
+ * @param ctx - host 上下文；只用 ctx.get()（官方能力探测）与 ctx.logger。
+ * @param env - 被诊断环境（EnvironmentInfo，来自环境列表）。
+ * @param config - 本插件配置；同时接受 CompanionConfig 与单独的 diagnostics 段。
+ * @returns 报告：分层问题数 + 按 code/作用域聚合的组 + 逐条问题清单 + 跳过项。
+ */
+export declare function analyzeEnvironment(ctx: Context, env: DiagnosticTargetEnvironment, config: CompanionConfig | DiagnosticsConfig): Promise<DiagnosticReport>;
+export type { DiagnosticGroup } from './types.ts';
+/**
+ * 组键：层级 + 类别 + 严重级别 + 作用域（同一个 code 落在不同包里是不同的问题）。
+ * @param issue - 一条发现。
+ * @returns 稳定组键。
+ */
+export declare function groupKeyOf(issue: DiagnosticIssue): string;
+/**
+ * 按组键聚合发现；组按问题数降序、同数按组键升序，结果确定性可测。
+ * @param issues - 逐条发现（在报告里已带唯一 id）。
+ * @returns 组列表；每组给出计数、归属包计数与样例标题。
+ */
+export declare function buildGroups(issues: readonly DiagnosticIssue[]): DiagnosticGroup[];
+/**
+ * 官方 ProfileContext 的安装锚点（launcher 之外的上下文没有它）。
+ * @param ctx - host 上下文。
+ * @returns package.json 绝对路径；拿不到时 undefined。
+ */
+export declare function readInstallAnchor(ctx: Context): string | undefined;
+/** patch 文件里一行的原始事实（行号只有读原始文本时才有）。 */
+interface RawRow {
+    readonly file: string;
+    readonly line: number;
+    readonly id?: string;
+    readonly name?: string;
+    /** 字面量 disabled 状态；条件表达式记 conditional（静态不可判定）。 */
+    readonly disabled: 'true' | 'false' | 'conditional';
+    /** 该行插入到哪个 group id 下（顶层 insert 为 undefined）。 */
+    readonly group?: string;
+}
+/**
+ * 原始文本里的 insert 行定位。
+ *
+ * 这不是 YAML 解析器：语义一律取官方返回值（见 readComposition），
+ * 这里只负责"哪一行、有没有显式 id、字面量上写没写 disabled"。
+ * 做法是按 insert 键的列号推出行缩进，再把该缩进上的列表条目当作一行，
+ * 因此不需要理解 YAML 的类型系统，也不会被条件表达式绊倒。
+ *
+ * @param file - patch 文件的绝对路径。
+ * @returns 按文件顺序排列的原始行；文件不可读时为空数组。
+ */
+export declare function locatePatchRows(file: string): RawRow[];
+/** 词法记号。扫描器只在**代码位置**识别关键字，注释与字符串字面量不参与匹配。 */
+interface Token {
+    readonly kind: 'word' | 'string' | 'punct';
+    readonly value: string;
+    readonly line: number;
+}
+/**
+ * 极简词法扫描：切出 word / string / punct 三类记号，跳过注释。
+ *
+ * 与"正则剥注释"相比的两点改进：字符串字面量内部不会被当成代码
+ * （"from 'x'" 不产生 import），注释里的 new Service(ctx, 'x') 不产生注册。
+ * 已知不做的事：正则字面量不做完整识别（含双斜杠的正则可能被当成注释吞掉），
+ * 模板字面量里的插值不求值。
+ *
+ * @param code - 源码文本。
+ * @returns 按出现顺序排列的记号；行号从 1 起。
+ */
+export declare function tokenize(code: string): Token[];
+/** 一份源码的扫描结果（说明符 + 命名注册，均带行号）。 */
+export interface CodeScan {
+    readonly imports: readonly {
+        readonly spec: string;
+        readonly line: number;
+        readonly kind: ScannedImport['kind'];
+    }[];
+    readonly services: readonly {
+        readonly name: string;
+        readonly line: number;
+    }[];
+    readonly injects: readonly {
+        readonly name: string;
+        readonly line: number;
+    }[];
+    readonly tools: readonly {
+        readonly name: string;
+        readonly line: number;
+    }[];
+    readonly sections: readonly {
+        readonly name: string;
+        readonly line: number;
+    }[];
+    readonly routes: readonly {
+        readonly name: string;
+        readonly line: number;
+    }[];
+}
+/**
+ * 扫描一份 JS/TS 源码：静态与动态 import、re-export、require，
+ * 以及服务、工具、提示词段落、HTTP 路由的命名注册点。
+ *
+ * @param code - 源码文本。
+ * @returns 说明符与注册点，均带行号。
+ */
+export declare function scanCode(code: string): CodeScan;
+/**
+ * 这条裸说明符看起来**可能**是一个真模块名吗（扫描器的输入过滤）。
+ *
+ * 为什么需要它：打包产物会把模板字面量拆成 "字面量 + ${…} 表达式"，字面量部分于是成了
+ * **无插值的反引号字符串**，被词法器当成 string 记号收集，形如 " || token.value === "、
+ * ") {\n  if (next?.kind === "。这些片段被当成说明符后，会给"这个包导入了不存在的依赖"这类
+ * 结论提供假输入（实测：CLI 逃生口路径上 9 条假 missing-import）。
+ *
+ * 判据只做"合法裸说明符"的形状检查：首字符字母或数字，其余字母/数字/._-~/%@+ 或查询串，
+ * 且不含空白与控制字符。npm 包名本来就不允许空白与这些符号，因此被丢弃的必然是打包碎片；
+ * 相对路径与绝对路径走的是另外的分支（由调用方先判），本函数只作用于裸说明符。
+ *
+ * @param spec - 说明符。
+ * @returns 是否可能是模块名（false 表示应当丢弃）。
+ */
+export declare function isPlausibleSpecifier(spec: string): boolean;
+/**
+ * 扫描一个已安装包：入口 → 相对 import 可达文件（有界 BFS）。
+ *
+ * @param pkgDir - 包目录绝对路径。
+ * @param manifest - 该包 package.json 的解析结果。
+ * @param maxFiles - 本次可用的文件预算（逐包递减，来自全局预算）。
+ * @returns 扫描结果；没有可解析入口时给出 reason。
+ */
+export declare function scanPackage(pkgDir: string, manifest: Record<string, unknown>, maxFiles?: number): PackageScan;
+/**
+ * 一个包声明的全部入口文件（exports 的每个子路径 + main + module）。
+ *
+ * 只取一个入口是历史缺陷：DSH 插件常同时带 host/client/worker 多个入口，
+ * 未声明依赖若只出现在 exports["./server"] 指向的文件里，单入口检查会整条漏过，
+ * 而挂载该子路径的行会让整个 profile 起不来。
+ *
+ * @param pkgDir - 包目录绝对路径。
+ * @param manifest - 该包 package.json 的解析结果。
+ * @returns 去重后仍存在的入口文件路径。
+ */
+export declare function packageEntryFiles(pkgDir: string, manifest: Record<string, unknown>): string[];
+/**
+ * 按 Node 的解析顺序探测相对说明符指向的文件。
+ * @param baseDir - 相对说明符的基准目录。
+ * @param spec - 相对说明符。
+ * @returns 命中文件的绝对路径；都不存在时 undefined。
+ */
+export declare function resolveRelativeFile(baseDir: string, spec: string): string | undefined;
+/**
+ * 安装锚点对应的 Node 解析根：**官方同款口径**。
+ *
+ * 官方 @deepseek-ai/dsh-app-boot/profile.ts 的 packageDirFromAnchor 从锚点走
+ * createRequire(anchor).resolve.paths(packageName)，本函数取同一串搜索路径里
+ * 以 node_modules 结尾的那些（Node 会按顺序往上走：包内 → 安装目录 → 祖先目录）。
+ * 官方包里已经存在的路径不再重复放进来。
+ *
+ * 锚点必须先 realpath：pnpm 的 bin shim 指向全局安装目录下的一个符号链接，
+ * 而 Node 用的是**字面路径**，不 realpath 时那条链上一个官方包都解析不到。
+ *
+ * @param installAnchor - dsh 应用包的 package.json 绝对路径（ProfileContext.installAnchor）。
+ * @returns 解析根（按 Node 的查找顺序）；锚点缺失、读不到或解析不出节点时为 null。
+ */
+export declare function installAnchorRoots(installAnchor: string | undefined): string[] | null;
+/**
+ * 环境的模块解析顺序：profile 层 → 共享兜底层 → Harness home 的 profiles 兜底 → 安装锚点。
+ *
+ * 前三个是 profile 自己的依赖；安装锚点由**安装侧**提供（官方包、bundle 本体与它们携带的
+ * 传递依赖都在这里），缺少它会把官方包的每一行都判成孤儿。
+ *
+ * @param envDir - 环境目录。
+ * @param installAnchor - dsh 应用包的 package.json（可省略）。
+ * @returns 去重后的解析根，按查找优先级排列。
+ */
+export declare function moduleRoots(envDir: string, installAnchor?: string): string[];
+/**
+ * 一个包在某个环境里的安装目录（profile 层优先，其次共享兜底层，最后是安装锚点）。
+ *
+ * 质量门与诊断共用这一套解析顺序，避免两处口径漂移。
+ *
+ * @param envDir - 环境目录。
+ * @param packageName - 包名。
+ * @param installAnchor - dsh 应用包的 package.json；省略时只按 profile 侧解析。
+ * @returns 包目录绝对路径；未安装时 undefined。
+ */
+export declare function installedPackageDir(envDir: string, packageName: string, installAnchor?: string): string | undefined;
+/**
+ * 一个说明符在当前环境里能否解析。
+ *
+ * 判定"能"用两把尺子（任一成立即可）：Node 的真实解析（createRequire）与
+ * 文件/exports 探测；判定"不能"必须两者都不成立——这样 scoped 子路径不会被
+ * 误判为可解析（前身仓库在这一点上有过 Critical 缺陷：只要 @scope/pkg 目录存在，
+ * @scope/pkg 下的任意子路径都返回 true，最后一道兜底检查因此完全失效）。
+ *
+ * @param envDir - 环境目录（解析锚点）。
+ * @param spec - 裸说明符或带子路径的说明符。
+ * @param installAnchor - dsh 应用包的 package.json；省略时只按 profile 侧解析。
+ * @returns 能否解析到模块。
+ */
+export declare function specifierResolves(envDir: string, spec: string, installAnchor?: string): boolean;
+/**
+ * exports 是否声明了某个子路径（支持星号通配）。
+ * @param exportsField - package.json 的 exports 字段。
+ * @param key - 形如 "./sub" 的子路径键。
+ * @returns 是否声明。
+ */
+export declare function exportsDeclaresSubpath(exportsField: unknown, key: string): boolean;
+/**
+ * 简化 semver：判断安装版本是否满足一个范围。
+ *
+ * 支持星号、=、^、~、>、>=、<、<=，空格或逗号连接的合取，以及 || 析取。
+ * prerelease 只参与"基线相同"时的排序（不实现 semver 的 prerelease 全规则），
+ * 因此不会把 0.1.6-alpha.2 这类官方版本误判为不满足。
+ *
+ * @param installed - 实际安装的版本。
+ * @param range - 声明的要求范围。
+ * @returns 是否满足。
+ */
+export declare function satisfiesRange(installed: string, range: string): boolean;
+/**
+ * JSON 文本里某个键所在的行号（证据要能点回 package.json:12）。
+ *
+ * @param text - package.json 的原始文本。
+ * @param section - 顶层段名（dependencies / peerDependencies）；传空串表示全文查找。
+ * @param key - 段内的键。
+ * @returns 1 起的行号；找不到时 undefined。
+ */
+export declare function jsonKeyLine(text: string, section: string, key: string): number | undefined;