# 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"

# ===== 触发提示 =====
# 当规则被触发时，AI 会看到这些提示
messages:
  no-export-search: |
    ⚠️ 检测到对 export/ 目录的操作。
    该目录包含导出的 HTML 文件（单文件可达数 MB），不适合搜索/读取。
    请改用源码模板文件 (src/main/resources/templates/apidoc/*.js) 进行调试。
  large-file-check: |
    ⚠️ 目标文件 >500KB，可能是压缩产物或大型导出文件。
    建议使用 head/tail 检查结构，或通过单元测试验证行为。