pullwise 0.3.0__tar.gz → 0.5.0__tar.gz

{pullwise-0.3.0 → pullwise-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pullwise
-Version: 0.3.0
+Version: 0.5.0
 Summary: AI-powered PR descriptions, labels, and code review using OpenAI
 License: MIT
 Project-URL: Homepage, https://github.com/albertusreza/pr-pilot
@@ -120,6 +120,11 @@ pr-pilot describe --markdown pr_description.md
 | `pr-pilot reviewers` | Suggest reviewers based on git blame of changed files |
 | `pr-pilot standup` | Generate a daily standup update from your recent commits |
 | `pr-pilot todos` | Scan for TODO/FIXME comments and create GitHub issues from them |
+| `pr-pilot commit` | Generate a Conventional Commit message from staged changes |
+| `pr-pilot release` | Full release: changelog + git tag + GitHub release in one command |
+| `pr-pilot docs` | Generate docstrings for functions in changed files |
+| `pr-pilot branch` | Suggest a git branch name from a plain-English task description |
+| `pr-pilot explain` | Explain what a file or function does in plain English |
 
 ## Usage
 
@@ -140,6 +145,40 @@ pr-pilot changelog
 pr-pilot changelog --output CHANGELOG.md
 ```
 
+```bash
+# Generate docstrings for all functions changed vs main
+pr-pilot docs
+
+# Document a specific file
+pr-pilot docs src/auth.py
+
+# Suggest a branch name from a task description
+pr-pilot branch "add rate limiting to upload endpoint"
+
+# Create the branch immediately
+pr-pilot branch "fix login timeout on mobile" --checkout
+
+# Explain what a file does
+pr-pilot explain src/auth.py
+
+# Explain a specific function
+pr-pilot explain src/auth.py --function authenticate
+```
+
+```bash
+# Generate a commit message from staged changes
+pr-pilot commit
+
+# Run git commit directly with the generated message
+pr-pilot commit --commit
+
+# Full release: bump version + write changelog + create GitHub release
+pr-pilot release --repo owner/repo
+
+# Preview release without publishing
+pr-pilot release --repo owner/repo --dry-run
+```
+
 ```bash
 # Suggest reviewers for your current branch
 pr-pilot reviewers --base main

{pullwise-0.3.0 → pullwise-0.5.0}/README.md

@@ -100,6 +100,11 @@ pr-pilot describe --markdown pr_description.md
 | `pr-pilot reviewers` | Suggest reviewers based on git blame of changed files |
 | `pr-pilot standup` | Generate a daily standup update from your recent commits |
 | `pr-pilot todos` | Scan for TODO/FIXME comments and create GitHub issues from them |
+| `pr-pilot commit` | Generate a Conventional Commit message from staged changes |
+| `pr-pilot release` | Full release: changelog + git tag + GitHub release in one command |
+| `pr-pilot docs` | Generate docstrings for functions in changed files |
+| `pr-pilot branch` | Suggest a git branch name from a plain-English task description |
+| `pr-pilot explain` | Explain what a file or function does in plain English |
 
 ## Usage
 
@@ -120,6 +125,40 @@ pr-pilot changelog
 pr-pilot changelog --output CHANGELOG.md
 ```
 
+```bash
+# Generate docstrings for all functions changed vs main
+pr-pilot docs
+
+# Document a specific file
+pr-pilot docs src/auth.py
+
+# Suggest a branch name from a task description
+pr-pilot branch "add rate limiting to upload endpoint"
+
+# Create the branch immediately
+pr-pilot branch "fix login timeout on mobile" --checkout
+
+# Explain what a file does
+pr-pilot explain src/auth.py
+
+# Explain a specific function
+pr-pilot explain src/auth.py --function authenticate
+```
+
+```bash
+# Generate a commit message from staged changes
+pr-pilot commit
+
+# Run git commit directly with the generated message
+pr-pilot commit --commit
+
+# Full release: bump version + write changelog + create GitHub release
+pr-pilot release --repo owner/repo
+
+# Preview release without publishing
+pr-pilot release --repo owner/repo --dry-run
+```
+
 ```bash
 # Suggest reviewers for your current branch
 pr-pilot reviewers --base main

pullwise-0.5.0/pr_pilot/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.5.0"

{pullwise-0.3.0 → pullwise-0.5.0}/pr_pilot/analyzer.py

@@ -11,6 +11,11 @@ from .templates import (
     REVIEWER_SYSTEM, REVIEWER_USER, REVIEWER_COMMENT_HEADER, REVIEWER_COMMENT_TEMPLATE,
     STANDUP_SYSTEM, STANDUP_USER,
     ISSUE_SYSTEM, ISSUE_USER,
+    COMMIT_SYSTEM, COMMIT_USER,
+    RELEASE_NOTES_SYSTEM, RELEASE_NOTES_USER,
+    DOCSTRING_SYSTEM, DOCSTRING_USER,
+    BRANCH_SYSTEM, BRANCH_USER,
+    EXPLAIN_SYSTEM, EXPLAIN_USER,
 )
 
 _MAX_DIFF_CHARS = 24_000   # stay well within context limits
@@ -390,3 +395,326 @@ def create_issues_from_todos(
             labels=data.get("labels", ["technical-debt"]),
         ))
     return issues
