@codragraph/cli 1.6.3 → 2.0.0

package/skills/codragraph-cross-repo-impact.md

@@ -0,0 +1,135 @@
+---
+name: codragraph-cross-repo-impact
+description: "Use when assessing the blast radius of a change that crosses repository boundaries — a shared library used by multiple services, a contract / protobuf / OpenAPI schema consumed by N consumers, a microservices change. Examples: \"what services consume X\", \"cross-repo blast radius\", \"will this break the consumers\", \"who depends on this contract\""
+---
+
+# Cross-Repo Impact Analysis with CodraGraph
+
+## When to Use
+
+- "What other repos consume `<symbol>` from this one?"
+- "If I change this gRPC method / OpenAPI route / protobuf message, what breaks?"
+- "Cross-repo blast radius for `<change>`"
+- Microservices architecture: assessing a contract change
+- Shared-library author: deciding if a function is safe to remove
+
+## Why CodraGraph helps here
+
+CodraGraph's **groups** (sets of related repos sharing a `group.yaml`)
+maintain a Contract Registry — provider/consumer rows for every cross-repo
+reference (gRPC service / method, OpenAPI route, protobuf message). The
+group-mode `impact` walks both the local call graph AND the contract
+bridges, so a single call returns the blast radius across every member
+repo. You don't need to re-run impact in each consumer separately.
+
+## Workflow
+
+```
+1. Identify the group:
+   codragraph_group_list({})
+   → list of groups + their member repos
+
+2. Confirm the symbol exists in the producer repo:
+   codragraph_context({repo: "<producerRepo>", name: "<symbol>"})
+
+3. Run group-mode impact:
+   codragraph_impact({repo: "@<group>", target: "<symbol>", direction: "upstream"})
+   → d=1 callers spanning every group member
+     (in-repo callers + contract-bridge consumers)
+
+4. Inspect the Contract Registry to see provider/consumer rows directly:
+   READ codragraph://group/<groupName>/contracts
+   → list of contracts touching the symbol or its API
+
+5. Check group-status / staleness:
+   READ codragraph://group/<groupName>/status
+   → which member repos haven't been re-indexed recently
+     (stale members produce stale impact results)
+
+6. Surface the worst-case consumer:
+   any consumer not updated since the schema change = potential breakage
+```
+
+> If any member repo's index is stale, group-mode impact may underreport.
+> Re-analyze stale members before relying on the results.
+
+## Checklist
+
+```
+- [ ] group_list to confirm the group exists and the producer is a member
+- [ ] context on the symbol in the producer repo
+- [ ] Group-mode impact upstream
+- [ ] Inspect Contract Registry for provider/consumer rows
+- [ ] Check group/status for stale members; re-analyze if needed
+- [ ] List affected consumer repos by impact depth
+- [ ] Recommend coordinated PRs across consumers (if breaking)
+```
+
+## When to Use Which Tool
+
+| Question | Tool |
+| --- | --- |
+| "Which repos are in my group?" | `group_list` |
+| "What contracts cross between member A and member B?" | Contract Registry resource |
+| "If I change this provider method, what breaks?" | Group-mode `impact` |
+| "Are all consumers up to date with the latest provider commit?" | `group/<name>/status` resource |
+| "What's the structural diff between last release and now in repo X?" | Per-repo `diff --semantic` |
+
+## Example: "Will renaming `getUserProfile` break my microservices?"
+
+```
+1. codragraph_group_list({})
+   → group "platform": [user-service, web-app, mobile-bff, admin-portal]
+
+2. codragraph_context({repo: "user-service", name: "getUserProfile"})
+   → exported gRPC method in user.proto, defined in user-service
+
+3. codragraph_impact({repo: "@platform", target: "getUserProfile", direction: "upstream"})
+   → d=1 callers (across the group):
+       - web-app/src/api/userClient.ts (CALLS via grpc-web)
+       - mobile-bff/internal/user.go (CALLS via grpc.NewClient)
+       - admin-portal/src/services/users.tsx (CALLS via grpc-web)
+   → 3 consumer repos depend on this method by exact name.
+
+4. READ codragraph://group/platform/contracts
+   → user.UserService.getUserProfile: provider=user-service,
+     consumers=[web-app, mobile-bff, admin-portal]
+
+5. READ codragraph://group/platform/status
+   → web-app last indexed 2 hours ago ✓
+   → mobile-bff last indexed 3 days ago ⚠ (might miss recent callers)
+   → admin-portal last indexed 1 month ago ⚠⚠ (re-analyze first!)
+
+6. Recommendation:
+   - HIGH-RISK rename. 3 consumer repos must change in lockstep.
+   - Re-index admin-portal before trusting the d=1 list.
+   - Coordinated PR sequence:
+     1. Add new method (getUserProfileV2) in user-service
+     2. Migrate web-app, mobile-bff, admin-portal to V2
+     3. Remove getUserProfile in user-service after all consumers ship
+   - Alternative: keep both, deprecate old, drop in next major.
+```
+
+## Output Format
+
+```markdown
+## Cross-Repo Impact: `<symbol>` in `<producer-repo>` (group `@<group>`)
+
+### Consumers (d=1)
+| Repo | Caller | Path | Notes |
+| --- | --- | --- | --- |
+| web-app | userClient.ts | grpc-web | active |
+| mobile-bff | internal/user.go | grpc native | active |
+| admin-portal | services/users.tsx | grpc-web | last indexed 1mo ago ⚠ |
+
+### Contracts touching this symbol
+- `user.UserService.getUserProfile` (provider: user-service)
+
+### Staleness
+Re-analyze `admin-portal` before trusting these results.
+
+### Recommended migration sequence
+1. Add `getUserProfileV2` alongside the old method
+2. Migrate consumers to V2 (separate PRs per repo)
+3. Remove old method after all consumers ship
+```

