@codragraph/cli 1.6.4 → 2.0.0

package/skills/codragraph-sql-tracing.md

@@ -0,0 +1,122 @@
+---
+name: codragraph-sql-tracing
+description: "Use when finding where SQL queries are constructed in code, tracing which functions execute a given query, auditing query patterns, or finding the call sites of a stored procedure. Examples: \"where is this SELECT defined\", \"who calls this query\", \"find all SQL in the auth module\", \"trace this stored procedure call\""
+---
+
+# SQL Query Tracing with CodraGraph
+
+## When to Use
+
+- "Where is the query for `<table>` constructed?"
+- "Which functions execute `<sql snippet>`?"
+- "Find all SQL string literals in `<area>`."
+- Auditing query patterns (N+1, missing indexes, etc.) before optimization
+- Tracing a stored-procedure call from production logs back to the caller
+
+## Why CodraGraph helps here
+
+SQL queries are usually plain string literals — the language-server knows
+nothing about them, but `query` over the index plus `cypher` against the
+graph can find them, and `context` / `impact` can trace who calls the
+enclosing function. This works equally well for raw SQL strings, query
+builders (Knex, SQLAlchemy, Diesel), and ORM-generated queries that
+include a recognizable identifier.
+
+## Workflow
+
+```
+1. codragraph_query({query: "SELECT FROM <table>"})
+   OR
+   codragraph_query({query: "<unique substring of the SQL>"})
+   → symbols whose body contains the SQL fragment
+
+2. For each candidate function:
+   codragraph_context({name: "<function>"})
+   → see who calls it (the actual query-execution site)
+
+3. codragraph_impact({target: "<function>", direction: "upstream"})
+   → blast radius: every caller of the SQL-executing function
+
+4. For ORM / query-builder users:
+   codragraph_query({query: "<table>.find OR <table>.where"})
+   → find ORM calls that compile to SQL touching the table
+
+5. Categorize: reads vs writes, hot paths vs cold paths
+```
+
+> CodraGraph indexes the *source* of the query, not the *executed* SQL.
+> Dynamically built queries (`f"SELECT * FROM {table}"`) require both a
+> string-literal search AND a check on the variable's binding via `context`.
+
+## Checklist
+
+```
+- [ ] query for the SQL substring or table name
+- [ ] context on each candidate function
+- [ ] impact upstream on the executor → who calls it from the application
+- [ ] Filter for ORM call patterns separately if relevant
+- [ ] Group results: read paths vs write paths, hot vs cold paths
+- [ ] Flag any query with no test reach (cross-ref with codragraph-test-coverage)
+```
+
+## SQL Patterns to Search
+
+| Pattern | Search query |
+| --- | --- |
+| Raw string SELECT | `"SELECT FROM users"` (with table name) |
+| Query builder (Knex) | `.from('users').where` |
+| ORM (SQLAlchemy) | `session.query(User)` |
+| Stored procedure call | `CALL sp_name` or `EXEC sp_name` |
+| Migration | `CREATE TABLE` / `ALTER TABLE` |
+
+## Example: "Find every place we read from the `audit_log` table"
+
+```
+1. codragraph_query({query: "FROM audit_log"})
+   → 5 symbols:
+     - getAuditByUser (src/admin/audit.ts)
+     - getAuditByAction (src/admin/audit.ts)
+     - exportAuditCSV (src/admin/audit.ts)
+     - countRecentAuditEntries (src/dashboard/health.ts)
+     - debugAuditDump (src/scripts/debug.ts)
+
+2. codragraph_query({query: "auditLog.find OR auditLog.where"})
+   → 0 (we're using raw SQL, not an ORM)
+
+3. codragraph_context({name: "getAuditByUser"})
+   → callers: AuditController.show, AuditController.export
+   → callees: db.query, parseAuditRow
+
+4. codragraph_impact({target: "getAuditByUser", direction: "upstream"})
+   → d=1: AuditController.show (admin UI), AuditController.export (CSV download)
+   → d=2: AdminRouter (HTTP layer)
+
+Findings: 5 read sites in 3 files. All go through AuditController. The
+debug script reads with no auth — flag for review.
+
+5. Cross-reference with codragraph-test-coverage:
+   - getAuditByUser: covered by AuditController.test
+   - debugAuditDump: NO TESTS, NO AUTH ⚠
+```
+
+## Output Format
+
+```markdown
+## SQL Trace: `audit_log` (reads)
+
+### Read sites
+| Function | File | Caller chain | Test reach |
+|----------|------|--------------|------------|
+| getAuditByUser | src/admin/audit.ts | Controller → Router | ✓ |
+| getAuditByAction | src/admin/audit.ts | Controller → Router | ✓ |
+| exportAuditCSV | src/admin/audit.ts | Controller → Router | ✗ |
+| countRecentAuditEntries | src/dashboard/health.ts | HealthCheck → cron | ✗ |
+| debugAuditDump | src/scripts/debug.ts | (no auth?) ⚠ | ✗ |
+
+### Hot path
+`AuditController` is the gateway for 3 of 5 read sites. Optimizations
+that route through it benefit the most.
+
+### Risks
+- `debugAuditDump` has no auth and no tests. Investigate.
+```