+
+
+# ── Commit message generator ──────────────────────────────────────────────────
+
+@dataclass
+class CommitMessage:
+    subject: str
+    body: str | None
+    breaking: bool
+    footer: str | None
+
+    def format(self) -> str:
+        parts = [self.subject]
+        if self.body:
+            parts.append("")
+            parts.append(self.body)
+        if self.footer:
+            parts.append("")
+            parts.append(self.footer)
+        return "\n".join(parts)
+
+
+def _get_staged_diff() -> str:
+    diff = _git("diff", "--cached")
+    if len(diff) > _MAX_DIFF_CHARS:
+        diff = diff[:_MAX_DIFF_CHARS] + "\n\n[diff truncated]"
+    return diff
+
+
+def generate_commit_message(api_key: str, model: str = _MODEL) -> CommitMessage:
+    client = OpenAI(api_key=api_key)
+    diff = _get_staged_diff()
+    if not diff:
+        raise ValueError("No staged changes found. Use 'git add' first.")
+    resp = client.chat.completions.create(
+        model=model,
+        max_tokens=512,
+        messages=[
+            {"role": "system", "content": COMMIT_SYSTEM},
+            {"role": "user", "content": COMMIT_USER.format(diff=diff)},
+        ],
+    )
+    raw = (resp.choices[0].message.content or "{}").strip()
+    if raw.startswith("```"):
+        raw = "\n".join(raw.splitlines()[1:])
+    if raw.endswith("```"):
+        raw = "\n".join(raw.splitlines()[:-1])
+    data = json.loads(raw.strip())
+    return CommitMessage(
+        subject=data.get("subject", "chore: update"),
+        body=data.get("body") or None,
+        breaking=data.get("breaking", False),
+        footer=data.get("footer") or None,
+    )
+
+
+# ── Full release workflow ─────────────────────────────────────────────────────
+
+@dataclass
+class ReleaseInfo:
+    version: str
+    tag: str
+    name: str
+    body: str
+    prerelease: bool
+
+
+def _generate_release_notes(
+    api_key: str, version: str, changelog_md: str, model: str = _MODEL
+) -> tuple[str, str]:
+    """Return (release_name, release_body)."""
+    client = OpenAI(api_key=api_key)
+    resp = client.chat.completions.create(
+        model=model,
+        max_tokens=1024,
+        messages=[
+            {"role": "system", "content": RELEASE_NOTES_SYSTEM},
+            {"role": "user", "content": RELEASE_NOTES_USER.format(
+                version=version, changelog_md=changelog_md
+            )},
+        ],
+    )
+    raw = (resp.choices[0].message.content or "{}").strip()
+    if raw.startswith("```"):
+        raw = "\n".join(raw.splitlines()[1:])
+    if raw.endswith("```"):
+        raw = "\n".join(raw.splitlines()[:-1])
+    data = json.loads(raw.strip())
+    return data.get("name", f"v{version}"), data.get("body", changelog_md)
+
+
+def run_release(
+    api_key: str,
+    repo: str,
+    changelog_path: str = "CHANGELOG.md",
+    model: str = _MODEL,
+    dry_run: bool = False,
+) -> ReleaseInfo:
+    """Full release: generate changelog → bump version → create GitHub release."""
+    import datetime
+    from .github_client import _api
+
+    # 1. Generate changelog entry
+    entry, new_version = generate_changelog(api_key, model=model)
+    today = datetime.date.today().isoformat()
+    changelog_md = entry.to_markdown(new_version, today)
+
+    # 2. Write CHANGELOG.md
+    import pathlib
+    p = pathlib.Path(changelog_path)
+    if p.exists():
+        existing = p.read_text()
+        if existing.startswith("# "):
+            header, rest = existing.split("\n", 1)
+            new_content = f"{header}\n\n{changelog_md}\n{rest}"
+        else:
+            new_content = f"{changelog_md}\n\n{existing}"
+    else:
+        new_content = f"# Changelog\n\n{changelog_md}\n"
+
+    if not dry_run:
+        p.write_text(new_content)
+
+    # 3. Generate release notes
+    release_name, release_body = _generate_release_notes(
+        api_key, new_version, changelog_md, model=model
+    )
+    tag = f"v{new_version}"
+
+    if not dry_run:
+        # 4. Commit changelog
+        import subprocess
+        subprocess.run(["git", "add", changelog_path], check=True)
+        subprocess.run(
+            ["git", "commit", "-m", f"chore: release {tag}"],
+            check=True
+        )
+        # 5. Create git tag
+        subprocess.run(["git", "tag", tag], check=True)
+        subprocess.run(["git", "push"], check=True)
+        subprocess.run(["git", "push", "--tags"], check=True)
+        # 6. Create GitHub release
+        _api("POST", f"/repos/{repo}/releases", {
+            "tag_name": tag,
+            "name": release_name,
+            "body": release_body,
+            "prerelease": False,
+        })
+
+    return ReleaseInfo(
+        version=new_version,
+        tag=tag,
+        name=release_name,
+        body=release_body,
+        prerelease=False,
+    )
+
+
+# ── Docstring generator ───────────────────────────────────────────────────────
+
+@dataclass
+class DocstringResult:
+    language: str
+    function_name: str
+    docstring: str
+    placement: str   # "above" | "inside"
+
+
+def _detect_language(path: str) -> str:
+    ext = path.rsplit(".", 1)[-1].lower()
+    if ext == "py":
+        return "python"
+    if ext in {"ts", "tsx"}:
+        return "typescript"
+    return "javascript"
+
+
+def _extract_functions(code: str, language: str) -> list[tuple[str, int]]:
+    """Return list of (function_source, start_line) for top-level functions."""
+    import re
+    lines = code.splitlines()
+    results = []
+    if language == "python":
+        pattern = re.compile(r"^(def |async def )")
+        i = 0
+        while i < len(lines):
+            if pattern.match(lines[i]):
+                start = i
+                # collect until next top-level def/class or EOF
+                j = i + 1
+                while j < len(lines) and (not lines[j] or lines[j][0] in " \t#"):
+                    j += 1
+                results.append(("\n".join(lines[start:j]), start + 1))
+                i = j
+            else:
+                i += 1
+    else:
+        pattern = re.compile(r"^(export\s+)?(async\s+)?function\s+\w+|^\s*(const|let|var)\s+\w+\s*=\s*(async\s+)?\(")
+        for i, line in enumerate(lines):
+            if pattern.match(line):
+                end = min(i + 30, len(lines))
+                results.append(("\n".join(lines[i:end]), i + 1))
+    return results
+
+
+def generate_docstrings(
+    api_key: str, file_path: str, model: str = _MODEL
+) -> list[DocstringResult]:
+    """Generate docstrings for all functions in a file changed in the diff."""
+    from pathlib import Path
+    client = OpenAI(api_key=api_key)
+    code = Path(file_path).read_text(errors="replace")
+    language = _detect_language(file_path)
+    functions = _extract_functions(code, language)
+    if not functions:
+        return []
+    results = []
+    for func_code, _lineno in functions[:10]:  # cap at 10 per file
+        resp = client.chat.completions.create(
+            model=model,
+            max_tokens=512,
+            messages=[
+                {"role": "system", "content": DOCSTRING_SYSTEM},
+                {"role": "user", "content": DOCSTRING_USER.format(
+                    language=language, code=func_code[:3000]
+                )},
+            ],
+        )
+        raw = (resp.choices[0].message.content or "{}").strip()
+        if raw.startswith("```"):
+            raw = "\n".join(raw.splitlines()[1:])
+        if raw.endswith("```"):
+            raw = "\n".join(raw.splitlines()[:-1])
+        try:
+            data = json.loads(raw.strip())
+            results.append(DocstringResult(
+                language=data.get("language", language),
+                function_name=data.get("function_name", "unknown"),
+                docstring=data.get("docstring", ""),
+                placement=data.get("placement", "inside"),
+            ))
+        except json.JSONDecodeError:
+            continue
+    return results
+
+
+# ── Branch namer ──────────────────────────────────────────────────────────────
+
+@dataclass
+class BranchSuggestion:
+    suggestions: list[str]
+    recommended: int   # index into suggestions
+
+    @property
+    def best(self) -> str:
+        return self.suggestions[self.recommended]
+
+
+def suggest_branch(api_key: str, task: str, model: str = _MODEL) -> BranchSuggestion:
+    client = OpenAI(api_key=api_key)
+    resp = client.chat.completions.create(
+        model=model,
+        max_tokens=200,
+        messages=[
+            {"role": "system", "content": BRANCH_SYSTEM},
+            {"role": "user", "content": BRANCH_USER.format(task=task)},
+        ],
+    )
+    raw = (resp.choices[0].message.content or "{}").strip()
+    if raw.startswith("```"):
+        raw = "\n".join(raw.splitlines()[1:])
+    if raw.endswith("```"):
+        raw = "\n".join(raw.splitlines()[:-1])
+    data = json.loads(raw.strip())
+    suggestions = data.get("suggestions", [f"feat/{task[:40].lower().replace(' ', '-')}"])
+    recommended = data.get("recommended", 0)
+    return BranchSuggestion(suggestions=suggestions, recommended=recommended)
+
+
+# ── Code explainer ────────────────────────────────────────────────────────────
+
+def explain_code(
+    api_key: str,
+    file_path: str,
+    selector: str | None = None,
+    model: str = _MODEL,
+) -> str:
+    """Explain a file or specific function in plain English."""
+    from pathlib import Path
+    client = OpenAI(api_key=api_key)
+    code = Path(file_path).read_text(errors="replace")
+
+    # If selector given, try to extract just that function/class
+    if selector:
+        import re
+        pattern = re.compile(
+            rf"^(def |async def |class |\w+ = (async )?function )"
+            rf".*{re.escape(selector)}",
+            re.MULTILINE
+        )
+        m = pattern.search(code)
+        if m:
+            start = m.start()
+            # grab next ~60 lines
+            snippet = "\n".join(code[start:].splitlines()[:60])
+            code = snippet
+
+    if len(code) > _MAX_DIFF_CHARS:
+        code = code[:_MAX_DIFF_CHARS] + "\n\n[truncated]"
+
+    resp = client.chat.completions.create(
+        model=model,
+        max_tokens=512,
+        messages=[
+            {"role": "system", "content": EXPLAIN_SYSTEM},
+            {"role": "user", "content": EXPLAIN_USER.format(
+                file_path=file_path,
+                selector=f"Function/class: {selector}" if selector else "Whole file",
+                code=code,
+            )},
+        ],
+    )
+    return (resp.choices[0].message.content or "").strip()

