@codragraph/cli 1.6.4 → 2.0.0

package/skills/codragraph-git-bisect.md

@@ -0,0 +1,176 @@
+---
+name: codragraph-git-bisect
+description: "Use when hunting a regression — narrowing down which commit introduced a bug across N commits using binary search. Covers manual bisect, automated bisect with a test script, and how to combine bisect with CodraGraph context to understand the bad commit. Examples: \"find which commit broke X\", \"git bisect\", \"regression hunt\", \"automated bisect\""
+---
+
+# Regression Hunting with `git bisect`
+
+## When to Use
+
+- "Tests pass at commit A but fail at commit B — which commit broke it?"
+- "Performance regressed somewhere in the last 200 commits."
+- "Find the commit that introduced this bug."
+- "Automate a bisect with my test suite."
+
+## The principle
+
+Bisect performs binary search over the commit graph. Given a
+known-good commit (`good`) and a known-bad commit (`bad`), it picks the
+midpoint, you mark it, and it halves the search space until exactly one
+commit is identified. Log₂(N) tests instead of N.
+
+## Manual workflow
+
+```bash
+# Start
+git bisect start
+git bisect bad <known-bad>            # often HEAD or a commit/tag
+git bisect good <known-good>          # something older that worked
+
+# Now git checks out the midpoint. Test it.
+# Mark each midpoint:
+git bisect bad                        # if the bug IS present
+git bisect good                       # if the bug is NOT present
+git bisect skip                       # if the commit can't be tested
+                                      # (won't compile, broken in some other way)
+
+# Bisect narrows down. Repeat marking until git announces:
+# → "<sha> is the first bad commit"
+
+# Done — back to your starting state:
+git bisect reset
+```
+
+## Automated workflow
+
+If you have a script that exits 0 on good and non-zero on bad, you can
+fully automate:
+
+```bash
+git bisect start HEAD <known-good>
+git bisect run ./scripts/repro-bug.sh
+# → bisect runs the script at each midpoint; marks good/bad automatically;
+#   announces the first bad commit when done
+```
+
+The script's exit codes:
+
+```
+exit 0          → mark as good
+exit 1..124,    → mark as bad
+   126..127
+exit 125        → mark as skip (can't test this commit)
+exit 128+       → abort the bisect
+```
+
+## Test-script template
+
+```bash
+#!/usr/bin/env bash
+# scripts/repro-bug.sh — bisect-aware reproduction script
+set -e
+
+# 1. If this commit can't even build, skip it (don't say bad).
+npm install --silent --no-audit > /dev/null 2>&1 || exit 125
+npm run build > /dev/null 2>&1 || exit 125
+
+# 2. Run the targeted test that demonstrates the bug.
+if npx vitest run path/to/regression.test.ts --reporter=basic > /dev/null 2>&1; then
+  exit 0    # good
+else
+  exit 1    # bad
+fi
+```
+
+## Why CodraGraph helps here
+
+Once bisect names the first bad commit, the next question is *why*
+that commit broke things. CodraGraph's `diff --semantic` and `context`
+tell you exactly what changed, structurally:
+
+```bash
+git bisect log                            # see the bisection that found it
+BAD=$(git bisect log | grep "first bad commit" | awk '{print $1}')
+
+# What changed structurally between good and bad?
+codragraph diff "$BAD"^ "$BAD" --semantic
+# → addedAPIs / removedAPIs / classifiedModifications
+
+# Get full context on the modified symbols
+codragraph_context({name: "<symbol from the diff>"})
+```
+
+This turns "commit X is bad" into "commit X removed/modified Y, which
+broke flow Z." That's the actionable answer.
+
+## Bisect across non-linear history
+
+If your history has merges, bisect handles them but the midpoints are
+weird (commits from sibling branches). Two helpful flags:
+
+```bash
+git bisect start --first-parent HEAD <known-good>
+# → only follows the first-parent path (main line of merges).
+#   Useful when feature-branch commits aren't worth testing individually.
+
+git bisect start --no-checkout HEAD <known-good>
+# → don't checkout each midpoint; instead just sets BISECT_HEAD ref.
+#   Use when checkout is expensive (huge repo, slow build).
+```
+
+## Pitfalls
+
+| Pitfall | What happens | Fix |
+|---|---|---|
+| Forgot to `bisect reset` after finishing | Stuck in detached state, future `git pull` weird | `git bisect reset` returns you to your branch |
+| Test depends on uncommitted state | Bisect finds noise, not the real bug | Stash before bisecting; ensure script is self-contained |
+| Build broken in middle of range | Every middle commit looks "bad" | Use `git bisect skip` or exit-code 125 in the auto script |
+| Submodules not in sync | Wrong code being tested | Add `git submodule update --init --recursive` to the script |
+| Found a "bad commit" that's a merge | Probably a transient issue or skip-worthy | Inspect the merge: `git show --first-parent <merge>` |
+
+## Checklist
+
+```
+- [ ] Identified a clear known-good and known-bad commit
+- [ ] Have a deterministic, single-command reproduction
+- [ ] Repro is fast enough (<2 min ideally; bisect runs ~log₂(N) times)
+- [ ] Build can complete on every commit in the range (or skip script handles it)
+- [ ] Use `git bisect run <script>` for full automation
+- [ ] After hit: codragraph diff <bad>^ <bad> --semantic to understand WHY
+- [ ] git bisect reset before resuming work
+```
+
+## Example: "Tests started failing in the last 3 weeks"
+
+```bash
+# 1. Confirm endpoints
+git checkout main && npx vitest run path/to/regression.test.ts
+# → fails
+
+git checkout v1.5.3                        # known-good 3 weeks ago
+npx vitest run path/to/regression.test.ts
+# → passes
+
+# 2. Automate
+git bisect start main v1.5.3
+cat > /tmp/repro.sh <<'EOF'
+#!/usr/bin/env bash
+set -e
+npm install --silent || exit 125
+npx vitest run path/to/regression.test.ts --reporter=basic > /dev/null 2>&1
+EOF
+chmod +x /tmp/repro.sh
+git bisect run /tmp/repro.sh
+# → "abc1234 is the first bad commit"
+
+# 3. Understand the bad commit
+codragraph diff abc1234^ abc1234 --semantic
+# → modified validateUser (parameter count 3→4)
+
+codragraph_context({name: "validateUser"})
+# → caller `loginFlow` still passes 3 args — that's the regression
+
+# 4. Reset and fix
+git bisect reset
+# Patch the caller; tests pass; ship.
+```

