@grafema/cli 0.2.5-beta → 0.2.7

package/skills/grafema-codebase-analysis/SKILL.md

@@ -0,0 +1,295 @@
+---
+name: grafema-codebase-analysis
+description: >
+  Analyze codebases using a graph database instead of reading source files.
+  Use when understanding code architecture, finding functions or call patterns,
+  tracing data flow, checking dependencies, or answering "where is X used?"
+  questions. Grafema builds a queryable code graph from static analysis —
+  prefer querying the graph over reading files manually.
+license: Apache-2.0
+compatibility: Requires Grafema MCP server configured (grafema or @grafema/mcp package)
+metadata:
+  author: Grafema
+  version: "0.2.5"
+---
+
+# Grafema: Graph-Based Codebase Analysis
+
+## Core Principle
+
+**Query the graph, not read code.**
+
+Grafema builds a graph database from your codebase via static analysis.
+Instead of reading dozens of files to understand how code connects,
+query the graph to get structured, complete answers instantly.
+
+```
+BAD:  Read 20 files hoping to find all callers of a function
+GOOD: find_calls({ name: "processPayment" }) -> get all callers in one query
+
+BAD:  Grep for variable name across files, miss aliased references
+GOOD: trace_dataflow({ source: "userInput", direction: "forward" }) -> complete data flow
+
+BAD:  Read file by file to understand module dependencies
+GOOD: get_file_overview({ file: "src/api.ts" }) -> structured imports, exports, classes, functions
+```
+
+### When to Use Grafema
+
+- Finding where functions/methods are called
+- Understanding module dependencies and imports
+- Tracing data flow (forward or backward)
+- Getting function details (signature, callers, callees)
+- Checking code invariants with Datalog rules
+- Exploring file structure and entity relationships
+
+### When NOT to Use Grafema
+
+- Reading a single specific file (use your editor/Read tool — faster)
+- Editing code (Grafema is read-only analysis)
+- Runtime behavior questions (Grafema is static analysis)
+- Files not yet analyzed (run `analyze_project` first)
+
+## Essential Tools (Tier 1)
+
+These 5 tools handle ~80% of queries. Start here.
+
+### find_nodes — Find entities by type, name, or file
+
+```json
+find_nodes({ type: "FUNCTION", name: "validateUser" })
+find_nodes({ type: "CLASS", file: "src/auth.ts" })
+find_nodes({ type: "http:request" })
+find_nodes({ type: "MODULE" })
+```
+
+**Use when:** "Find all X", "What functions are in file Y", "List all routes"
+
+**Node types:** MODULE, FUNCTION, METHOD, CLASS, VARIABLE, PARAMETER,
+CALL, PROPERTY_ACCESS, METHOD_CALL, CALL_SITE,
+http:route, http:request, db:query, socketio:emit, socketio:on
+
+### find_calls — Find function/method call sites
+
+```json
+find_calls({ name: "processPayment" })
+find_calls({ name: "query", className: "Database" })
+```
+
+**Use when:** "Where is X called?", "Who calls this function?", "Find all usages"
+
+Returns call sites with file locations and whether the target is resolved.
+
+### get_function_details — Complete function info
+
+```json
+get_function_details({ name: "handleRequest" })
+get_function_details({ name: "validate", file: "src/auth.ts" })
+get_function_details({ name: "processOrder", transitive: true })
+```
+
+**Use when:** "What does function X do?", "What does it call?", "Who calls it?"
+
+Returns: signature, parameters, what it calls, who calls it.
+Use `transitive: true` to follow call chains (A calls B calls C, max depth 5).
+
+### get_context — Deep context for any node
+
+```json
+get_context({ semanticId: "src/api.ts:handleRequest#fn" })
+get_context({ semanticId: "src/db.ts:Database#class", edgeType: "CALLS" })
+```
+
+**Use when:** "Tell me everything about this entity", "Show me its relationships"
+
+Returns: node info, source code, ALL incoming/outgoing edges with code context.
+Use after `find_nodes` to deep-dive into a specific result.
+
+### trace_dataflow — Trace data flow
+
+```json
+trace_dataflow({ source: "userInput", file: "src/handler.ts", direction: "forward" })
+trace_dataflow({ source: "dbResult", file: "src/query.ts", direction: "backward" })
+trace_dataflow({ source: "config", direction: "both", max_depth: 5 })
+```
+
+**Use when:** "Where does this value end up?", "Where does this data come from?",
+"Is user input reaching the database unsanitized?"
+
+Directions: `forward` (where does it go?), `backward` (where did it come from?), `both`.
+
+## Decision Tree
+
+```
+START: What do you need?
+|
+|-- "Find entities (functions, classes, routes)"
+|   -> find_nodes({ type, name, file })
+|
+|-- "Find who calls function X"
+|   -> find_calls({ name: "X" })
+|   -> For full details: get_function_details({ name: "X" })
+|
+|-- "Understand a specific entity deeply"
+|   -> First: find_nodes to get its semantic ID
+|   -> Then: get_context({ semanticId: "..." })
+|
+|-- "Trace data flow"
+|   -> trace_dataflow({ source, file, direction })
+|
+|-- "Understand a file's structure"
+|   -> get_file_overview({ file: "path/to/file.ts" })
+|
+|-- "Trace an alias/re-export chain"
+|   -> trace_alias({ variableName: "alias", file: "path.ts" })
+|
+|-- "Check a code rule/invariant"
+|   -> check_invariant({ rule: "violation(X) :- ..." })
+|
+|-- "Custom complex query"
+|   -> query_graph({ query: "violation(X) :- ..." })
+|   -> See references/query-patterns.md for Datalog syntax
+|
+|-- "Explore unknown codebase"
+|   -> get_stats() for high-level overview
+|   -> get_schema() for available node/edge types
+|   -> find_nodes({ type: "MODULE" }) for module list
+|   -> get_file_overview for specific files
+```
+
+## Common Workflows
+
+### 1. Impact Analysis: "What breaks if I change function X?"
+
+```
+get_function_details({ name: "X", transitive: true })
+-> Check calledBy array for all callers (direct + transitive)
+-> For critical callers: get_context({ semanticId }) for full picture
+```
+
+### 2. Security Audit: "Does user input reach the database?"
+
+```
+find_nodes({ type: "http:request" })
+-> For each route, trace_dataflow({ source: requestParam, direction: "forward" })
+-> Check if flow reaches db:query nodes
+-> Use find_guards to check for sanitization
+```
+
+### 3. Onboarding: "How is this codebase structured?"
+
+```
+get_stats()                              -> Node/edge counts by type
+find_nodes({ type: "MODULE" })           -> All modules
+get_file_overview({ file: "src/index.ts" })  -> Entry point structure
+find_nodes({ type: "http:request" })     -> All API endpoints
+```
+
+### 4. Dependency Analysis: "What does module X depend on?"
+
+```
+get_file_overview({ file: "src/service.ts" })
+-> Check imports section for dependencies
+-> For each import: get_context for deeper relationships
+```
+
+### 5. Find Dead Code: "What functions have no callers?"
+
+```
+query_graph({
+  query: 'violation(X) :- node(X, "FUNCTION"), \\+ edge(_, X, "CALLS").'
+})
+```
+
+## Anti-Patterns
+
+**Don't read files to find call sites.** Use `find_calls` — it finds ALL callers across
+the entire codebase, including indirect references you'd miss by grepping.
+
+**Don't use `query_graph` for simple lookups.** `find_nodes`, `find_calls`, and
+`get_function_details` are optimized for common queries. Reserve Datalog for
+complex patterns (joins, transitive closure, invariant checks).
+
+**Don't skip analysis status.** If you just ran `analyze_project`, check
+`get_analysis_status` before querying — partial results are misleading.
+
+**Don't request excessive depth.** `get_context` with no filters returns everything.
+Use `edgeType` filter to focus on specific relationships (e.g., `"CALLS,ASSIGNED_FROM"`).
+
+**Don't use Grafema for single-file questions.** If you only need to read one file,
+use your editor. Grafema shines for cross-file relationships.
+
+## Advanced Tools (Tier 2)
+
+### query_graph — Custom Datalog queries
+
+For complex patterns not covered by high-level tools.
+See [references/query-patterns.md](references/query-patterns.md) for syntax and examples.
+
+```json
+query_graph({
+  query: "violation(X) :- node(X, \"CALL\"), attr(X, \"name\", \"eval\").",
+  explain: true
+})
+```
+
+Available predicates: `node(Id, Type)`, `edge(Src, Dst, Type)`, `attr(Id, Name, Value)`.
+Must define `violation/1` predicate for results. Use `explain: true` to debug empty results.
+
+### get_file_overview — File-level structure
+
+Structured overview of imports, exports, classes, functions, variables with relationships.
+Recommended first step when exploring a specific file before using `get_context`.
+
+### trace_alias — Resolve alias chains
+
+For code like `const alias = obj.method; alias()` — traces "alias" back to "obj.method".
+
+### get_schema — Available types
+
+Returns all node and edge types in the graph. Use when you need exact type names.
+
+### check_invariant — Code rule checking
+
+Check if a Datalog rule has violations. For persistent rules, use `create_guarantee`.
+
+## Specialized Tools (Tier 3)
+
+| Tool | Purpose |
+|------|---------|
+| get_stats | Graph statistics (node/edge counts by type) |
+| get_coverage | Analysis coverage for a path |
+| find_guards | Conditional guards protecting a node |
+| create_guarantee | Create persistent code invariant |
+| list_guarantees | List all guarantees |
+| check_guarantees | Check guarantee violations |
+| delete_guarantee | Remove a guarantee |
+| discover_services | Discover services without full analysis |
+| analyze_project | Run/re-run analysis |
+| get_analysis_status | Check analysis progress |
+| read_project_structure | Directory tree |
+| write_config | Update .grafema/config.yaml |
+| get_documentation | Grafema usage docs |
+| report_issue | Report bugs |
+
+## Troubleshooting
+
+**Query returns nothing?**
+1. Check analysis ran: `get_analysis_status`
+2. Check type names: `get_schema` for available types
+3. Use `explain: true` in `query_graph` to debug
+4. Check file paths match (relative to project root)
+
+**Need help with Datalog syntax?**
+- See [references/query-patterns.md](references/query-patterns.md)
+- Use `get_documentation({ topic: "queries" })` for inline help
+
+**Graph seems incomplete?**
+- Run `get_coverage({ path: "src/" })` to check coverage
+- Re-analyze with `analyze_project({ force: true })`
+- Check `.grafema/config.yaml` for include/exclude patterns
+
+## References
+
+- [Node and Edge Types](references/node-edge-types.md) — Complete graph schema
+- [Query Patterns](references/query-patterns.md) — Datalog cookbook with examples