{pullwise-0.3.0 → pullwise-0.5.0}/pr_pilot/cli.py

@@ -6,6 +6,8 @@ import sys
 from .analyzer import (
     describe_pr, suggest_labels, review_pr, review_pr_as_comment,
     generate_changelog, suggest_reviewers, generate_standup, create_issues_from_todos,
+    generate_commit_message, run_release,
+    generate_docstrings, suggest_branch, explain_code,
 )
 
 _RESET = "\033[0m"
@@ -103,6 +105,143 @@ def cmd_changelog(args: argparse.Namespace) -> None:
     print()
 
 
+def cmd_commit(args: argparse.Namespace) -> None:
+    print(f"\n  {_DIM}Analyzing staged changes...{_RESET}\n")
+    msg = generate_commit_message(_key(), model=args.model)
+
+    print(f"{_BOLD}Commit message:{_RESET}\n")
+    print(f"  {_GREEN}{msg.subject}{_RESET}")
+    if msg.body:
+        print()
+        for line in msg.body.splitlines():
+            print(f"  {line}")
+    if msg.footer:
+        print(f"\n  {_YELLOW}{msg.footer}{_RESET}")
+    if msg.breaking:
+        print(f"\n  {_YELLOW}⚠ Breaking change{_RESET}")
+
+    if args.commit:
+        import subprocess
+        full = msg.format()
+        result = subprocess.run(["git", "commit", "-m", full])
+        if result.returncode == 0:
+            print(f"\n  {_GREEN}✓{_RESET} Committed.")
+        else:
+            print(f"\n  Commit failed — copy the message above and run git commit manually.")
+    elif args.copy:
+        try:
+            import subprocess
+            subprocess.run(["pbcopy"], input=msg.format().encode(), check=True)
+            print(f"\n  {_GREEN}✓{_RESET} Copied to clipboard")
+        except Exception:
+            print(f"\n  {_DIM}(--copy requires macOS pbcopy){_RESET}")
+    print()
+
+
+def cmd_release(args: argparse.Namespace) -> None:
+    repo = args.repo or os.environ.get("GITHUB_REPOSITORY", "")
+    if not repo:
+        print("pr-pilot release: --repo is required (or set GITHUB_REPOSITORY)", file=sys.stderr)
+        sys.exit(1)
+
+    if args.dry_run:
+        print(f"\n  {_DIM}Dry run — nothing will be committed or published{_RESET}\n")
+    else:
+        print(f"\n  {_DIM}Running full release workflow for {repo}...{_RESET}\n")
+
+    release = run_release(
+        _key(),
+        repo=repo,
+        changelog_path=args.changelog,
+        model=args.model,
+        dry_run=args.dry_run,
+    )
+
+    print(f"  {_BOLD}Version:{_RESET}  {_GREEN}{release.tag}{_RESET}")
+    print(f"  {_BOLD}Name:{_RESET}     {release.name}\n")
+    print(release.body)
+
+    if args.dry_run:
+        print(f"\n  {_YELLOW}Dry run complete — no changes made.{_RESET}")
+    else:
+        print(f"\n  {_GREEN}✓{_RESET} CHANGELOG.md updated")
+        print(f"  {_GREEN}✓{_RESET} Committed and tagged {release.tag}")
+        print(f"  {_GREEN}✓{_RESET} GitHub release created")
+    print()
+
+
+def cmd_docs(args: argparse.Namespace) -> None:
+    import os as _os
+    files = args.files
+    if not files:
+        # Default: Python/JS/TS files changed vs base
+        from .analyzer import _git
+        changed = _git("diff", f"{args.base}...HEAD", "--name-only").splitlines()
+        files = [f for f in changed
+                 if f.endswith((".py", ".js", ".ts", ".tsx", ".jsx")) and _os.path.exists(f)]
+    if not files:
+        print("  No changed source files found. Pass file paths as arguments.")
+        return
+
+    for file_path in files:
+        print(f"\n  {_DIM}Generating docstrings for {file_path}...{_RESET}\n")
+        results = generate_docstrings(_key(), file_path, model=args.model)
+        if not results:
+            print(f"  No functions found in {file_path}")
+            continue
+        for r in results:
+            delim = '"""' if r.language == "python" else "/**"
+            delim_end = '"""' if r.language == "python" else " */"
+            print(f"  {_BOLD}{r.function_name}{_RESET}  {_DIM}({r.placement}){_RESET}")
+            print(f"  {_DIM}{delim}{_RESET}")
+            for line in r.docstring.splitlines():
+                prefix = "   " if r.language != "python" else "    "
+                print(f"  {prefix}{line}")
+            print(f"  {_DIM}{delim_end}{_RESET}\n")
+    print()
+
+
+def cmd_branch(args: argparse.Namespace) -> None:
+    task = " ".join(args.task)
+    if not task:
+        print("pr-pilot branch: provide a task description", file=sys.stderr)
+        sys.exit(1)
+    print(f"\n  {_DIM}Generating branch names for: \"{task}\"{_RESET}\n")
+    suggestion = suggest_branch(_key(), task=task, model=args.model)
+    for i, name in enumerate(suggestion.suggestions):
+        marker = f"{_GREEN}★{_RESET}" if i == suggestion.recommended else " "
+        print(f"  {marker} {_BOLD}{name}{_RESET}")
+
+    if args.checkout:
+        import subprocess
+        best = suggestion.best
+        result = subprocess.run(["git", "checkout", "-b", best])
+        if result.returncode == 0:
+            print(f"\n  {_GREEN}✓{_RESET} Switched to new branch '{best}'")
+        else:
+            print(f"\n  Could not create branch — it may already exist.")
+    elif args.copy:
+        try:
+            import subprocess
+            subprocess.run(["pbcopy"], input=suggestion.best.encode(), check=True)
+            print(f"\n  {_GREEN}✓{_RESET} '{suggestion.best}' copied to clipboard")
+        except Exception:
+            pass
+    print()
+
+
+def cmd_explain(args: argparse.Namespace) -> None:
+    import os as _os
+    if not _os.path.exists(args.file):
+        print(f"pr-pilot explain: file not found: {args.file}", file=sys.stderr)
+        sys.exit(1)
+    selector_label = f" → {args.function}" if args.function else ""
+    print(f"\n  {_DIM}Explaining {args.file}{selector_label}...{_RESET}\n")
+    explanation = explain_code(_key(), args.file, selector=args.function, model=args.model)
+    print(explanation)
+    print()
+
+
 def cmd_reviewers(args: argparse.Namespace) -> None:
     from .github_client import upsert_comment
     from .templates import REVIEWER_COMMENT_HEADER
