# WorkUtils 项目规则
# https://www.codebuddy.ai/docs/zh/IDE/User-guide/Workspace
version: 1

# ===== 项目信息 =====
name: workutils
description: WorkUtils API 文档生成工具

# ===== 规则定义 =====
rules:

  # 1. 导出目录 —— 禁止全文搜索
  - id: no-export-search
    description: |
      禁止对 export/ 目录进行搜索/读取操作。
      该目录包含导出的 HTML 文件，单文件可达数 MB，ripgrep 默认跳过超长行导致结果不准确。
    condition: "path starts with 'export/'"
    action: "reject"
    fallback: "如需调试导出结果，使用源码模板文件 (templates/apidoc/*.js) + 单元测试验证"

  # 2. 模板规范 —— 禁止 code-in-string 反模式
  - id: no-code-in-string
    description: |
      禁止在 JS 中用函数返回压缩字符串来重复已有代码。
      典型反模式：SNAPSHOT_JS() { return 'function sendDubboRequest(){...}' }
      这种方式导致：
        - 三层转义地狱 (JS字符串→HTML→JS参数)
        - 无法调试、无法 lint、无法语法高亮
        - 代码漂移：修改 api-doc.js 后快照版不会同步
      正确方式：window.__API_DOC_JS__ = {{JS_JSON}}; // 复用原文
    example: |
      # 错误示例
      function SNAPSHOT_JS() {
        return 'function sendDubboRequest(){var e=buildDubboBody();...}';
      }
      # 正确示例
      var mainJs = window.__API_DOC_JS__; // 由 Java 注入的 JSON
      var override = 'function getActiveDubboCard(){...}';
      var fullJs = override + '\n' + mainJs;
    enforcement: "warn"
    severity: high

  # 3. 占位符命名规范
  - id: placeholder-naming
    description: "模板占位符统一使用 {{NAME}} 格式，双大写加下划线"
    pattern: "\\{\\{[A-Z][A-Z0-9_]*\\}\\}"
    enforcement: "review"

  # 4. 大文件读取检查
  - id: large-file-check
    description: |
      读取 >500KB 文件前先检查行数和内容分布。
      超大文件（如压缩后的 JS/CSS、生成的 HTML）不适合直接读取全文。
    condition: "file.size > 500KB"
    action: "warn"
    suggestion: "使用 head/tail 检查文件结构，或使用单元测试验证行为"

  # 5. 转义函数集中管理
  - id: escape-centralized
    description: |
      HTML/JS/JSON 转义函数统一在 Java 侧或独立工具模块管理。
      避免在 JS 源码中混用多种转义方式（\\、\\\、\\'、' 等）。
    files: ["ApiDocGenerator.java"]
    enforcement: "review"

  # 6. Git 忽略大型产物
  - id: gitignore-export
    description: "export/ 目录应加入 .gitignore，避免提交大型产物文件"
    action: "suggest"
    suggestion: "echo 'export/' >> .gitignore"

  # 7. 复杂重构分步提交 —— 避免会话中断丢失工作
  - id: refactor-step-by-step
    description: |
      涉及 ≥4 个文件 或 ≥200 行变更 的复杂重构，必须分多个 commit 完成，避免单次会话中断丢失全部工作。
      典型场景：
        - 字段/类重命名（如 navButtons → navList）会触发多文件交叉引用更新
        - 组件替换（Button → ListView）涉及字段、方法、引用、样式、测试多文件
        - 框架/库升级涉及配置文件、依赖、调用点、文档
      推荐步骤：
        ① 第一步：加新常量/CSS/配置项（与旧实现共存）
        ② 第二步：替换实现/切换调用点
        ③ 第三步：删除旧代码（清理 commit）
      每步完成后提交，便于回滚。
    condition: "涉及文件数 >= 4 OR 变更行数 >= 200"
    action: "warn"
    severity: high

  # 8. AtlantaFX UI 防中断规则 —— 修改 MainWindow/Theme/CSS 时必读
  - id: atlantafx-ui-pitfalls
    description: |
      修改 MainWindow.java、Theme.java 或 light-theme.css 时，必须遵守以下规则，避免反复修改同一问题导致会话中断：

      【CSS 优先级】
      - AtlantaFX 的 .label 规则优先级极高，!important 也会被覆盖
      - 导航栏选中文字色：必须用 Java 代码 label.setTextFill(Color.WHITE)，不能靠 CSS
      - ListView 选中态：必须同时覆盖 .list-cell:selected（为空 cell 兜底）和 .list-cell:filled:selected（为非空 cell 设置激活背景）
      - 背景透明：需要完整覆盖 .list-view → .virtual-flow → .clipped-container → .sheet 全链路

      【ListView 虚拟化】
      - cell 会被 VirtualFlow 复用，updateItem(empty=true) 时必须清理自定义 style class
      - 不要用 getStyleClass().setAll()，会误删 JavaFX 内置 list-cell class；用 removeAll + add
      - 窗口 resize 时 cell 复用会暴露 empty cell 被 selected 的问题

      【布局】
      - 导航 ListView 用 VBox.setVgrow(ALWAYS) 撑满
      - refreshNavItems() 中不要重新设置 prefHeight/minHeight/maxHeight

      【修改后自检清单】
      ① 小窗口（菜单项少）→ 无滚动条，无底部蓝块
      ② 选中菜单 → 文字白色，背景蓝色，左侧蓝条可见
      ③ 最大化窗口 → 无额外蓝色块闪现，滚动条在导航栏底部
    files: ["MainWindow.java", "Theme.java", "light-theme.css"]
    action: "warn"
    severity: high

# ===== 触发提示 =====
# 当规则被触发时，AI 会看到这些提示
messages:
  no-export-search: |
    ⚠️ 检测到对 export/ 目录的操作。
    该目录包含导出的 HTML 文件（单文件可达数 MB），不适合搜索/读取。
    请改用源码模板文件 (src/main/resources/templates/apidoc/*.js) 进行调试。
  large-file-check: |
    ⚠️ 目标文件 >500KB，可能是压缩产物或大型导出文件。
    建议使用 head/tail 检查结构，或通过单元测试验证行为。
  refactor-step-by-step: |
    ⚠️ 检测到复杂重构（≥4 文件 或 ≥200 行）。
    建议分步提交：
      ① 第一步：加新常量/CSS（与旧实现共存）
      ② 第二步：替换实现/切换调用点
      ③ 第三步：删除旧代码
    每步完成后 git commit，避免会话中断丢失工作。