package/skills/grafema-codebase-analysis/references/node-edge-types.md

@@ -0,0 +1,123 @@
+# Grafema Graph Schema: Node and Edge Types
+
+## Node Types
+
+### Core Entities
+
+| Type | Description | Key Attributes |
+|------|-------------|----------------|
+| `MODULE` | A source file/module | name, file |
+| `FUNCTION` | Function declaration | name, file, line, async |
+| `METHOD` | Class method | name, file, line, className |
+| `CLASS` | Class declaration | name, file, line |
+| `VARIABLE` | Variable declaration | name, file, line, kind (const/let/var) |
+| `PARAMETER` | Function parameter | name, file, line, index |
+
+### Call & Access Nodes
+
+| Type | Description | Key Attributes |
+|------|-------------|----------------|
+| `CALL` | Function call expression | name, file, line, resolved |
+| `METHOD_CALL` | Method call expression | name, file, line, object, resolved |
+| `CALL_SITE` | Call site context | file, line |
+| `PROPERTY_ACCESS` | Property access (obj.prop) | name, object, file, line |
+
+### Domain-Specific Nodes
+
+| Type | Description | Key Attributes |
+|------|-------------|----------------|
+| `http:route` | HTTP route definition | path, method |
+| `http:request` | HTTP request handler | path, method, file, line |
+| `db:query` | Database query | file, line |
+| `socketio:emit` | Socket.IO emit call | event, file, line |
+| `socketio:on` | Socket.IO event listener | event, file, line |
+
+### Structural Nodes
+
+| Type | Description |
+|------|-------------|
+| `SCOPE` | Code scope (function body, if block, loop) |
+| `OBJECT_LITERAL` | Object literal expression |
+| `ARRAY_LITERAL` | Array literal expression |
+| `LITERAL` | Primitive literal value |
+| `IMPORT` | Import declaration |
+| `EXPORT` | Export declaration |
+
+## Edge Types
+
+| Type | Direction | Description |
+|------|-----------|-------------|
+| `CONTAINS` | Parent -> Child | Structural containment (module contains function) |
+| `CALLS` | Caller -> Callee | Function/method call relationship |
+| `DEPENDS_ON` | Module -> Module | Module dependency (import) |
+| `ASSIGNED_FROM` | Variable -> Source | Value assignment source |
+| `INSTANCE_OF` | Instance -> Class | Class instantiation |
+| `PASSES_ARGUMENT` | Call -> Value | Argument passing at call site |
+| `HAS_SCOPE` | Function -> Scope | Function's scope chain |
+| `EXTENDS` | Class -> Class | Class inheritance |
+| `IMPLEMENTS` | Class -> Interface | Interface implementation |
+| `RETURNS` | Function -> Type | Return type relationship |
+| `DATAFLOW` | Source -> Sink | Data flow edge |
+| `GUARDED_BY` | Node -> Scope | Conditional guard relationship |
+
+## Common Attribute Names
+
+These can be used with `attr(Id, Name, Value)` in Datalog queries:
+
+| Attribute | Types | Description |
+|-----------|-------|-------------|
+| `name` | All named nodes | Entity name |
+| `file` | All nodes | Source file path (relative) |
+| `line` | All located nodes | Line number |
+| `column` | All located nodes | Column number |
+| `type` | All nodes | Node type (via `node(Id, Type)`) |
+| `async` | FUNCTION, METHOD | Is async function |
+| `kind` | VARIABLE | const, let, or var |
+| `method` | http:request | HTTP method (GET, POST, etc.) |
+| `path` | http:request, http:route | URL path pattern |
+| `resolved` | CALL, METHOD_CALL | Whether call target is resolved |
+| `object` | METHOD_CALL, PROPERTY_ACCESS | Receiver object name |
+| `className` | METHOD | Owning class name |
+| `event` | socketio:emit, socketio:on | Socket.IO event name |
+
+## Quick Reference: Finding Common Patterns
+
+### Find all functions
+```
+node(X, "FUNCTION")
+```
+
+### Find all classes
+```
+node(X, "CLASS")
+```
+
+### Find all HTTP endpoints
+```
+node(X, "http:request")
+```
+
+### Find calls to a specific function
+```
+node(X, "CALL"), attr(X, "name", "targetFunction")
+```
+
+### Find all methods of a class
+```
+node(C, "CLASS"), attr(C, "name", "MyClass"), edge(C, M, "CONTAINS"), node(M, "METHOD")
+```
+
+### Find module dependencies
+```
+edge(A, B, "DEPENDS_ON"), node(A, "MODULE"), node(B, "MODULE")
+```
+
+### Find data flow from a variable
+```
+node(X, "VARIABLE"), attr(X, "name", "myVar"), edge(X, Y, "DATAFLOW")
+```
+
+### Find unresolved calls
+```
+node(X, "CALL"), attr(X, "resolved", "false")
+```

