From b78b121a30d2b73e1f4515c1b702189478dd22b4 Mon Sep 17 00:00:00 2001 From: ajaycanvas Date: Wed, 28 Oct 2026 20:25:00 +0530 Subject: [PATCH] feat(code-review-kit): add code review, conventional commits and PR description plugin --- .../code-review-kit/.zcode-plugin/plugin.json | 19 ++++++ external_plugins/code-review-kit/README.md | 64 +++++++++++++++++++ external_plugins/code-review-kit/README_CN.md | 64 +++++++++++++++++++ .../code-review-kit/commands/commit.md | 28 ++++++++ .../code-review-kit/commands/pr.md | 21 ++++++ .../code-review-kit/commands/review.md | 35 ++++++++++ .../skills/code-review/SKILL.md | 53 +++++++++++++++ .../skills/conventional-commits/SKILL.md | 56 ++++++++++++++++ marketplace.json | 35 +++++++++- 9 files changed, 374 insertions(+), 1 deletion(-) create mode 100644 external_plugins/code-review-kit/.zcode-plugin/plugin.json create mode 100644 external_plugins/code-review-kit/README.md create mode 100644 external_plugins/code-review-kit/README_CN.md create mode 100644 external_plugins/code-review-kit/commands/commit.md create mode 100644 external_plugins/code-review-kit/commands/pr.md create mode 100644 external_plugins/code-review-kit/commands/review.md create mode 100644 external_plugins/code-review-kit/skills/code-review/SKILL.md create mode 100644 external_plugins/code-review-kit/skills/conventional-commits/SKILL.md diff --git a/external_plugins/code-review-kit/.zcode-plugin/plugin.json b/external_plugins/code-review-kit/.zcode-plugin/plugin.json new file mode 100644 index 0000000..3c39d92 --- /dev/null +++ b/external_plugins/code-review-kit/.zcode-plugin/plugin.json @@ -0,0 +1,19 @@ +{ + "name": "code-review-kit", + "version": "0.1.0", + "description": "Structured code review, conventional commits and PR descriptions performed by the agent on local git diffs. No API keys, no external services — the agent reads your diff, applies a severity-ordered checklist and reports actionable findings.", + "description_i18n": { + "en": "Structured code review, conventional commits and PR descriptions performed by the agent on local git diffs. No API keys, no external services — the agent reads your diff, applies a severity-ordered checklist and reports actionable findings.", + "zh-CN": "基于本地 git diff 的结构化代码评审、约定式提交信息与 PR 描述生成，全部由 agent 完成。无需 API 密钥、无需外部服务——agent 阅读你的改动，按严重程度逐项检查清单，并给出可执行的评审结论。" + }, + "author": { "name": "Ajay Sharma" }, + "keywords": [ + "code-review", + "git", + "commit", + "pull-request", + "conventional-commits" + ], + "skills": "./skills", + "commands": "./commands" +} diff --git a/external_plugins/code-review-kit/README.md b/external_plugins/code-review-kit/README.md new file mode 100644 index 0000000..8e7f090 --- /dev/null +++ b/external_plugins/code-review-kit/README.md @@ -0,0 +1,64 @@ +# code-review-kit + +[中文文档](./README_CN.md) + +Structured code review, commit messages and pull-request descriptions for ZCode — performed entirely by the agent on local git diffs. No API keys, no external services, no runtime dependencies: every capability is a skill or slash command that instructs the agent, so reviews run on any machine where ZCode runs. + +## What it does + +| Capability | How to invoke | What you get | +| --- | --- | --- | +| Code review | `/review` command, or just ask "review my changes" | Severity-grouped findings (`file:line — issue — why — fix`) and a merge verdict | +| Conventional commit | `/commit` command | A Conventional Commits message derived from the staged diff, checked for secrets and debug leftovers before committing | +| PR description | `/pr` command | Copy-ready PR title and body: summary, changes grouped by area, testing steps, risks | + +The `code-review` skill also triggers automatically whenever you ask ZCode to review a diff, check recent edits, or audit changes before committing. + +## How it works + +The agent is the reviewer. The commands and skill teach it a method: + +1. **Establish the change set** — staged diff, unstaged diff, or an explicit `base..head` range / branch / files. +2. **Read for context, not just diff** — full file around every hunk; callers are checked when a signature or behavior changes. +3. **Severity-ordered checklist** — 🔴 correctness and security (ship-blockers), 🟡 reliability, performance and test coverage, 🔵 maintainability. +4. **Actionable report** — one line per finding, explicit "no findings" per severity, and a final verdict on what must be fixed before merge. + +Reviews are read-only: nothing is modified unless you ask for fixes afterward. If the diff contains a secret, the report redacts it and advises rotating the credential. + +## Structure + +```text +code-review-kit/ +├── .zcode-plugin/ +│ └── plugin.json # Manifest (required) +├── commands/ +│ ├── review.md # /review — severity-grouped diff review +│ ├── commit.md # /commit — conventional commit from staged diff +│ └── pr.md # /pr — PR title and description +├── skills/ +│ ├── code-review/ +│ │ └── SKILL.md # Full review methodology (context-triggered) +│ └── conventional-commits/ +│ └── SKILL.md # Commit message format reference +├── README.md +└── README_CN.md +``` + +Component fields in the manifest (`commands` / `skills`) are declared explicitly and point at the standard paths above. + +## Usage examples + +```text +/review # review staged (or, if none, unstaged) changes +/review main..HEAD # review the whole branch against main +/review src/auth/ # review specific paths +/commit # stage-aware conventional commit +/pr # PR description vs the repo's default branch +/pr develop # PR description against a chosen base +``` + +The report language follows the conversation language; commit messages themselves stay in Conventional Commits form so tooling can parse them. + +## Privacy + +The plugin sends nothing anywhere. Diffs are read locally with git, and review output is produced in the session. Whether conversation content leaves your machine is governed by your ZCode/model-provider settings, not by this plugin. diff --git a/external_plugins/code-review-kit/README_CN.md b/external_plugins/code-review-kit/README_CN.md new file mode 100644 index 0000000..3667f92 --- /dev/null +++ b/external_plugins/code-review-kit/README_CN.md @@ -0,0 +1,64 @@ +# code-review-kit + +[English](./README.md) + +面向 ZCode 的结构化代码评审、提交信息与 PR 描述生成——完全由 agent 在本地 git diff 上完成。无需 API 密钥、无需外部服务、无运行时依赖：所有能力都以技能或斜杠命令的形式指导 agent 工作，因此任何能运行 ZCode 的机器都可以使用。 + +## 功能一览 + +| 能力 | 调用方式 | 输出 | +| --- | --- | --- | +| 代码评审 | `/review` 命令，或直接说"帮我评审改动" | 按严重程度分组的发现（`file:line — 问题 — 影响 — 建议修复`）与合并结论 | +| 约定式提交 | `/commit` 命令 | 基于暂存 diff 生成的 Conventional Commits 提交信息，提交前检查密钥泄露与调试残留 | +| PR 描述 | `/pr` 命令 | 可直接复制的 PR 标题与正文：摘要、按模块分组的变更、测试步骤、风险说明 | + +当你让 ZCode 评审 diff、检查最近的改动或在提交前审计代码时，`code-review` 技能也会自动触发。 + +## 工作原理 + +评审者就是 agent 本身。命令与技能教会它一套方法： + +1. **确定变更集** —— 暂存 diff、未暂存 diff，或显式指定的 `base..head` 区间 / 分支 / 文件。 +2. **读上下文，而不是只看 diff** —— 读取每个 hunk 周围的完整文件；签名或行为变化时检查所有调用方。 +3. **按严重程度排序的检查清单** —— 🔴 正确性与安全性（阻塞发布）、🟡 可靠性、性能与测试覆盖、🔵 可维护性。 +4. **可执行的报告** —— 每个发现一行，每个严重级别明确说明"无发现"，最后给出合并前必须修复的结论。 + +评审是只读的：除非你要求修复，否则不会修改任何文件。如果 diff 中出现密钥，报告会将其脱敏并建议轮换该凭据。 + +## 目录结构 + +```text +code-review-kit/ +├── .zcode-plugin/ +│ └── plugin.json # 清单（必需） +├── commands/ +│ ├── review.md # /review —— 按严重程度分组的 diff 评审 +│ ├── commit.md # /commit —— 基于暂存 diff 的约定式提交 +│ └── pr.md # /pr —— PR 标题与描述 +├── skills/ +│ ├── code-review/ +│ │ └── SKILL.md # 完整评审方法（按上下文触发） +│ └── conventional-commits/ +│ └── SKILL.md # 提交信息格式参考 +├── README.md +└── README_CN.md +``` + +清单中的组件字段（`commands` / `skills`）为显式声明，指向上述标准路径。 + +## 使用示例 + +```text +/review # 评审暂存改动（若为空则评审未暂存改动） +/review main..HEAD # 对照 main 评审整个分支 +/review src/auth/ # 评审指定路径 +/commit # 感知暂存状态的约定式提交 +/pr # 针对仓库默认分支生成 PR 描述 +/pr develop # 针对指定基础分支生成 PR 描述 +``` + +报告语言跟随对话语言；提交信息本身保持 Conventional Commits 形式（英文类型与主题），以便工具链解析。 + +## 隐私 + +本插件不向任何地方发送数据。diff 通过 git 在本地读取，评审输出在会话内生成。对话内容是否会离开你的机器由你的 ZCode / 模型服务方设置决定，与本插件无关。 diff --git a/external_plugins/code-review-kit/commands/commit.md b/external_plugins/code-review-kit/commands/commit.md new file mode 100644 index 0000000..104db81 --- /dev/null +++ b/external_plugins/code-review-kit/commands/commit.md @@ -0,0 +1,28 @@ +--- +description: Commit staged changes with a Conventional Commits message generated from the diff +--- + +Create a git commit for the currently staged changes. + +1. Run `git status --short` and `git diff --cached --stat`. + - If nothing is staged, show the user what is unstaged/untracked and ask which files to stage. Do not stage files on your own initiative. +2. Read the full staged diff (`git diff --cached`). Before proposing a message, check it for: + - Secrets (API keys, tokens, passwords, private keys, connection strings with credentials). If found: stop, warn, advise removing them and rotating anything already exposed. Do not commit. + - Debug leftovers (`console.log`, `debugger`, `print` debugging, commented-out code). Mention them; commit anyway unless the user says otherwise. +3. Compose the message in Conventional Commits format: `type(scope): subject`. + - Types: feat, fix, refactor, docs, test, perf, style, build, ci, chore. Pick the dominant change; use scope only when it is obvious (module or package name). + - Subject: imperative mood ("add", not "added"), max 72 characters, no trailing period. + - Body: only when the *why* is not obvious from the diff; wrap at 72 characters. + - Footer: `BREAKING CHANGE: ` when a public API or behavior contract changed. +4. Commit using a heredoc so quotes and newlines survive the shell: + ``` + git commit -m "$(cat <<'EOF' + (): + + + EOF + )" + ``` +5. Confirm with `git log -1 --stat` and report the hash, subject and file count. Explain the reasoning in the user's language; the commit message itself stays in Conventional Commits form (English type and subject). + +Never push, never amend without being asked, and never use `--force` or `--no-verify` unless the user explicitly requests it. diff --git a/external_plugins/code-review-kit/commands/pr.md b/external_plugins/code-review-kit/commands/pr.md new file mode 100644 index 0000000..d76b5c8 --- /dev/null +++ b/external_plugins/code-review-kit/commands/pr.md @@ -0,0 +1,21 @@ +--- +description: Generate a pull request title and description from the branch diff and commit history +argument-hint: [base branch] (defaults to the repo's default branch) +--- + +Generate a PR title and description for the current branch. + +1. Determine the base branch: the argument if given; otherwise `git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null` (strip the `origin/` prefix); fall back to `main`, then `master`. If none exist, ask the user. +2. Gather the material: `git log --oneline ..HEAD`, `git diff ...HEAD --stat`, then the full diff — read the full file wherever a hunk lacks context. +3. Write the PR body as markdown: + + - **Title** — one line in conventional style (`type(scope): summary`), max 72 characters, covering the dominant change rather than listing files. + - **Summary** — 2–4 sentences: what changed and why it matters to the product or the team. + - **Changes** — bullets grouped by area or module, each describing the concrete behavior change, not file names. + - **Testing** — how a reviewer verifies this: exact commands to run and their expected results. Note explicitly which paths are untested. + - **Risks & notes** — breaking changes, migration steps, follow-up work. Omit the section entirely if empty. + +4. Output the finished title and body as a copy-ready markdown block, written in the user's language (match the conversation). The title keeps Conventional Commits form. +5. Then offer next steps without executing them: create the PR with `gh pr create` if the `gh` CLI is available, or print the `git push` command with the right upstream. Push and PR creation happen only after the user confirms. + +Never push, and never create the PR, without an explicit confirmation from the user. diff --git a/external_plugins/code-review-kit/commands/review.md b/external_plugins/code-review-kit/commands/review.md new file mode 100644 index 0000000..d4790a2 --- /dev/null +++ b/external_plugins/code-review-kit/commands/review.md @@ -0,0 +1,35 @@ +--- +description: Review code changes for bugs, security issues and quality problems before they ship +argument-hint: [base..head | branch | file paths] (defaults to staged changes) +--- + +Review the code changes the user asked for. Do not modify any files — this is a review-only pass; fix things afterward only if asked. + +**Pick the target, in this order of precedence:** + +1. If arguments were given ($ARGUMENTS), use them: a `base..head` range, a branch name, a commit, or file paths. +2. Otherwise use staged changes: `git diff --cached`. +3. If that is empty, use unstaged changes: `git diff`. +4. If that is empty too, tell the user there are no changes to review and list what could be reviewed instead (recent commits via `git log --oneline -10`, local branches) — do not guess a target. + +**Method:** + +- Run the diff with enough context (`git diff -U10` or higher) and read the full file around every hunk. Never judge a hunk in isolation. +- When a function signature or behavior changed, check its callers across the repo before claiming it is safe. +- Apply the checklist below in severity order; ignore flagrant-only style rules unless the user asked for a style pass. + +**Checklist:** + +- 🔴 Correctness: logic errors, broken edge cases (null/empty/zero/huge input), off-by-one, wrong error handling, race conditions, resource leaks, breaking changes to public APIs. +- 🔴 Security: hardcoded credentials or tokens, SQL/command/XSS injection, path traversal, missing authorization checks, unsafe deserialization, secrets reaching logs. +- 🟡 Reliability & performance: unbounded loops or queries (N+1), hot-path allocations, missing timeouts/retries, swallowed errors, silent fallbacks that hide failures. +- 🟡 Tests: behavior changed without a corresponding test change; new code paths with no coverage. +- 🔵 Maintainability: misleading names, dead code, duplicated logic — only what a teammate would flag. + +**Output:** + +- Group findings under severity headings. Each finding on one line: `file:line — issue — why it matters — suggested fix`. +- For each severity with no findings, say so explicitly in one line. +- End with a verdict paragraph: overall risk, what must be fixed before merge, what can wait. +- Write the report in the user's language, matching the language of the conversation. +- If the diff contains a secret, redact it to its first 4 characters in the output, warn prominently at the top of the report, and advise rotating it. diff --git a/external_plugins/code-review-kit/skills/code-review/SKILL.md b/external_plugins/code-review-kit/skills/code-review/SKILL.md new file mode 100644 index 0000000..d803b9c --- /dev/null +++ b/external_plugins/code-review-kit/skills/code-review/SKILL.md @@ -0,0 +1,53 @@ +--- +name: code-review +description: Review code changes for correctness, security, performance and maintainability issues. Use when the user asks to review code, check a diff, look over recent edits, audit changes before committing, or find bugs in what changed. +--- + +# Code review methodology + +This skill is the full review method; the /review, /commit and /pr commands apply shorter versions of it. The reviewer is the agent itself — every conclusion must come from actually reading the code, never from pattern-matching the diff shape. + +## 1. Establish the change set + +- Staged changes: `git diff --cached`. Unstaged: `git diff`. Branch vs base: `git diff ...HEAD -U10`. +- Outside a git repository, review only the files the user named and say that repo-level checks (callers, history) were skipped. +- Note the change size up front. Over ~400 changed lines, review in passes: correctness first, then security, then everything else. + +## 2. Read for context, not just diff + +- Read the full file around each hunk; a hunk that looks fine in isolation is often wrong in context. +- When a function signature, return shape, or error behavior changes, grep for its callers and check each one. +- Check adjacent code the diff touches but does not show (initialization, cleanup, config) before declaring a bug or clearing one. + +## 3. Checklist, in severity order + +**🔴 Correctness (ship-blockers)** +- Logic errors and inverted conditions; edge cases: null/undefined/empty/zero/negative/huge input, unicode, concurrent access. +- Error handling: caught-and-swallowed errors, wrong error types, promises without rejection handling, missing timeouts. +- Resource leaks: files, connections, subscribers, locks not released on every path including the error path. +- Public API or persisted-data changes that break existing consumers. + +**🔴 Security (ship-blockers)** +- Hardcoded credentials, tokens, private keys; secrets interpolated into logs or error messages. +- Injection: SQL, shell, XPath, XSS (unsanitized output), path traversal on user-supplied paths. +- Missing authorization checks on new endpoints or actions; trusting client-side data. +- Unsafe deserialization; crypto misuse (weak algorithms, non-random IVs, homegrown schemes). + +**🟡 Reliability & performance** +- Unbounded work: N+1 queries, loops growing with request size, unpaginated list endpoints. +- Hot-path allocations, repeated recomputation of loop-invariant values. +- Missing retry/backoff on network calls; silent fallbacks that turn failures into wrong results. + +**🟡 Tests** +- Behavior changed with no test change; new branches with no coverage. Suggest the specific missing test case, not "add tests". + +**🔵 Maintainability** +- Misleading names, dead code, duplicated logic, magic constants. Only flag what a teammate would; skip personal style. + +## 4. Report + +- One line per finding: `file:line — issue — why it matters — suggested fix`. The fix must be concrete enough to act on. +- Group by severity; explicitly state when a severity has no findings. +- End with a verdict: overall risk, the short list that must be fixed before merge, what can wait. +- Write the report in the user's language, matching the language of the conversation. +- Review only. Do not edit files unless asked. If a secret appears in the diff, redact it to its first 4 characters, put the warning at the very top of the report, and advise rotation. diff --git a/external_plugins/code-review-kit/skills/conventional-commits/SKILL.md b/external_plugins/code-review-kit/skills/conventional-commits/SKILL.md new file mode 100644 index 0000000..23411e9 --- /dev/null +++ b/external_plugins/code-review-kit/skills/conventional-commits/SKILL.md @@ -0,0 +1,56 @@ +--- +name: conventional-commits +description: Write git commit messages in Conventional Commits format derived from the actual diff. Use when creating a commit, writing a commit message, or when the user asks for commit message help. +--- + +# Conventional Commits + +Format: `(): ` followed by optional body and footers. + +## Type — pick the one that describes the dominant change + +- `feat` — new user-visible capability +- `fix` — bug fix +- `perf` — performance change with no behavior change +- `refactor` — neither fixes a bug nor adds a feature +- `docs`, `test`, `style`, `build`, `ci`, `chore` — the obvious counterparts + +A change that both fixes and adds is `feat` if users would call the result new behavior, otherwise `fix`. + +## Subject + +- Imperative mood: "add filter", not "added filter" or "adds filter". +- Max 72 characters, no trailing period, no capitalization of the first letter beyond what a proper noun forces. +- Describe the change, not the symptom: "reject expired tokens in auth middleware", not "auth bugfix". + +## Scope + +Optional, in parentheses. Use it when the repository has natural module boundaries and the change is contained in one; omit it rather than inventing one. + +## Body + +Only when the *why* is not obvious from the diff. Explain motivation and trade-offs, wrap at 72 characters, blank line after the subject. + +## Breaking changes + +Either a `BREAKING CHANGE: ` footer or a `!` after the type (`feat!:`), never both. State what breaks and the migration path. + +## Examples + +``` +feat(search): support quoted phrases in query parser + +Queries like "error handling" now match the exact phrase instead of +any of the words, matching user expectations from the support tickets. +``` + +``` +fix(api): return 404 instead of 500 for deleted project ids + +Deleted projects were raising NotFoundError inside a generic handler +that mapped unknown errors to 500. +``` + +Derive the message from `git diff --cached` (or the range being committed), never from the file list alone — file names hide the actual behavior change. + +Explain your choices to the user in their language; the commit message itself stays in Conventional Commits form (English type and subject) so tooling can parse it. diff --git a/marketplace.json b/marketplace.json index 2fc615c..57723d2 100644 --- a/marketplace.json +++ b/marketplace.json @@ -1443,6 +1443,39 @@ "mcp", "verification" ] - } + }, + { + "name": "code-review-kit", + "source": "./external_plugins/code-review-kit", + "description": "Structured code review, conventional commits and PR descriptions performed by the agent on local git diffs. No API keys, no external services — the agent reads your diff, applies a severity-ordered checklist and reports actionable findings.", + "description_i18n": { + "en": "Structured code review, conventional commits and PR descriptions performed by the agent on local git diffs. No API keys, no external services — the agent reads your diff, applies a severity-ordered checklist and reports actionable findings.", + "zh-CN": "基于本地 git diff 的结构化代码评审、约定式提交信息与 PR 描述生成，全部由 agent 完成。无需 API 密钥、无需外部服务——agent 阅读你的改动，按严重程度逐项检查清单，并给出可执行的评审结论。" + }, + "version": "0.1.0", + "author": { + "name": "Ajay Sharma" + }, + "category": "developer-tools", + "keywords": [ + "code-review", + "git", + "commit", + "pull-request", + "conventional-commits" + ], + "examplePrompts": [ + "Review my staged changes before I commit", + "Review this branch against main and tell me what must be fixed before merge", + "Write a conventional commit message for what's staged" + ], + "examplePrompts_i18n": { + "zh-CN": [ + "在我提交之前评审暂存的改动", + "对照 main 评审这个分支，告诉我合并前必须修复什么", + "为暂存的改动写一条约定式提交信息" + ] + } +} ] } \ No newline at end of file