github-action.md

Codelens GitHub Action

在 CI 里跑代码健康门禁：健康分低于阈值、或相对基线分支出现回归时让 PR 变红，并把报告贴成 PR 置顶评论和 step summary。

快速开始

name: Code Health
on:
  pull_request:

permissions:
  contents: read
  pull-requests: write   # 贴 PR 评论需要

jobs:
  health:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0        # baseline 需要能解析到基线分支
      - uses: DropFan/codelens@rust
        with:
          health-model: 'v2'                            # 可选；默认仍为 v1
          fail-under: 'C'                                # 绝对阈值门禁
          baseline: 'origin/${{ github.base_ref }}'      # 回归门禁基线
          fail-on-regression: 'true'

效果：本次 PR 让任何文件的健康等级下降（例如 B → C），或项目等级下降时，检查失败并在 PR 评论里列出退步的文件；存量债务不会拦截 PR——只有这次改动引入的劣化才会。

输入

输入	默认	说明
path	.	要分析的路径（空格分隔多个）
version	latest	codelens 版本（release tag）。baseline 回归门禁需要 v0.1.5-rust 之后的版本；装到旧版时 Action 会明确报错而不是静默跳过门禁
health-model	空	可选 v1/v2；留空时读取 .codelens.toml，未配置则使用兼容默认值 v1
fail-under	空	绝对门禁：健康分低于该等级（A/B/C/D）或分数（0-100）时失败；v2 数据不足也会失败
baseline	空	回归基线 git ref（推荐 origin/${{ github.base_ref }}）
fail-on-regression	false	相对基线出现回归、或 v2 比较数据不足时失败
summary	true	报告写入 step summary
comment	true	贴/更新 PR 置顶评论（仅 pull_request 事件）

输出

输出	说明
score	项目健康分（0-100）
grade	项目健康等级（A-F）
assessment	评估状态：scored、insufficient-data，旧版本 CLI 无此字段时为 unknown
model	实际使用的评分模型（如 default、default-v2）
gate	passed / failed

健康分徽章

Action 每次运行都会生成 codelens-badge.json（shields.io endpoint 格式）。v2 数据不足时徽章显示中性的 insufficient data，不会把估算等级显示成绿色通过。把它发布到 gist 或 gh-pages，README 就能挂实时健康分徽章：

      - name: Update badge gist
        if: github.ref == 'refs/heads/main'
        env:
          GH_TOKEN: ${{ secrets.BADGE_GIST_TOKEN }}   # 需要 gist 权限
        run: gh gist edit <GIST_ID> codelens-badge.json

README 中引用：

![code health](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/<USER>/<GIST_ID>/raw/codelens-badge.json)

注意事项

• 浅克隆：actions/checkout 默认 fetch-depth: 1，用 baseline 时请设 fetch-depth: 0（Action 也会尽力补拉基线 ref，但完整历史最可靠）。
• 私有仓库：无需额外配置，二进制从公开 release 下载。
• PR 评论权限：fork 发起的 PR 上 GITHUB_TOKEN 是只读的，评论步骤会打一条 warning 后继续，不影响门禁结果；也可以直接关掉 comment 只用 step summary。