package/skills/grafema-codebase-analysis/references/query-patterns.md

@@ -0,0 +1,205 @@
+# Grafema Datalog Query Patterns
+
+All queries use `query_graph` tool. Every query must define a `violation/1` predicate —
+matching nodes are returned as results.
+
+## Syntax Quick Reference
+
+```
+violation(X) :- <body>.         # Rule: X is a result if body is true
+node(X, "TYPE")                 # Match node by type
+edge(X, Y, "TYPE")             # Match edge: X -> Y of given type
+attr(X, "name", "value")       # Match node attribute
+\+ <condition>                  # Negation: condition is NOT true
+```
+
+## Basic Patterns
+
+### Find nodes by type
+
+```datalog
+violation(X) :- node(X, "FUNCTION").
+```
+
+### Find nodes by type and name
+
+```datalog
+violation(X) :- node(X, "FUNCTION"), attr(X, "name", "processPayment").
+```
+
+### Find nodes by type and file
+
+```datalog
+violation(X) :- node(X, "FUNCTION"), attr(X, "file", "src/api.ts").
+```
+
+### Find nodes matching multiple criteria
+
+```datalog
+violation(X) :- node(X, "CALL"), attr(X, "name", "eval"), attr(X, "file", "src/handler.ts").
+```
+
+## Edge Traversal
+
+### One-hop: Find all calls from a function
+
+```datalog
+violation(Call) :-
+  node(F, "FUNCTION"), attr(F, "name", "main"),
+  edge(F, S, "HAS_SCOPE"), edge(S, Call, "CONTAINS"),
+  node(Call, "CALL").
+```
+
+### One-hop: Find all callers of a function
+
+```datalog
+violation(Caller) :-
+  node(Target, "FUNCTION"), attr(Target, "name", "validate"),
+  edge(Call, Target, "CALLS"),
+  edge(Scope, Call, "CONTAINS"),
+  edge(Caller, Scope, "HAS_SCOPE"),
+  node(Caller, "FUNCTION").
+```
+
+### Find module dependencies
+
+```datalog
+violation(Dep) :-
+  node(M, "MODULE"), attr(M, "name", "api"),
+  edge(M, Dep, "DEPENDS_ON"), node(Dep, "MODULE").
+```
+
+### Find what a variable is assigned from
+
+```datalog
+violation(Source) :-
+  node(V, "VARIABLE"), attr(V, "name", "config"),
+  edge(V, Source, "ASSIGNED_FROM").
+```
+
+## Negation Patterns
+
+### Functions with no callers (potential dead code)
+
+```datalog
+violation(X) :-
+  node(X, "FUNCTION"),
+  \+ edge(_, X, "CALLS").
+```
+
+### Modules with no dependents (unused modules)
+
+```datalog
+violation(X) :-
+  node(X, "MODULE"),
+  \+ edge(_, X, "DEPENDS_ON").
+```
+
+### Unresolved calls (external/dynamic targets)
+
+```datalog
+violation(X) :-
+  node(X, "CALL"),
+  attr(X, "resolved", "false").
+```
+
+## Invariant Patterns
+
+### No eval() usage
+
+```datalog
+violation(X) :- node(X, "CALL"), attr(X, "name", "eval").
+```
+
+### No direct database queries outside service layer
+
+```datalog
+violation(X) :-
+  node(X, "db:query"),
+  attr(X, "file", File),
+  \+ attr(X, "file", "src/services/").
+```
+
+Note: File matching is exact. For pattern matching, use the `find_nodes` tool instead.
+
+### All HTTP endpoints must have handlers
+
+```datalog
+violation(X) :-
+  node(X, "http:request"),
+  \+ edge(_, X, "CALLS").
+```
+
+## Join Patterns
+
+### Find functions that call both X and Y
+
+```datalog
+violation(F) :-
+  node(F, "FUNCTION"),
+  edge(F, S, "HAS_SCOPE"),
+  edge(S, C1, "CONTAINS"), node(C1, "CALL"), attr(C1, "name", "readFile"),
+  edge(S, C2, "CONTAINS"), node(C2, "CALL"), attr(C2, "name", "writeFile").
+```
+
+### Find classes that extend a specific base class
+
+```datalog
+violation(Child) :-
+  node(Base, "CLASS"), attr(Base, "name", "BaseService"),
+  edge(Child, Base, "EXTENDS"),
+  node(Child, "CLASS").
+```
+
+## Performance Tips
+
+1. **Put most selective filters first.** `attr(X, "name", "specific")` before `node(X, "FUNCTION")`.
+
+2. **Avoid unconstrained joins.** Every variable should be bounded by at least one specific condition.
+
+3. **Use high-level tools when possible.** `find_calls` is faster than writing a Datalog query for the same pattern — it uses optimized indexes.
+
+4. **Use `explain: true` to debug.** If a query returns nothing, add `explain: true` to see step-by-step execution.
+
+5. **Use `limit` and `offset` for large result sets.** Default limit applies, but you can paginate through results.
+
+## Common Mistakes
+
+### Wrong: Unbound variable
+
+```datalog
+# BAD: Y is never constrained
+violation(X) :- node(X, "FUNCTION"), edge(X, Y, "CALLS").
+```
+
+```datalog
+# GOOD: Constrain Y
+violation(X) :- node(X, "FUNCTION"), edge(X, Y, "CALLS"), node(Y, "FUNCTION").
+```
+
+### Wrong: Using wrong edge direction
+
+```datalog
+# BAD: CALLS edge goes Caller -> Callee, not reverse
+violation(X) :- node(X, "FUNCTION"), edge(X, Target, "CALLS").
+```
+
+The CALLS edge typically goes from CALL/CALL_SITE node to target FUNCTION,
+not directly from FUNCTION to FUNCTION. Check [node-edge-types.md](node-edge-types.md)
+for correct edge directions.
+
+### Wrong: Missing scope traversal
+
+Functions don't directly CONTAIN calls — they have scopes that contain calls:
+
+```datalog
+# BAD: No direct CONTAINS edge from FUNCTION to CALL
+violation(C) :- node(F, "FUNCTION"), edge(F, C, "CONTAINS"), node(C, "CALL").
+```
+
+```datalog
+# GOOD: Go through HAS_SCOPE
+violation(C) :-
+  node(F, "FUNCTION"), edge(F, S, "HAS_SCOPE"),
+  edge(S, C, "CONTAINS"), node(C, "CALL").
+```

