模块边界与文件长度维护

返回文档导航 · 技术架构

字段定义排版

• 接口、对象类型字面量和类的字段每行只定义一个。
  • 类型别名、嵌套类型、函数参数和返回值中的内联类型遵循相同规则。
  • 含多个字段的定义展开为多行，避免用分号或逗号将多个字段挤在同一行。
  • 单字段内联类型可以保留单行；运行时对象初始化不属于本次字段声明排版范围。
• 2026-10-12 已统一调整主进程、渲染层、托管服务、脚本、类型声明及测试中的同类定义。
  • 仅修改换行和缩进，保留字段名称、类型、修饰符、可选标记及原有注释。
  • 使用语法树扫描确认没有同一声明体中相邻字段共用一行的遗漏，并使用解析器比对修改前后的代码 token 和注释。
  • 验证通过：类型检查、lint（含文件长度门禁）及 688 项单元测试；此排版调整无需重启应用或服务。

字段排版后的集中提取安排

• 2026-10-12 合并 format 分支时解决 7 个冲突文件。

  • 保留本地设置持久化、热键事务、Quick Cmd Form 设置入口和逐文档视图状态逻辑，同时应用字段逐行排版。
  • 冲突文件经 TypeScript 语法树及注释比对确认与合并前 master 逻辑一致。
  • 合并后 test/electron-smoke.ts 为 1097 行，test/menu.test.ts 为 963 行，继续纳入下述独立、集中的测试模块提取安排。
  • 类型检查、全仓 lint（含文件长度门禁）和 693 项单元测试通过。
  • 快捷键设置（含命令面板）、工作区会话恢复及 Quick Cmd Form 三组 Electron 冒烟测试通过。

• 本次调整后，以下改动文件超过 800 行；它们位于现有长度门禁排除的测试目录。

  • test/electron-smoke.ts：1088 行。
  • test/menu.test.ts：963 行。

• 后续安排一次独立、集中的测试模块提取，不在本次排版中混入结构调整。

  • test/electron-smoke.ts 按场景准备、窗口访问和场景调度职责整理，复用现有 test/smoke/ 模块。
  • test/menu.test.ts 按菜单构造、命令执行和可用性检查分组，保留共享测试替身与断言。
  • 提取时保留原有覆盖范围、错误处理、注释及测试入口，并运行相关测试验证。

集中提取范围

• 本轮集中处理 src/ 和 server/ 中超过 500 行的 20 个生产文件。
• 当轮提取后的生产文件均不超过 500 行，给当时的 600 行检查上限预留空间。
• 测试场景和长篇专题文档保留原有组织；未通过删减测试、注释或功能说明缩短文件。
• 保留公开类、函数接口、日志、异常处理和持久化格式。
• 当前 scripts/quality/file-length.mts 执行 800 行上限，排除 Markdown、测试目录及指定生成物；下文的 500/600 行和测试长度是对应提取或迁移时的记录，不代表当前门禁。

主进程与托管服务

• 客户端继续由目录入口组合方法分组。
• 工作区管理器、同步管理器和托管存储将提取的方法描述符复制到原有公开类原型。
  • 调用者仍使用原来的实例和方法。
  • 不增加代理包装，不复制实例状态。
• 原有同步入口的按需加载保持不变。

渲染层

初始化与加载顺序

• Runtime 已统一为 ESM；renderer.mts 显式导入业务模块，并按原有顺序调用初始化函数。
• runtime/state.mts 集中管理窗口状态，runtime/types.mts 共享类型；业务函数使用命名导入。
• runtime/keyboard.mts 集中注册应用命令及默认快捷键。
• runtime/keyboard-dispatch.mts 保留界面辅助函数、服务初始化、上下文、提示和事件分发。
  • 注册回调仅保存函数，不在注册阶段调用其他模块中的界面辅助函数。
  • 所有默认绑定均在创建 KeybindingService 前收集完成。