package/skills/codragraph-supply-chain-audit.md

@@ -0,0 +1,153 @@
+---
+name: codragraph-supply-chain-audit
+description: "Use to audit external dependency risk — which packages does the codebase actually use, where are the deepest integration points (a single dep used across N modules is high-blast-radius), what would break if a dep was removed. Examples: \"audit dependencies\", \"supply chain risk\", \"what would break if I drop X\", \"deep dep usage\", \"vendor in or replace\""
+---
+
+# Supply Chain / Dependency Audit with CodraGraph
+
+## When to Use
+
+- "Which deps are used the most?"
+- "What would actually break if I removed `<package>`?"
+- "Find deps imported in only 1-2 places (cheap to replace)."
+- "Which deps are deeply integrated and risky to change?"
+- "Pre-vendor audit: should I vendor `<dep>` to lock the version?"
+- "Post-CVE: which of our code paths reach this vulnerable function?"
+
+## Why CodraGraph helps here
+
+`npm ls` / `pip list` / `go.sum` tell you which packages are *installed*.
+CodraGraph tells you where they're *imported and called* — which is the
+real measure of how integrated a dep is. Pair with `impact` for "what
+breaks if this dep changes" and you have a much sharper risk picture
+than pure dependency-tree analysis.
+
+## Workflow
+
+```
+1. List external dependency import sites:
+   codragraph_cypher({query: `
+     MATCH (n)-[:IMPORTS]->(dep)
+     WHERE dep.isExternal = true OR dep.id STARTS WITH 'package:'
+     RETURN dep.id, dep.name, count(DISTINCT n) AS importers
+     ORDER BY importers DESC
+   `})
+   → per-package import counts
+
+2. For each high-import package, find which symbols call into it:
+   codragraph_cypher({query: `
+     MATCH (caller)-[:CALLS]->(target)
+     WHERE target.filePath CONTAINS 'node_modules/<pkg>'
+        OR target.id STARTS WITH 'package:<pkg>:'
+     RETURN caller.name, caller.filePath, count(*) AS calls
+     ORDER BY calls DESC
+   `})
+   → per-package call sites; high-call-site = deeply integrated
+
+3. Identify shallow deps (cheap-to-replace):
+   - 1-2 importers → easy to swap out
+   - usage limited to one cluster → bounded blast radius
+
+4. Identify deep deps (high replacement cost):
+   - imported across many clusters → cross-cutting
+   - referenced in critical processes → request-path criticality
+
+5. CVE-specific: given a vulnerable function name from the advisory,
+   find which of YOUR symbols reach it:
+   codragraph_impact({target: "<vulnerableFn>", direction: "upstream"})
+   → only paths through this function are actually exposed
+```
+
+## Risk categorization
+
+| Category | Signal | Action |
+|---|---|---|
+| **Trivial** | 1-2 importers, one cluster | Easy to replace; consider native impl |
+| **Local** | Many importers in 1-2 clusters | Wrap behind a façade for future swap |
+| **Cross-cutting** | Importers spread across most clusters | Treat as core infra; vendor if licensing allows |
+| **Critical** | In every request-path process | Pin version, monitor CVEs, plan migration before EOL |
+| **Vulnerable now** | Reachable code path to a known-CVE function | Patch / replace ASAP |
+
+## CVE response workflow
+
+```
+1. CVE published: "<package> <vulnerable-fn> allows X"
+
+2. Quick check: do we even reach the vulnerable function?
+   codragraph_query({query: "<vulnerable-fn>"})
+   → list of call sites in YOUR code
+
+3. For each call site, walk upstream:
+   codragraph_impact({target: "<our-caller>", direction: "upstream"})
+   → which entry points / processes reach the vulnerable code
+
+4. If 0 reachable paths → not exposed. Patch when convenient.
+5. If reachable from request-path → patch ASAP, communicate scope.
+6. If reachable from internal-only paths → patch in the next maintenance window.
+```
+
+## Checklist
+
+```
+- [ ] Cypher: per-package importer + caller counts
+- [ ] Categorize each top-N package: trivial / local / cross-cutting / critical
+- [ ] For deep deps: identify a façade boundary if one exists / propose one
+- [ ] CVE list cross-check: any current advisories against our deps?
+- [ ] For each open advisory: codragraph_impact on the vulnerable function
+- [ ] Output: ranked deps with risk tier + replaceability cost
+```
+
+## Example: "Should I replace lodash with native?"
+
+```
+1. codragraph_cypher for lodash imports:
+   → 47 importers across all 8 clusters
+   → Cross-cutting category.
+
+2. codragraph_cypher for lodash calls:
+   → top-called: _.get (78), _.isEmpty (54), _.cloneDeep (32),
+     _.debounce (12), 25 other functions ≤ 5 calls each
+
+3. Replacement cost analysis:
+   - _.get → optional chaining `?.` (47 sites)
+   - _.isEmpty → custom helper (3 lines)
+   - _.cloneDeep → structuredClone() (Node 17+)
+   - _.debounce → keep (lodash version is well-tuned, native lacks)
+   - 25 long-tail functions → ~75 individual replacement decisions
+
+4. Decision matrix:
+   - High-frequency simple ones: easy native swap (saves 70%% of bundle hit)
+   - _.debounce: keep lodash for this one (or use a 50-line single-purpose dep)
+   - Long-tail: case-by-case during routine refactors
+
+5. Migration plan:
+   - Phase 1: replace _.get / _.isEmpty / _.cloneDeep (top 3 = ~200 call sites)
+   - Phase 2: revisit long-tail in next major refactor
+   - Phase 3: keep lodash only if _.debounce's replacement isn't ready
+```
+
+## Output Format
+
+```markdown
+## Supply Chain Audit: <scope>
+
+### Top deps by integration depth
+| Package | Importers | Call sites | Clusters touched | Tier |
+|---|--:|--:|--:|---|
+| react | 142 | 380 | 4 | critical |
+| lodash | 47 | 220 | 8 | cross-cutting |
+| date-fns | 12 | 45 | 3 | local |
+| classnames | 4 | 9 | 2 | local |
+| md5 | 1 | 1 | 1 | trivial |
+
+### Replacement candidates
+- `md5` — 1 call site, ~5 lines of native crypto. Trivial removal.
+- `lodash` — replace top 3 functions for 70%% of usage; keep for `_.debounce`.
+
+### CVE exposure
+- 0 active advisories matching code paths reachable from request handlers.
+
+### Recommended next step
+1. Drop `md5` (5-line PR).
+2. Phase-1 lodash slim-down (~200 sites; can be incremental).
+```