package/skills/codragraph-git-force-push.md

@@ -0,0 +1,147 @@
+---
+name: codragraph-git-force-push
+description: "Use when the user is about to force-push, recovering after someone else force-pushed, or asking whether it's safe. Covers --force vs --force-with-lease, recovery from a bad force-push, and the rules for shared vs personal branches. Examples: \"force push\", \"is force push safe\", \"someone overwrote my work\", \"git push rejected\", \"--force-with-lease\""
+---
+
+# Force Push — When, How, and Recovery
+
+## When to Use
+
+- "Can I force push to this branch?"
+- "Git is rejecting my push, is force the answer?"
+- "Someone force-pushed and lost my commits — help."
+- "What's the difference between --force and --force-with-lease?"
+
+## The rules
+
+1. **Never `--force` on a shared branch** without coordinating. You will
+   silently overwrite collaborators' commits. Their reflogs save them; their
+   patience does not.
+2. **Always prefer `--force-with-lease`** over `--force`. It refuses the
+   push if the remote has commits you haven't seen — i.e. someone pushed
+   while you were rebasing.
+3. **Never force on `main` / `master` / `release/*`** unless you're recovering
+   from a documented incident with explicit sign-off. Branch protection
+   should make this impossible; if it's possible, fix the protection rule.
+4. **Force-pushing your OWN feature branch** after a rebase is normal and
+   expected. Just use `--force-with-lease`.
+
+## Decision tree
+
+```
+Is the branch protected on the remote?
+├─ yes → STOP. Don't force. Open a PR or get an admin to lift protection
+│        for a documented operation.
+└─ no → Is anyone else committing to this branch?
+        ├─ yes → STOP. Coordinate. They'll lose work if you force.
+        └─ no → Have you fetched the latest remote tip?
+                ├─ no  → git fetch first, then `git push --force-with-lease`
+                └─ yes → `git push --force-with-lease` is safe.
+```
+
+## --force vs --force-with-lease
+
+```bash
+# DANGEROUS: overwrites whatever is on the remote, no matter what.
+git push --force
+
+# SAFER: only succeeds if the remote tip matches what you last fetched.
+# If anyone pushed in the meantime, this aborts.
+git push --force-with-lease
+
+# EVEN SAFER: explicitly require the remote SHA to be what you expect.
+git push --force-with-lease=<branch>:<expected-sha>
+```
+
+> Make `--force-with-lease` your default by aliasing:
+> `git config --global alias.fwl 'push --force-with-lease'`
+
+## Recovery: someone force-pushed and lost your work
+
+Your local clone has the original commits in its reflog. You haven't lost
+anything as long as you haven't run `git gc --prune=now` AND your reflog
+is still intact (default 90-day expiry).
+
+```bash
+# 1. Find the lost commit on YOUR machine
+git reflog show <branch>
+# → look for "<branch>@{N}: ... before force push" or your last commit
+
+# 2. Inspect it
+git show <sha>
+git log <sha> --oneline -20
+
+# 3a. If they overwrote with rubbish: reset your branch to your old tip
+#     (this re-creates the divergence; coordinate before re-pushing)
+git checkout <branch>
+git reset --hard <sha-from-reflog>
+
+# 3b. If they had legitimate changes you also want to keep: cherry-pick
+#     YOUR lost commits onto their version
+git checkout <branch>
+git pull              # accept their version
+git cherry-pick <your-lost-sha-1> <your-lost-sha-2> ...
+
+# 4. Push back (with --force-with-lease to avoid the same problem)
+git push --force-with-lease
+```
+
+If the only copy of the lost commits was on the remote (no local clone),
+the recovery options are:
+
+- GitHub: contact GitHub Support — they retain dangling commits for ~30 days.
+- Self-hosted GitLab/Gitea: server-side reflog (if enabled) or a backup.
+
+## Recovery: I force-pushed something I shouldn't have
+
+If you JUST did it and have a terminal where the previous local state still
+exists:
+
+```bash
+git reflog                     # find the previous tip
+git reset --hard <previous-sha>
+git push --force-with-lease    # restore the remote
+```
+
+If you've already moved on locally:
+
+```bash
+git fetch origin
+git reflog show origin/<branch>
+# → look for the line BEFORE the force push you just did
+git reset --hard <recovered-sha>
+git push --force-with-lease
+```
+
+## Why CodraGraph helps here
+
+After a force-push (yours or theirs), `codragraph diff` against the
+recovered SHA tells you EXACTLY what structural changes were undone or
+reapplied — so you can verify nothing important got lost in the
+recovery:
+
+```bash
+codragraph diff <recovered-sha> HEAD --semantic
+# If addedAPIs / removedAPIs reveals work that should still be present,
+# the recovery is incomplete — go back to the reflog and pick more.
+```
+
+## Checklist (before any --force / --force-with-lease)
+
+```
+- [ ] Branch is NOT protected on the remote
+- [ ] Branch is NOT main / master / release/*
+- [ ] You're the only one committing to it (git log <branch> | grep -c Author)
+- [ ] You've git-fetched recently (so --force-with-lease has fresh info)
+- [ ] Using --force-with-lease, NEVER bare --force
+- [ ] If recovering: verified the recovered SHA via codragraph diff
+```
+
+## Pitfalls
+
+| Pitfall | What goes wrong | Avoidance |
+|---|---|---|
+| `git push -f` on shared branch | collaborators' commits silently gone | --force-with-lease + check `git log <branch>` for other authors first |
+| `--force-with-lease` after `git fetch` | lease check passes against the freshly-fetched tip — no protection | run lease BEFORE the fetch, or specify the expected SHA explicitly |
+| Force-push during CI run | CI race conditions, half-deployed states | wait for CI to finish, then force |
+| Forgetting reflog can save you | panic | reflogs default to 90 days; check `git reflog` before destroying anything |

