@codragraph/cli 1.6.3 → 2.0.0

package/skills/codragraph-git-recovery.md

@@ -0,0 +1,181 @@
+---
+name: codragraph-git-recovery
+description: "Use when work appears lost — bad reset, dropped commit, blown-away stash, deleted branch, broken merge, accidental rm in tracked files. Covers reflog spelunking, stash recovery, dangling-commit revival, and what's actually unrecoverable. Examples: \"I lost my commits\", \"deleted my branch\", \"reset --hard by mistake\", \"recover work\", \"reflog\""
+---
+
+# Lost-Work Recovery Playbook
+
+## When to Use
+
+- "I ran `git reset --hard` and lost my work"
+- "I deleted a branch — can I get it back?"
+- "I dropped a stash by accident"
+- "I rm'd a file and committed before I noticed"
+- "Help, I think I lost everything."
+
+## The first-aid rules
+
+1. **STOP committing.** Every new commit pushes the lost ones further into
+   the reflog. Don't `git gc`, don't clone fresh.
+2. **Don't close the terminal yet.** Some recovery paths (e.g.,
+   `ORIG_HEAD`) live until you run another mutating command.
+3. **Reflog is your friend.** Default expiry is 90 days for reachable
+   commits, 30 days for unreachable. You almost always have time.
+4. **Local-only state survives EVERYTHING except** explicit `git gc
+   --prune=now` and disk loss. Even `reset --hard` leaves the old SHAs
+   in the reflog.
+
+## Recovery paths by symptom
+
+### "I ran `git reset --hard` and lost commits"
+
+```bash
+git reflog                            # newest first
+# → look for "HEAD@{1}: commit: <message>" — that was you, before reset
+git reset --hard HEAD@{1}             # OR the explicit SHA
+```
+
+`ORIG_HEAD` is the convenience alias for "what HEAD was before the most
+recent destructive operation":
+
+```bash
+git reset --hard ORIG_HEAD            # undoes the last reset / merge / rebase
+```
+
+### "I deleted a branch (`git branch -D`) and want it back"
+
+```bash
+git reflog                            # the last entry of that branch is here
+# → look for "<branch>@{N}: ..." OR walk HEAD's history to find where you were
+git branch <branch> <sha>             # recreates the branch at the old tip
+```
+
+If the reflog entry for the branch is gone (rare), search dangling
+commits:
+
+```bash
+git fsck --lost-found
+# → "dangling commit <sha>" lines
+git show <sha>                        # inspect each candidate
+git branch <branch> <sha>             # restore the one you want
+```
+
+### "I dropped a stash with `stash drop` (or by accident)"
+
+```bash
+git fsck --unreachable | grep commit
+# → unreachable commits include dropped stashes
+git show <sha>                        # confirm it's the right stash
+git stash apply <sha>                 # apply it back (or stash branch <name> <sha>)
+```
+
+### "I committed a file I shouldn't have" (no remote push yet)
+
+```bash
+git reset --soft HEAD~1               # undo the commit, keep the changes staged
+git restore --staged <file>           # unstage the offending file
+echo "<file>" >> .gitignore
+git commit -m "<original message>"
+```
+
+If you already pushed:
+
+```bash
+git reset --soft HEAD~1
+git restore --staged <file>
+echo "<file>" >> .gitignore
+git commit -m "<original message>"
+git push --force-with-lease           # SEE codragraph-git-force-push skill
+```
+
+If the file contained secrets, `--force-with-lease` is NOT enough —
+rotate the secret first, then use `git filter-repo` or BFG to scrub
+history (see codragraph-git-history-rewrite).
+
+### "I deleted a file with `rm` (NOT git rm) and haven't committed"
+
+```bash
+git restore <file>                    # restores from index
+# OR if it was never tracked, you're out of luck — check editor backups / Time Machine
+```
+
+### "I have a broken merge in progress"
+
+```bash
+git merge --abort                     # cleanly back out
+git rebase --abort                    # for in-progress rebase
+git cherry-pick --abort               # for in-progress cherry-pick
+```
+
+If `--abort` doesn't work (rare):
+
+```bash
+git reset --merge ORIG_HEAD
+```
+
+## When recovery WON'T work
+
+| Situation | Recoverable? |
+|---|---|
+| Reset --hard within last 90 days (no `gc --prune=now`) | ✓ via reflog |
+| Branch deleted within last 30 days | ✓ via fsck or branch reflog |
+| Stash dropped within last 30 days | ✓ via fsck |
+| Untracked / unstaged files deleted with `rm` | ✗ git never saw them |
+| `.git/` dir deleted | ✗ catastrophic; restore from backup or remote |
+| `git gc --prune=now` after the disaster | ✗ unreachable objects gone |
+| Force-pushed-over commits AND local clone gone | ✗ unless GitHub Support recovers |
+
+## Recovery diagnostics
+
+```bash
+# What does my reflog look like?
+git reflog --all --date=iso | head -50
+
+# What dangling commits exist?
+git fsck --lost-found
+
+# What was HEAD recently?
+git reflog show HEAD --date=iso | head -10
+
+# What was BRANCH recently?
+git reflog show <branch> --date=iso | head -10
+
+# Where did this commit live? (by sha)
+git branch --contains <sha>
+git tag --contains <sha>
+```
+
+## Why CodraGraph helps after recovery
+
+Recovery is mechanical (reflog → reset). The real question is "did I
+actually get back what I lost?" CodraGraph's diff lets you compare:
+
+```bash
+# Compare your recovered tree to the suspected lost-work SHA:
+codragraph diff <recovered-head> <reflog-candidate-sha> --semantic
+
+# If you see addedAPIs in the candidate that aren't in your recovered HEAD,
+# the recovery is incomplete — try a different reflog entry.
+```
+
+For deleted branches with no clear "right" tip:
+
+```bash
+git fsck --lost-found
+# For each candidate dangling-commit SHA:
+codragraph diff main <dangling-sha> --semantic
+# Pick the one whose diff matches the work you remember doing.
+```
+
+## Checklist when in panic mode
+
+```
+- [ ] STOP committing / running git gc / reinstalling
+- [ ] git reflog | head -30 — see what's there
+- [ ] Identify the candidate SHA for the lost work
+- [ ] git show <sha> to verify it's the right thing
+- [ ] git reset --hard / git branch <name> <sha> / git stash apply <sha>
+- [ ] codragraph diff to verify the recovery captured the real work
+- [ ] Set up git config --global core.autocrlf and longer reflog expiry
+      (gc.reflogExpire) for the future
+```

