dsh-composition-doctor 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.2.0
+
+- Release the verified 0.2.0 package without changing the established diagnostic architecture or evidence boundaries.
+
+## 0.1.3
+
+- Hardened the release package contract with the `dsh-doctor` binary entry.
+- Added packed-package verification coverage and documented scan exit-code thresholds.
+- Hardened npm artifact cache writes with integrity metadata and atomic temporary-file publication.
+- Reject unsafe tar paths and link entries before reading package metadata.
+- Kept DSH compatibility verified only for `0.1.5-rc.1` and `0.1.5-rc.2`; `0.1.6-alpha.1` remains expected-compatible only.
+- Runtime smoke remains `not-run` unless a trusted OS-level isolation backend is available.
+- Two Windows symlink regressions may remain `skipped` when the test process cannot create file symlinks; this is not a compatibility PASS.
+- `0.1.6-alpha.1` is experimental/expected-compatible and is not part of the verified release range.
+- A temporary directory is not a security sandbox; no runtime safety claim is made from temporary-directory execution.

package/README.md

@@ -1,12 +1,14 @@
 # dsh-composition-doctor
 
 [![npm version](https://img.shields.io/npm/v/dsh-composition-doctor)](https://www.npmjs.com/package/dsh-composition-doctor)
-[![CI](https://github.com/lemonxiny55/dsh-composition-doctor/actions/workflows/ci.yml/badge.svg)](https://github.com/lemonxiny55/dsh-composition-doctor/actions)
+[![CI](https://github.com/lemonxiny55/dsh-composition-doctor/actions/workflows/ci.yml/badge.svg)](https://github.com/lemonxiny55/dsh-composition-doctor/actions/workflows/ci.yml)
 
 English | [中文](README.zh.md)
 
 Composition and upgrade preflight doctor for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`). It reads an explicitly selected profile and explains observable Cordis/plugin composition risks with concrete evidence. It never edits a real profile or silently changes permissions.
 
+Current package release: `0.2.0`.
+
 ## What the model gets
 
 | Command | Purpose |
@@ -18,33 +20,45 @@ Composition and upgrade preflight doctor for [DeepSeek Harness](https://github.c
 
 The Web Settings page is display/export only: it reads the latest local report, shows a conflict graph, and exports JSON/Markdown. It has no repair, install, or uninstall action.
 
+## Reports and evidence boundaries
+
+`scan --output <dir>` writes only to the requested directory. To make the same report visible to the read-only Settings page, opt in explicitly: `--publish` copies it to the default plugin directory `.dsh-composition-doctor/reports`, while `--report-dir <dir>` publishes to a configured plugin directory. Use `--format both` so the Web route has `report.json` and Markdown remains exportable. Do not use a profile directory, `.env` location, or any directory containing keys, tokens, or other secrets as a report directory.
+
+Reports declare `evidenceMode`: `static` means allow-listed manifest/patch/package metadata only; `composed` means a public `dsh --profile <name> --dump-config` command returned a composition result; `runtime-observed` is reserved for a successful isolated runtime observation backend; and `mixed` is reserved for an adapter that supplies both. `dump-config` never proves runtime execution, including when a `!!js` or other runtime-dependent value is present. Static findings and bounded metadata coverage are not proof of the final runtime composition. If no compatible public DSH CLI is available, scan falls back to static and records a warning. Reports written before evidence schema 2 may still be read as legacy `resolved`, but new reports never emit that label.
+
+`preflight --candidate package@version` records a validated exact reference in an isolated temporary `package.json`. Target artifact discovery is local-first (`--dsh-bin`, package directory, tarball, installed `dsh`, `--package-manager-cache`, then Doctor-owned cache); registry access is allowed only with explicit `--online`. Online resolution downloads exact registry tarballs into Doctor-owned cache, records source/version/integrity/hash, and never installs or runs lifecycle scripts. `--allow-build` does not grant permission to execute third-party runtime code.
+
+`scan --fail-on never|info|warning|error` controls the scan exit code. The default is `never`: warnings and errors remain in the report without changing the exit code. `info` fails on any diagnostic, `warning` fails on warnings or errors, and `error` fails only on errors. Malformed arguments return exit code 2; operational failures return 1.
+
 ## Install
 
 ```powershell
 npm install -g dsh-composition-doctor
 npx @deepseek-ai/dsh plugin --profile web add dsh-composition-doctor
+dsh-doctor --version
 ```
 
-Restart the Web UI (`npx @deepseek-ai/dsh web`) after changing a profile. The CLI can also run from a checkout with `node dist/cli/main.js`.
+Restart the Web UI (`npx @deepseek-ai/dsh web`) after changing a profile.
 
 ## Example
 
 ```powershell
-dsh-doctor scan --profile C:\path\to\profile --format both --output .\reports\profile
+dsh-doctor scan --profile C:\path\to\profile --format both --output .\reports\profile --publish
+dsh-doctor scan --profile C:\path\to\profile --format both --output .\reports\archive --report-dir C:\safe\doctor-reports
 dsh-doctor snapshot --profile C:\path\to\profile --output .\reports\before.json
 dsh-doctor diff --before .\reports\before.json --after .\reports\after.json --format both
-dsh-doctor preflight --profile C:\path\to\profile --target-dsh 0.1.0-rc.6
+dsh-doctor preflight --profile C:\path\to\profile --target-dsh 0.1.5-rc.2
 ```
 
-Each finding is `info`, `warning`, or `error` and includes evidence, explanation, and the smallest remediation. Missing runtime evidence is reported as a warning, never as a confirmed failure.
+Each finding is `info`, `warning`, or `error` and includes evidence, explanation, and the smallest remediation. `runtimeSmoke.status=not-run` is not a runtime PASS; `artifact-unavailable` is not `incompatible`; and a warning is not a confirmed failure.
 
 ## Safety and privacy
 
-Default operations are read-only or isolated under the OS temporary directory. The plugin does not modify profiles, install/remove plugins, migrate configuration, escalate permissions, or perform network I/O by default. It never reads `.env`, keys, tokens, environment values, session bodies, or workspace file contents.
+Default operations are read-only or isolated under the OS temporary directory. The plugin does not modify profiles, install/remove plugins, migrate configuration, escalate permissions, or perform network I/O by default. It never reads `.env`, profile secrets, session bodies, or workspace file contents, and does not collect or persist arbitrary environment-variable values. Public CLI execution receives only the minimal process-routing variables required by the host platform.
 
 ## Support and limitations
 
-Verified preview range: DSH `>=0.1.0-rc.5 <0.2.0`, Cordis `>=4 <5`, Node.js `>=20`; Windows is first-class and macOS/Linux are supported. DSH has not yet exposed a stable resolved-composition introspection API, so static findings are explicitly labelled when no public provider is available.
+The real public CLI harness verifies `@deepseek-ai/dsh@0.1.5-rc.1` and `@deepseek-ai/dsh@0.1.5-rc.2`. `0.1.6-alpha.1` remains expected-compatible/experimental only; `0.1.0-rc.6` is historical context, not a current verified target. Missing artifacts are reported as unavailable, never as PASS. Verified development runtime: Node.js 24 on Windows; CI covers Node.js 20 on Ubuntu. Runtime hook/UI ownership is reported as unverified unless public metadata supplies it, and a temp profile is not a security sandbox.
 
 ## Development
 
@@ -54,4 +68,6 @@ pnpm typecheck
 pnpm build
 ```
 
+For checkout-only development, run the CLI with `node dist/cli/main.js` after building.
+
 See [`README.zh.md`](README.zh.md), [`docs/compatibility.md`](docs/compatibility.md), and [`docs/examples/scan-report.md`](docs/examples/scan-report.md). MIT licensed.

package/README.zh.md

@@ -1,28 +1,73 @@
 # dsh-composition-doctor（中文）
 
+[![npm version](https://img.shields.io/npm/v/dsh-composition-doctor)](https://www.npmjs.com/package/dsh-composition-doctor)
+[![CI](https://github.com/lemonxiny55/dsh-composition-doctor/actions/workflows/ci.yml/badge.svg)](https://github.com/lemonxiny55/dsh-composition-doctor/actions/workflows/ci.yml)
+
 [English](README.md) | 中文
 
-面向 DeepSeek Harness（DSH）的本地只读组合与升级预检插件。它读取明确指定的 profile，分析 Cordis/plugin 组合风险，生成脱敏快照，比较升级差异，并在独立临时目录中演练升级。
+面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（`dsh`）的组合与升级预检工具。它读取明确指定的 profile，用可追溯证据说明可观察到的 Cordis/plugin 组合风险；不会编辑真实 profile，也不会静默扩大权限。
+
+当前 package release：`0.2.0`。
 
-## 功能
+## 模型可用能力
 
 | 命令 | 作用 |
 |---|---|
-| `dsh-doctor scan` | 检测重复 row、hook 顺序风险、UI slot/route 冲突、bundle 覆盖、peer/platform 不匹配和 profile 漂移。 |
-| `dsh-doctor snapshot` | 生成脱敏、可比较的 profile 快照和 lockfile 哈希。 |
-| `dsh-doctor diff` | 比较插件、rows、hooks、UI、peer 和平台变化。 |
-| `dsh-doctor preflight` | 在独立临时目录预演目标 DSH 升级。 |
+| `dsh-doctor scan` | 检测重复 Cordis row、hook 顺序风险、UI slot/route 所有权冲突、bundle 覆盖、peer/platform 不匹配和 profile 漂移。 |
+| `dsh-doctor snapshot` | 生成脱敏、可比较的 profile 快照及 lockfile 哈希。 |
+| `dsh-doctor diff` | 汇总新增、删除或升级的插件，以及 rows、hooks、UI 声明、peer 和平台变化。 |
+| `dsh-doctor preflight` | 在独立临时 profile 中演练目标 DSH 升级。 |
+
+Web Settings 页面仅供显示与导出：它读取最新本地报告、展示冲突图，并导出 JSON/Markdown；不提供修复、安装或卸载操作。
+
+## 报告与证据边界
+
+`scan --output <目录>` 只写入显式指定的目录。要让只读 Settings 页面看到同一份报告，必须显式选择 `--publish`，它会复制到默认插件目录 `.dsh-composition-doctor/reports`；也可以使用 `--report-dir <目录>` 发布到配置的插件报告目录。请使用 `--format both`，使 Web route 能读取 `report.json`，同时保留 Markdown 导出。报告目录不能是 profile、`.env` 所在位置，或任何含密钥、token 或其他敏感信息的目录。
+
+报告中的 `evidenceMode` 标明证据来源：`static` 仅表示 allow-list 中的 manifest、patch、package metadata 等静态证据；`composed` 表示公开 `dsh --profile <name> --dump-config` 返回了 composition 结果；`runtime-observed` 只允许真正启动隔离 runtime 并观察到注册/行为的后端使用；`mixed` 预留给同时提供多类来源的适配器。`dump-config` 即使成功，也不代表 runtime 已验证；存在 `!!js` 等运行时依赖时尤其如此。找不到兼容的公开 DSH CLI 时会回退到 static，并明确报告 warning。旧的 evidence schema 2 之前报告仍可按 legacy `resolved` 读取，但新报告不会再输出该标签。
 
-Web Settings 只读显示最近报告、冲突图并导出 JSON/Markdown，不提供修复、安装或卸载操作。
+`preflight --candidate package@version` 只会把通过校验的精确引用记录到隔离临时 `package.json`。目标 artifact 默认按本地优先顺序查找：`--dsh-bin`、本地 package directory、本地 tarball、已安装 `dsh`、`--package-manager-cache`、Doctor 自己的 cache；只有显式 `--online` 才允许访问 registry。在线解析会把精确 tarball 写入 Doctor 自己的 cache，记录来源、版本、integrity 和 hash，并且不会安装或执行 lifecycle script。`--allow-build` 不等于允许执行第三方 runtime code。
 
-## 安装与使用
+`scan --fail-on never|info|warning|error` 控制 scan 的退出码。默认是 `never`：warning 和 error 会写入报告，但不改变退出码；`info` 遇到任意诊断时退出 1，`warning` 遇到 warning 或 error 时退出 1，`error` 只在 error 时退出 1。参数错误退出 2，执行失败退出 1。
+
+## 安装
 
 ```powershell
 npm install -g dsh-composition-doctor
 npx @deepseek-ai/dsh plugin --profile web add dsh-composition-doctor
-dsh-doctor scan --profile C:\path\to\profile --format both --output .\reports\profile
+dsh-doctor --version
+```
+
+更改 profile 后重启 Web UI：`npx @deepseek-ai/dsh web`。
+
+## 示例
+
+```powershell
+dsh-doctor scan --profile C:\path\to\profile --format both --output .\reports\profile --publish
+dsh-doctor scan --profile C:\path\to\profile --format both --output .\reports\archive --report-dir C:\safe\doctor-reports
+dsh-doctor snapshot --profile C:\path\to\profile --output .\reports\before.json
+dsh-doctor diff --before .\reports\before.json --after .\reports\after.json --format both
+dsh-doctor preflight --profile C:\path\to\profile --target-dsh 0.1.5-rc.2
+```
+
+每条诊断均为 `info`、`warning` 或 `error`，并附带 evidence、explanation 和最小 remediation。`runtimeSmoke.status=not-run` 不等于 runtime PASS；`artifact-unavailable` 不等于 `incompatible`；warning 也不等于已确认失败。
+
+## 安全与隐私
+
+默认操作只读，或仅在操作系统临时目录中隔离运行。插件不会修改 profile、安装或删除插件、迁移配置、扩大权限，默认也不会执行网络 I/O。它不会读取 `.env`、profile 密钥、会话正文或工作区源文件内容，也不会收集或持久化任意环境变量值；启动公开 CLI 时只传递平台所需的最小进程路由变量。
+
+## 支持范围与限制
+
+real-release harness 已使用真实公开 CLI 验证 `@deepseek-ai/dsh@0.1.5-rc.1` 和 `@deepseek-ai/dsh@0.1.5-rc.2`。`0.1.6-alpha.1` 仍只是 expected-compatible/experimental；`0.1.0-rc.6` 仅作历史兼容背景，不是当前 verified target。artifact 不可用时会明确报告 unavailable，绝不记为 PASS。已验证开发环境为 Windows + Node.js 24；CI 覆盖 Ubuntu + Node.js 20。只有公开 metadata 能提供 hook/UI ownership 时才会确认，否则标为 unverified；临时目录不是安全 sandbox。
+
+## 开发
+
+```powershell
+pnpm test
+pnpm typecheck
+pnpm build
 ```
 
-默认操作只读或写入操作系统临时目录，不修改真实 profile，不扩大权限，不默认联网，不读取 `.env`、密钥、token、环境变量值、会话正文或工作区文件内容。证据不足时只报告 warning。
+仅在 checkout 开发时，构建完成后使用 `node dist/cli/main.js` 运行 CLI。
 
-已验证范围：DSH `>=0.1.0-rc.5 <0.2.0`、Cordis `>=4 <5`、Node.js `>=20`；Windows 优先，同时支持 macOS/Linux。
+参阅 [`README.md`](README.md)、[`docs/compatibility.md`](docs/compatibility.md) 和 [`docs/examples/scan-report.md`](docs/examples/scan-report.md)。MIT 许可。

package/dist/cli/main.js

@@ -1,16 +1,27 @@
 import { fileURLToPath } from 'node:url';
+import { readFileSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
+import { dirname, resolve } from 'node:path';
 import { resolveComposition } from '../core/composition-adapter.js';
 import { diffSnapshots, renderSnapshotDiffMarkdown } from '../core/diff.js';
 import { readProfile } from '../core/profile-reader.js';
-import { createSnapshot } from '../core/snapshot.js';
+import { createSnapshot, isSnapshotV1, isSnapshotV2 } from '../core/snapshot.js';
 import { analyseComposition } from '../core/rules.js';
 import { renderJson } from '../reports/json.js';
 import { renderMarkdown } from '../reports/markdown.js';
+import { resolveReportDirectory } from '../reports/location.js';
 import { runPreflight } from '../core/preflight.js';
 const usage = 'Usage: dsh-doctor <scan | snapshot | diff | preflight>';
 const commands = new Set(['scan', 'snapshot', 'diff', 'preflight']);
+function packageVersion() {
+    try {
+        const manifest = JSON.parse(readFileSync(resolve(dirname(fileURLToPath(import.meta.url)), '../../package.json'), 'utf8'));
+        return typeof manifest.version === 'string' ? manifest.version : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
 function option(argv, name) {
     const index = argv.indexOf(name);
     return index >= 0 && typeof argv[index + 1] === 'string' ? argv[index + 1] : undefined;
@@ -30,19 +41,41 @@ function invalid(io, message) {
 async function scan(argv, io) {
     const profile = option(argv, '--profile');
     const output = option(argv, '--output');
+    const configuredReportDir = option(argv, '--report-dir');
+    const publish = argv.includes('--publish') || configuredReportDir !== undefined;
     const format = option(argv, '--format') ?? 'json';
     if (profile === undefined || output === undefined)
         return invalid(io, 'scan requires --profile and --output');
     if (format !== 'json' && format !== 'markdown' && format !== 'both')
         return invalid(io, '--format must be json, markdown, or both');
-    const report = analyseComposition(await resolveComposition(await readProfile({ profileDir: resolve(profile) })));
+    const failOn = option(argv, '--fail-on') ?? 'never';
+    if (failOn !== 'never' && failOn !== 'info' && failOn !== 'warning' && failOn !== 'error')
+        return invalid(io, '--fail-on must be info, warning, error, or never');
+    const primary = await resolveComposition(await readProfile({ profileDir: resolve(profile) }));
+    const compared = await Promise.all(options(argv, '--compare-profile').map(async (value) => ({ name: value, model: await resolveComposition(await readProfile({ profileDir: resolve(value) })) })));
+    const report = analyseComposition(compared.length === 0 ? primary : {
+        ...primary,
+        bundles: [...(primary.bundles ?? []), ...compared.flatMap(({ name, model }) => (model.bundles ?? []).map((bundle) => ({ ...bundle, profile: name })))],
+        adapterDiagnostics: [...primary.adapterDiagnostics, ...compared.flatMap(({ model }) => model.adapterDiagnostics)]
+    });
     const destination = resolve(output);
-    await mkdir(destination, { recursive: true });
-    if (format === 'json' || format === 'both')
-        await writeFile(resolve(destination, 'report.json'), renderJson(report), 'utf8');
-    if (format === 'markdown' || format === 'both')
-        await writeFile(resolve(destination, 'report.md'), renderMarkdown(report), 'utf8');
+    const destinations = [destination, ...(publish ? [resolveReportDirectory(configuredReportDir)] : [])];
+    for (const directory of destinations) {
+        await mkdir(directory, { recursive: true });
+        if (format === 'json' || format === 'both')
+            await writeFile(resolve(directory, 'report.json'), renderJson(report), 'utf8');
+        if (format === 'markdown' || format === 'both')
+            await writeFile(resolve(directory, 'report.md'), renderMarkdown(report), 'utf8');
+    }
     io.write(`Wrote reports to ${destination}`);
+    if (publish)
+        io.write(`Published reports to ${destinations[1]}`);
+    if (failOn === 'info' && report.diagnostics.length > 0)
+        return 1;
+    if (failOn === 'error' && report.diagnostics.some((item) => item.severity === 'error'))
+        return 1;
+    if (failOn === 'warning' && report.diagnostics.some((item) => item.severity === 'warning' || item.severity === 'error'))
+        return 1;
     return 0;
 }
 async function snapshot(argv, io) {
@@ -51,13 +84,12 @@ async function snapshot(argv, io) {
     if (profile === undefined || output === undefined)
         return invalid(io, 'snapshot requires --profile and --output');
     const destination = resolve(output);
+    await mkdir(dirname(destination), { recursive: true });
     await writeFile(destination, `${JSON.stringify(await createSnapshot(await readProfile({ profileDir: resolve(profile) })), null, 2)}\n`, 'utf8');
     io.write(`Wrote snapshot to ${destination}`);
     return 0;
 }
-function isSnapshot(value) {
-    return value !== null && typeof value === 'object' && value.schemaVersion === 1;
-}
+function isSnapshot(value) { return isSnapshotV1(value) || isSnapshotV2(value); }
 async function diff(argv, io) {
     const beforePath = option(argv, '--before');
     const afterPath = option(argv, '--after');
@@ -69,12 +101,21 @@ async function diff(argv, io) {
     const before = JSON.parse(await readFile(resolve(beforePath), 'utf8'));
     const after = JSON.parse(await readFile(resolve(afterPath), 'utf8'));
     if (!isSnapshot(before) || !isSnapshot(after))
-        return invalid(io, 'diff inputs must be schema version 1 snapshots');
+        return invalid(io, 'diff inputs must be schema version 1 or 2 snapshots');
     const result = diffSnapshots(before, after);
-    if (format === 'json' || format === 'both')
-        io.write(`${JSON.stringify(result, null, 2)}\n`);
-    if (format === 'markdown' || format === 'both')
-        io.write(renderSnapshotDiffMarkdown(result));
+    const output = option(argv, '--output');
+    const rendered = [
+        ...(format === 'json' || format === 'both' ? [`${JSON.stringify(result, null, 2)}\n`] : []),
+        ...(format === 'markdown' || format === 'both' ? [renderSnapshotDiffMarkdown(result)] : [])
+    ];
+    if (output === undefined)
+        rendered.forEach((value) => io.write(value));
+    else {
+        const destination = resolve(output);
+        await mkdir(dirname(destination), { recursive: true });
+        await writeFile(destination, rendered.join(''), 'utf8');
+        io.write(`Wrote diff to ${destination}`);
+    }
     return 0;
 }
 async function preflight(argv, io) {
@@ -89,14 +130,17 @@ async function preflight(argv, io) {
         candidates: options(argv, '--candidate'),
         allowBuild: argv.includes('--allow-build'),
         online: argv.includes('--online'),
-        keepTemp: argv.includes('--keep-temp')
+        keepTemp: argv.includes('--keep-temp'),
+        dshBin: option(argv, '--dsh-bin'),
+        dshPackage: option(argv, '--dsh-package'),
+        packageManagerCacheDirs: options(argv, '--package-manager-cache')
     });
     const rendered = `${JSON.stringify(result, null, 2)}\n`;
     if (output === undefined)
         io.write(rendered);
     else {
         const destination = resolve(output);
-        await mkdir(resolve(destination, '..'), { recursive: true });
+        await mkdir(dirname(destination), { recursive: true });
         await writeFile(destination, rendered, 'utf8');
         io.write(`Wrote preflight report to ${destination}`);
     }
@@ -108,6 +152,10 @@ export async function runCli(argv, io = { write: (line) => console.log(line) })
         io.write(usage);
         return 0;
     }
+    if (command === '--version') {
+        io.write(packageVersion());
+        return 0;
+    }
     if (!commands.has(command)) {
         io.write(`Unknown command: ${command}`);
         return 2;

package/dist/client/index.js

@@ -1,13 +1,14 @@
-import { createReportView } from './report-view.js';
+import { createElement } from 'react';
+import { ReportView } from './report-view.js';
 export const name = 'dsh-composition-doctor';
 export const registration = Object.freeze({
     id: name,
     actions: ['export-json', 'export-markdown'],
-    component: () => createReportView()
+    component: () => createElement(ReportView, { translate: (key) => key })
 });
 export const apply = Object.assign((ctx) => {
     const messages = {
-        zh: { title: 'DSH 组合医生', exportJson: '导出 JSON', exportMarkdown: '导出 Markdown' },
+        zh: { title: 'DSH Composition Doctor', exportJson: '导出 JSON', exportMarkdown: '导出 Markdown' },
         en: { title: 'DSH Composition Doctor', exportJson: 'Export JSON', exportMarkdown: 'Export Markdown' }
     };
     const disposeLocale = ctx.locale?.register('dshCompositionDoctor', messages);
@@ -15,7 +16,7 @@ export const apply = Object.assign((ctx) => {
     const disposeSlot = ctx.slots.inject('settings.plugins.tab', () => ctx.slots.register({
         name: 'settings.plugins.tab', id: registration.id, order: 70,
         locale: 'dshCompositionDoctor', label: () => t('title')
-    }, () => createReportView(undefined, t)));
+    }, () => createElement(ReportView, { translate: t })));
     return () => {
         if (typeof disposeSlot === 'function')
             disposeSlot();

package/dist/client/report-view.js

@@ -1,5 +1,20 @@
+import { createElement, useEffect, useRef } from 'react';
 import { renderMarkdown } from '../reports/markdown.js';
 export const clientReportPath = '/dsh-composition-doctor/reports/latest';
+export const downloadRevokeDelayMs = 1000;
+export function evidenceBadgeLabel(mode, runtimeObserved) {
+    if (mode === 'runtime-observed' && runtimeObserved)
+        return 'runtime-observed';
+    if (mode === 'runtime-observed')
+        return 'composed; runtime not observed';
+    if (mode === 'composed')
+        return 'composed; runtime not observed';
+    if (mode === 'mixed')
+        return runtimeObserved ? 'mixed; runtime observed' : 'mixed; runtime not observed';
+    if (mode === 'resolved')
+        return 'legacy resolved; runtime not observed';
+    return 'static';
+}
 export function buildConflictGraph(report) {
     const nodes = new Map();
     const edges = [];
@@ -22,6 +37,28 @@ export function toReportViewModel(report) {
         counts[diagnostic.severity] += 1;
     return { report, counts, graph: buildConflictGraph(report) };
 }
+function renderConflictGraph(document, graph) {
+    const section = document.createElement('section');
+    section.setAttribute('aria-labelledby', 'dsh-composition-doctor-conflict-graph');
+    const heading = document.createElement('h3');
+    heading.id = 'dsh-composition-doctor-conflict-graph';
+    heading.textContent = 'Conflict graph';
+    section.append(heading);
+    const list = document.createElement('ul');
+    for (const node of graph.nodes) {
+        const item = document.createElement('li');
+        const outgoing = graph.edges.filter((edge) => edge.from === node.id).map((edge) => graph.nodes.find((candidate) => candidate.id === edge.to)?.label ?? edge.to);
+        item.textContent = `${node.label} (${node.source})${outgoing.length === 0 ? '' : ` → ${outgoing.join(', ')}`}`;
+        list.append(item);
+    }
+    if (graph.nodes.length === 0) {
+        const item = document.createElement('li');
+        item.textContent = 'No evidence relationships were produced.';
+        list.append(item);
+    }
+    section.append(list);
+    return section;
+}
 function isReport(value) {
     if (value === null || typeof value !== 'object')
         return false;
@@ -47,12 +84,37 @@ async function fetchReport(fetcher = globalThis.fetch) {
         throw new Error('The latest report has an unsupported schema.');
     return value;
 }
-function download(document, content, filename, mime) {
+const browserDownloadHooks = {
+    createObjectURL: (blob) => URL.createObjectURL(blob),
+    revokeObjectURL: (url) => URL.revokeObjectURL(url),
+    schedule: (callback, delay) => globalThis.setTimeout(callback, delay)
+};
+/** Create a local browser download without sending report data anywhere. */
+export function download(document, content, filename, mime, hooks = browserDownloadHooks) {
+    const blob = new Blob([content], { type: mime });
     const link = document.createElement('a');
-    link.href = URL.createObjectURL(new Blob([content], { type: mime }));
+    const objectUrl = hooks.createObjectURL(blob);
+    link.hidden = true;
+    link.href = objectUrl;
     link.download = filename;
-    link.click();
-    URL.revokeObjectURL(link.href);
+    document.body.append(link);
+    try {
+        link.click();
+    }
+    finally {
+        link.remove();
+        hooks.schedule(() => hooks.revokeObjectURL(objectUrl), downloadRevokeDelayMs);
+    }
+}
+export async function exportReport(document, format, dependencies = {}) {
+    const report = await fetchReport(dependencies.fetcher);
+    if (format === 'json') {
+        ;
+        (dependencies.download ?? download)(document, `${JSON.stringify(report, null, 2)}\n`, 'dsh-composition-doctor-report.json', 'application/json');
+        return;
+    }
+    ;
+    (dependencies.download ?? download)(document, renderMarkdown(report), 'dsh-composition-doctor-report.md', 'text/markdown');
 }
 /**
  * Browser-native settings section. It only performs a GET and offers local
@@ -60,7 +122,7 @@ function download(document, content, filename, mime) {
  */
 export function createReportView(document = globalThis.document, translate = (key) => ({
     title: 'DSH Composition Doctor', exportJson: 'Export JSON', exportMarkdown: 'Export Markdown', loading: 'Loading the latest local report…', unavailable: 'The latest report is unavailable.'
-}[key] ?? key)) {
+}[key] ?? key), dependencies = {}) {
     const root = document.createElement('section');
     root.dataset.plugin = nameForDom;
     root.setAttribute('aria-labelledby', 'dsh-composition-doctor-title');
@@ -72,21 +134,58 @@ export function createReportView(document = globalThis.document, translate = (ke
     status.textContent = translate('loading');
     root.append(status);
     const actions = document.createElement('p');
-    actions.append(button(document, translate('exportJson'), () => { void fetchReport().then((report) => download(document, `${JSON.stringify(report, null, 2)}\n`, 'dsh-composition-doctor-report.json', 'application/json')).catch(() => undefined); }), text(document, ' '), button(document, translate('exportMarkdown'), () => { void fetchReport().then((report) => download(document, renderMarkdown(report), 'dsh-composition-doctor-report.md', 'text/markdown')).catch(() => undefined); }));
+    actions.append(button(document, translate('exportJson'), () => { void exportReport(document, 'json', dependencies).catch(() => undefined); }), text(document, ' '), button(document, translate('exportMarkdown'), () => { void exportReport(document, 'markdown', dependencies).catch(() => undefined); }));
     root.append(actions);
-    void fetchReport().then((report) => {
+    void fetchReport(dependencies.fetcher).then((report) => {
         const model = toReportViewModel(report);
-        status.textContent = `Diagnostics: ${model.counts.error} error, ${model.counts.warning} warning, ${model.counts.info} info. Conflict graph: ${model.graph.nodes.length} evidence nodes.`;
+        const badge = document.createElement('span');
+        badge.dataset.evidenceKind = report.evidenceMode;
+        badge.setAttribute('aria-label', 'Evidence capability');
+        badge.textContent = `Evidence: ${evidenceBadgeLabel(report.evidenceMode, report.runtimeObserved === true)}`;
+        status.textContent = `Generated: ${report.generatedAt}. Profile: ${report.profileDir}. Diagnostics: ${model.counts.error} error, ${model.counts.warning} warning, ${model.counts.info} info.`;
+        status.append(document.createTextNode(' '), badge);
+        root.append(renderConflictGraph(document, model.graph));
         const list = document.createElement('ul');
         for (const diagnostic of report.diagnostics) {
             const item = document.createElement('li');
-            item.textContent = `[${diagnostic.severity}] ${diagnostic.title}`;
+            const details = document.createElement('details');
+            const summary = document.createElement('summary');
+            summary.textContent = `[${diagnostic.severity}] ${diagnostic.title}`;
+            details.append(summary);
+            const explanation = document.createElement('p');
+            explanation.textContent = diagnostic.explanation;
+            const evidence = document.createElement('pre');
+            evidence.textContent = diagnostic.evidence.map((entry) => `${entry.source}: ${entry.detail}`).join('\n') || 'No concrete evidence.';
+            const remediation = document.createElement('p');
+            remediation.textContent = `Remediation: ${diagnostic.remediation}`;
+            details.append(explanation, evidence, remediation);
+            item.append(details);
             list.append(item);
         }
         root.append(list);
-    }).catch((error) => {
-        status.textContent = error instanceof Error ? error.message : translate('unavailable');
+    }).catch(() => {
+        status.textContent = translate('unavailable');
     });
     return root;
 }
+/**
+ * DSH settings slots are rendered by React. Keep the browser-native report
+ * view as the implementation detail, but mount it through a React component
+ * rather than returning an HTMLElement directly to the slot renderer.
+ */
+export function ReportView({ translate }) {
+    const host = useRef(null);
+    useEffect(() => {
+        const container = host.current;
+        if (container === null)
+            return;
+        const view = createReportView(globalThis.document, translate);
+        container.replaceChildren(view);
+        return () => {
+            view.remove();
+            container.replaceChildren();
+        };
+    }, [translate]);
+    return createElement('div', { className: 'dsh-composition-doctor-report-view', ref: host });
+}
 const nameForDom = 'dsh-composition-doctor';