@@ -246,6 +385,45 @@ def main() -> None:
     p_rev.add_argument("--model", default="gpt-4o", help="OpenAI model to use")
     p_rev.set_defaults(func=cmd_review)
 
+    # --- docs ---
+    p_docs = sub.add_parser("docs", help="Generate docstrings for functions in changed files")
+    p_docs.add_argument("files", nargs="*", help="Files to document (default: changed files vs base)")
+    p_docs.add_argument("--base", default="main")
+    p_docs.add_argument("--model", default="gpt-4o")
+    p_docs.set_defaults(func=cmd_docs)
+
+    # --- branch ---
+    p_branch = sub.add_parser("branch", help="Suggest a git branch name from a task description")
+    p_branch.add_argument("task", nargs="+", help="Plain-English task description")
+    p_branch.add_argument("--model", default="gpt-4o")
+    p_branch.add_argument("--checkout", action="store_true", help="Run git checkout -b with the best suggestion")
+    p_branch.add_argument("--copy", action="store_true", help="Copy best suggestion to clipboard (macOS)")
+    p_branch.set_defaults(func=cmd_branch)
+
+    # --- explain ---
+    p_explain = sub.add_parser("explain", help="Explain what a file or function does in plain English")
+    p_explain.add_argument("file", help="File to explain")
+    p_explain.add_argument("--function", "-f", default=None, help="Specific function or class to explain")
+    p_explain.add_argument("--model", default="gpt-4o")
+    p_explain.set_defaults(func=cmd_explain)
+
+    # --- commit ---
+    p_commit = sub.add_parser("commit", help="Generate a conventional commit message from staged changes")
+    p_commit.add_argument("--model", default="gpt-4o")
+    p_commit.add_argument("--commit", action="store_true", help="Run git commit with the generated message")
+    p_commit.add_argument("--copy", action="store_true", help="Copy message to clipboard (macOS)")
+    p_commit.set_defaults(func=cmd_commit)
+
+    # --- release ---
+    p_release = sub.add_parser("release", help="Full release: changelog + git tag + GitHub release")
+    p_release.add_argument("--repo", default=None, help="GitHub repo slug (owner/repo)")
+    p_release.add_argument("--model", default="gpt-4o")
+    p_release.add_argument("--changelog", default="CHANGELOG.md", metavar="FILE",
+                           help="Path to CHANGELOG.md (default: CHANGELOG.md)")
+    p_release.add_argument("--dry-run", action="store_true",
+                           help="Preview release without committing or publishing")
+    p_release.set_defaults(func=cmd_release)
+
     # --- reviewers ---
     p_rev2 = sub.add_parser("reviewers", help="Suggest reviewers based on git blame of changed files")
     p_rev2.add_argument("--base", default="main")