package/skills/codragraph-git-worktree.md

@@ -0,0 +1,145 @@
+---
+name: codragraph-git-worktree
+description: "Use when working on multiple branches in parallel without re-cloning, juggling a long-running branch alongside hotfixes, or running CI/build on one branch while editing another. Covers `git worktree` setup, conventions, and gotchas. Examples: \"work on two branches at once\", \"git worktree\", \"hotfix without losing my context\", \"avoid stash-juggling\""
+---
+
+# Parallel Branches with `git worktree`
+
+## When to Use
+
+- "I'm in the middle of something and need to do a hotfix on main."
+- "I want CI to run on one branch while I edit another."
+- "I have N agents working on N branches simultaneously."
+- "I'm sick of `git stash` between branch switches."
+
+## The idea
+
+A *worktree* is a separate working directory backed by the same git
+repository. One `.git/`, many checkouts. Switching between branches no
+longer requires re-running build / re-installing deps / re-warming editor
+indexes — you just `cd` to a different directory.
+
+## Setup
+
+```bash
+# From inside your existing repo (e.g. ~/code/myrepo):
+git worktree add ../myrepo-hotfix main          # check out 'main' at ../myrepo-hotfix
+git worktree add ../myrepo-feat-x feat/x        # check out feat/x at ../myrepo-feat-x
+
+# List all worktrees:
+git worktree list
+# → /home/anit/code/myrepo            abc1234 [feature/foo]
+# → /home/anit/code/myrepo-hotfix     def5678 [main]
+# → /home/anit/code/myrepo-feat-x     fed9876 [feat/x]
+
+# Each is a real working directory. cd into it; git commands operate on its
+# checked-out branch automatically.
+cd ../myrepo-hotfix
+git status                                       # → on branch 'main'
+```
+
+## Conventions that scale
+
+```
+~/code/
+├── myrepo/                # main worktree (your "primary" branch's checkout)
+├── myrepo-hotfix/         # for emergency fixes off main
+├── myrepo-pr-143/         # parking a PR for review
+└── myrepo-bisect/         # dedicated to long-running bisects
+```
+
+Or co-locate inside the primary repo as siblings under `.worktrees/`:
+
+```bash
+mkdir -p .worktrees
+git worktree add .worktrees/hotfix main
+echo ".worktrees/" >> .gitignore                # don't index worktrees as files
+```
+
+## Removing worktrees
+
+```bash
+git worktree remove ../myrepo-hotfix
+# or, if the directory was already deleted manually:
+git worktree prune
+```
+
+## Why CodraGraph helps here
+
+Each worktree gets its own working directory but shares the `.git/`. This
+matters for indexing: CodraGraph indexes `.codragraph/` in the working
+directory, so each worktree gets its OWN index. That's actually useful:
+
+```bash
+# Two worktrees, two independent CodraGraph indexes.
+cd ~/code/myrepo                                  # primary, on feature/foo
+codragraph analyze                                # index of feature/foo
+
+cd ~/code/myrepo-hotfix                           # worktree, on main
+codragraph analyze                                # index of main
+
+# Now you can run cross-worktree impact analysis:
+codragraph_query({repo: "myrepo", query: "auth"})        # primary index
+codragraph_query({repo: "myrepo-hotfix", query: "auth"}) # main's index
+```
+
+This is especially handy for **migration tracking** (compare a
+long-running migration branch's structural state to current main without
+checking out and re-indexing repeatedly).
+
+## Pitfalls
+
+| Pitfall | What happens | Fix |
+|---|---|---|
+| Same branch checked out in two worktrees | git refuses; only one worktree per branch | Use a different branch in the second worktree (or `--detach`) |
+| Worktree dir deleted manually (no `worktree remove`) | git still tracks it as live | `git worktree prune` |
+| Hooks / config differ across worktrees | Worktrees share `.git/` but each has its own `.git/info/` and per-worktree config | Use `git config --worktree` for per-worktree settings |
+| Editor's "open repo" features confused | VS Code sometimes treats each worktree as its own repo | Open each worktree as a separate workspace; this is actually correct |
+| `npm install` in every worktree | Slow, duplicated `node_modules` | Use pnpm with shared store, or yarn berry's PnP |
+
+## Variants
+
+```bash
+# Detached HEAD worktree (no branch — useful for inspecting old commits):
+git worktree add --detach ../myrepo-old <commit-sha>
+
+# Lock a worktree (prevents `worktree prune` from cleaning it):
+git worktree lock ../myrepo-old
+
+# Move a worktree:
+git worktree move ../myrepo-old ../myrepo-archive
+```
+
+## Checklist
+
+```
+- [ ] Created worktree with a clear directory name and the right branch
+- [ ] Confirmed `git worktree list` shows all expected entries
+- [ ] Per-worktree CodraGraph index where relevant (codragraph analyze in each)
+- [ ] Editor opened per worktree (separate workspace each)
+- [ ] When done: git worktree remove <path> (or rm + git worktree prune)
+```
+
+## Example: "I need to ship a hotfix without losing my WIP"
+
+```bash
+# Currently on feature/big-refactor, 8 uncommitted files, half-broken.
+
+# 1. Create a worktree for the hotfix off main
+git worktree add ../myrepo-hotfix main
+
+# 2. cd over and do the work
+cd ../myrepo-hotfix
+git switch -c hotfix/null-pointer
+# ... edit, test, commit ...
+git push -u origin hotfix/null-pointer
+gh pr create --title "..." --body "..."
+gh pr merge --squash --delete-branch
+
+# 3. Clean up the worktree
+cd ../myrepo
+git worktree remove ../myrepo-hotfix
+
+# 4. Continue your refactor as if nothing happened
+git status                                       # still 8 uncommitted files, intact
+```