package/skills/codragraph-data-lineage.md

@@ -0,0 +1,137 @@
+---
+name: codragraph-data-lineage
+description: "Use when tracing data flow through an ETL pipeline, finding where a column or table is read/written, mapping data dependencies in a notebook-heavy or data-engineering project. Examples: \"where does this data come from\", \"trace this column\", \"data lineage for X\", \"who reads from this table\", \"what's downstream of this query\""
+---
+
+# Data Lineage with CodraGraph
+
+## When to Use
+
+- "Where does the `user_events` table get written?"
+- "Trace the data flow that produces `daily_revenue.csv`"
+- "What's downstream of this Snowflake query?"
+- "Which notebook cells transform this DataFrame?"
+- Auditing a data pipeline before changing a schema
+- Understanding an unfamiliar ETL project
+
+## Why CodraGraph helps here
+
+Data pipelines often look like a graph of small functions: `extract_*`,
+`transform_*`, `load_*`, `enrich_*`. Their connections are *function calls*
+plus *string-literal table names* and *file paths*. CodraGraph already
+captures the call graph; combining it with `query` over identifier strings
+gives you data lineage at the *symbol* level, regardless of whether your
+pipeline is in vanilla Python, Airflow, dbt, Pandas, PySpark, or Notebooks.
+
+## Workflow
+
+```
+1. codragraph_query({query: "<table_or_column_name>"})
+   → find every symbol that mentions the data identifier
+
+2. For each candidate symbol:
+   codragraph_context({name: "<symbol>"})
+   → see callers (who triggers this read/write) and callees (what it depends on)
+
+3. Walk the producer side (downstream → upstream):
+   codragraph_impact({target: "<load function>", direction: "upstream"})
+   → trace back to where the data originates
+
+4. Walk the consumer side (upstream → downstream):
+   codragraph_impact({target: "<extract function>", direction: "downstream"})
+   → trace forward to every transform / sink that depends on it
+
+5. READ codragraph://repo/{name}/process/<pipeline-flow>
+   → the canonical step-by-step flow if CodraGraph detected this as a process
+
+6. Build the lineage diagram: source → transform stages → sink
+```
+
+> CodraGraph is graph-aware, not SQL-aware: it sees a string literal that
+> *looks* like a table name, but doesn't parse SQL semantics. For mature SQL
+> lineage tooling (column-level resolution), pair with `codragraph-sql-tracing`
+> skill and a SQL parser like sqlglot.
+
+## Checklist
+
+```
+- [ ] query for the table/column/file identifier
+- [ ] context on each candidate to map producers vs consumers
+- [ ] impact upstream on the load/sink function
+- [ ] impact downstream on the extract/source function
+- [ ] Cross-reference with processes for canonical pipeline flows
+- [ ] Render the lineage as: source → transform_1 → transform_2 → sink
+```
+
+## Identifier Patterns to Search
+
+| Layer | Search hints |
+| --- | --- |
+| File-based source | filename, path fragments (`raw_events.parquet`) |
+| Database table | bare table name + `FROM table_name` |
+| Column / field | column name in conjunction with the table name |
+| API endpoint | URL path or function name (`fetchUserEvents`) |
+| Event topic / queue | topic name (`user.signup.v2`) |
+
+## Example: "Where does daily_revenue.csv come from?"
+
+```
+1. codragraph_query({query: "daily_revenue"})
+   → 4 symbols:
+     - write_daily_revenue (src/etl/daily.py)
+     - read_daily_revenue (src/dashboards/finance.py)
+     - DailyRevenueRow (src/schemas/types.py)
+     - daily_revenue_dag (airflow/dags/finance_etl.py)
+
+2. codragraph_context({name: "write_daily_revenue"})
+   → callers: daily_revenue_dag (Airflow task)
+   → callees: aggregate_orders, attach_currency_rates, format_csv_row
+
+3. codragraph_impact({target: "aggregate_orders", direction: "upstream"})
+   → reads from: orders_raw, returns_raw (both tables)
+
+4. codragraph_impact({target: "read_daily_revenue", direction: "downstream"})
+   → consumed by: finance_dashboard.render(), revenue_alerts.check()
+
+5. READ codragraph://repo/CodraGraph/process/DailyRevenueETL
+   → 6 steps:
+       fetch_orders → fetch_returns → aggregate_orders →
+       attach_currency_rates → format_csv_row → write_daily_revenue
+
+Lineage:
+  orders_raw, returns_raw  (DB tables)
+       ↓
+  fetch_orders + fetch_returns  (extract)
+       ↓
+  aggregate_orders → attach_currency_rates → format_csv_row  (transform)
+       ↓
+  daily_revenue.csv  (sink)
+       ↓
+  finance_dashboard, revenue_alerts  (consumers)
+```
+
+## Output Format
+
+```markdown
+## Data Lineage: <data-asset>
+
+### Sources
+- `orders_raw` (DB)
+- `returns_raw` (DB)
+
+### Pipeline (DailyRevenueETL flow, 6 steps)
+1. `fetch_orders` — reads `orders_raw`
+2. `fetch_returns` — reads `returns_raw`
+3. `aggregate_orders` — joins, sums by day
+4. `attach_currency_rates` — enriches with FX
+5. `format_csv_row` — schema-conforming serialization
+6. `write_daily_revenue` — writes `daily_revenue.csv`
+
+### Consumers
+- `finance_dashboard` (renders chart)
+- `revenue_alerts` (threshold checks)
+
+### Risk if `<schema/source>` changes
+- 6 transform stages depend on it
+- 2 consumers depend on the output schema
+```