package/src/cli.ts

@@ -16,7 +16,8 @@ import { lsCommand } from './commands/ls.js';
 import { getCommand } from './commands/get.js';
 import { traceCommand } from './commands/trace.js';
 import { impactCommand } from './commands/impact.js';
-import { exploreCommand } from './commands/explore.js';
+import { contextCommand } from './commands/context.js';
+
 import { statsCommand } from './commands/stats.js';
 import { checkCommand } from './commands/check.js';
 import { serverCommand } from './commands/server.js';
@@ -24,6 +25,8 @@ import { coverageCommand } from './commands/coverage.js';
 import { doctorCommand } from './commands/doctor.js';
 import { schemaCommand } from './commands/schema.js';
 import { explainCommand } from './commands/explain.js';
+import { fileCommand } from './commands/file.js';
+import { setupSkillCommand } from './commands/setup-skill.js';
 
 // Read version from package.json
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -41,12 +44,13 @@ program.addCommand(initCommand);
 program.addCommand(analyzeCommand);
 program.addCommand(overviewCommand);
 program.addCommand(queryCommand);
+program.addCommand(contextCommand);
 program.addCommand(typesCommand);
 program.addCommand(lsCommand);
 program.addCommand(getCommand);
 program.addCommand(traceCommand);
 program.addCommand(impactCommand);
-program.addCommand(exploreCommand);
+
 program.addCommand(statsCommand);  // Keep for backwards compat
 program.addCommand(coverageCommand);
 program.addCommand(checkCommand);
@@ -54,5 +58,7 @@ program.addCommand(serverCommand);
 program.addCommand(doctorCommand);
 program.addCommand(schemaCommand);
 program.addCommand(explainCommand);
+program.addCommand(fileCommand);
+program.addCommand(setupSkillCommand);
 
 program.parse();