@codragraph/cli 1.6.4 → 2.1.0

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-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 |
+```

package/skills/codragraph-gh-issue-workflow.md

@@ -0,0 +1,178 @@
+---
+name: codragraph-gh-issue-workflow
+description: "Use for issue management via GitHub CLI — create, triage, label, assign, link to PRs, manage projects (v2), close with reason. Examples: \"open an issue\", \"triage issues\", \"add labels\", \"link this PR to issue\", \"close issue\", \"manage GitHub projects\""
+---
+
+# Issue Workflow with `gh`
+
+## When to Use
+
+- "Open an issue for this bug."
+- "Triage the open issues — sort by labels / priority."
+- "Link this PR to issue #42 so it auto-closes on merge."
+- "Add this issue to my project board."
+- "Bulk-relabel old issues."
+
+## Lifecycle commands
+
+### Create
+
+```bash
+# Quick create:
+gh issue create --title "…" --body "…" --label bug --assignee "@me"
+
+# Multi-line body via HEREDOC:
+gh issue create --title "Auth times out after 30s" --body "$(cat <<'EOF'
+## Repro
+1. Login as user X
+2. Wait 30s
+3. Click anywhere
+
+## Expected
+Session refresh transparent.
+
+## Actual
+Hard logout with no warning.
+
+## Environment
+- App version: …
+- Browser: …
+EOF
+)"
+
+# From a template (.github/ISSUE_TEMPLATE/<x>.md):
+gh issue create --template bug_report.md
+```
+
+### List / search / view
+
+```bash
+gh issue list                                     # open issues
+gh issue list --state all --limit 100             # everything
+gh issue list --label "bug,priority:high"          # filter
+gh issue list --search "in:title auth"             # full-text in title/body
+gh issue list --assignee "@me"                    # assigned to you
+
+gh issue view <N>                                 # one issue
+gh issue view <N> --comments                      # include comments
+gh issue status                                   # issues needing your attention
+```
+
+### Triage / edit
+
+```bash
+gh issue edit <N> --add-label "bug,needs-repro" --add-assignee @teammate
+gh issue edit <N> --remove-label "stale" --milestone "v1.7.0"
+gh issue comment <N> --body "Cannot repro. Could you share <X>?"
+gh issue pin <N>                                  # pin to top of issues page
+gh issue unpin <N>
+gh issue lock <N>                                 # freeze further comments
+gh issue unlock <N>
+```
+
+### Link issues to PRs
+
+GitHub auto-closes the issue when a PR with `Closes #N` / `Fixes #N` /
+`Resolves #N` in the body merges. From the CLI:
+
+```bash
+gh pr create --body "$(cat <<'EOF'
+Fixes #42.
+
+## Summary
+…
+EOF
+)"
+```
+
+For sub-issues / dependencies (no auto-close, just visual link):
+
+```
+Related: #43, #44
+Blocks: #50
+```
+
+### Close / reopen
+
+```bash
+# State reasons (GitHub Issue State Reasons API):
+gh issue close <N> --reason completed             # default
+gh issue close <N> --reason "not planned"         # won't fix
+gh issue close <N> --reason duplicate --comment "duplicate of #M"
+
+gh issue reopen <N>
+```
+
+## Triage workflow (recurring)
+
+A weekly / per-stand-up triage pass:
+
+```bash
+# 1. Surface issues with no labels (the worst offender):
+gh issue list --search "no:label" --limit 50
+
+# 2. Surface "needs repro" stale-bait:
+gh issue list --label "needs-repro" \
+  --search "updated:<$(date -u -d '14 days ago' +%Y-%m-%d)" --limit 50
+
+# 3. Bulk-label or bulk-close (loop with gh):
+for n in $(gh issue list --label "needs-repro" \
+  --search "updated:<$(date -u -d '30 days ago' +%Y-%m-%d)" \
+  --json number --jq '.[].number'); do
+  gh issue close "$n" --reason "not planned" \
+    --comment "Closing for inactivity. Reopen with a fresh repro."
+done
+```
+
+## Projects (v2)
+
+GitHub Projects v2 is the modern board. The CLI has first-class support
+via `gh project`:
+
+```bash
+gh project list --owner <org-or-user>
+gh project view <number> --owner <org>            # full board contents
+gh project item-add <project-number> --owner <org> --url <issue-url>
+gh project item-edit --id <item-id> --field-id <fid> --single-select-option-id <oid>
+```
+
+Adding from issue context (one-liner):
+
+```bash
+gh project item-add <pn> --owner <org> --url $(gh issue view <N> --json url --jq .url)
+```
+
+## Why CodraGraph helps here
+
+When triaging a bug, jump straight from issue text to the suspect code:
+
+```
+1. gh issue view 42 --comments
+   → "validateUser fails for users with X"
+
+2. codragraph_query({query: "validateUser X"})
+   → suspect symbols ranked
+
+3. codragraph_context({name: "validateUser"})
+   → callers + callees + processes
+
+4. codragraph_impact({target: "validateUser", direction: "upstream"})
+   → which flows are affected — confirms the bug's blast radius
+
+5. Comment on the issue with concrete next steps:
+   gh issue comment 42 --body "Fix likely in src/auth/validate.ts:42 …"
+```
+
+Combine with the `codragraph-debugging` skill for full bug-investigation
+workflow.
+
+## Pitfalls
+
+| Pitfall | Fix |
+|---|---|
+| Issue body forgets the repro | Always include "Repro / Expected / Actual / Env" in the template |
+| Closing without a reason | Use `--reason "not planned"` so the state is searchable |
+| Linking to PR via `#N` only | Use `Fixes #N` in PR body — that's what triggers auto-close |
+| Bulk-relabeling without a `--dry-run` | gh has no built-in dry run; do `gh issue list` first to preview |
+| Mixing v1 boards (deprecated) and v2 | New automation: only `gh project` (v2). Old `gh project` v1 commands removed in CLI 2.20+ |
+```