package/skills/codragraph-dead-code.md

@@ -0,0 +1,119 @@
+---
+name: codragraph-dead-code
+description: "Use when the user wants to find unused code, orphan functions/classes, dead code, or symbols safe to delete. Examples: \"what's unused\", \"find dead code\", \"can I delete this function\", \"orphan symbols\", \"clean up unused exports\""
+---
+
+# Dead Code Detection with CodraGraph
+
+## When to Use
+
+- "What's unused in this codebase?"
+- "Find dead code / orphan functions / unused exports"
+- "Can I safely delete `<symbol>`?"
+- Periodic cleanup before a release
+- Identifying candidates for the next refactor
+
+## Why CodraGraph helps here
+
+Linters can find unreachable code in *one file*. CodraGraph walks the
+*whole-repo* call graph, including dynamic dispatch, framework entry
+points, and exports — so it can tell you a symbol is genuinely unreachable
+rather than just "the linter couldn't see the caller."
+
+The trick is to combine three signals:
+
+1. **No incoming references** — `cypher` query for symbols with zero
+   `<-[:CALLS|REFERENCES]-` edges.
+2. **Not exported** — internal-only symbols are stronger candidates than
+   `isExported = true` ones (which may be public API).
+3. **Not in any process** — execution flows are the canonical "this is
+   used" signal; symbols outside every process are extra suspect.
+
+## Workflow
+
+```
+1. codragraph_cypher({query: `
+     MATCH (n)
+     WHERE NOT (n)<-[:CALLS|REFERENCES]-()
+       AND NOT (n.isExported = true)
+     RETURN n.id, n.name, labels(n)[0] AS label, n.filePath
+     LIMIT 200
+   `})
+   → list of orphan candidates
+
+2. For each candidate:
+   codragraph_context({name: "<candidate>"})
+   → confirm: 0 callers, 0 callees that matter, not in any process
+
+3. Cross-check against processes:
+   READ codragraph://repo/{name}/processes
+   → if the symbol appears in ANY process, it's not actually dead
+
+4. For exported orphans (potentially public API):
+   codragraph_impact({target: "<symbol>", direction: "upstream"})
+   → if d=1 has external callers (in another indexed repo group), keep it
+
+5. Group by file/cluster, prioritize by file size of dead code
+```
+
+> If "Index is stale" → run `npx @codragraph/cli analyze` first. Stale
+> indexes produce false-positive dead-code reports because new callers
+> aren't visible.
+
+## Checklist
+
+```
+- [ ] Cypher query for orphan symbols (no incoming edges, not exported)
+- [ ] context check on each candidate (confirm 0 callers)
+- [ ] Cross-reference with processes (symbols in flows are not dead)
+- [ ] For exported orphans, impact across groups (cross-repo callers?)
+- [ ] Group findings by file → suggest which files can lose the most code
+- [ ] Flag any candidate that's a framework convention (e.g., default export
+      of a Next.js page route) — those LOOK orphan but aren't
+```
+
+## Pitfalls
+
+| Pitfall | What to do |
+| --- | --- |
+| Framework conventions (Next.js pages, Astro routes, Django URLs) | Check `isEntryPoint` on the node — these often score high |
+| Test-only symbols | Filter `filePath CONTAINS '/test'` separately |
+| Re-exported symbols | A re-export creates `REFERENCES` edges; a true orphan has none |
+| Dynamic dispatch (factories, plugin systems) | Cross-check with `query` for the registration string |
+
+## Example: "Clean up unused code in src/utils/"
+
+```
+1. codragraph_cypher({
+     query: `MATCH (n) WHERE n.filePath STARTS WITH 'src/utils/'
+              AND NOT (n)<-[:CALLS|REFERENCES]-()
+              AND NOT (n.isExported = true)
+              RETURN n.id, n.name, n.filePath`
+   })
+   → 7 candidates
+
+2. codragraph_context({name: "formatLegacyDate"})
+   → 0 callers, 0 callees, not in any process. Truly dead.
+
+3. codragraph_context({name: "DEBUG_TIMER"})
+   → 0 callers but called dynamically via process.env injection.
+   → Keep it.
+
+4. Final: 6 of 7 candidates safe to delete. Total: 142 LoC across 4 files.
+```
+
+## Output Format
+
+```markdown
+## Dead Code Audit: <scope>
+
+### High-confidence (0 callers, 0 callees, not in any process)
+- `formatLegacyDate` — `src/utils/date.ts:42` (12 LoC)
+- ...
+
+### Possibly dead (verify dynamic dispatch first)
+- `DEBUG_TIMER` — used via env-driven hook?
+
+### Total cleanup potential
+N functions, M LoC, X files.
+```