{pullwise-0.3.0 → pullwise-0.5.0}/pr_pilot/templates.py

@@ -175,3 +175,134 @@ Comment: {comment}
 Surrounding code:
 {context}
 """
+
+# ── Commit message generator ──────────────────────────────────────────────────
+
+COMMIT_SYSTEM = """\
+You are an expert at writing git commit messages following the Conventional Commits
+specification (https://www.conventionalcommits.org).
+
+Given a staged diff, write a commit message.
+
+Return a JSON object:
+{
+  "subject": "type(scope): short description, max 72 chars, lowercase after colon",
+  "body": "optional longer explanation (2-4 sentences). null if the subject is self-explanatory.",
+  "breaking": true or false,
+  "footer": "BREAKING CHANGE: description" or null
+}
+
+Types: feat | fix | docs | style | refactor | perf | test | chore | ci | build
+Rules:
+- subject must be lowercase after the colon
+- subject must NOT end with a period
+- body wraps at 72 chars
+- Return ONLY the JSON object, no markdown fences
+"""
+
+COMMIT_USER = """\
+Staged diff:
+{diff}
+"""
+
+# ── Full release workflow ─────────────────────────────────────────────────────
+
+RELEASE_NOTES_SYSTEM = """\
+You are a technical writer creating GitHub release notes for a software project.
+Given a changelog entry and version info, write engaging release notes.
+
+Return a JSON object:
+{
+  "name": "release name (e.g. 'v1.2.0 — Dark Mode & Performance')",
+  "body": "markdown release notes: lead with a 1-2 sentence overview, then bullet sections for Added/Changed/Fixed. Max 400 words.",
+  "prerelease": false
+}
+
+Rules:
+- Be specific about what changed. No filler phrases.
+- Use emoji sparingly: one per section header max.
+- Return ONLY the JSON object, no markdown fences
+"""
+
+RELEASE_NOTES_USER = """\
+Version: {version}
+Changelog entry:
+{changelog_md}
+"""
+
+# ── Docstring generator ───────────────────────────────────────────────────────
+
+DOCSTRING_SYSTEM = """\
+You are an expert technical writer generating docstrings for source code functions.
+
+Given a function's source code and language, write a concise, accurate docstring.
+
+Return a JSON object:
+{
+  "language": "python" | "javascript" | "typescript",
+  "function_name": "the function name",
+  "docstring": "the full docstring text to insert (without surrounding quotes/delimiters)",
+  "placement": "above" | "inside"
+}
+
+Rules:
+- Python: use Google-style docstrings. placement = "inside" (first line after def)
+- JS/TS: use JSDoc format. placement = "above" (/** ... */ block before the function)
+- Include Args/Parameters, Returns, and Raises/Throws only if non-trivial
+- Be concise — max 6 lines for simple functions
+- Return ONLY the JSON object, no markdown fences
+"""
+
+DOCSTRING_USER = """\
+Language: {language}
+Function:
+{code}
+"""
+
+# ── Branch namer ──────────────────────────────────────────────────────────────
+
+BRANCH_SYSTEM = """\
+You are a developer assistant suggesting clean git branch names.
+
+Given a task description, return 3 branch name suggestions.
+
+Return a JSON object:
+{
+  "suggestions": [
+    "type/short-kebab-description",
+    "type/alternative-name",
+    "type/another-option"
+  ],
+  "recommended": 0
+}
+
+Types: feat | fix | chore | docs | refactor | test | hotfix
+Rules:
+- lowercase only
+- use hyphens, no underscores or spaces
+- max 50 chars total
+- be specific, not generic (not "fix/bug" but "fix/login-timeout-safari")
+- Return ONLY the JSON object, no markdown fences
+"""
+
+BRANCH_USER = "Task: {task}"
+
+# ── Code explainer ────────────────────────────────────────────────────────────
+
+EXPLAIN_SYSTEM = """\
+You are a senior engineer explaining code to a teammate.
+Given source code (a file or function), explain:
+1. What it does — in 2-3 plain sentences
+2. Key design decisions or patterns used (if any)
+3. Any gotchas, assumptions, or side effects worth knowing
+
+Be direct. Write like you're doing a quick code walkthrough over Slack, not writing docs.
+No headers. No bullet points for the overview — save bullets for gotchas only.
+"""
+
+EXPLAIN_USER = """\
+File: {file_path}
+{selector}
+Code:
+{code}
+"""

{pullwise-0.3.0 → pullwise-0.5.0}/pullwise.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pullwise
-Version: 0.3.0
+Version: 0.5.0
 Summary: AI-powered PR descriptions, labels, and code review using OpenAI
 License: MIT
 Project-URL: Homepage, https://github.com/albertusreza/pr-pilot
@@ -120,6 +120,11 @@ pr-pilot describe --markdown pr_description.md
 | `pr-pilot reviewers` | Suggest reviewers based on git blame of changed files |
 | `pr-pilot standup` | Generate a daily standup update from your recent commits |
 | `pr-pilot todos` | Scan for TODO/FIXME comments and create GitHub issues from them |
+| `pr-pilot commit` | Generate a Conventional Commit message from staged changes |
+| `pr-pilot release` | Full release: changelog + git tag + GitHub release in one command |
+| `pr-pilot docs` | Generate docstrings for functions in changed files |
+| `pr-pilot branch` | Suggest a git branch name from a plain-English task description |
+| `pr-pilot explain` | Explain what a file or function does in plain English |
 
 ## Usage
 
@@ -140,6 +145,40 @@ pr-pilot changelog
 pr-pilot changelog --output CHANGELOG.md
 ```
 
+```bash
+# Generate docstrings for all functions changed vs main
+pr-pilot docs
+
+# Document a specific file
+pr-pilot docs src/auth.py
+
+# Suggest a branch name from a task description
+pr-pilot branch "add rate limiting to upload endpoint"
+
+# Create the branch immediately
+pr-pilot branch "fix login timeout on mobile" --checkout
+
+# Explain what a file does
+pr-pilot explain src/auth.py
+
+# Explain a specific function
+pr-pilot explain src/auth.py --function authenticate
+```
+
+```bash
+# Generate a commit message from staged changes
+pr-pilot commit
+
+# Run git commit directly with the generated message
+pr-pilot commit --commit
+
+# Full release: bump version + write changelog + create GitHub release
+pr-pilot release --repo owner/repo
+
+# Preview release without publishing
+pr-pilot release --repo owner/repo --dry-run
+```
+
 ```bash
 # Suggest reviewers for your current branch
 pr-pilot reviewers --base main

{pullwise-0.3.0 → pullwise-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pullwise"
-version = "0.3.0"
+version = "0.5.0"
 description = "AI-powered PR descriptions, labels, and code review using OpenAI"
 readme = "README.md"
 license = { text = "MIT" }

{pullwise-0.3.0 → pullwise-0.5.0}/tests/test_analyzer.py

@@ -1,10 +1,14 @@
 from __future__ import annotations
 import json
+import pytest
 from unittest.mock import MagicMock, patch
 from pr_pilot.analyzer import (
     describe_pr, suggest_labels, review_pr, PRDescription,
     review_pr_as_comment, generate_changelog, ChangelogEntry,
     suggest_reviewers, generate_standup, create_issues_from_todos, _bump_version,
+    generate_commit_message, CommitMessage, run_release,
+    generate_docstrings, suggest_branch, explain_code,
+    _extract_functions, _detect_language,
 )
 from pr_pilot.templates import REVIEW_COMMENT_HEADER, REVIEWER_COMMENT_HEADER
 
@@ -238,3 +242,174 @@ def test_create_issues_from_todos(tmp_path):
     assert len(issues) == 1
     assert issues[0].title == "Fix slow foo()"
     assert "technical-debt" in issues[0].labels
+
+
+# ── Commit message generator tests ───────────────────────────────────────────
+
+@patch("pr_pilot.analyzer._get_staged_diff", return_value="+ def login(user, password):\n+     return auth(user)")
+def test_generate_commit_message_basic(mock_diff):
+    payload = {
+        "subject": "feat(auth): add login function",
+        "body": "Implements basic login using the auth helper.",
+        "breaking": False,
+        "footer": None,
+    }
+    with patch("pr_pilot.analyzer.OpenAI") as MockOpenAI:
+        MockOpenAI.return_value.chat.completions.create.return_value = \
+            _mock_openai_response(json.dumps(payload))
+        msg = generate_commit_message("fake-key")
+    assert msg.subject == "feat(auth): add login function"
+    assert msg.breaking is False
+    assert msg.footer is None
+
+
+@patch("pr_pilot.analyzer._get_staged_diff", return_value="")
+def test_generate_commit_message_no_staged(mock_diff):
+    with pytest.raises(ValueError, match="No staged changes"):
+        generate_commit_message("fake-key")
+
+
+def test_commit_message_format_full():
+    msg = CommitMessage(
+        subject="feat(api): add rate limiting",
+        body="Adds sliding window rate limiting to all endpoints.",
+        breaking=True,
+        footer="BREAKING CHANGE: Rate limit headers are now always present.",
+    )
+    formatted = msg.format()
+    assert "feat(api): add rate limiting" in formatted
+    assert "sliding window" in formatted
+    assert "BREAKING CHANGE" in formatted
+
+
+def test_commit_message_format_subject_only():
+    msg = CommitMessage(subject="chore: update deps", body=None, breaking=False, footer=None)
+    assert msg.format() == "chore: update deps"
+
+
+# ── Release workflow tests ────────────────────────────────────────────────────
+
+@patch("pr_pilot.analyzer._get_commits_since_tag", return_value="abc Fix login\ndef Add dark mode")
+@patch("pr_pilot.analyzer._get_current_version", return_value="1.0.0")
+@patch("pr_pilot.analyzer.get_diff", return_value="+ new code")
+@patch("pr_pilot.analyzer.get_commits", return_value="")
+@patch("pr_pilot.analyzer.get_branch", return_value="main")
+def test_run_release_dry_run(mock_branch, mock_commits, mock_diff, mock_ver, mock_ctag, tmp_path):  # noqa: E501
+    changelog_payload = {
+        "version": "minor", "highlights": "New features.",
+        "added": ["Dark mode"], "changed": [], "fixed": ["Login bug"],
+        "removed": [], "security": [],
+    }
+    release_payload = {
+        "name": "v1.1.0 — Dark Mode",
+        "body": "## What's new\n- Dark mode added\n- Login bug fixed",
+        "prerelease": False,
+    }
+    responses = [
+        _mock_openai_response(json.dumps(changelog_payload)),
+        _mock_openai_response(json.dumps(release_payload)),
+    ]
+    changelog_file = str(tmp_path / "CHANGELOG.md")
+    with patch("pr_pilot.analyzer.OpenAI") as MockOpenAI:
+        MockOpenAI.return_value.chat.completions.create.side_effect = responses
+        release = run_release("fake-key", repo="owner/repo",
+                              changelog_path=changelog_file, dry_run=True)
+    assert release.version == "1.1.0"
+    assert release.tag == "v1.1.0"
+    assert "Dark Mode" in release.name
+    # dry run: changelog file should NOT be written
+    import pathlib
+    assert not pathlib.Path(changelog_file).exists()
+
+
+# ── Docstring generator tests ─────────────────────────────────────────────────
+
+def test_detect_language():
+    assert _detect_language("app.py") == "python"
+    assert _detect_language("index.ts") == "typescript"
+    assert _detect_language("utils.tsx") == "typescript"
+    assert _detect_language("main.js") == "javascript"
+
+
+def test_extract_functions_python():
+    code = "x = 1\n\ndef foo(a, b):\n    return a + b\n\ndef bar():\n    pass\n"
+    funcs = _extract_functions(code, "python")
+    assert len(funcs) == 2
+    assert "def foo" in funcs[0][0]
+    assert funcs[0][1] == 3  # line number
+
+
+def test_generate_docstrings(tmp_path):
+    py_file = tmp_path / "utils.py"
+    py_file.write_text("def add(a, b):\n    return a + b\n")
+    payload = {
+        "language": "python",
+        "function_name": "add",
+        "docstring": "Add two numbers and return the result.",
+        "placement": "inside",
+    }
+    with patch("pr_pilot.analyzer.OpenAI") as MockOpenAI:
+        MockOpenAI.return_value.chat.completions.create.return_value = \
+            _mock_openai_response(json.dumps(payload))
+        results = generate_docstrings("fake-key", str(py_file))
+    assert len(results) == 1
+    assert results[0].function_name == "add"
+    assert "Add two numbers" in results[0].docstring
+    assert results[0].placement == "inside"
+
+
+def test_generate_docstrings_no_functions(tmp_path):
+    py_file = tmp_path / "constants.py"
+    py_file.write_text("MAX = 100\nMIN = 0\n")
+    results = generate_docstrings("fake-key", str(py_file))
+    assert results == []
+
+
+# ── Branch namer tests ────────────────────────────────────────────────────────
+
+def test_suggest_branch_basic():
+    payload = {
+        "suggestions": ["feat/add-dark-mode", "feat/dark-mode-toggle", "feat/theme-switcher"],
+        "recommended": 0,
+    }
+    with patch("pr_pilot.analyzer.OpenAI") as MockOpenAI:
+        MockOpenAI.return_value.chat.completions.create.return_value = \
+            _mock_openai_response(json.dumps(payload))
+        result = suggest_branch("fake-key", task="add dark mode to settings page")
+    assert result.best == "feat/add-dark-mode"
+    assert len(result.suggestions) == 3
+    assert result.recommended == 0
+
+
+def test_suggest_branch_recommended_index():
+    payload = {
+        "suggestions": ["fix/login-bug", "fix/auth-timeout", "fix/session-expiry"],
+        "recommended": 2,
+    }
+    with patch("pr_pilot.analyzer.OpenAI") as MockOpenAI:
+        MockOpenAI.return_value.chat.completions.create.return_value = \
+            _mock_openai_response(json.dumps(payload))
+        result = suggest_branch("fake-key", task="fix session expiry on mobile")
+    assert result.best == "fix/session-expiry"
+
+
+# ── Code explainer tests ──────────────────────────────────────────────────────
+
+def test_explain_code_file(tmp_path):
+    py_file = tmp_path / "auth.py"
+    py_file.write_text("def authenticate(user, password):\n    return user == 'admin'\n")
+    with patch("pr_pilot.analyzer.OpenAI") as MockOpenAI:
+        MockOpenAI.return_value.chat.completions.create.return_value = \
+            _mock_openai_response("This file handles basic authentication by comparing credentials.")
+        result = explain_code("fake-key", str(py_file))
+    assert "authentication" in result.lower()
+
+
+def test_explain_code_with_selector(tmp_path):
+    py_file = tmp_path / "utils.py"
+    py_file.write_text("def add(a, b):\n    return a + b\n\ndef sub(a, b):\n    return a - b\n")
+    with patch("pr_pilot.analyzer.OpenAI") as MockOpenAI:
+        MockOpenAI.return_value.chat.completions.create.return_value = \
+            _mock_openai_response("The add function takes two numbers and returns their sum.")
+        result = explain_code("fake-key", str(py_file), selector="add")
+    assert "add" in result.lower() or "sum" in result.lower()

pullwise-0.3.0/pr_pilot/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.3.0"