package/skills/codragraph-guide.md

@@ -15,7 +15,7 @@ For any task involving code understanding, debugging, impact analysis, or refact
 2. **Match your task to a skill below** and **read that skill file**
 3. **Follow the skill's workflow and checklist**
 
-> If step 1 warns the index is stale, run `npx codragraph analyze` in the terminal first.
+> If step 1 warns the index is stale, run `npx @codragraph/cli analyze` in the terminal first.
 
 ## Skills
 

package/skills/codragraph-impact-analysis.md

@@ -23,7 +23,7 @@ description: "Use when the user wants to know what will break if they change som
 4. Assess risk and report to user
 ```
 
-> If "Index is stale" → run `npx codragraph analyze` in terminal.
+> If "Index is stale" → run `npx @codragraph/cli analyze` in terminal.
 
 ## Checklist
 

package/skills/codragraph-migration-tracking.md

@@ -0,0 +1,130 @@
+---
+name: codragraph-migration-tracking
+description: "Use when tracking the progress of a phased refactor or migration (renaming an API, swapping a library, moving from class- to functional-components, deprecating a flag). Examples: \"how far is the migration\", \"what's left to migrate\", \"track this refactor\", \"are we done with the move from X to Y\", \"is the migration done\""
+---
+
+# Migration Progress Tracking with CodraGraph
+
+## When to Use
+
+- "How far along is the migration from `<old>` to `<new>`?"
+- "What's left to migrate / refactor / deprecate?"
+- "Are we done with `<old API>`?"
+- Coordinating a phased refactor across many PRs
+- Reporting migration status to stakeholders
+
+## Why CodraGraph helps here
+
+Migrations span dozens of PRs and weeks. Without a structural index, the
+question "are we done?" reduces to grep-and-eyeball. CodraGraph's versioned
+graphstore lets you snapshot the codebase at the start of the migration,
+then diff against today to see exactly what's converted and what isn't.
+Pair with `cypher` to count remaining instances of the old pattern.
+
+## Workflow
+
+```
+1. Establish baseline (once, at migration start):
+   codragraph commit -m "migration baseline: pre-X-removal"
+   codragraph branch create migration-baseline
+   → captures the structural state for later comparison
+
+2. Count remaining old-API call sites today:
+   codragraph_cypher({query: `
+     MATCH (n)-[:CALLS]->(target)
+     WHERE target.name = '<oldFunction>'
+     RETURN n.filePath, count(n) AS callers
+     ORDER BY callers DESC
+   `})
+   → "27 callers in 14 files still using <oldFunction>"
+
+3. Diff against the baseline to see structural progress:
+   codragraph diff migration-baseline HEAD --semantic --json
+   → look at removedAPIs (old surface gone), addedAPIs (new surface added),
+     classifiedModifications (signatures swapped)
+
+4. Assess flows still touching the old API:
+   codragraph_impact({target: "<oldFunction>", direction: "upstream"})
+   → list of remaining callers grouped by depth
+
+5. Suggest the next batch of files to migrate (highest caller-count first)
+```
+
+> If `migration-baseline` doesn't exist, you skipped step 1 — fall back to
+> the earliest commit in `codragraph log` as a baseline (less precise but
+> usable).
+
+## Checklist
+
+```
+- [ ] Establish a baseline (branch / tagged commit) at migration start
+- [ ] Cypher count of remaining old-API references
+- [ ] codragraph diff baseline HEAD --semantic for structural progress
+- [ ] impact upstream on the old API → list of remaining callers
+- [ ] Group remaining work by file → suggest next batch
+- [ ] Report: "<N>%% of <total> call sites converted. <K> files remaining."
+```
+
+## Migration Patterns This Catches
+
+| Pattern | Cypher hint |
+| --- | --- |
+| API rename (foo → bar) | `MATCH ()-[:CALLS]->(n) WHERE n.name = 'foo' RETURN n.filePath, count(*)` |
+| Library swap (lodash → native) | Filter on `filePath` for files still importing the old library |
+| Class → functional component | Match by `n.label = 'Class'` in the relevant directory |
+| Feature flag removal | Cypher for string literals matching the flag name |
+| Type-system migration (any → typed) | `MATCH (n) WHERE n.returnType = 'any' OR n.returnType IS NULL` |
+
+## Example: "Track our migration from `validatePaymentV1` to `validatePaymentV2`"
+
+```
+1. (Baseline established 3 months ago: codragraph branch migration-v2-start)
+
+2. codragraph_cypher({query: `
+     MATCH (caller)-[:CALLS]->(target)
+     WHERE target.name STARTS WITH 'validatePayment'
+     RETURN target.name, count(caller) AS callers
+   `})
+   → validatePaymentV1: 8 callers
+   → validatePaymentV2: 31 callers
+
+3. codragraph diff migration-v2-start HEAD --semantic
+   → addedAPIs: validatePaymentV2 (and 4 helpers)
+   → classifiedModifications: 23 functions migrated from V1 to V2
+   → removedAPIs: 0 (V1 still exported)
+
+4. codragraph_impact({target: "validatePaymentV1", direction: "upstream"})
+   → d=1 callers (still on V1):
+       - legacyCheckout (src/legacy/checkout.ts)
+       - webhookV1 (src/webhooks/v1.ts)
+       - … 6 more
+
+Report: 79%% migrated (31 / 39 callers). 8 callers in 3 files remaining.
+Next batch: src/legacy/checkout.ts (5 callers in one file).
+```
+
+## Output Format
+
+```markdown
+## Migration Progress: <name>
+
+### Baseline
+`migration-baseline` (3 months ago, before refactor started)
+
+### Current state
+- **Converted:** 31 / 39 call sites (79%%)
+- **Remaining:** 8 callers in 3 files
+- **Old API surface:** still exported (cannot remove yet)
+- **New API surface:** stable (4 helpers added)
+
+### Remaining work
+| File | Old-API callers | Notes |
+| --- | --- | --- |
+| `src/legacy/checkout.ts` | 5 | one batch |
+| `src/webhooks/v1.ts` | 2 | tied to legacy webhook contract |
+| ... | ... | ... |
+
+### Done criteria
+- 0 remaining callers
+- removedAPIs in `codragraph diff` includes `validatePaymentV1`
+```

package/skills/codragraph-notebook-context.md

@@ -0,0 +1,136 @@
+---
+name: codragraph-notebook-context
+description: "Use when working with notebook-heavy projects (Jupyter, Databricks, Colab, Marimo) where each notebook contains long pipelines of cells, and the user needs to navigate, summarize, or refactor across them. Examples: \"what do these notebooks do\", \"summarize this analysis pipeline\", \"refactor cells from this notebook into modules\", \"data analysis project tour\""
+---
+
+# Notebook-Heavy Project Navigation with CodraGraph
+
+## When to Use
+
+- "What's in these notebooks?"
+- "Summarize the analysis pipeline across `<notebook>.ipynb`"
+- "Help me refactor a notebook into a proper module"
+- "What functions defined in notebooks does the production code call?"
+- "Audit the data analyses in this project"
+
+## Why CodraGraph helps here
+
+Data-science / analytics projects often have 80%% of the logic inside
+`.ipynb` files: top-level imports, helper functions, ad-hoc transforms.
+CodraGraph indexes Python (the most common notebook language) and treats
+notebook-derived code as first-class graph content. That means `query`,
+`context`, and `impact` work on notebook-defined symbols just like
+production-code symbols, so you can navigate a 30-cell notebook the same
+way you'd navigate a typical module.
+
+## Workflow
+
+```
+1. List notebook-derived symbols:
+   codragraph_cypher({query: `
+     MATCH (n)
+     WHERE n.filePath ENDS WITH '.ipynb'
+     RETURN n.filePath, n.name, labels(n)[0] AS label
+     ORDER BY n.filePath, n.startLine
+   `})
+   → every function/class defined inside any notebook
+
+2. For each notebook of interest:
+   codragraph_query({query: "<notebook concept, e.g. 'monthly retention'>"})
+   → top-ranked symbols across notebooks (process-grouped)
+
+3. codragraph_context({name: "<notebook function>"})
+   → callers (other notebooks? production?) and callees (libraries used)
+
+4. Cross-notebook reuse check:
+   codragraph_impact({target: "<helper>", direction: "upstream"})
+   → if multiple notebooks call the same helper, that's a refactor candidate
+     (extract into a shared module)
+
+5. Production / notebook bridge:
+   codragraph_cypher({query: `
+     MATCH (caller)-[:CALLS]->(target)
+     WHERE NOT caller.filePath ENDS WITH '.ipynb'
+       AND target.filePath ENDS WITH '.ipynb'
+     RETURN caller.filePath, target.filePath, target.name
+   `})
+   → production code calling into notebooks (usually a bug — flag it)
+```
+
+> Notebooks export when wrapped in nbconvert / papermill / databricks-cli.
+> CodraGraph parses the `.ipynb` JSON and treats each code cell as part of
+> the file's symbol space.
+
+## Checklist
+
+```
+- [ ] Cypher query for all symbols with .ipynb file paths
+- [ ] Group by notebook → see total symbol count per notebook
+- [ ] query for the analysis topic to find top-ranked symbols
+- [ ] context on key notebook helpers
+- [ ] impact upstream on cross-notebook helpers → refactor candidates
+- [ ] Cypher for production-code → notebook calls (bridge audit)
+```
+
+## Refactor Signals
+
+| Signal | What to do |
+| --- | --- |
+| Same helper defined in 3+ notebooks | Extract into a shared `.py` module |
+| Notebook function called from production code | Move to production module; notebook should re-import |
+| Notebook with > 30 distinct symbols | Likely needs to be split (or graduated to a module) |
+| Notebook calling another notebook | Strong refactor signal — extract the shared part |
+
+## Example: "Summarize the customer-churn analyses in notebooks/"
+
+```
+1. codragraph_cypher({
+     query: `MATCH (n) WHERE n.filePath STARTS WITH 'notebooks/'
+              AND n.filePath ENDS WITH '.ipynb'
+              RETURN n.filePath, count(n) AS symbols
+              ORDER BY symbols DESC`
+   })
+   → 4 notebooks: churn_baseline.ipynb (28 symbols),
+                  churn_features.ipynb (35 symbols),
+                  churn_model.ipynb (22 symbols),
+                  churn_eval.ipynb (12 symbols)
+
+2. codragraph_query({query: "customer churn cohort"})
+   → top symbols across the 4 notebooks, grouped by detected processes
+
+3. codragraph_context({name: "compute_cohort_retention"})
+   → defined in: churn_features.ipynb
+   → called by: churn_model.ipynb, churn_eval.ipynb (TWO notebooks)
+   → REFACTOR CANDIDATE — extract into src/churn/cohort.py
+
+4. codragraph_cypher for production → notebook calls
+   → 1 hit: scripts/daily_churn_report.py imports from churn_eval.ipynb ⚠
+   → Production should not depend on a notebook. Extract.
+
+Findings:
+- 97 total symbols across 4 notebooks
+- 1 multi-notebook helper (compute_cohort_retention) → extract to module
+- 1 production → notebook bridge (daily_churn_report) → flag as tech debt
+```
+
+## Output Format
+
+```markdown
+## Notebook Tour: `notebooks/`
+
+### Notebooks
+| Notebook | Symbols | Purpose (top-3 symbols) |
+| --- | --- | --- |
+| churn_baseline.ipynb | 28 | baseline_churn_rate, … |
+| churn_features.ipynb | 35 | compute_cohort_retention, … |
+| churn_model.ipynb | 22 | train_churn_classifier, … |
+| churn_eval.ipynb | 12 | evaluate_churn_model, … |
+
+### Refactor candidates
+1. `compute_cohort_retention` — used in 2 notebooks → extract to `src/churn/cohort.py`
+2. ...
+
+### Bridge audits
+- ⚠ `scripts/daily_churn_report.py` imports from `churn_eval.ipynb` —
+  production should not depend on a notebook.
+```