package/skills/codragraph-debugging.md

@@ -22,7 +22,7 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
 4. codragraph_cypher({query: "MATCH path..."})                 → Custom traces if needed
 ```
 
-> 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-exploring.md

@@ -23,7 +23,7 @@ description: "Use when the user asks how code works, wants to understand archite
 5. READ codragraph://repo/{name}/process/{name}      → Trace full execution flow
 ```
 
-> If step 2 says "Index is stale" → run `npx codragraph analyze` in terminal.
+> If step 2 says "Index is stale" → run `npx @codragraph/cli analyze` in terminal.
 
 ## Checklist
 

package/skills/codragraph-gh-actions-debug.md

@@ -0,0 +1,162 @@
+---
+name: codragraph-gh-actions-debug
+description: "Use when a GitHub Actions workflow fails, needs to be re-run, dispatched manually, or inspected. Covers `gh run` for inspecting/rerunning runs, `gh workflow` for triggering, secrets, and the most common failure modes. Examples: \"why did CI fail\", \"rerun this workflow\", \"dispatch a workflow manually\", \"debug GitHub Action\", \"set GitHub secret\""
+---
+
+# GitHub Actions Debugging with `gh`
+
+## When to Use
+
+- "CI failed on my PR — show me why."
+- "Rerun the failed jobs only."
+- "Dispatch a workflow manually with custom inputs."
+- "Add or rotate a secret."
+- "Cancel a hung workflow run."
+
+## Lifecycle commands
+
+### List / inspect runs
+
+```bash
+gh run list                                       # most recent runs
+gh run list --workflow ci.yml                     # one workflow's runs
+gh run list --branch my-feature --status failure  # failed runs on a branch
+gh run list --json conclusion,databaseId,headBranch,name --jq '.[] | select(.conclusion=="failure")'
+
+gh run view <run-id>                              # run summary + jobs
+gh run view <run-id> --log                        # FULL logs (verbose)
+gh run view <run-id> --log-failed                 # only the failed steps' logs
+gh run view <run-id> --json jobs --jq '.jobs[] | {name, conclusion}'
+```
+
+If you don't know the run id:
+
+```bash
+# Most recent run on current branch:
+gh run view --branch "$(git branch --show-current)"
+
+# Most recent failed run anywhere:
+gh run list --status failure --limit 1 --json databaseId --jq '.[0].databaseId'
+```
+
+### Re-run
+
+```bash
+gh run rerun <run-id>                             # rerun the WHOLE run
+gh run rerun <run-id> --failed                    # only the failed jobs
+gh run rerun <run-id> --job <job-id>              # only one specific job
+gh run rerun <run-id> --debug                     # enable runner debug logging
+```
+
+`--failed` is the right default for "I think the failure was flaky."
+
+### Cancel / delete
+
+```bash
+gh run cancel <run-id>                            # cancel an in-progress run
+gh run delete <run-id>                            # remove from history (rare)
+gh run watch <run-id>                             # tail the run live
+```
+
+### Manual dispatch (workflow_dispatch)
+
+For workflows with `on: workflow_dispatch:`:
+
+```bash
+gh workflow list                                  # which workflows are dispatchable
+gh workflow run <workflow-name-or-id>             # run on default branch
+gh workflow run ci.yml --ref my-branch            # run on a specific branch
+gh workflow run deploy.yml --field environment=staging --field version=1.7.0
+```
+
+Re-list runs to see the dispatched one:
+
+```bash
+gh run list --workflow ci.yml --limit 5
+```
+
+### Secrets and variables
+
+```bash
+# Repo-scope secrets:
+gh secret list
+gh secret set ANTHROPIC_API_KEY --body "sk-…"
+gh secret set ANTHROPIC_API_KEY < ~/api-key.txt    # from file
+gh secret delete OLD_KEY
+
+# Repo-scope variables (non-secret):
+gh variable list
+gh variable set DEPLOY_REGION --body "us-east-1"
+
+# Environment-scope (e.g., production):
+gh secret set MY_KEY --env production --body "…"
+```
+
+## Why CodraGraph helps here
+
+When a workflow YAML changes break CI, treat the workflow as code: the
+PR review Action's structural diff doesn't help (Actions aren't TS/Python),
+but two CodraGraph patterns DO help:
+
+1. **Find the symbol the workflow invokes** — many workflows call into
+   the codebase (`npm test`, `npx my-cli`, `python scripts/foo.py`).
+   Trace what each step actually executes:
+
+```
+codragraph_query({query: "<command the action runs, e.g. 'analyze repo'>"})
+→ which CLI handler / script the workflow ends up running
+```
+
+2. **After a CI break, diff against the last green run's commit** — was
+   it a code change or a workflow YAML change?
+
+```
+gh run list --workflow ci.yml --status success --limit 1 --json headSha
+→ <last-green-sha>
+
+codragraph diff <last-green-sha> HEAD --semantic
+→ if structural diff is empty, the break is in YAML / env / runner — not code
+```
+
+## Failure-mode triage
+
+| Symptom | Likely cause | Where to look |
+|---|---|---|
+| `npm install` fails on Linux only | Native deps need apt packages | Add `apt-get install` step or use a different runner |
+| Tests pass locally, fail in CI | Env diff (Node version, locale, timezone) | Compare runner env vs local; add `node-version` matrix |
+| Workflow re-runs with no code change still fail | Flaky test or external service | `gh run rerun --failed --debug` and read the debug logs |
+| Action can't see secret | Secret scope mismatch | `gh secret list` per env / repo / org; secrets don't leak across environments |
+| Pull-request workflow can't write | Default `GITHUB_TOKEN` is read-only on PRs from forks | Switch to `pull_request_target` (with care) or PAT-based action |
+
+## Debugging steps that actually work
+
+```bash
+# 1. Re-run with debug:
+gh run rerun <run-id> --failed --debug
+
+# 2. Tail the live run:
+gh run watch <run-id>
+
+# 3. Pull only the failed step's logs:
+gh run view <run-id> --log-failed | less
+
+# 4. If you need full context, download artifacts:
+gh run download <run-id>
+ls ./
+
+# 5. To enable verbose runner logs without re-running, set repo secrets:
+gh secret set ACTIONS_RUNNER_DEBUG --body "true"
+gh secret set ACTIONS_STEP_DEBUG --body "true"
+# (re-run the workflow to pick these up)
+```
+
+## Pitfalls
+
+| Pitfall | Symptom | Fix |
+|---|---|---|
+| `--debug` doesn't show extra logs | Repo doesn't have the debug secrets set | Set `ACTIONS_STEP_DEBUG=true` repo secret |
+| Workflow doesn't appear in dispatch list | Missing `on: workflow_dispatch:` | Add the trigger to the workflow YAML |
+| Inputs to dispatch silently ignored | Type mismatch or missing `inputs:` block | Re-check the workflow YAML's `inputs:` schema |
+| Re-run doesn't pick up your fix | Re-run uses the SAME commit; you need a NEW push for the new code | Push a fix; or use `--debug` if you want runner-level debugging only |
+| Secrets leaked in logs | Used `${{ secrets.X }}` in a `run:` step that echoes | Use env: with secret values; never echo |
+```