weapp-vite 7.4.0 → 7.5.0

package/dist/doctor.mjs

@@ -0,0 +1,848 @@
+import { l as getProjectPlatformOptions, m as resolveMiniPlatform, o as getPlatformOutputExtensions } from "./platform-CnkySBKz.mjs";
+import { i as createAnalyzeBudgetCheck } from "./analyze-ZJUvEdaY.mjs";
+import { n as classifyPackage, t as version } from "./package-7swhyLmf.mjs";
+import { n as parseObject, r as readDoctorFiles, t as objectValue } from "./files-BqxFIPRp.mjs";
+import process from "node:process";
+import { constants } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path, { posix } from "node:path";
+import { parseJsLike, traverse } from "@weapp-vite/ast/babel";
+import { access, readFile, stat } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { Parser } from "htmlparser2";
+import postcss from "postcss";
+import valueParser from "postcss-value-parser";
+import { fork } from "node:child_process";
+import { connectOpenedAutomator, queryWechatIdeLogin, resolveProjectAutomatorPort } from "weapp-ide-cli";
+import { createConnection } from "node:net";
+import { miniProgramRuntimePlugin, wevuCompatibilityPlugin } from "@weapp-vite/eslint";
+import tsParser from "@typescript-eslint/parser";
+import { Linter } from "eslint";
+import vueParser from "vue-eslint-parser";
+import { OperationLifecycle, classifyOperationError } from "@weapp-vite/miniprogram-automator";
+//#region src/doctor/report.ts
+function addDiagnostic(report, diagnostic) {
+	const fingerprint = createHash("sha256").update(JSON.stringify([
+		diagnostic.ruleId,
+		diagnostic.target,
+		diagnostic.layer,
+		diagnostic.location,
+		diagnostic.evidence
+	])).digest("hex");
+	if (!report.diagnostics.some((item) => item.fingerprint === fingerprint)) report.diagnostics.push({
+		...diagnostic,
+		fingerprint
+	});
+}
+function finishReport(report) {
+	report.diagnostics.sort((a, b) => a.fingerprint.localeCompare(b.fingerprint));
+	report.exitCode = report.coverage.some((item) => item.status === "incomplete") ? 2 : report.diagnostics.some((item) => item.severity === "error") ? 1 : 0;
+	return report;
+}
+function formatDoctorReport(report, format = "terminal") {
+	if (format === "json") return JSON.stringify(report, null, 2);
+	if (format === "sarif") return JSON.stringify({
+		$schema: "https://json.schemastore.org/sarif-2.1.0.json",
+		version: "2.1.0",
+		runs: [{
+			tool: { driver: {
+				name: "weapp-vite doctor",
+				rules: [...new Set(report.diagnostics.map((d) => d.ruleId))].map((id) => ({ id }))
+			} },
+			invocations: [{ executionSuccessful: report.exitCode !== 2 }],
+			properties: {
+				coverage: report.coverage,
+				exitCode: report.exitCode,
+				artifacts: report.artifacts,
+				runtime: report.runtime
+			},
+			results: report.diagnostics.map((d) => ({
+				ruleId: d.ruleId,
+				level: d.severity,
+				message: { text: d.message },
+				partialFingerprints: { "doctor/v1": d.fingerprint },
+				locations: d.location ? [{ physicalLocation: {
+					artifactLocation: { uri: d.location.file.split("/").map(encodeURIComponent).join("/") },
+					region: d.location.line ? {
+						startLine: d.location.line,
+						startColumn: d.location.column ?? 1
+					} : void 0
+				} }] : [],
+				properties: {
+					target: d.target,
+					layer: d.layer,
+					evidence: d.evidence,
+					responsibility: d.responsibility,
+					suggestion: d.suggestion
+				}
+			}))
+		}]
+	}, null, 2);
+	return [
+		`Doctor: exit ${report.exitCode}`,
+		...report.coverage.map((c) => `[${c.target}] ${c.layer}/${c.check}: ${c.status}${c.reason ? ` — ${c.reason}` : ""}`),
+		...Object.entries(report.runtime).flatMap(([target, evidence]) => evidence.bundle ? [
+			`[${target}] framework=${evidence.bundle.frameworkVersion} node=${evidence.bundle.nodeVersion} IDE=${evidence.bundle.versions.ide ?? "unknown"} SDK=${evidence.bundle.versions.sdk ?? "unknown"}`,
+			`最后成功阶段：${evidence.bundle.lastSuccessfulStage ?? "unknown"}`,
+			`复现：${evidence.bundle.reproduction}`
+		] : []),
+		...report.diagnostics.map((d) => `[${d.severity}] ${d.target} ${d.ruleId} ${d.location?.file ?? ""} ${d.message}\n  ${d.suggestion}`)
+	].join("\n");
+}
+//#endregion
+//#region src/doctor/source.ts
+function checkDoctorScripts(report, target, files, layer) {
+	const linter = new Linter();
+	let incomplete = false;
+	const eligible = files.filter((file) => layer === "artifact" ? /\.js$/.test(file.path) : /\.(?:[cm]?[jt]sx?|vue)$/.test(file.path) && !/(?:^|\/)(?:scripts|generated|node_modules)\/|\.web\.|(?:^|\/)node\.|\.(?:test|spec)\.|\.d\.[cm]?ts$/.test(file.path));
+	for (const file of eligible) {
+		const messages = linter.verify(file.text ?? "", {
+			files: ["**/*.{js,mjs,cjs,jsx,ts,mts,cts,tsx,vue}"],
+			languageOptions: {
+				parser: file.path.endsWith(".vue") ? vueParser : tsParser,
+				parserOptions: {
+					parser: tsParser,
+					ecmaVersion: "latest",
+					sourceType: "module",
+					ecmaFeatures: { jsx: true }
+				}
+			},
+			plugins: {
+				"mini-program": miniProgramRuntimePlugin,
+				"wevu": wevuCompatibilityPlugin
+			},
+			rules: {
+				"no-eval": "error",
+				"no-new-func": "error",
+				...target === "weapp" ? {
+					"mini-program/no-unsupported-runtime-api": layer === "artifact" ? "error" : "warn",
+					"mini-program/no-implicit-runtime-polyfill": "warn"
+				} : {},
+				...layer === "source" ? {
+					"wevu/no-unsupported-api": "warn",
+					"wevu/no-risky-api": "warn",
+					"wevu/no-unsupported-template-feature": "warn"
+				} : {}
+			}
+		}, { filename: file.path });
+		for (const message of messages) {
+			if (message.fatal) incomplete = true;
+			addDiagnostic(report, {
+				ruleId: `doctor/${layer}/${message.ruleId ?? "parse"}`,
+				layer,
+				target,
+				severity: message.severity === 2 ? "error" : "warning",
+				message: message.message,
+				location: {
+					file: file.path,
+					line: message.line,
+					column: message.column
+				},
+				evidence: {
+					expected: "可解析且符合所选执行域的静态契约",
+					actual: message.message
+				},
+				responsibility: {
+					owner: "unknown",
+					confidence: layer === "source" ? "suspected" : "confirmed"
+				},
+				suggestion: layer === "source" ? "核对编译转换与兼容层，再检查最终产物；源码风险不等同于宿主失败。" : "定位对应源码及构建插件，保留最小复现并在目标宿主验证。"
+			});
+		}
+	}
+	report.coverage.push({
+		target,
+		layer,
+		check: "script-syntax-and-static-risks",
+		status: incomplete ? "incomplete" : "complete",
+		reason: `检查 ${eligible.length} 个脚本；不推断动态类型或将静态扫描等同于完整运行正确性。`
+	});
+	if (target !== "weapp") report.coverage.push({
+		target,
+		layer,
+		check: "host-api-baseline",
+		status: "incomplete",
+		reason: "所选平台尚无可复用的完整 API 基线；未套用微信规则。"
+	});
+}
+function incompleteCoverage(report, target, layer, check, reason) {
+	report.coverage.push({
+		target,
+		layer,
+		check,
+		status: "incomplete",
+		reason
+	});
+}
+//#endregion
+//#region src/doctor/references.ts
+function checkArtifactReferences(report, target, snapshot, classifier) {
+	const files = new Set(snapshot.files.map((file) => file.path));
+	const ext = getPlatformOutputExtensions(target);
+	const reference = (owner, specifier, script = false) => {
+		if (/^[a-z]+:\/\//i.test(specifier) || specifier.includes("{{")) {
+			incompleteCoverage(report, target, "artifact", "references", "动态或外部引用不能由本地静态快照验证。");
+			return;
+		}
+		const base = posix.normalize(specifier.startsWith("/") ? specifier.slice(1) : posix.join(posix.dirname(owner), specifier));
+		const found = (script ? [
+			base,
+			`${base}.js`,
+			`${base}.json`,
+			`${base}/index.js`
+		] : [base]).find((candidate) => files.has(candidate));
+		const from = classifyPackage(owner, "main", classifier);
+		const to = found && classifyPackage(found, "main", classifier);
+		const crosses = to && (from.type === "independent" && from.id !== to.id || to.type !== "main" && from.id !== to.id);
+		if (!found || crosses) addDiagnostic(report, {
+			ruleId: `doctor/artifact/${crosses ? "package-import" : "missing-import"}`,
+			target,
+			layer: "artifact",
+			severity: "error",
+			message: crosses ? "产物引用跨越包边界" : "产物引用指向不存在的文件",
+			location: { file: owner },
+			evidence: {
+				expected: "引用可在所属包及允许的依赖范围内解析",
+				actual: specifier
+			},
+			responsibility: {
+				owner: "unknown",
+				confidence: "confirmed"
+			},
+			suggestion: "检查最终产物路径、native npm 输出目录及独立分包归属；不要只修改源码导入规避编译器问题。"
+		});
+	};
+	for (const file of snapshot.files) {
+		if (file.text === void 0) continue;
+		try {
+			if (file.path.endsWith(`.${ext.js}`)) {
+				const ast = parseJsLike(file.text);
+				traverse(ast, {
+					ImportDeclaration(p) {
+						reference(file.path, p.node.source.value, true);
+					},
+					ExportNamedDeclaration(p) {
+						if (p.node.source) reference(file.path, p.node.source.value, true);
+					},
+					ExportAllDeclaration(p) {
+						reference(file.path, p.node.source.value, true);
+					},
+					CallExpression(p) {
+						if (!p.get("callee").isIdentifier({ name: "require" }) || p.scope.getBinding("require")) return;
+						const arg = p.node.arguments[0];
+						if (arg?.type === "StringLiteral") reference(file.path, arg.value, true);
+						else incompleteCoverage(report, target, "artifact", "dynamic-import", "动态 require 无法由静态快照解析。");
+					}
+				});
+			} else if (file.path.endsWith(`.${ext.wxml}`)) new Parser({ onopentag(name, attributes) {
+				if ([
+					"import",
+					"include",
+					"wxs",
+					"sjs",
+					"import-sjs"
+				].includes(name) && attributes.src) reference(file.path, attributes.src);
+			} }, { xmlMode: true }).end(file.text);
+			else if (file.path.endsWith(`.${ext.wxss}`)) postcss.parse(file.text).walkAtRules("import", (rule) => {
+				const first = valueParser(rule.params).nodes[0];
+				const value = first?.type === "string" ? first.value : void 0;
+				if (value) reference(file.path, value);
+				else incompleteCoverage(report, target, "artifact", "style-import", "非字符串样式导入需要目标宿主或适配器验证。");
+			});
+		} catch {
+			incompleteCoverage(report, target, "artifact", "reference-parse", "产物无法解析，未将引用图视为完整。");
+		}
+	}
+	report.coverage.push({
+		target,
+		layer: "artifact",
+		check: "static-references",
+		status: "complete",
+		reason: "覆盖静态脚本、模板和样式引用；动态/外部引用另记 incomplete。"
+	});
+}
+//#endregion
+//#region src/doctor/artifact.ts
+function checkDoctorArtifact(report, target, snapshot) {
+	const files = new Map(snapshot.files.map((file) => [file.path, file]));
+	const ext = getPlatformOutputExtensions(target);
+	const fail = (rule, file, expected, actual) => addDiagnostic(report, {
+		ruleId: `doctor/artifact/${rule}`,
+		target,
+		layer: "artifact",
+		severity: "error",
+		message: `${file}: ${expected}`,
+		location: { file },
+		evidence: {
+			expected,
+			actual
+		},
+		responsibility: {
+			owner: "unknown",
+			confidence: "confirmed"
+		},
+		suggestion: "比较来源声明和最终编译产物，确定配置、插件或编译器责任后补充最小回归。"
+	});
+	const readJson = (file) => {
+		try {
+			return parseObject(files.get(file)?.text);
+		} catch {
+			fail("json", file, "存在合法的 JSON 对象", files.has(file) ? "无法解析 JSON 对象" : "文件缺失");
+			return;
+		}
+	};
+	const app = readJson("app.json");
+	if (!app) {
+		incompleteCoverage(report, target, "artifact", "reachable-graph", "app.json 不可读，无法遍历页面图。");
+		return;
+	}
+	if (!files.has(`app.${ext.js}`)) fail("entry-file", `app.${ext.js}`, "应用入口脚本存在", "文件缺失");
+	const packages = Array.isArray(app.subPackages ?? app.subpackages) ? app.subPackages ?? app.subpackages : [];
+	if ((app.subPackages ?? app.subpackages) !== void 0 && !Array.isArray(app.subPackages ?? app.subpackages)) fail("subpackage", "app.json", "subPackages 为数组", "非法分包声明");
+	const subPackageRoots = /* @__PURE__ */ new Set();
+	const independentRoots = /* @__PURE__ */ new Set();
+	const pages = [];
+	const addPages = (value, root = "") => {
+		if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+			fail("pages", "app.json", "pages 为字符串数组", "页面列表缺失或类型错误");
+			return;
+		}
+		for (const item of value) pages.push(root ? `${root}/${item}` : item);
+	};
+	addPages(app.pages);
+	for (const value of packages) {
+		const pkg = objectValue(value);
+		if (!pkg || typeof pkg.root !== "string" || !pkg.root || posix.normalize(pkg.root) !== pkg.root || /^[./]/.test(pkg.root)) {
+			fail("subpackage", "app.json", "分包 root 为规范的相对路径", "非法分包声明");
+			continue;
+		}
+		subPackageRoots.add(pkg.root);
+		if (pkg.independent === true) independentRoots.add(pkg.root);
+		addPages(pkg.pages, pkg.root);
+	}
+	const classifier = {
+		subPackageRoots,
+		independentRoots
+	};
+	const checked = /* @__PURE__ */ new Set();
+	const queued = pages.map((base) => ({
+		base,
+		component: false
+	}));
+	const resolveReference = (owner, reference) => posix.normalize(reference.startsWith("/") ? reference.slice(1) : posix.join(posix.dirname(owner), reference));
+	const checkComponents = (owner, config) => {
+		const components = objectValue(config.usingComponents);
+		if (config.usingComponents !== void 0 && !components) fail("components", owner, "usingComponents 为路径映射", "非法组件映射");
+		for (const [name, value] of Object.entries(components ?? {})) {
+			if (typeof value !== "string") {
+				fail("components", owner, "组件引用为字符串", name);
+				continue;
+			}
+			if (/^[a-z]+:\/\//i.test(value)) {
+				incompleteCoverage(report, target, "artifact", "external-component", "外部插件组件不在本地产物快照中。");
+				continue;
+			}
+			const base = resolveReference(owner, value);
+			const from = classifyPackage(owner, "main", classifier);
+			const to = classifyPackage(base, "main", classifier);
+			if (from.type === "independent" && from.id !== to.id || to.type !== "main" && from.id !== to.id) fail("package-boundary", owner, "组件引用不跨越独立包或其他分包边界", base);
+			queued.push({
+				base,
+				component: true
+			});
+		}
+	};
+	checkComponents("app.json", app);
+	while (queued.length) {
+		const { base, component } = queued.shift();
+		if (base.startsWith("../") || base.startsWith("/") || posix.normalize(base) !== base) {
+			fail("path", "app.json", "引用位于产物根目录内且已规范化", base);
+			continue;
+		}
+		if (checked.has(base)) continue;
+		checked.add(base);
+		for (const extension of [
+			ext.js,
+			ext.json,
+			ext.wxml
+		]) if (!files.has(`${base}.${extension}`)) fail("entry-file", `${base}.${extension}`, "页面/组件的宿主必需文件存在", "文件缺失");
+		const config = readJson(`${base}.${ext.json}`);
+		if (config) {
+			if (component && config.component !== true) fail("component-flag", `${base}.${ext.json}`, "被引用的组件声明 component: true", "未声明组件");
+			checkComponents(`${base}.${ext.json}`, config);
+		}
+	}
+	if (typeof app.workers === "string" && !snapshot.files.some((file) => file.path.startsWith(`${app.workers}/`) && file.path.endsWith(ext.js))) fail("worker-root", "app.json", "workers 目录内有脚本产物", app.workers);
+	const packageMap = /* @__PURE__ */ new Map();
+	for (const file of snapshot.files) {
+		const pkg = classifyPackage(file.path, "main", classifier);
+		const current = packageMap.get(pkg.id) ?? {
+			...pkg,
+			files: []
+		};
+		current.files.push({
+			file: file.path,
+			size: file.size,
+			type: file.path.endsWith(ext.js) ? "chunk" : "asset",
+			from: "main"
+		});
+		packageMap.set(pkg.id, current);
+	}
+	if (snapshot.budgets) {
+		for (const item of createAnalyzeBudgetCheck({
+			packages: [...packageMap.values()],
+			metadata: {
+				generatedAt: snapshot.capturedAt,
+				budgets: snapshot.budgets,
+				history: {
+					enabled: false,
+					dir: "",
+					limit: 0
+				}
+			}
+		})) if (item.status === "exceeded") fail("budget", item.id, `包体不超过 ${item.limitBytes} 字节`, `${item.currentBytes} 字节`);
+	} else incompleteCoverage(report, target, "artifact", "budgets", "复用目录未提供编译器实际预算；不套用其他平台默认预算。");
+	report.coverage.push({
+		target,
+		layer: "artifact",
+		check: "pages-components-packages-workers",
+		status: "complete"
+	});
+	checkArtifactReferences(report, target, snapshot, classifier);
+	checkDoctorScripts(report, target, snapshot.files, "artifact");
+}
+//#endregion
+//#region src/doctor/build.ts
+/** 将显式构建隔离到子进程，避免全局编译上下文和插件日志污染并发 API/JSON 输出。 */
+async function buildDoctorSnapshot(options, target) {
+	const worker = path.join(path.dirname(fileURLToPath(import.meta.resolve("weapp-vite/package.json"))), "dist/doctor-worker.mjs");
+	return new Promise((resolve, reject) => {
+		const child = fork(worker, [], {
+			cwd: options.cwd,
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe",
+				"ipc"
+			],
+			execArgv: []
+		});
+		let result;
+		const timer = setTimeout(() => {
+			child.kill();
+			reject(/* @__PURE__ */ new Error("Doctor 构建超时"));
+		}, 18e4);
+		child.stdout?.on("data", (chunk) => options.onBuildLog?.(String(chunk)));
+		child.stderr?.on("data", (chunk) => options.onBuildLog?.(String(chunk)));
+		child.on("message", (message) => {
+			result = message.snapshot;
+		});
+		child.on("error", (error) => {
+			clearTimeout(timer);
+			reject(error);
+		});
+		child.on("close", (code) => {
+			clearTimeout(timer);
+			if (code === 0 && result) resolve(result);
+			else reject(/* @__PURE__ */ new Error("Doctor 构建未完成"));
+		});
+		child.send({
+			cwd: options.cwd,
+			configFile: options.configFile,
+			target
+		});
+	});
+}
+//#endregion
+//#region src/doctor/runtimeProbes.ts
+/** 仅检查文件及平台执行条件，不执行 CLI 或项目配置。 */
+async function inspectDoctorCli(cliPath) {
+	try {
+		if (!(await stat(cliPath)).isFile()) return false;
+		if (process.platform === "win32" && ![
+			".exe",
+			".cmd",
+			".bat",
+			".com"
+		].includes(path.extname(cliPath).toLowerCase())) return false;
+		await access(cliPath, process.platform === "win32" ? constants.F_OK : constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/** TCP 可达只证明监听存在，不证明宿主身份；仅销毁本次创建的 socket。 */
+async function inspectDoctorListener(port, signal) {
+	if (!Number.isInteger(port) || port < 1 || port > 65535) return "invalid-port";
+	signal?.throwIfAborted();
+	return new Promise((resolve) => {
+		let abort;
+		const socket = createConnection({
+			host: "127.0.0.1",
+			port
+		});
+		let settled = false;
+		function finish(result) {
+			if (!settled) {
+				settled = true;
+				signal?.removeEventListener("abort", abort);
+				socket.destroy();
+				resolve(result);
+			}
+		}
+		abort = () => finish("timeout");
+		signal?.addEventListener("abort", abort, { once: true });
+		socket.setTimeout(1e3, () => finish("timeout"));
+		socket.once("connect", () => finish("listening"));
+		socket.once("error", (error) => finish(error.code === "ECONNREFUSED" ? "not-listening" : "unavailable"));
+	});
+}
+/** 宿主版本只保留数值版本，不透传任意 Tool.getInfo 字段。 */
+function readDoctorHostVersions(info) {
+	if (!info || typeof info !== "object") return {};
+	const version = (value) => typeof value === "string" && value.length <= 64 && /^\d+(?:\.\d+){1,3}$/.test(value) ? value : void 0;
+	return {
+		ide: version("version" in info ? info.version : void 0),
+		sdk: version("SDKVersion" in info ? info.SDKVersion : void 0)
+	};
+}
+/** 页面查询参数可能包含业务凭据，只保留相对逻辑路由。 */
+function readDoctorRoute(value) {
+	if (typeof value !== "string") return;
+	const route = value.split(/[?#]/, 1)[0];
+	if (!route || route.startsWith("/") || route.length > 256 || route.includes("..") || /[\\:\s]/.test(route)) return;
+	return route;
+}
+//#endregion
+//#region src/doctor/runtime.ts
+const stages = [
+	"cli-executable",
+	"service-listener",
+	"login-query",
+	"login-state",
+	"project-connection",
+	"tool-info",
+	"host-version",
+	"sdk-version",
+	"current-page",
+	"session-release"
+];
+/** 每个探针保留局部上限，并受同一个总 deadline 约束。 */
+async function probeStep(scope, stage, cap, run, disposeLate) {
+	const phase = new OperationLifecycle(scope.remainingMs(cap), stage, scope.signal);
+	return await scope.step(() => phase.run(() => phase.step(() => run(phase.signal, phase.remainingMs()), {
+		stage,
+		disposeLate
+	})), { stage });
+}
+/** 默认只连接已有项目；原生登录查询单独显式授权，不改变路由或业务状态。 */
+async function probeDoctorRuntime(cwd, target, port, options = {}) {
+	const scope = new OperationLifecycle(options.timeout ?? 1e4, "Doctor runtime", options.signal);
+	let finalized = false;
+	const facts = stages.map((stage) => ({
+		stage,
+		status: "not-run",
+		code: "not-requested"
+	}));
+	const events = [];
+	const provider = target === "weapp" ? "devtools" : "unsupported";
+	const bundle = {
+		frameworkVersion: version,
+		nodeVersion: process.version,
+		versions: {},
+		configuration: {
+			target,
+			provider,
+			explicitCli: !!options.cliPath,
+			explicitAutomatorPort: port !== void 0,
+			explicitServicePort: options.servicePort !== void 0,
+			loginRequested: options.login === true
+		},
+		lastSuccessfulStage: void 0,
+		events,
+		operation: scope.diagnostics,
+		reproduction: `wv doctor --runtime --platform ${target} --format json${port !== void 0 ? " --runtime-port <automator-port>" : ""}${options.cliPath ? " --runtime-cli <selected-cli>" : ""}${options.servicePort !== void 0 ? " --runtime-service-port <service-port>" : ""}${options.login ? " --runtime-login" : ""}`
+	};
+	const evidence = {
+		host: "unknown",
+		route: "",
+		provider,
+		checks: [],
+		facts,
+		bundle,
+		complete: false
+	};
+	const record = (stage, status, code) => {
+		if (finalized) return;
+		const fact = {
+			stage,
+			status,
+			code
+		};
+		facts[stages.indexOf(stage)] = fact;
+		events.push(fact);
+		if (status === "passed" && stage !== "session-release") bundle.lastSuccessfulStage = stage;
+	};
+	if (target !== "weapp") {
+		record("project-connection", "unknown", "unsupported-host");
+		return evidence;
+	}
+	if (port !== void 0 && (!Number.isInteger(port) || port < 1 || port > 65535)) {
+		record("project-connection", "failed", "invalid-port");
+		return evidence;
+	}
+	try {
+		return await scope.run(async () => {
+			scope.attempt();
+			let executable = false;
+			if (options.cliPath) {
+				executable = await probeStep(scope, "cli-executable", 1e3, () => inspectDoctorCli(options.cliPath));
+				record("cli-executable", executable ? "passed" : "failed", executable ? "executable" : "not-executable");
+			}
+			if (options.servicePort !== void 0) {
+				const result = await probeStep(scope, "service-listener", 1e3, (signal) => inspectDoctorListener(options.servicePort, signal));
+				record("service-listener", result === "listening" ? "passed" : result === "not-listening" || result === "invalid-port" ? "failed" : "unknown", result);
+			}
+			if (options.login) {
+				if (!executable || !options.cliPath) {
+					record("login-query", "not-run", "explicit-executable-required");
+					record("login-state", "unknown", "query-not-run");
+				} else {
+					const result = await probeStep(scope, "login-query", 3e3, (signal, timeout) => queryWechatIdeLogin(options.cliPath, {
+						timeout,
+						signal
+					}));
+					record("login-query", result.status === "success" ? "passed" : "unknown", result.status === "success" ? "response-received" : result.reason);
+					record("login-state", result.status === "success" ? result.login ? "passed" : "failed" : "unknown", result.status === "success" ? result.login ? "logged-in" : "logged-out" : "query-incomplete");
+				}
+			}
+			let session;
+			try {
+				session = await probeStep(scope, "project-connection", 3e3, async (signal, timeout) => await connectOpenedAutomator({
+					projectPath: cwd,
+					cliPath: options.cliPath,
+					port: port ?? resolveProjectAutomatorPort(cwd),
+					timeout,
+					signal
+				}), (session) => session.disconnect());
+				record("project-connection", "passed", "connected");
+			} catch (error) {
+				record("project-connection", "failed", classifyOperationError(error) === "timeout" ? "timeout" : "connection-failed");
+				for (const stage of [
+					"tool-info",
+					"host-version",
+					"sdk-version",
+					"current-page"
+				]) record(stage, "not-run", "connection-unavailable");
+				return evidence;
+			}
+			let released = false;
+			const release = () => {
+				if (released) return;
+				released = true;
+				try {
+					session.disconnect();
+					record("session-release", "passed", "disconnected");
+				} catch {
+					record("session-release", "failed", "disconnect-failed");
+				}
+			};
+			scope.own(release, "doctor-websocket");
+			const checks = [];
+			const read = async (stage, check, operation, accept) => {
+				checks.push(check);
+				try {
+					const valid = accept(await probeStep(scope, stage, 5e3, operation));
+					record(stage, valid ? "passed" : "failed", valid ? "snapshot-read" : "invalid-response");
+				} catch (error) {
+					record(stage, "failed", classifyOperationError(error) === "timeout" ? "timeout" : "rpc-failed");
+				}
+			};
+			try {
+				await Promise.all([read("tool-info", "Tool.getInfo", () => session.toolInfo(), (info) => {
+					if (!info || typeof info !== "object") return false;
+					evidence.host = "wechat-devtools";
+					bundle.versions = readDoctorHostVersions(info);
+					record("host-version", bundle.versions.ide ? "passed" : "unknown", bundle.versions.ide ? "version-read" : "version-unavailable");
+					record("sdk-version", bundle.versions.sdk ? "passed" : "unknown", bundle.versions.sdk ? "version-read" : "version-unavailable");
+					return true;
+				}), read("current-page", "App.getCurrentPage", () => session.currentPage(), (page) => {
+					const route = readDoctorRoute(page?.path);
+					if (!route) return false;
+					evidence.route = route;
+					return true;
+				})]);
+			} finally {
+				release();
+			}
+			for (const stage of ["host-version", "sdk-version"]) if (facts.find((fact) => fact.stage === stage)?.status === "not-run") record(stage, "unknown", "tool-info-unavailable");
+			evidence.checks = checks;
+			evidence.complete = facts.every((fact) => fact.status === "passed" || fact.status === "not-run");
+			return evidence;
+		});
+	} catch (error) {
+		record(stages.includes(scope.diagnostics.stage) ? scope.diagnostics.stage : "project-connection", "failed", classifyOperationError(error));
+		evidence.complete = false;
+		return evidence;
+	} finally {
+		bundle.operation = scope.diagnostics;
+		finalized = true;
+	}
+}
+//#endregion
+//#region src/doctor/runtimeReport.ts
+const suggestions = {
+	"cli-executable": "确认所选 CLI 是可执行文件；不会自动回退到其他安装。",
+	"service-listener": "核对所选安装的服务端口与监听状态；TCP 可达不能证明监听者身份。",
+	"login-query": "确认所选 CLI 可响应查询；未知结果不能推断未登录。",
+	"login-state": "仅在原生查询明确未登录时完成正常登录；其他情况先排查查询链路。",
+	"project-connection": "确认目标项目已有可连接的 automator 会话及正确端口，不清理其他项目。",
+	"tool-info": "确认目标项目工具协议可用；缺失版本不能归因于编译器。",
+	"host-version": "从实际连接宿主取得 IDE 版本，不用 CLI 路径或历史记录代替。",
+	"sdk-version": "从实际宿主取得基础库版本，不将项目配置值视为实际运行版本。",
+	"current-page": "确认目标项目已打开有效页面；页面快照不代替应用功能 E2E。",
+	"session-release": "保留环境现场并检查本次 websocket 释放，不终止共享 IDE。"
+};
+/** 部分失败保留已有事实，按稳定阶段诊断输出；不推断平台或框架责任。 */
+function appendDoctorRuntimeEvidence(report, target, evidence) {
+	report.runtime[target] = evidence;
+	const incomplete = evidence.complete === false || evidence.facts?.some((fact) => fact.status === "failed" || fact.status === "unknown");
+	report.coverage.push({
+		target,
+		layer: "runtime",
+		check: "connected-page-snapshot",
+		status: incomplete ? "incomplete" : "complete",
+		reason: incomplete ? "请求的宿主探针没有全部完成，已保留部分事实。" : "仅证明请求的工具信息和当前页面可读取；不代表完整应用功能验收。"
+	});
+	for (const fact of evidence.facts ?? []) {
+		report.coverage.push({
+			target,
+			layer: "runtime",
+			check: fact.stage,
+			status: fact.status === "passed" ? "complete" : fact.status === "not-run" && fact.code === "not-requested" ? "not-requested" : "incomplete",
+			reason: fact.code
+		});
+		if (fact.status === "failed" || fact.status === "unknown") addDiagnostic(report, {
+			ruleId: `doctor/runtime/${fact.stage}`,
+			target,
+			layer: "runtime",
+			severity: "warning",
+			message: `宿主探针 ${fact.stage}：${fact.code}`,
+			evidence: {
+				expected: "取得该阶段明确事实",
+				actual: fact.code
+			},
+			responsibility: {
+				owner: "unknown",
+				confidence: "suspected"
+			},
+			suggestion: suggestions[fact.stage]
+		});
+	}
+}
+//#endregion
+//#region src/doctor/index.ts
+/** 分层收集事实；静态路径永不调用配置加载器、构建或宿主连接。 */
+async function runDoctor(options = {}, adapters = {}) {
+	const cwd = path.resolve(options.cwd ?? process.cwd());
+	const report = {
+		schemaVersion: 1,
+		generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		targets: [...new Set(options.targets ?? ["weapp"])],
+		coverage: [],
+		diagnostics: [],
+		artifacts: {},
+		runtime: {},
+		exitCode: 0
+	};
+	for (const requested of report.targets) {
+		const target = resolveMiniPlatform(requested);
+		if (!target) {
+			incompleteCoverage(report, requested, "project", "target", "当前编译器没有注册该目标。");
+			continue;
+		}
+		const configName = getProjectPlatformOptions(target).projectConfigFileName;
+		for (const file of ["package.json", configName]) try {
+			parseObject(await readFile(path.join(cwd, file), "utf8"));
+			report.coverage.push({
+				target,
+				layer: "project",
+				check: file,
+				status: "complete",
+				reason: "只读 JSON 结构；未执行项目配置或插件。"
+			});
+		} catch {
+			incompleteCoverage(report, target, "project", file, "文件缺失、不可读或不是合法 JSON 对象。");
+		}
+		let sourceRoot = options.source;
+		if (options.build && options.artifact) incompleteCoverage(report, target, "artifact", "selection", "build 与 artifact 不能同时选择。");
+		else if (options.build || options.artifact) try {
+			const snapshot = options.build ? await (adapters.build ?? buildDoctorSnapshot)({
+				...options,
+				cwd
+			}, target) : {
+				files: await readDoctorFiles(path.resolve(cwd, options.artifact)),
+				origin: "existing",
+				capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				freshness: "unverified"
+			};
+			report.artifacts[target] = {
+				...snapshot,
+				files: snapshot.files.map(({ text: _text, ...file }) => file)
+			};
+			sourceRoot ??= snapshot.sourceRoot;
+			for (const limitation of snapshot.limitations ?? []) incompleteCoverage(report, target, "artifact", "compiler-scope", limitation);
+			checkDoctorArtifact(report, target, snapshot);
+		} catch {
+			incompleteCoverage(report, target, "artifact", "collection", "构建或最终产物快照失败；没有采用旧产物作为本轮通过证据。");
+		}
+		else report.coverage.push({
+			target,
+			layer: "artifact",
+			check: "collection",
+			status: "not-requested"
+		});
+		try {
+			checkDoctorScripts(report, target, await readDoctorFiles(path.resolve(cwd, sourceRoot ?? "src"), true), "source");
+		} catch {
+			incompleteCoverage(report, target, "source", "scan", "源码目录无法完整读取；可用 source 显式指定目录。");
+		}
+		if (options.runtime) try {
+			const probe = adapters.runtime ?? probeDoctorRuntime;
+			appendDoctorRuntimeEvidence(report, target, options.runtimeCliPath !== void 0 || options.runtimeLogin !== void 0 || options.runtimeServicePort !== void 0 ? await probe(cwd, target, options.runtimePort, {
+				cliPath: options.runtimeCliPath,
+				login: options.runtimeLogin,
+				servicePort: options.runtimeServicePort
+			}) : await probe(cwd, target, options.runtimePort));
+		} catch {
+			incompleteCoverage(report, target, "runtime", "connected-page-snapshot", "没有可连接的受支持宿主或探针执行失败；请先打开目标项目并启用服务端口。");
+		}
+		else report.coverage.push({
+			target,
+			layer: "runtime",
+			check: "connected-page-snapshot",
+			status: "not-requested"
+		});
+	}
+	if (!report.targets.length) incompleteCoverage(report, "unknown", "project", "target", "至少需要一个注册目标。");
+	if (!options.runtime && (options.runtimeCliPath !== void 0 || options.runtimeLogin || options.runtimeServicePort !== void 0)) incompleteCoverage(report, "all", "runtime", "selection", "宿主检查选项需要显式 runtime；本轮未执行宿主操作。");
+	if (options.build && options.artifact) addDiagnostic(report, {
+		ruleId: "doctor/options",
+		target: "all",
+		layer: "project",
+		severity: "error",
+		message: "build 与 artifact 不能同时选择",
+		evidence: {
+			expected: "一个产物来源",
+			actual: "两个产物来源"
+		},
+		responsibility: {
+			owner: "project",
+			confidence: "confirmed"
+		},
+		suggestion: "选择重新构建或复用目录。"
+	});
+	return finishReport(report);
+}
+//#endregion
+export { formatDoctorReport, runDoctor };