package/skills/codragraph-git-history-rewrite.md

@@ -0,0 +1,174 @@
+---
+name: codragraph-git-history-rewrite
+description: "Use when rewriting commit history — squashing WIP commits, splitting a fat commit, removing a leaked secret, changing author info, or running git filter-repo / BFG. Covers interactive rebase, fixup/autosquash, splitting commits, and the safety rules for rewriting public history. Examples: \"squash my commits\", \"clean up history\", \"remove a leaked secret from history\", \"split this commit\", \"git filter-repo\""
+---
+
+# History Rewriting — Safely
+
+## When to Use
+
+- "Squash my last 5 WIP commits before opening a PR."
+- "Split this giant commit into 3 logical ones."
+- "Remove a leaked secret from history."
+- "Change the author of past commits."
+- "Drop a commit from the middle of the branch."
+
+## The cardinal rule
+
+**Never rewrite history that's been pushed to a shared branch.** Rewriting
+public history breaks every clone that pulled it. For shared branches:
+make a new commit that fixes/reverts the offending one. For your own
+branch (or any branch you alone work on), rewrite freely with
+`--force-with-lease`.
+
+## Interactive rebase
+
+```bash
+git rebase -i origin/main           # rebase your branch onto main, interactively
+# OR rebase the last N commits without changing the base:
+git rebase -i HEAD~N
+```
+
+You get an editor with one line per commit:
+
+```
+pick   abc1234 wip: hack on auth
+pick   def5678 wip: more auth
+pick   fed9876 fix typo
+pick   012abcd add real auth flow
+```
+
+Change `pick` to one of:
+
+| Command | Effect |
+|---|---|
+| `pick` | keep the commit as-is |
+| `reword` | keep the changes, edit the message |
+| `edit` | pause after applying so you can `git commit --amend` or split |
+| `squash` | merge into previous commit, edit combined message |
+| `fixup` | merge into previous commit, drop this commit's message |
+| `drop` | remove the commit entirely (its changes are gone) |
+| `exec <cmd>` | run a shell command after this commit (CI-style validation per commit) |
+
+Reorder lines to reorder commits. Save and exit; rebase replays them.
+
+## Fixup + autosquash workflow (the cleanest pattern)
+
+```bash
+# While developing, instead of "wip" commits, mark fixups against a target:
+git commit --fixup=<sha-of-target-commit>
+
+# At the end, squash all fixups in one go:
+git rebase -i --autosquash origin/main
+# → all `fixup!` commits are auto-placed and pre-marked. Just save.
+```
+
+This produces a clean, atomic-commit branch ready to PR — no manual
+reordering needed.
+
+## Splitting a fat commit
+
+```bash
+git rebase -i <commit>^             # interactive rebase starting AT the fat commit
+# Mark it `edit` and save.
+
+# Now you're paused at the fat commit. Reset to its parent, keep the changes:
+git reset HEAD^
+
+# Stage and commit each logical chunk separately:
+git add <files-for-part-1>
+git commit -m "first logical part"
+git add <files-for-part-2>
+git commit -m "second logical part"
+git add -A
+git commit -m "third logical part"
+
+# Resume the rebase:
+git rebase --continue
+```
+
+## Removing a leaked secret from history
+
+If a secret (API key, password, .env) was committed:
+
+1. **Rotate the secret first.** Once it's on a public remote, treat it as
+   leaked — even after history scrub.
+2. **Then scrub history with `git filter-repo`** (the modern replacement
+   for `filter-branch`):
+
+```bash
+# Install: pip install git-filter-repo (or pipx)
+
+# Remove a specific file from all history:
+git filter-repo --invert-paths --path path/to/leaked.env
+
+# Or remove a string/secret from blob contents:
+echo 'sk_live_abc***123==>REDACTED' > /tmp/replacements.txt
+git filter-repo --replace-text /tmp/replacements.txt
+
+# After filter-repo, the remote is forcibly out of sync. Coordinate with the
+# team and force-push:
+git push --force-with-lease origin --all
+git push --force-with-lease origin --tags
+```
+
+Alternative: BFG (`https://rtyley.github.io/bfg-repo-cleaner/`) is
+faster for large repos but more limited.
+
+> **Important:** GitHub caches blobs even after force-push. The blob is
+> still accessible by SHA URL for ~30 days unless you contact GitHub
+> Support to purge. Treat the secret as compromised.
+
+## Changing author info on past commits
+
+```bash
+# Most recent commit only:
+git commit --amend --author="New Name <new@email>"
+
+# Multiple commits with filter-repo:
+git filter-repo --commit-callback '
+  if commit.author_email == b"old@email":
+    commit.author_email = b"new@email"
+    commit.author_name = b"New Name"
+'
+```
+
+## Why CodraGraph helps here
+
+After any history rewrite, the structural diff against the pre-rewrite
+state proves you didn't accidentally drop or alter functional code:
+
+```bash
+# Before rewrite: snapshot the structural state
+codragraph commit -m "pre-rewrite snapshot"
+git rebase -i origin/main             # do the rewrite
+codragraph analyze                    # re-index after
+
+# Confirm structural equivalence (or see exactly what differs):
+codragraph diff <pre-snapshot-id> HEAD --semantic
+# → Should be empty if you only rewrote messages / order.
+# → If addedAPIs / removedAPIs appear, the rewrite changed semantics.
+```
+
+## Pitfalls
+
+| Pitfall | What goes wrong | Avoidance |
+|---|---|---|
+| Rewriting shared branch | Collaborators' clones diverge | Only rewrite local-or-personal branches |
+| `drop` instead of `fixup` | Lost changes silently | Verify with `codragraph diff` after the rebase |
+| Editing during rebase, forgetting `--continue` | Stuck in detached state | `git rebase --continue` after each manual step |
+| `git rebase --abort` after edits | Loses your edits | Stash before rebase if you have uncommitted work |
+| `filter-branch` (legacy) | Slow, error-prone, deprecated | Use `git filter-repo` |
+| Force-pushing after secret scrub without rotation | Secret still compromised | Rotate FIRST, scrub SECOND |
+
+## Checklist before any history rewrite
+
+```
+- [ ] Branch is NOT shared (or you have explicit team coordination)
+- [ ] Snapshot pre-state with `codragraph commit -m "pre-rewrite"`
+- [ ] Decide: interactive rebase (small) vs filter-repo (large/secrets)
+- [ ] Run the rewrite
+- [ ] Re-analyze + `codragraph diff` to verify no semantic surprises
+- [ ] Push with --force-with-lease
+- [ ] If secrets were involved: rotate FIRST, then scrub, then push
+```

