dsh-a11y-scan

Readme

# dsh-a11y-scan

> [!IMPORTANT]
> **依赖前置：相邻 `dsh-src` 检出（`link:` 依赖）**
> 本项目在开发形态下使用 `link:` 依赖指向相邻的 DeepSeek Harness 源码检出（`dsh-src`），
> 与当前仓库保持同一父目录布局（`<parent>/dsh-src`）。克隆本仓库后：
> 1. 先把官方 `deepseek-ai/deepseek-harness` 检出到与本仓库同级的 `dsh-src/` 目录，并执行其 `pnpm install && pnpm run build`；
> 2. 再按下方「安装」一节执行本仓库的 `pnpm install --offline && pnpm build` 与测试。
> 发布到 npm 的版本会尽量把 `link:` 依赖替换为 registry 真实版本；无法替换的内部包保持 `link:`，见各包 README 说明。


DSH 原生**无障碍（WCAG）扫描工具**：扫描前端项目的 HTML（单文件 / 目录，含 vite/next 构建产物 / 用户确认后的 URL），用 [axe-core](https://github.com/dequelabs/axe-core) 按 WCAG 2.1 A/AA/AAA 自动检测违规，输出 **规则 id、impact 严重度、WCAG 2.1 关联（如 1.4.3 对比度）、元素定位（nodes：选择器/摘要/failureSummary）、修复建议**，并可生成 Markdown / 自包含 HTML / JSON 报告。

- **只读扫描**：绝不自动修改代码或文件；写报告文件需显式 `reportFile` 参数。
- **可编程独立工具**：调用即得结构化结果，可进 CI / Workflow / Agent 循环。
- **自动化 + 人工复核并存**：axe 扫不到或无法判定的项（焦点顺序语义、键盘操作、朗读顺序等）输出为「需人工复核清单」与 `incomplete` 项。

## 定位边界（避免与 dsh-frontend-engineer-agent 混淆）

| | dsh-a11y-scan（本插件） | dsh-frontend-engineer-agent |
| --- | --- | --- |
| 形态 | 可编程调用的独立工具（`a11y_scan`） | Agent 预设（含 80 个技能之一「无障碍审查」） |
| 用法 | `a11y_scan` 工具调用 / CI / Workflow | 对话式前端工程师会话 |
| 输出 | 结构化违规 JSON + 报告 | 自然语言审查意见 |

本插件与现有预设**不重叠**：预设负责「人机对话式审查」，本插件负责「确定性的自动化扫描」。二者可协同：先用本插件扫出规则命中清单，再请预设做人工复核位的解读。

## 安装与挂载

```bash
# 1) 安装运行时依赖（前置依赖见下节）
npm install

# 2) 构建
npm run build        # 产出 lib/（tsc）

# 3) 挂载到 profile
dsh plugin --profile <name> add /path/to/dsh-a11y-scan
```

`package.json` 声明 `dsh.bundle.patch: ./cordis.yml`；`cordis.yml` 以 `insert` 行将
`dsh-a11y-scan/lib/index.js`（Cordis `name`/`inject`/`apply` 插件）挂入会话注册表。默认注入
`tools`（注册）、`fs`（文件读写）、`subprocess`（axe 扫描后端）。

## 前置依赖（扫描后端）

| 依赖 | 用途 | License |
| --- | --- | --- |
| `@axe-core/cli`（含 axe-core 与 puppeteer/Chrome 无头浏览器） | 实际扫描引擎 | MPL-2.0（**不随本包分发**，按需安装；见下） |
| `@deepseek-ai/cordis` / `dsh-fs` / `dsh-subprocess` / `dsh-tools` | DSH 插件运行时 | MIT（DSH 内部包，link 安装） |

```bash
# 在待扫描的前端项目里（或目标目录可达的 node_modules 中）安装引擎：
npm i -D @axe-core/cli
```

未安装时 `a11y_scan` 返回明确的 `prerequisite` 错误并给出安装命令（绝不自动安装、
不静默失败）。工具对本地文件优先，云扫描只在本机无头浏览器内进行。

> **axe-core License 声明**：axe-core 为 MPL-2.0。本包**不打包、不修改** axe-core 源码，
> 运行时子进程调用用户安装的 `@axe-core/cli`；分发义务说明见 [NOTICE](./NOTICE)。

## 工具：`a11y_scan`

### 参数

| 参数 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `path` | string | 工作区根 | 项目目录 / 单个 HTML 文件 / URL。目录会递归发现 `.html`（**含 dist/out 构建产物**，跳过 `node_modules`/`.git` 等，最多 50 页）；URL 需 `confirmUrl` |
| `level` | `'A'\|'AA'\|'AAA'` | `'AA'` | 决定 axe runOnly 标签族（A/AA/AAA） |
| `wcag21` | bool | `true` | `true` 用 `wcag21a/aa/aaa` 标签；`false` 用经典 `wcag2a/aa/aaa` |
| `out` | `'md'\|'html'\|'json'` | `'md'` | 报告格式；`html` 为自包含单文件（可离线打开） |
| `confirmUrl` | bool | `false` | URL 目标的显式用户确认；缺省时 URL 扫描被拒绝 |
| `reportFile` | string | 无 | 可选：把渲染报告写入此路径（只读默认，显式 opt-in） |

### 返回值（结构化值）

```
scanned   目标/类别/级别/规则集/引擎/时间/页面
violations 按 impact 排序（critical→…→minor）：规则id、impact、
           WCAG 2.1 引用、修复建议(fix.steps+链接)、nodes[](selector/html/summary/failureSummary)、page
incomplete axe 无法自动判定项（需人工复核）
summary  total/critical/serious/moderate/minor/unknown + byRule 计数
manualReview 固定人工复核清单（焦点顺序、键盘陷阱、朗读顺序、alt 质量、颜色非唯一通道等 9 项，各带 WCAG 章节）
errors   url-confirmation-required / prerequisite / empty-file / no-html / axe / fs（含 retryable）
rendered 按 `out` 渲染的 Markdown / 自包含 HTML / 漂亮 JSON
```

### 行为要点

- **axe 调用链**：本机静态服务（127.0.0.1 临时端口，防路径穿越）→
  `npx --no-install @axe-core/cli <url> --format json --tags <runOnly>`（经 `ctx.subprocess`，逐页顺序执行）；
- **修复建议**：每条违规给常见修法 + axe 规则链接 + WCAG 2.1 quickref 链接（对照
  wcag-audit-patterns 思路：给出「2.1 章节链接 + 常见修法」）；
- **人工复核**：axe 的 `incomplete` 结果 + 固定 9 项感知/操作清单（焦点顺序语义、键盘操作等自动化覆盖不了项）；
- **URL 确认**：未设 `confirmUrl: true` 时返回 `url-confirmation-required` 错误且**引擎不会运行**；
- **前置提示**：目标无 HTML（`no-html`）、文件为空（`empty-file`）、非 HTML 文件、axe 未装（`prerequisite`）均有明确中文提示。

### CI 示例

```yaml
# .github/workflows/a11y.yml（示意）
- run: npm ci && npm i -D @axe-core/cli
- run: dsh tool run a11y_scan '{"path": "dist", "level": "AA", "out": "html", "reportFile": "reports/a11y.html"}'
- uses: actions/upload-artifact@v4
  with: { path: reports/a11y.html }
```

## 测试

```bash
pnpm typecheck        # tsc --noEmit（src + tests）
pnpm test             # 离线冒烟：本地 fixture 页面 + 录制 axe 结果驱动全管线
pnpm test:live        # 已安装 @axe-core/cli 时，对 fixture 跑真实 axe（未装则跳过）
```

离线测试覆盖（对照验收标准）：

1. **fixture 违规页命中 color-contrast + aria 错误**，impact/nodes（selector/失败摘要）字段正确；
2. **按 impact 排序**，汇总计数与实际一致；**HTML 报告自包含**（内嵌 JSON 可往返解析、
   无外部资源，`assets/report-template.html` 与代码内嵌模板逐字节一致）；
3. **level/wcag21 切换改变 runOnly 规则集**（`runOnlyTags` 单测 + 引擎收到的标签断言）；
4. **URL 无确认被拒**（引擎零调用），`confirmUrl: true` 放行；
5. **全离线可跑**（本地静态页面/文件，无浏览器、无网络）。

## 目录结构

```
dsh-a11y-scan/
├── cordis.yml                # DSH bundle 挂载层（insert 行）
├── package.json              # dsh.bundle.patch 声明；MIT
├── tsconfig.json / tsconfig.build.json
├── LICENSE / NOTICE          # MIT + axe-core MPL-2.0 声明
├── assets/report-template.html  # 自包含 HTML 报告模板（与内嵌模板保持字节一致）
├── src/
│   ├── index.ts              # 装配：name/inject/apply + 注册 a11y_scan
│   ├── runner.ts             # 目标解析/页面发现/URL 门/静态服务/axe-CLI 引擎/编排
│   ├── report.ts             # 归一化/WCAG 映射/排序/汇总/MD·HTML·JSON 渲染（纯函数）
│   └── tools/a11y-scan.ts    # defineTool + 输出 schema + presentationMeta
└── tests/
    ├── smoke.e2e.ts          # 离线冒烟 + 可选 live（DSH_A11Y_LIVE=1）
    ├── support/simulated-engine.ts
    └── fixtures/             # 违规页/干净页/空文件/无 HTML 目录/多页项目 + 录制 axe JSON
```

## License

本插件代码 MIT（见 [LICENSE](./LICENSE)）。扫描后端 axe-core 为 **MPL-2.0**，
不随本包分发，分发义务声明见 [NOTICE](./NOTICE)。扫描流程「自动化 → 人工复核 →
修复建议 → CI」字段模型参考 wshobson/agents accessibility-compliance（MIT），
仅复用流程与字段模型，未复制其源码。

> 只读声明：本工具不自动修改代码；所有修复建议需人工确认后执行。

## 权限、失败边界与 DSH STORE 状态

- [PERMISSIONS.md](./PERMISSIONS.md)：运行时读取面 / 命令面（固定 argv，非 shell）/ 写面 / 外部服务 / 失败边界 / 供应链 / 文件权限信号（无 chmod/chown、644、无 setuid/setgid）。
- [docs/store-evidence.md](./docs/store-evidence.md)：一次性 Profile 安装 → 启动（工具注册清单）→ 卸载步骤、本地离线证据、待宿主补录真实运行记录说明，并逐项回应 DSH STORE 五类审查信号（仓库 canonical 匹配 / Node 声明 / 供应链 / 文件权限 / 命令权限）。
- STORE 复检由 dsh-safe-plugin-manager 每 3 小时自动执行；本仓库已按清单契约声明（package.json 的 `repository` / `engines.node` / `dsh.compatibility` / `dsh.permissions`）。