• ESLint 和 TypeScript 逐模块检查 runtime；原有拼接 lint 与 classic 加载机制已移除。
• 启动时同步挂载对话框，然后创建界面辅助对象并初始化 runtime。
  • 这些节点在启动时就被查找和绑定事件，因此不改为首次打开时加载。
  • 对话框的 ID、结构、属性及 DOM 顺序保持不变。
• 快捷键设置、命令面板、Mermaid、大纲解析和文件打包继续使用原有动态导入。
• document.css 紧随 base.css 加载，保持原有规则顺序；独立布局测试也使用相同顺序。

文件树职责收拢（2026-10-11）

• runtime/tree-view.mts 接收原 tree-controls.mts 的可见性、遍历和整体渲染逻辑。
  • 同时接收 context-menus.mts 的节点渲染与树内键盘导航，以及 dialogs.mts 的路径定位和当前文档关联逻辑。
  • 全部展开与折叠按钮事件随树视图初始化，不再在 surface-events.mts 中注册。
• runtime/tree-difference-form.mts 接收原编辑器模块中的差异表单、校验、草稿、持久化转换、状态文案、重置和循环切换逻辑。
  • 表单字段初始化与事件绑定一起迁入，编辑器模块保留差异展示、基线读取和 Git HEAD 刷新。
• tree-controls.mts 保留标题控件、筛选应用与设置交互，并接收原全局事件中的弹层外部点击关闭行为。
• 原模块保留迁移函数的命名再导出，生产调用者和相关冒烟测试直接引用新所属模块。
  • 迁移函数保留原函数正文、注释、错误处理、焦点恢复和仓库切换保护。
  • 新模块启动时同步初始化；文件打包仍按需加载。
• 初始化覆盖测试同步检查新增模块，以及编辑器状态、差异表单、树控件和工作区恢复的先后关系。
• 本次涉及的生产文件均不超过 600 行。
  • test/smoke/renderer/tree-heading.ts 仍为 692 行，本次仅更新导入路径。
  • 继续纳入下文既有的测试模块集中提取安排，保留场景、断言和时序。
• 验证结果：类型检查、全仓 lint 与文件长度检查通过；32 个迁移函数的正文与迁移前一致。
  • 模块初始化、文件遍历、组合筛选和时间解析共 16 项相关单元测试通过。
  • tree-heading、tree-multiselect、keyboard、file-pack、command-palette 和 workspace-session 六组 Electron 冒烟测试通过。
  • 清理构建遇到 .build 目录占用后，使用现有增量构建入口完成编译，再串行运行上述冒烟测试。

验证入口

• npm run check:file-length：检查人工维护的生产文件长度。
• node scripts/run.mts node --test test/module-extraction.test.js：检查 runtime 初始化覆盖和顺序，以及公开类的方法描述符。
• npm run test:unit：覆盖工作区查询、菜单、同步预览、合并、恢复、账号和仓库事务。
• npm run test:smoke：覆盖完整 Electron 初始化、编辑、布局、粘贴、片段窗口和文件树交互。
• npm run pack：验证构建后的应用目录包含提取模块。

本轮验证结果

• 532 项单元测试通过，文件长度检查通过；人工维护的生产文件最长为 498 行。
• Windows 目录打包通过，并逐字节核对新增客户端模块和查找控制器已进入 app.asar。
• 原有注释保留；51 个提取的类方法与修改前的方法正文一致。
• lint 仍受修改前已有的三项规则错误阻塞：收藏排序重置函数未使用、快捷键正则多余转义、链接镜像正则中的控制字符。
• 完整 Electron 冒烟测试在 editorFindVisibleQueryPreservesScroll 断言失败；修改前代码在同一环境中也复现了该失败。
  • 原有测试与查找行为保持不变，不在模块提取中修复这项独立问题。
  • 在临时测试副本中仅跳过该断言后，其余完整 Electron 流程通过；临时副本不进入仓库。