package/skills/codragraph-git-rebase-vs-merge.md

@@ -0,0 +1,138 @@
+---
+name: codragraph-git-rebase-vs-merge
+description: "Use when deciding between rebase, merge, squash-merge, or rebase-and-merge for integrating a branch — both for local catch-up (pulling main into a feature branch) and for landing a PR. Examples: \"should I rebase or merge\", \"how do I integrate main into my branch\", \"squash vs rebase merge\", \"clean up my branch history before PR\""
+---
+
+# Rebase vs Merge — A Decision Guide
+
+## When to Use
+
+- "How do I bring main into my feature branch?"
+- "Should I squash this PR or merge it?"
+- "Should I rebase before pushing?"
+- "Which merge strategy do I pick on the GitHub PR button?"
+- Any time you have a branch and need to combine it with another.
+
+## The decision rule (read this first)
+
+| Situation | Use | Why |
+|---|---|---|
+| Branch is **local-only**, you want it to track main | `git pull --rebase` or `git rebase main` | Keeps your local history linear; nothing has been shared yet |
+| Branch is **shared** (already pushed, others may have pulled) | `git merge main` (or `--no-rebase`) | Rebase rewrites SHAs — collaborators' clones break |
+| You're about to **open a PR** and want clean history | `git rebase -i main` (interactive) | Squash WIP commits, reword messages, end with N tidy commits |
+| You're **landing a PR** with one logical change | **Squash-merge** on GitHub | One commit on main, clean log, PR description becomes the body |
+| You're landing a PR with multiple **already-tidy** commits | **Rebase-and-merge** on GitHub | Preserves your atomic commits; no merge bubble |
+| You're landing a long-running branch that **must show as a unit** | **Merge commit** on GitHub | Preserves the branch topology — useful for release branches |
+
+If you remember nothing else: **rebase what's only yours, merge what's already shared.**
+
+## Workflow: catching up a feature branch
+
+```bash
+# Local-only branch (fast-forward integration)
+git fetch origin
+git rebase origin/main          # replays your commits on top of main
+
+# Already pushed branch (avoid SHA churn for collaborators)
+git fetch origin
+git merge origin/main           # creates a merge commit — collaborators stay in sync
+
+# OR explicitly opt into rebase even on shared branches (coordinate first!)
+git rebase origin/main
+git push --force-with-lease     # SEE codragraph-git-force-push skill
+```
+
+## Workflow: cleaning up before opening a PR
+
+```bash
+git fetch origin
+git rebase -i origin/main       # interactive — squash, fixup, reword
+
+# Common interactive-rebase actions:
+#   pick   - keep commit
+#   reword - change message
+#   squash - merge into previous, edit combined message
+#   fixup  - merge into previous, drop this message
+#   drop   - remove the commit entirely
+```
+
+## Workflow: landing a PR (GitHub UI / `gh pr merge`)
+
+```bash
+# Squash-merge — one logical change, one commit on main:
+gh pr merge --squash --delete-branch
+
+# Rebase-and-merge — preserve your N commits as N commits on main:
+gh pr merge --rebase --delete-branch
+
+# Merge commit — preserve the branch as a unit (rare; use for releases):
+gh pr merge --merge --delete-branch
+```
+
+## Why CodraGraph helps here
+
+The hardest part of choosing a strategy isn't the mechanics — it's
+predicting whether your branch will conflict structurally with main.
+CodraGraph's `diff --semantic` tells you exactly which APIs / signatures
+changed on each side, so you can see *before* the merge whether your
+branch and main both touched the same callgraph regions.
+
+```
+codragraph diff main HEAD --semantic --json | jq '.semantic'
+→ added APIs / removed APIs / classified modifications on YOUR branch
+
+codragraph diff <last-shared-ancestor> main --semantic --json | jq '.semantic'
+→ what main has done since you forked
+```
+
+If both diffs touch overlapping symbols, prefer **merge** (preserves both
+sides as branches you can reason about) over rebase (which re-writes your
+side and may produce noisy conflicts).
+
+## Pitfalls
+
+| Pitfall | Symptom | Fix |
+|---|---|---|
+| Rebasing a shared branch | Collaborators report "diverged history", lost commits | Merge instead; don't rebase shared branches without coordination |
+| Squash-merge into long-running branch | Loses individual commit context | Use rebase-and-merge for branches that need history preserved |
+| `git pull` without `--rebase` flag on a feature branch | Random merge bubbles in your branch | Set `git config --global pull.rebase true` or always `pull --rebase` on feature branches |
+| Rebasing ON TOP of work in progress (uncommitted) | "Your local changes would be overwritten" | `git stash` first, rebase, `git stash pop` |
+
+## Checklist before merging a PR
+
+```
+- [ ] CI green (lint, tests, typecheck)
+- [ ] codragraph_detect_changes({scope: "compare", base_ref: "main"}) clean
+- [ ] codragraph diff main HEAD --semantic — review removed APIs
+- [ ] PR description matches the (would-be-squash) commit message
+- [ ] Decided strategy: squash (single change) vs rebase-and-merge (multiple atomic) vs merge (release/topology)
+- [ ] gh pr merge --squash --delete-branch  (or appropriate flag)
+```
+
+## Example: "Should I rebase or merge main into my 4-day-old branch?"
+
+```
+1. Check if the branch is shared:
+   git config branch.<your-branch>.remote
+   → "origin"  — yes, pushed.
+
+2. Check who else might have it:
+   gh api repos/{owner}/{repo}/pulls?head={your-branch} --jq '.[].user.login'
+   git log origin/<your-branch>..main --oneline | head
+   → no co-authors observed; just you and CI.
+
+3. Check structural conflict potential:
+   codragraph diff main <your-branch> --semantic
+   → 2 added APIs, 1 modified signature
+   codragraph diff <merge-base> main --semantic
+   → 0 changes touching the same files
+   → no structural conflict expected.
+
+4. Decision: rebase (it's effectively local) + force-with-lease.
+   git fetch origin
+   git rebase origin/main
+   # Resolve any conflicts file-by-file
+   git push --force-with-lease
+
+5. If structural conflict HAD been likely → merge, not rebase.
+```