Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions .agents/plugins/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,20 +9,20 @@
"source": {
"source": "url",
"url": "https://github.com/partme-ai/partme-codeguard-plugin.git",
"ref": "v0.14.6"
"ref": "v0.14.7"
},
"policy": {
"installation": "AVAILABLE",
"authentication": "ON_USE"
},
"category": "Developer Tools",
"version": "0.14.6",
"version": "0.14.7",
"description": "Evidence-backed code checks and Git content gates for AI assistants, with Maven/Gradle module impact analysis. Save hooks provide feedback; unverified checks are explicit.",
"icon": "https://cdn.jsdelivr.net/gh/full-stack-plugins/codeguard-plugin@v0.14.6/assets/official-logo.png",
"icon": "https://cdn.jsdelivr.net/gh/full-stack-plugins/codeguard-plugin@v0.14.7/assets/official-logo.png",
"interface": {
"displayName": "代码规范守卫",
"shortDescription": "Trustworthy code checks and Java impact analysis",
"logo": "https://cdn.jsdelivr.net/gh/full-stack-plugins/codeguard-plugin@v0.14.6/assets/official-logo.png"
"logo": "https://cdn.jsdelivr.net/gh/full-stack-plugins/codeguard-plugin@v0.14.7/assets/official-logo.png"
}
}
]
Expand Down
2 changes: 1 addition & 1 deletion .codex-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "codeguard",
"version": "0.14.6+codex.20260923",
"version": "0.14.7+codex.20260923",
"description": "Evidence-backed code checks and Git content gates for AI assistants, with Maven/Gradle module impact analysis. Save hooks provide feedback; unverified checks are explicit.",
"author": {
"name": "Full Stack Skills / PartMe.AI",
Expand Down
2 changes: 1 addition & 1 deletion .zcode-plugin/plugin.json
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
"en": "CodeGuard",
"zh-CN": "代码规范检查"
},
"version": "0.14.6",
"version": "0.14.7",
"description": "Evidence-backed code checks and Git content gates for AI assistants, with Maven/Gradle module impact analysis. Save hooks provide feedback; unverified checks are explicit.",
"description_i18n": {
"en": "Evidence-backed code checks and Git content gates for AI assistants, with Maven/Gradle module impact analysis. Save hooks provide feedback; unverified checks are explicit.",
Expand Down
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ The installed plugin version is recorded in its manifests. The architecture refa
| PostToolUse | Edited file, for file-scoped tools | Feedback, exit 0; project-level checks deferred |
| UserPromptSubmit | Working-tree changes relevant to commit intent | Advisory, never blocks the user message |
| PreToolUse Git gate | Proposed index snapshot or HEAD snapshot for push | Verified violations exit 2; uncertain checks report UNVERIFIED and fail open |
| CLI check / MCP check_code_style | Project checks, including Java build verification | Explicit status, reason, raw exit code and output log |
| CLI check / MCP check_code_style | Project checks, including Java build verification | Explicit status, reason, raw exit code, ordered execution trace and output log |
| pre-commit / CI | Independently configured checks | Separate acceptance; not replaced by hook success |

Hooks do not run in every host command surface automatically. Historical V0.5.4 installation evidence is not acceptance of this version in Codex, ZCode or Kimi.
Expand Down Expand Up @@ -107,12 +107,12 @@ python3 scripts/run_check.py --mcp /path/to/project

| Tool | Contract |
|---|---|
| check_code_style | Per-language status/reason/passed/raw exit code and full output log path |
| check_code_style | Per-language status/reason/passed/raw exit code, per-command status metadata and full failure log path |
| auto_fix | Format Git-changed files and recheck the same scope; refuse unbounded project formatters; fixed means actual modifications |
| list_languages | Registry ids and display names |
| analyze_java_impact | Read-only plan; accepts path and optional changed array |

Output logs default to <project>/out/.codeguard-last.log; CLI --quiet disables log writing. MCP auto_fix does not write when a Git scope cannot be established.
Output logs default to <project>/out/.codeguard-last.log; CLI --quiet disables log writing. A failed multi-command check logs output from every executed check. The MCP execution trace reports phase, sequence, program, exit/failure and output lengths; it does not echo argv, environment overrides or captured output. Local logs can contain sensitive checker output: keep them out of version control. MCP auto_fix does not write when a Git scope cannot be established.

## Configuration and coverage

Expand Down
6 changes: 3 additions & 3 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ CodeGuard 为 AI 编程助手提供原生检查证据,守护已支持的 Git
| PostToolUse | 文件型工具检查本次编辑文件 | 反馈、exit 0;项目级检查延后 |
| UserPromptSubmit | 与提交意图相关的工作树变更 | 建议,不阻断用户消息 |
| PreToolUse Git 门禁 | 拟提交 index 快照或推送 HEAD 快照 | 确定违规 exit 2;不确定项明确 UNVERIFIED 并 fail-open |
| CLI check / MCP check_code_style | 项目检查,含 Java 构建验证 | 明确状态、原因、原始退出码和日志 |
| CLI check / MCP check_code_style | 项目检查,含 Java 构建验证 | 明确状态、原因、原始退出码、顺序执行证据和日志 |
| pre-commit / CI | 独立配置的检查 | 单独验收,不能由钩子成功代替 |

钩子不会自动覆盖宿主的每个命令入口。历史 V0.5.4 安装证据不能代表当前版本已在 Codex、ZCode、Kimi 验收。
Expand Down Expand Up @@ -107,12 +107,12 @@ python3 scripts/run_check.py --mcp /path/to/project

| 工具 | 契约 |
|---|---|
| check_code_style | 逐语言状态、原因、passed、原始退出码与完整日志路径 |
| check_code_style | 逐语言状态、原因、passed、原始退出码、逐命令状态元数据与完整失败日志路径 |
| auto_fix | 只修 Git 改动文件、同范围复检,拒绝无界项目 formatter;fixed 表示实际修改 |
| list_languages | 注册表语言标识和名称 |
| analyze_java_impact | 只读计划,接受 path 和可选 changed 数组 |

日志默认在 <project>/out/.codeguard-last.log;CLI --quiet 关闭写日志。MCP auto_fix 无法确定 Git 范围时不会写入。
日志默认在 <project>/out/.codeguard-last.log;CLI --quiet 关闭写日志。多命令检查失败时,日志保存每条已执行检查的完整输出。MCP 执行轨迹只返回阶段、序号、程序名、退出/故障及输出长度,不回显 argv、环境覆盖或检查器输出。本地日志可能含敏感文本,应排除出版本控制。MCP auto_fix 无法确定 Git 范围时不会写入。

## 配置与覆盖

Expand Down
1 change: 1 addition & 0 deletions docs/current-architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ flowchart TD
```

`execution` 只记录进程证据,不把非零退出自动认定为代码违规。`verdict`、CVE 与 Dockerfile 报告解析决定 PASS、FAIL 或 UNVERIFIED;入口仅按各自协议呈现和聚合退出码。Git 提交检查使用 index 或预测暂存快照,推送检查使用 HEAD;保存钩子只给反馈。计划、未执行和未验证不能宣传为通过。
`language_check` 将 `PlanExecution` 的实际命令依序映射为应用层有界 `execution_trace`(检查、修复、复检阶段);`check_application` 将其进一步压成 MCP 安全元数据,不回显原始 argv、环境覆盖或捕获输出。失败日志保留各已执行检查的完整输出,可能含敏感文本,应排除出版本控制。终止命令仍决定既有状态、退出码和旧字段;未运行的计划命令不进入证据。
Git 命令的仓库定位与拟暂存解析共用入口传入的 cwd;显式 `cd`/`git -C` 无法绑定 Git 工作树时,硬门禁给出目标未验证并阻断,不退回到调用者仓或无关子仓。未给出显式目标且调用目录非仓时仍保留 workspace 子仓兜底。静态命令解析不等于完整 Shell 执行模拟。
一条命令链中的 Git 副作用先绑定为仓库与操作的有序对,再按仓库聚合检查面:纯 push 不读取该仓未提交的 index,同仓 commit→push 则保留已有 HEAD 与拟提交内容的并集。仓库级、内联及链式 `skipGate` 均按目标仓与操作顺序生效;已存在的仓库配置也可被同链先行 `git config --unset` 取消。链式设置跨 `||`、`;` 或换行时无法证明生效,门禁要求拆分命令;写入其它文件的 config 设置也不构成本仓豁免。语法、仓库归属、间接脚本与拟暂存分析共用引号/转义感知切分;参数文本中的控制符不能合成豁免。解析能力仍限于受支持的静态 Shell 形态。
一层 `bash`/`sh`/`zsh` 的 `-c`(含组合短选项)及可读脚本现在携带调用目录与正文进入同一 Git 操作计划;脚本内的 `git add` 可进入拟暂存范围,外层和内层 Git 操作按仓分别检查。识别到无法建模的间接 Git 操作、脚本内 `skipGate` 配置变更或跨解释器的暂存/提交关系时,明确以 Git 意图 UNVERIFIED 阻断,不借用调用者仓的检查结果。动态脚本、任意控制流及 Python/Node 中构造的 subprocess 仍未建模。
Expand Down
2 changes: 1 addition & 1 deletion kimi.plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "codeguard",
"version": "0.14.6",
"version": "0.14.7",
"description": "Evidence-backed code checks and Git content gates for AI assistants, with Maven/Gradle module impact analysis. Save hooks provide feedback; unverified checks are explicit.",
"author": {
"name": "Full Stack Skills / PartMe.AI"
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -45,11 +45,20 @@
### Requirement: Check plans SHALL retain execution context

检查计划 MUST 显式区分 repo、delta 与 save,保存物化后的命令、工作目录和逐命令环境覆盖。执行 MUST 按序进行,首个非零结果终止普通检查批次,保留已执行证据;未执行的命令不得计为成功。空计划不得生成 PASS。Java 原生计划给出的环境覆盖 MUST 在子进程中生效,不改变宿主环境。修复后的检查 MUST 复用原计划,不重新扩大范围。Git 门禁的逐文件基线豁免是独立策略,不由通用执行器决定。
语言检查与修复的应用结果 MUST 保留实际运行的每条命令身份、目录、退出码、故障标识和有界输出摘要;MCP 适配不得只保留终止命令,但其公开执行轨迹 MUST 只包含阶段、序号、程序名、退出码、故障标识和输出长度,不得新增暴露原始 argv、命令环境覆盖或任意检查器输出。失败日志 MUST 保留同一检查批次中此前已执行命令的完整输出,不能只记录最后一条。证据不得把尚未运行的计划命令写成已执行。

#### Scenario: Java commands use the selected JDK
- **WHEN** Java 项目计划选择 JAVA_HOME,且声明多条权威检查命令
- **THEN** 每条实际运行的命令使用该环境;后续命令失败时返回失败而非首条成功,宿主 JAVA_HOME 不变

#### Scenario: Multi-command result retains prior execution evidence
- **WHEN** Java 权威计划的第一条命令输出诊断后通过,第二条命令失败,第三条未执行
- **THEN** 内部检查结果保留前两条的 argv、目录、退出码、有界输出摘要和故障标识;MCP 返回对应的安全元数据与失败日志路径,不回显原始参数或输出;第三条不得出现于执行证据

#### Scenario: Configured command includes a credential argument
- **WHEN** 权威命令的 argv 含凭据文本,且检查器输出也包含该文本
- **THEN** 真实子进程仍收到原始 argv,MCP 的 `check_code_style` 和 `auto_fix` 执行轨迹不回显凭据;日志仍按既有本地路径保存原始诊断

#### Scenario: Repair retains the original scope
- **WHEN** delta 或 save 检查失败并成功运行 formatter
- **THEN** 复检执行原物化命令,仅包含原检查范围;被跳过的文件不导致漏掉其它文件的复检
Expand Down
2 changes: 1 addition & 1 deletion openspec/changes/refactor-codeguard-architecture/tasks.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,5 +34,5 @@
- [x] 5.2 四个历史 skipped 已全部恢复;Dockerfile CLI 接入统一报告解析与扫描应用,14 项真实进程边界测试通过;基线比较按诊断内容和次数核验并要求基线实际 FAIL,三项误豁免用例先红后绿。完整 433 项单测零跳过、142 项回归零失败。
- [x] 5.3 新增当前架构 Mermaid 与扩展指南;报告版本读取插件 manifest,双语 README 指向当前证据,旧设计标明历史范围;双语标题/链接/版本及本地链接存在性测试通过。发布版本仍需在 5.5 检查。
- [x] 5.4 全量单测/真实 hook 回归/ruff/语言 schema/vendor 离线与在线/本 change strict 和逐条规格追溯通过;第二十批 500 项单测、143 项真实 Hook 回归、57 项/11 规则,证据见 verification.md。仅证明本地契约,不等同三宿主现场验收。
- [ ] 5.5 按仓规升级版本、生成市场元数据、授权的 PR/CI/不可变 tag/Release 闭环;第十九批已发布 v0.14.5(插件 PR #51、市场 PR #8、PR/main CI、注释 tag/正式 Release 均核对)。第二十批已准备 v0.14.6 元数据与本地验证,远端 PR/CI/tag/Release/市场主线仍待核对。宿主安装运行独立记录,未授权不得改宿主。
- [ ] 5.5 按仓规升级版本、生成市场元数据、授权的 PR/CI/不可变 tag/Release 闭环;第二十批已发布 v0.14.6(插件 PR #52、市场 PR #9、源码 PR/main CI、注释 tag/正式 Release 均核对;市场 PR 无 CI 检查)。第二十一批新增的逐命令证据仍只在本地,需独立升级版本并发布。宿主安装运行独立记录,未授权不得改宿主。
- [ ] 5.6 完成全目标审计,代码/规格/证据一致后同步并归档 change,才可将整体优化标记完成。
10 changes: 10 additions & 0 deletions openspec/changes/refactor-codeguard-architecture/verification.md
Original file line number Diff line number Diff line change
Expand Up @@ -213,3 +213,13 @@
- `/opt/anaconda3/bin/python3` 3.13.5 完整执行 **498 unittest、0 skipped**;真实 Hook 回归 **143/0/0**。Ruff、架构门禁、语言 schema **57 项/11 规则**、vendor 离线与在线、本 change strict、diff whitespace 均通过。CodeGraph 的 `affected` 对本次核心文件返回空,但真实目标测试存在且已运行,故不把空图谱结果当无影响证明。受管技能和 lock 未改;本批尚未版本升级、提交或发布,三宿主现场/Windows/在线漏洞库仍未验收。
- 同步最新 CodeGraph 后继续追踪 `git_syntax` 发现:`inline_skip_gate` 和 `skip_gate_config_change` 仍用原始空白分词,与已共用的直接 Git/解释器前缀语义分叉。真实仓库 RED 证明已有持久 `skipGate=true` 时,`env FOO=1 git config codeguard.skipGate false && git commit` 被错误放行;带前缀的 `git -c` 单次豁免则被错误阻断且失去审计。二者现复用同一 `_segment_tokens`,目标测试转绿;此证据补充前述批内回归,不将早先 498 项计数当最终全量结果。
- 最终本地完整回归:`/opt/anaconda3/bin/python3` 3.13.5 执行 **500 unittest、0 skipped**,真实 Hook **143/0/0**;Ruff、架构门禁、语言 schema **57 项/11 规则**、vendor 离线与在线、本 change strict、diff whitespace 均通过。两项新 RED 场景及既有豁免/引号边界均转绿。本批已准备 v0.14.6 元数据;在 PR/CI/tag/Release/市场主线核对前,不能用 v0.14.5 的证据证明新改动已发布。

- 第二十批随后发布为 v0.14.6:源码 PR #52 合并为 `e32b10648b2d3e048b30ee6fc04f7945affa44fc`,市场 PR #9 合并为 `9430df2e24095dbb50eb65dde3e9df670853c9e8`;源码 PR 和合并后 main 的 `skills-check` 成功,远端注释 tag 解引用到源码 main 合并提交,GitHub Release 非 draft、非 prerelease。市场三宿主清单与 README 导航同步到 0.14.6,合并后远端 tag/Release 校验通过;市场 PR 没有报告 CI 检查,不能声称市场 CI 已通过。此发布不覆盖以下第二十一批工作树。

## 第二十一批实际验证:逐命令执行证据不在应用层丢失

- 将 v0.14.6 的当前源码同步到临时 CodeGraph 索引(136 文件;源仓未初始化索引),沿 `execute_plan → language_check.run_check/run_fix → check_application.result_envelope` 追踪。内核 `PlanExecution` 保留全部已执行命令,但应用只读取 `terminal`;Java 第一条命令通过并输出诊断、第二条失败时,前者从结果和失败日志消失。真实 Python 子进程测试先 RED(缺少 `execution_trace`),不是模拟返回值。
- 语言检查现保留检查、修复和复检各阶段的实际命令、目录、退出码、故障标识及有界 stdout/stderr 尾部;MCP 的既有字段不变,附加逐命令安全元数据。失败日志记录所有已执行检查的完整输出,未执行的第三条命令不进入证据。Java 选定的 `JAVA_HOME` 进入子进程但不出现在公开 trace,宿主环境不变;`.zsh` 仍跳过 formatter,但修复后的复检保持原范围。
- 真实 MCP stdio RED 复现:`codeguard.json` 权威命令中的哨兵 token 经原始 argv 和检查器输出进入新增轨迹,扩大了公开面。`check_application` 现将 `check_code_style` 与 `auto_fix` 的新增轨迹压成阶段/序号/程序名/退出与故障/输出长度,不回显 argv、环境覆盖或输出文本;原始证据仍由内部执行结果和本地失败日志保留。后者可能含敏感内容,文档明确要求排除版本控制,不宣称日志已脱敏。
- 新目标测试经真实 `mcp_tool_payload` 路径转绿;进一步通过官方 MCP SDK 的 stdio 客户端从 `check_code_style` 收到两条实际命令状态与完整失败日志路径,token 未出现在 JSON 响应。加入 `auto_fix` 轨迹收敛测试后完整本地单测 **503/503、0 skipped**,Hook 回归 **143/0/0**,Ruff、架构门禁、语言 schema **57 项/11 规则**、vendor 离线/在线、本 change strict 与 diff whitespace 通过。受管技能与 lock 未改;这仍是本地证据,当前发布的 v0.14.6 不含本批修改,三宿主安装现场、真实 Maven/Gradle、在线漏洞库及 Windows 未验收。
- 宿主安装登记只读抽查:本机 ZCode 的 `installed_plugins.json` 将 `codeguard@full-stack-plugins` 指向 `v0.12.1` 与其缓存目录;它不能证明 v0.14.6 或本批在 ZCode 的加载/触发。当前抽查的 Codex/Kimi 缓存路径未提供当前版证据,但不能据路径缺失推断所有宿主环境均未安装。宿主安装和真实加载需在后续有权限的独立验收中验证,不由源码测试、市场 ref 或旧缓存替代。
Loading
Loading