package/skills/codragraph-test-coverage.md

@@ -0,0 +1,97 @@
+---
+name: codragraph-test-coverage
+description: "Use when the user wants to find untested code paths, audit test coverage gaps, identify functions or execution flows that have no test reach, or assess whether a refactor needs new tests. Examples: \"what isn't tested\", \"test coverage gaps\", \"which flows have no tests\", \"do I need a test for X\""
+---
+
+# Test Coverage Audit with CodraGraph
+
+## When to Use
+
+- "What's not tested in this codebase?"
+- "Which execution flows have no test coverage?"
+- "Are there tests that cover X?"
+- "Do I need to add a test for this function?"
+- Auditing coverage before a release / freeze
+- Justifying a "needs more tests" review comment with evidence
+
+## Why CodraGraph helps here
+
+Line-coverage tools (jest --coverage, c8, pytest-cov) tell you *which lines
+ran*. They don't tell you *which call paths an agent / engineer should be
+worried about*. CodraGraph's `impact({includeTests: true})` walks the call
+graph and lists every test that transitively reaches a symbol — direct or
+indirect — so you can prove a flow is exercised, or prove it isn't.
+
+## Workflow
+
+```
+1. codragraph_query({query: "<area you care about>"})        → find candidate symbols
+2. For each non-trivial symbol:
+   codragraph_impact({target: "<symbol>", direction: "upstream", includeTests: true})
+   → returns: callers + tests that transitively reach this symbol
+3. READ codragraph://repo/{name}/processes
+   → list every execution flow
+4. For each flow, codragraph_impact on the flow's entry point with includeTests: true
+   → flows with 0 tests = real gaps
+5. Summarize: which symbols and flows have no test reach
+```
+
+> If "Index is stale" → run `npx @codragraph/cli analyze` first.
+
+## Checklist
+
+```
+- [ ] List candidate symbols (query) or take from a recent diff (detect_changes)
+- [ ] Run impact({includeTests: true}) on each
+- [ ] Note symbols where the test list is empty
+- [ ] Cross-reference with processes — flows with no test coverage are the real risk
+- [ ] Report: gaps + the cheapest test that would close each gap (entry point)
+- [ ] If reviewing a PR: limit to symbols changed in the PR
+```
+
+## Example: "What's not tested in the auth area?"
+
+```
+1. codragraph_query({query: "auth validation login session"})
+   → 14 symbols across 6 files
+
+2. codragraph_impact({target: "validateSession", direction: "upstream", includeTests: true})
+   → callers: requireAuth, refreshToken
+   → tests: 0 (no test reaches validateSession)
+   ⚠ GAP
+
+3. codragraph_impact({target: "hashPassword", direction: "upstream", includeTests: true})
+   → tests: hashPassword.test.ts [direct], auth.integration.test.ts [via signup]
+   ✓ covered
+
+4. READ codragraph://repo/CodraGraph/processes
+   → 3 auth flows: SignupFlow, LoginFlow, PasswordResetFlow
+
+5. codragraph_impact for each flow's entry point with includeTests: true
+   → SignupFlow: covered (3 tests)
+   → LoginFlow: covered (2 tests)
+   → PasswordResetFlow: NO TESTS ⚠
+
+Findings:
+- 2 untested gaps: validateSession (symbol), PasswordResetFlow (entire flow)
+- Cheapest fix: one integration test calling resetPassword end-to-end would
+  close both gaps simultaneously (it's the entry point for the flow that
+  also calls validateSession).
+```
+
+## Output Format
+
+```markdown
+## Test Coverage Audit: <scope>
+
+### Gaps (no test reach)
+- **[symbol]** `validateSession` — called by 2 functions, no transitive test
+- **[flow]** `PasswordResetFlow` — entire flow untested
+
+### Covered (for reference)
+- `hashPassword` — direct + integration test
+
+### Suggested fixes
+1. Add integration test for `resetPassword` → covers PasswordResetFlow + validateSession
+2. ...
+```