diff --git a/README.md b/README.md index 0aa8b32..6086d4a 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@

diffnote

Turn local Git changes into a reviewable pull request summary.

-[![CI](https://github.com/LucasXlab/diffnote/actions/workflows/ci.yml/badge.svg)](https://github.com/LucasXlab/diffnote/actions/workflows/ci.yml) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Version](https://img.shields.io/badge/source-v0.1.0-6b7280.svg)](https://github.com/LucasXlab/diffnote/blob/main/pyproject.toml) ![Runtime](https://img.shields.io/badge/Python-3.8%2B-3776ab.svg) [![Stars](https://img.shields.io/github/stars/LucasYanzy/diffnote?style=flat)](https://github.com/LucasXlab/diffnote/stargazers) +[![CI](https://github.com/LucasXlab/diffnote/actions/workflows/ci.yml/badge.svg)](https://github.com/LucasXlab/diffnote/actions/workflows/ci.yml) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Version](https://img.shields.io/badge/source-v0.1.0-6b7280.svg)](https://github.com/LucasXlab/diffnote/blob/main/pyproject.toml) ![Runtime](https://img.shields.io/badge/Python-3.8%2B-3776ab.svg) [![Stars](https://img.shields.io/github/stars/LucasXlab/diffnote?style=flat)](https://github.com/LucasXlab/diffnote/stargazers) [English](README.md) · [简体中文](README.zh-CN.md) @@ -21,10 +21,17 @@ Writing a PR description after the coding is finished is easy to postpone. diffn ## Quick start +```bash +git clone https://github.com/LucasXlab/diffnote.git && cd diffnote +python3 -m pip install . +python3 scripts/demo.py +``` +Install from this checkout to use the reviewed source version. The installed tool has no third-party runtime dependencies; cloning and installation can require network access. ## Features +### Choose your diff Summarize tracked working-tree changes, staged changes, a base ref, or a commit range. @@ -34,7 +41,7 @@ Bucket source, tests, docs, configuration and migrations; surface file and line- ### Export a draft -Generate terminal, Markdown or JSON output. Titles and risk signals are heuristics, not a semantic code review. +Generate terminal, Markdown or JSON output. Save Markdown to a file with `--markdown --save body.md`; successful saving leaves stdout empty. Titles and risk signals are heuristics, not a semantic code review. ### Optional prose @@ -49,8 +56,15 @@ diffnote --staged diffnote --base main --markdown diffnote --range main..HEAD --json diffnote --commits 2 +diffnote --markdown --save body.md +diffnote --color +diffnote --no-color ``` +Terminal output uses ANSI colors only when stdout is a terminal. `--color` forces colors; `--no-color` disables them. + +Breaking-change hints use `!:` subjects from the selected `--commits`, `--range`, or `--base` comparison, without a 25-commit cutoff. Working-tree and staged-only summaries do not reuse historical commit subjects. Public API path hints still apply in every mode. + ## Architecture ```mermaid @@ -75,6 +89,12 @@ python3 -m pytest -q The demo uses a temporary fixture and does not inspect your personal repositories or agent homes. +## Roadmap + +- [ ] Improve error messages for invalid refs and empty histories. +- [ ] Add configurable grouping rules. + +## Contributing Read [CONTRIBUTING.md](CONTRIBUTING.md). Report reproducible problems in [Issues](https://github.com/LucasXlab/diffnote/issues). Follow [SECURITY.md](SECURITY.md) for sensitive reports. diff --git a/README.zh-CN.md b/README.zh-CN.md index 2200f03..ebbfb7b 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -2,7 +2,7 @@

diffnote

将本地 Git 改动整理成便于审阅的 PR 摘要。

-[![CI](https://github.com/LucasXlab/diffnote/actions/workflows/ci.yml/badge.svg)](https://github.com/LucasXlab/diffnote/actions/workflows/ci.yml) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Version](https://img.shields.io/badge/source-v0.1.0-6b7280.svg)](https://github.com/LucasXlab/diffnote/blob/main/pyproject.toml) ![Runtime](https://img.shields.io/badge/Python-3.8%2B-3776ab.svg) [![Stars](https://img.shields.io/github/stars/LucasYanzy/diffnote?style=flat)](https://github.com/LucasXlab/diffnote/stargazers) +[![CI](https://github.com/LucasXlab/diffnote/actions/workflows/ci.yml/badge.svg)](https://github.com/LucasXlab/diffnote/actions/workflows/ci.yml) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Version](https://img.shields.io/badge/source-v0.1.0-6b7280.svg)](https://github.com/LucasXlab/diffnote/blob/main/pyproject.toml) ![Runtime](https://img.shields.io/badge/Python-3.8%2B-3776ab.svg) [![Stars](https://img.shields.io/github/stars/LucasXlab/diffnote?style=flat)](https://github.com/LucasXlab/diffnote/stargazers) [English](README.md) · [简体中文](README.zh-CN.md) @@ -36,7 +36,7 @@ python3 scripts/demo.py ### 导出初稿 -输出终端、Markdown 或 JSON;标题与风险信号来自启发式规则,不代替语义审查。 +输出终端、Markdown 或 JSON;用 `--markdown --save body.md` 可保存文件,成功时标准输出为空。标题与风险信号来自启发式规则,不代替语义审查。 ### 可选模型润色 @@ -51,8 +51,15 @@ diffnote --staged diffnote --base main --markdown diffnote --range main..HEAD --json diffnote --commits 2 +diffnote --markdown --save body.md +diffnote --color +diffnote --no-color ``` +默认仅在标准输出连接终端时使用 ANSI 颜色;`--color` 强制开启,`--no-color` 禁用。 + +破坏性变更提示只读取 `--commits`、`--range` 或 `--base` 所选比较范围内的 `!:` 提交标记,不再截断为最近 25 个提交。纯工作区或暂存摘要不套用历史提交标记;公共 API 路径提示仍对所有模式生效。 + ## 架构 ```mermaid diff --git a/assets/demo.gif b/assets/demo.gif index 3d941bd..ccb2e54 100644 Binary files a/assets/demo.gif and b/assets/demo.gif differ diff --git a/assets/demo.png b/assets/demo.png index dfe7433..67e6b96 100644 Binary files a/assets/demo.png and b/assets/demo.png differ diff --git a/assets/social-preview.png b/assets/social-preview.png index 5ee4fad..a4c28d9 100644 Binary files a/assets/social-preview.png and b/assets/social-preview.png differ diff --git a/demo.gif b/demo.gif index 3d941bd..ccb2e54 100644 Binary files a/demo.gif and b/demo.gif differ diff --git a/demo/terminal.txt b/demo/terminal.txt index a1c5131..21580e3 100644 --- a/demo/terminal.txt +++ b/demo/terminal.txt @@ -3,7 +3,7 @@ $ diffnote --no-color diffnote — PR / changelog summary ────────────────────────────────────────── 2 files changed (+2 / -1) - Suggested title: fix: round checkout amounts + Suggested title: fix: update implementation Changelog section: fix Changes by area diff --git a/src/diffnote/cli.py b/src/diffnote/cli.py index e9907cc..6975cbc 100644 --- a/src/diffnote/cli.py +++ b/src/diffnote/cli.py @@ -56,6 +56,20 @@ def get_diff(args, cwd): return gitutil.get_diff_text("HEAD", cwd=cwd, staged=args.staged) +def get_selected_commit_messages(args, cwd): + if args.commits: + revision_range = f"HEAD~{args.commits}..HEAD" + elif args.range: + base, _, head = args.range.partition("..") + revision_range = f"{base}..{head or 'HEAD'}" + elif args.base: + revision_range = f"{args.base}..HEAD" + else: + # Working-tree and staged changes have no commit subjects of their own. + return [] + return gitutil.get_commit_messages(n=None, cwd=cwd, revision_range=revision_range) + + def main(argv=None): parser = build_parser() args = parser.parse_args(argv) @@ -80,7 +94,7 @@ def main(argv=None): print("diffnote: no file changes parsed.", file=sys.stderr) return 0 - commit_messages = gitutil.get_commit_messages(cwd=cwd) + commit_messages = get_selected_commit_messages(args, cwd) summary = analyze.build_summary(files, commit_messages) llm_prose = None diff --git a/src/diffnote/gitutil.py b/src/diffnote/gitutil.py index 2d95c08..cbe6829 100644 --- a/src/diffnote/gitutil.py +++ b/src/diffnote/gitutil.py @@ -45,10 +45,18 @@ def get_range_diff(base, head="HEAD", cwd=None): return proc.stdout -def get_commit_messages(n=25, cwd=None): - proc = _run( - ["log", "-n", str(n), "--no-merges", "--pretty=format:%s"], cwd=cwd - ) +def get_commit_messages(n=25, cwd=None, revision_range=None): + """Read commit subjects, optionally restricted to an explicit comparison. + + Pass n=None to include every commit in a selected range. + """ + args = ["log", "--no-merges", "--pretty=format:%s"] + if n is not None: + args.extend(["-n", str(n)]) + if revision_range is not None: + args.append(revision_range) + args.append("--") + proc = _run(args, cwd=cwd) return [m for m in proc.stdout.splitlines() if m.strip()] diff --git a/tests/test_commit_scope.py b/tests/test_commit_scope.py new file mode 100644 index 0000000..84a674b --- /dev/null +++ b/tests/test_commit_scope.py @@ -0,0 +1,111 @@ +"""Regression coverage for commit markers belonging to the selected diff.""" + +import json +import subprocess + +import pytest + +from diffnote import cli + + +def _git(repo, *args): + return subprocess.check_output(["git", *args], cwd=repo, text=True).strip() + + +def _init(repo): + _git(repo, "init", "-q", "-b", "main") + _git(repo, "config", "user.name", "Scope Fixture") + _git(repo, "config", "user.email", "fixture@example.invalid") + + +def _commit(repo, message, text): + (repo / "README.md").write_text(text, encoding="utf-8") + _git(repo, "add", "README.md") + _git(repo, "-c", "commit.gpgsign=false", "commit", "-qm", message) + + +def _summary(args, capsys): + assert cli.main([*args, "--json"]) == 0 + return json.loads(capsys.readouterr().out) + + +def _is_breaking(summary): + return any(risk["label"] == "possible breaking change" + for risk in summary["risks"]) + + +@pytest.mark.parametrize("args", [ + [], + ["--staged"], + ["--commits", "1"], + ["--range", "old-marker..docs-end"], + ["--base", "old-marker"], +]) +def test_old_breaking_marker_does_not_contaminate_selected_docs( + tmp_path, monkeypatch, capsys, args, +): + _init(tmp_path) + _commit(tmp_path, "feat!: retire an old API", "# Original\n") + _git(tmp_path, "tag", "old-marker") + _commit(tmp_path, "docs: clarify wording", "# Clarified\n") + _git(tmp_path, "tag", "docs-end") + (tmp_path / "README.md").write_text("# Current docs\n", encoding="utf-8") + _git(tmp_path, "add", "README.md") + monkeypatch.chdir(tmp_path) + + summary = _summary(args, capsys) + + assert summary["total_files"] == 1 + assert not _is_breaking(summary) + assert summary["title"] != "feat!: retire an old API" + + +def test_range_reads_markers_from_selected_branch_instead_of_head( + tmp_path, monkeypatch, capsys, +): + _init(tmp_path) + _commit(tmp_path, "docs: initial", "# Initial\n") + _git(tmp_path, "tag", "start") + _git(tmp_path, "checkout", "-qb", "feature") + _commit(tmp_path, "feat!: remove legacy response", "# New response\n") + _git(tmp_path, "tag", "feature-end") + _git(tmp_path, "checkout", "-q", "main") + _commit(tmp_path, "docs: sibling branch", "# Sibling\n") + monkeypatch.chdir(tmp_path) + + summary = _summary(["--range", "start..feature-end"], capsys) + + assert _is_breaking(summary) + assert summary["title"] == "feat!: remove legacy response" + + +def test_range_excludes_markers_committed_after_its_endpoint( + tmp_path, monkeypatch, capsys, +): + _init(tmp_path) + _commit(tmp_path, "docs: initial", "# Initial\n") + _git(tmp_path, "tag", "start") + _commit(tmp_path, "docs: selected change", "# Selected\n") + _git(tmp_path, "tag", "selected") + _commit(tmp_path, "feat!: later change", "# Later\n") + monkeypatch.chdir(tmp_path) + + summary = _summary(["--range", "start..selected"], capsys) + + assert not _is_breaking(summary) + assert summary["title"] == "docs: selected change" + + +def test_commit_selection_is_not_silently_limited_to_25_messages( + tmp_path, monkeypatch, capsys, +): + _init(tmp_path) + _commit(tmp_path, "docs: initial", "# Initial\n") + _commit(tmp_path, "feat!: selected API change", "# API change\n") + for i in range(26): + _commit(tmp_path, "docs: update {}".format(i), "# Update {}\n".format(i)) + monkeypatch.chdir(tmp_path) + + summary = _summary(["--commits", "27"], capsys) + + assert _is_breaking(summary)