Development and Testing

开发、测试与发布

本页面向希望从源码运行、审查或贡献 TriForge Git 的开发者。

项目发起者 zhangxh-math 不会写代码；需求、产品方向、界面反馈与验收由 zhangxh-math 完成，方案分析、代码、审查、测试和文档由 Codex 协助完成。仓库保留源码和自动化测试，方便社区独立审查这套协作成果。

技术栈

• TypeScript，严格类型检查；
• VS Code Extension API 1.98；
• Node.js 20 目标；
• esbuild 打包为 CommonJS；
• Node 内置测试运行器；
• pnpm；
• @vscode/vsce 打包 VSIX。

生产依赖为空；发布包将扩展逻辑打成 dist/extension.js，vscode 由扩展宿主提供。

目录结构

src/
  extension.ts              激活、视图和存储装配
  commands.ts               命令、交互与操作一致性检查
  connectionStore.ts        连接元数据与 SecretStorage
  repositoryController.ts   活动仓库快照与刷新
  git/
    auth.ts                 临时认证环境和脱敏
    runner.ts               shell-free Git 子进程执行
    service.ts              高层 Git 操作
    parsers.ts              状态、分支、日志等解析
  remote/
    githubProvider.ts       GitHub REST 适配
    gitlabProvider.ts       GitLab REST 适配
    giteaProvider.ts        Gitea REST 适配
    httpClient.ts           HTTP、超时、重定向和响应限制
    repositoryValidation.ts 平台返回仓库/URL 校验
  ui/
    repositoryTree.ts       分支、更改与远程树
    operationView.ts        提交与同步 Webview
    sidebarGraphView.ts     侧栏紧凑提交图
    graphPanel.ts           完整 Git Graph
test/
  *.test.ts                 单元与回归测试
  bundle-smoke.cjs          Bundle 激活加载冒烟检查
media/                      图标与品牌资源
docs/wiki/                  GitHub Wiki 源页面

安装依赖

pnpm install

锁文件是 pnpm-lock.yaml。贡献时不要无故换包管理器或重写锁文件。

常用命令

命令	作用
pnpm run check	对生产源码运行 tsc --noEmit
pnpm run test:compile	编译测试到 .test-dist
pnpm test	编译并使用 Node test runner 执行测试
pnpm run compile	esbuild 生成 dist/extension.js
pnpm run test:bundle	对发布 Bundle 做加载冒烟检查
pnpm run verify	按顺序执行类型检查、测试、编译和 Bundle 检查
pnpm run watch	监听源码并重新打包
pnpm run package	完整验证后用 vsce 生成 VSIX

提交前至少运行：

pnpm run verify

调试扩展

1. 用 VS Code 打开 triforge-git 文件夹；
2. 运行 pnpm install；
3. 按 F5 启动 Extension Development Host；
4. 在新窗口打开一个测试仓库；
5. “输出”面板选择“TriForge Git”；
6. Webview 问题可运行“Developer: Open Webview Developer Tools”。

不要用真实生产 Token 调试未审查分支。为远程 API 测试使用权限受限、可随时撤销的测试账号与仓库。

测试关注点

现有测试覆盖的主要类别包括：

• Git porcelain/status、分支、remote、log、Diff 解析；
• 特殊字符 pathspec 与 shell-free 参数；
• HTTP 认证范围、重定向和脱敏；
• 三个平台 API 映射、分页、创建和 URL 校验；
• ConnectionStore 并发、修订与回滚；
• manifest 命令、视图、菜单与设置；
• Webview CSP、消息白名单、HTML 转义和配色回归；
• 侧栏布局与 Graph 平台标签；
• 打包 Bundle 的无 VS Code 主机加载。

不同平台文件系统行为仍需 OS CI/实机覆盖。Windows 无法创建的特殊文件名测试可能需要在 macOS/Linux 才能真正运行。

手工回归清单

本地 Git

• 空文件夹初始化与 unborn branch；
• 未跟踪/修改/删除/重命名/冲突；
• 单文件和全部暂存/取消暂存；
• Diff 两阶段；
• 首次提交与 Detached HEAD 保护；
• 本地/远程分支切换和同名冲突；
• 普通及强制分支删除确认；
• 四种 Merge 与冲突 continue/abort；
• Revert 和三种 Reset。

远程平台

• GitHub.com、GitLab.com、Gitea；
• 自建路径前缀；
• Token 过期、scope 不足和 401/403/404；
• 空查询/分页/取消/部分连接失败；
• 已有/缺失仓库组合；
• 公开/私有创建；
• 多平台部分成功与取消；
• remote 在等待期间被改址；
• LFS、子模块和 Hook 隔离提示。

UI 与兼容性

• 深色、浅色、高对比度；
• 窄侧栏与三视图拖动；
• 视图位置重置；
• 键盘、屏幕阅读器标签与 tooltip；
• Windows、macOS Intel/Apple Silicon、Linux；
• Remote SSH/WSL/Dev Container 扩展宿主。

版本发布

1. 更新 package.json 版本；
2. 更新 CHANGELOG.md；
3. 确认 README/Wiki 与实际功能一致；
4. 运行 pnpm run verify；
5. 运行 pnpm run package；
6. 解包检查 VSIX，不得包含源码密钥、测试凭据、无关缓存或原生未知二进制；
7. 在干净 VS Code Profile 安装冒烟；
8. 在受支持 OS 做真实 Git 测试；
9. 创建带版本号的 Git Tag/Release；
10. 发布后从最终下载物再次安装验证。

package 使用 --no-dependencies --allow-missing-repository。正式 GitHub 发布前仍应在 package.json 添加正确 repository、homepage 和 bugs 元数据，便于 Marketplace 和用户定位源码、Wiki 与 Issue。

Wiki 发布方式

docs/wiki/ 是 Wiki 内容源。GitHub Wiki 是独立的 <repository>.wiki.git 仓库；启用 Wiki 后，把这些 Markdown 页面复制到 Wiki 仓库根目录并提交。必须保留页面文件名和 _Sidebar.md，因为内部 Wiki 链接按目标页面文件名解析。

发布前检查：

• 所有 _Sidebar.md 链接都有对应页面；
• 版本号与扩展一致；
• 外部官方文档链接仍有效；
• 页面无 Token、内部账号或测试域名；
• GitHub 页面预览中的表格、代码块和中文标题正常。

贡献原则

• 不在错误、日志、测试快照里保留 Token；
• 新增网络目标必须定义明确 URL/协议/重定向策略；
• 新增 Git 命令使用参数数组，不拼 shell 字符串；
• 文件路径必须按字面量处理；
• 任何 Hard、Force、Discard 类动作都要二次确认和状态复核；
• 多步骤 UI 必须考虑等待期间仓库/连接状态变化；
• 修改 Webview 时保持 CSP、nonce、消息白名单和 HTML 转义；
• 修复安全问题时补回归测试和 CHANGELOG。