@grafema/cli 0.2.5-beta → 0.2.6-beta

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();