全量测试修复后的集中提取安排

ESM renderer 迁移后的集中安排

• 本次修改后仍超过 600 行的测试保留现有场景顺序，纳入下一次统一提取。
  • test/smoke/renderer/document-outline.ts：611 行，按大纲展示、筛选和导航分组。
  • test/smoke/renderer/tree-heading.ts：692 行，按文件树标题操作、筛选与控件交互分组。
• 提取时复用测试专用的 ESM 访问适配器和现有辅助函数，保留断言、注释、日志与原有时序。
• 这些测试与下列 TypeScript 迁移遗留测试一起安排，避免每次功能修改单独拆分。
• 本次修改的生产文件均未超过 600 行。

TypeScript 迁移后的统一后续工作

• 将本次迁移涉及的以下测试纳入同一次独立模块提取，迁移本身保留现有组织和断言顺序。

  • test/electron-smoke.ts、test/paste-undo-smoke.ts、test/snippet-window-smoke.ts。
  • test/smoke/renderer/document-outline.ts、test/smoke/renderer/initial-editor-flow.ts、test/smoke/renderer/tree-heading.ts。
  • test/menu.test.ts、test/sync-client.test.ts。

• 按现有场景边界复用 test/helpers/ 与 test/smoke/，保持按需加载、日志、注释、IPC 和剪贴板串行约定。

• 集中提取完成后重新运行严格类型检查、单元测试与全部 Electron 冒烟。

• package-lock.json 是依赖管理生成文件，记录最终行数，但不安排人工拆分。

• 后续单独集中提取 test/electron-smoke.ts、test/paste-undo-smoke.ts 与 test/smoke/renderer/document-outline.ts 的场景模块。

• 本次先保留测试入口、断言顺序、共享剪贴板串行执行、注释与诊断日志。

• 复用现有 test/smoke/renderer/ 和 test/helpers/ 边界，按场景按需加载，不为每项修复新增模块。

• 2026-10-08 冒烟修复、收集器初始化及错误弹窗场景隔离后的 test/electron-smoke.ts 为 1055 行，继续纳入上述独立集中提取安排。

• 2026-10-08 合并冲突解决后，test/electron-smoke.ts 为 1046 行；沿用上述集中提取安排，保留单一收集器初始化及原有专项退出分支。

全项目注释规范后的集中安排

• 2026-10-11 补充文件头、函数定义说明与定义间空行后，以下测试文件超过当前 800 行阈值。
  • test/electron-smoke.ts：1082 行，保留现有启动、窗口协调与专项退出顺序。
  • test/menu.test.ts：945 行，保留原生菜单替身与各平台命令断言。
• 两个文件一并纳入独立的集中模块提取，不在本次注释调整中逐项拆分。
  • 菜单测试按窗口、文件、编辑与快捷键场景整理，复用共用的菜单和窗口替身。
  • Electron 冒烟入口复用现有 test/smoke/ 场景边界，保持共享 IPC、剪贴板和窗口初始化顺序。
  • 提取时保留注释、日志、断言及错误处理，完成后运行类型检查、单元测试和相关 Electron 冒烟。

全项目格式整理后的集中安排

• 2026-10-12 按 120 字符行宽整理源码后，以下生产文件超过 800 行。
  • src/index.html：836 行。
  • src/main/workspace-handlers.ts：804 行。
  • src/renderer/runtime/editor/selection-toolbar.mts：930 行。
  • src/renderer/runtime/keyboard.mts：1104 行。
  • src/renderer/styles/dialogs.css：975 行。
  • src/snippet.mts：965 行。
  • types/markdown-api.d.ts：833 行。
• 将这些文件纳入独立的集中模块提取，按现有功能边界分组并保留运行顺序与公开类型。
• 提取完成后运行文件长度检查、类型检查、单元测试和相关 Electron 冒烟。