TypeSpec Spec DashboardSpector Dashboard开发运行与配置指南【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespecSpec Dashboard包名typespec/spec-dashboard代码中常被称为 Spector Dashboard是 TypeSpec 仓库中用于可视化场景覆盖报告Coverage Report的 React 前端应用。本文围绕其官方 README 展开完整覆盖本地启动方式、?showtesttrue调试开关并结合仓库源码深入讲解数据加载管线、CoverageFromAzureStorageOptions配置模型、多表拆分与场景分级Tier过滤的实现原理帮助你在自己的 TypeSpec 生态项目中快速搭建一套可观测的规范覆盖仪表盘。一、项目定位覆盖报告的可视化前端Spec Dashboard 属于 TypeSpec 生态中规范Spec覆盖测试体系的一部分packages/spector负责运行场景测试并产出覆盖率数据packages/spec-coverage-sdk负责从 Azure Storage 读取这些数据而packages/spec-dashboard则负责把这些数据渲染为可交互的仪表盘界面。从 src/index.ts 可以看到该包对外只暴露三个核心出口DashboardFromAzureStorage组件传入配置后自动从 Azure Storage 拉取覆盖数据并渲染Dashboard组件接收已经组装好的CoverageSummary[]直接渲染类型CoverageFromAzureStorageOptions、TableDefinition。因此该包既可作为独立页面使用也可作为可嵌入的 React 组件库被其他页面引用package.json中声明了main: dist/index.js与exports入口且vite.config.ts以lib模式构建 ES 产物并生成style.css。二、本地开发与启动官方 README 给出的启动方式极为简洁在仓库根目录下进入本包后执行npm run start # 或 npm run dev在 package.json 中start与dev虽然未单独列出脚本名但从 TypeSpec 仓库使用 pnpm workspace turbo 的惯例见根目录 package.json 与 turbo.jsonnpm run start/npm run dev会解析到 workspace 脚本典型实现为vite启动开发服务器。开发服务器由 vite.config.ts 配置默认端口即 Vite 的 5173并设置了server.fs.strict: false以允许读取工作区外文件。启动后浏览器打开本地地址即可看到仪表盘页面。README 还给出了一条极具实用价值的调试提示在 URL 上添加查询参数?showtesttrue例如http://localhost:5173/?showtesttrue即可显示测试生成器test generator。该参数用于在开发阶段打开测试用例生成相关的调试入口便于开发者在调整覆盖数据或生成器逻辑时快速校验。三、项目结构与数据流概览本包目录结构清晰各模块职责如下路径职责src/apis.ts数据加载管线从 Azure Storage 拉取 manifest 与覆盖率报告组装为CoverageSummarysrc/components/dashboard-az-storage.tsx面向 Azure Storage 的高层组件src/components/dashboard.tsx主仪表盘搜索、Tier 过滤、概览、表格编排src/components/dashboard-table.tsx场景树形表格与生成器表头渲染src/components/coverage-overview.tsx各生成器的覆盖率总览卡片src/components/scenario-status.tsx场景状态图标pass/fail/not-implemented 等src/hooks/use-tier-filtering.ts按 Tier 过滤场景的 React Hooksrc/utils/tier-filtering-utils.tsTier 配置编译与场景分类算法整体数据流为SpecCoverageClient来自typespec/spec-coverage-sdk→ 读取 Scenario Manifest → 读取各 emitter 的最新覆盖率报告 →getCoverageSummaries()合并为CoverageSummary[]→ 传入Dashboard渲染。四、数据加载 APICoverageFromAzureStorageOptions 详解DashboardFromAzureStorage组件接收一个options对象类型为CoverageFromAzureStorageOptions定义见 src/apis.ts。这是定制仪表盘最核心的配置入口各字段含义如下字段类型必填说明storageAccountNamestring是Azure Storage 账户名用于构造SpecCoverageClientcontainerNamestring是存储容器名manifestsstring[]是要展示的场景清单名对应存储中manifests/name.json下的文件emitterNamesstring[]是全局生成器emitter包名列表例如typespec/http-client-csharpmodesstring[]否覆盖报告的模式默认[standard]tablesTableDefinition[]否多表拆分定义可将一个 manifest 按前缀拆成多张表tiersTierConfig否场景分级配置用于按 Tier 过滤showOverviewboolean否是否在仪表盘顶部显示覆盖率总览卡片emitterDisplayNamesRecordstring, string否生成器包名到友好显示名的映射如typespec/http-client-python→Python加载流程源码解析getCoverageSummaries()src/apis.ts的执行步骤通过getCoverageClient()单例化SpecCoverageClient并发加载所有 manifestcoverageClient.manifest.get(x)若配置了tables调用splitManifestByTables()按表定义拆分并按配置顺序重排否则每个 manifest 直接使用displayName || packageName作为表名汇总所有需要的 emitter 名全局 表级专属通过loadReports()并发拉取每个 emitter 在每种 mode 下的最新报告coverageClient.coverage.getLatestCoverageFor(emitter, mode)单个 emitter 拉取失败只会打印错误并返回undefined不会让整个仪表盘崩溃用getSuiteReportForManifest()按packageName匹配报告与 manifest组装为CoverageSummary。其中modes支持多模式并行拉取loadReports()用Promise.all并发执行所有组合最终按键值结构{ [mode]: { [emitterName]: report } }返回。五、多表拆分TableDefinition 与 splitManifestByTables当需要把一个大 manifest 的场景按业务域拆成多张表格展示时使用tables配置。TableDefinitionsrc/apis.ts字段字段说明name自定义表名会显示在表格左上角packageName该表适用的 spec 包名与 manifest 的packageName匹配prefixes?前缀过滤数组场景名以任一前缀开头即归入该表emitterNames?该表专属的 emitter 列表不填则回退到全局emitterNamessplitManifestByTables()src/apis.ts的拆分算法值得注意先扫描所有带prefixes的表把命中任意前缀的场景预占起来避免落入 catch-all 表按tableDefinitions的声明顺序逐表过滤已被分配的场景不会重复出现不带prefixes的表视为 catch-all只接收既未被分配、又不命中任何前缀的场景完全未被任何表命中的场景最后归入默认表表名为displayName || packageName。这套前缀表 兜底表的设计使得一个 manifest 可以优雅地拆成多张语义清晰的表格同时保证所有场景都有归属、无遗漏。六、场景分级Tier过滤TierConfig 与分类算法仪表盘支持按场景的重要程度分级过滤。TierConfig定义于 src/utils/tier-filtering-utils.tsinterface TierConfig { default: string; // 默认层级名必须存在于 tiers 中 tiers: Recordstring, string[]; // 层级名 - 场景名模式数组 }tiers中的每个模式支持两种写法精确匹配不含*的场景名例如Autorest通配匹配含*的模式*会被编译为正则.*例如Azure.*。compileTierConfig()把配置编译为三部分精确匹配 Map、模式正则数组、默认层级名编译时若default指定的层级不在tiers中会直接抛出错误Invalid tierConfig.default。classifyScenario()则按先精确匹配、再正则匹配、最后回退默认层级的顺序分类场景useTierFilteringHooksrc/hooks/use-tier-filtering.ts负责在运行时按所选 Tier 过滤所有 summary 的场景列表并在Dashboard顶部渲染TierFilterTabs标签页。七、界面渲染树形表格、状态色与概览卡片场景树形表格dashboard-table.tsx中的createTree()src/components/dashboard-table.tsx把场景名按_分段构建多级树例如场景Azure_Core_Get会形成Azure → Core → Get的层级。buildTreeRows()负责把树展开为扁平行列表支持行级展开/折叠也支持expandAll搜索时自动全展开。每个叶子场景行对每个 emitter 渲染一个状态框非叶子分组行则渲染该分组下所有场景的完成比例。表头GeneratorHeaderCell展示每个生成器的友好名称、生成器版本、场景包版本以及覆盖率状态条鼠标悬停会弹出GeneratorInformation详情包含报告日期、生成器 commit、报告当时覆盖率与当前覆盖率对比。状态语义与配色场景状态共六种见 src/components/scenario-status.tsx与typespec/spec-coverage-sdk的ScenarioStatus类型对应状态含义图标/颜色pass场景通过绿色对勾#5E9732fail场景失败红色错误圈#ef3e36not-implemented未实现黄色警告#ef3e36not-applicable不适用灰色静音图标not-supported不支持灰色静音图标undefinednot-reported未上报灰色问号覆盖率比例的颜色阈值定义于 src/constants.ts 的GroupRatios1perfect绿→0.8good→0.5average黄→0.01bad橙红→0zero红。表格与总览卡片共用这套阈值保证视觉语义一致。覆盖率总览开启showOverview后CoverageOverview会在顶部渲染每个 emitter 的概览卡片显示友好名称与覆盖率百分比。其统计口径src/components/coverage-overview.tsx为所有 summary 的场景总数中状态为pass、not-applicable、not-supported的场景占比友好名称解析优先级为emitterDisplayNames配置 →generatorMetadata.name→ 从包名正则提取如typespec/http-client-python→Python。名称搜索Dashboard顶部的SearchBox支持按场景名过滤并借助 React 的useDeferredValue把输入更新与昂贵的树形过滤渲染分离保证输入流畅搜索结果会自动全展开所有匹配行无匹配时显示 No scenarios match ... 提示。八、构建与质量检查命令除了开发启动package.json 还提供以下脚本npm run build # vite build产出库构建产物dist/与类型声明vite-plugin-dts npm run watch # vite build --watch监听变更增量构建 npm run test:ui # vitest --ui带 UI 的测试运行器 npm run test:ci # vitest run --coverage --reporterjunit --reporterdefaultCI 用输出 JUnit 报告 npm run lint # oxlint . --deny-warnings严格 lint npm run lint:fix # oxlint . --fix自动修复构建配置要点vite.config.ts以src/index.ts为入口做 ES 库构建所有dependencies声明为 external不打包进产物开启 TypeScript 类型检查插件vite-plugin-checker与 DTS 生成测试环境为node globals。本包要求 Node.js22.0.0见engines字段请确保本地环境满足该版本要求。九、写在最后Spec Dashboard 把场景清单 多生成器覆盖报告这一冷冰冰的数据流变成了一张可搜索、可分级、可逐场景下钻的交互式表格。理解CoverageFromAzureStorageOptions、TableDefinition与TierConfig三套配置模型就掌握了定制该仪表盘的核心能力你可以据此在自己的 TypeSpec 仓库中接入多套 manifests、多语言 emitter并以场景分级的方式聚焦重点规范的覆盖情况。配合?showtesttrue调试开关与npm run dev热更新二次开发体验十分顺畅。【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespec创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考