@grafema/mcp 0.3.15 → 0.3.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/dist/definitions/project-tools.d.ts.map +1 -1
  2. package/dist/definitions/project-tools.js +5 -3
  3. package/dist/definitions/project-tools.js.map +1 -1
  4. package/dist/definitions/query-tools.d.ts.map +1 -1
  5. package/dist/definitions/query-tools.js +8 -2
  6. package/dist/definitions/query-tools.js.map +1 -1
  7. package/dist/handlers/documentation-handlers.d.ts.map +1 -1
  8. package/dist/handlers/documentation-handlers.js +100 -1
  9. package/dist/handlers/documentation-handlers.js.map +1 -1
  10. package/package.json +10 -4
  11. package/src/definitions/project-tools.ts +5 -3
  12. package/src/definitions/query-tools.ts +8 -2
  13. package/src/handlers/documentation-handlers.ts +100 -1
package/dist/definitions/project-tools.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"project-tools.d.ts","sourceRoot":"","sources":["../../src/definitions/project-tools.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,eAAO,MAAM,aAAa,EAAE,cAAc,EAgLzC,CAAC"}
1
+ {"version":3,"file":"project-tools.d.ts","sourceRoot":"","sources":["../../src/definitions/project-tools.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,eAAO,MAAM,aAAa,EAAE,cAAc,EAkLzC,CAAC"}
package/dist/definitions/project-tools.js CHANGED
@@ -119,10 +119,12 @@ Use AFTER analyze_project when queries return unexpected empty results.`,
119
119
  description: `Get documentation about Grafema usage and query syntax.
120
120
 
121
121
  Topics available:
122
- - queries: Datalog query syntax and examples
123
- - types: Available node and edge types
122
+ - queries: Datalog query syntax, predicates (including numeric comparisons), and examples
123
+ - types: Available node and edge types (including METRIC and ISSUE diagnostic nodes)
124
124
  - guarantees: How to create and manage code guarantees
125
125
  - notation: DSL notation reference (archetypes, operators, LOD, perspectives)
126
+ - metrics: Performance metrics (METRIC nodes) and analysis issues (ISSUE nodes)
127
+ - effects: Side-effect taxonomy and manifest system
126
128
  - onboarding: Step-by-step guide for new projects
127
129
  - overview: High-level Grafema architecture
128
130
 
@@ -132,7 +134,7 @@ Use this when you need to learn Datalog syntax, DSL notation, or understand avai
132
134
  properties: {
133
135
  topic: {
134
136
  type: 'string',
135
- description: 'Topic: queries, types, guarantees, notation, onboarding, or overview',
137
+ description: 'Topic: queries, types, guarantees, notation, metrics, effects, onboarding, or overview',
136
138
  },
137
139
  },
138
140
  },
package/dist/definitions/project-tools.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"project-tools.js","sourceRoot":"","sources":["../../src/definitions/project-tools.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"project-tools.js","sourceRoot":"","sources":["../../src/definitions/project-tools.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,MAAM,CAAC,MAAM,aAAa,GAAqB;IAC7C;QACE,IAAI,EAAE,wBAAwB;QAC9B,WAAW,EAAE;;;;;;;4BAOW;QACxB,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,IAAI,EAAE;oBACJ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,yEAAyE;iBACvF;gBACD,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,8CAA8C;iBAC5D;gBACD,aAAa,EAAE;oBACb,IAAI,EAAE,SAAS;oBACf,WAAW,EAAE,+DAA+D;iBAC7E;aACF;SACF;KACF;IACD;QACE,IAAI,EAAE,cAAc;QACpB,WAAW,EAAE;;;;iFAIgE;QAC7E,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,QAAQ,EAAE;oBACR,IAAI,EAAE,OAAO;oBACb,KAAK,EAAE;wBACL,IAAI,EAAE,QAAQ;wBACd,UAAU,EAAE;4BACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,gCAAgC,EAAE;4BACvE,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,sDAAsD,EAAE;4BAC7F,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,kEAAkE,EAAE;yBAChH;wBACD,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC;qBAC3B;oBACD,WAAW,EAAE,yDAAyD;iBACvE;gBACD,OAAO,EAAE;oBACP,IAAI,EAAE,QAAQ;oBACd,UAAU,EAAE;wBACV,QAAQ,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,WAAW,EAAE,kBAAkB,EAAE;wBACvF,QAAQ,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,WAAW,EAAE,kBAAkB,EAAE;wBACvF,UAAU,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,WAAW,EAAE,oBAAoB,EAAE;wBAC3F,UAAU,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,WAAW,EAAE,oBAAoB,EAAE;qBAC5F;oBACD,WAAW,EAAE,6CAA6C;iBAC3D;gBACD,OAAO,EAAE;oBACP,IAAI,EAAE,OAAO;oBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;oBACzB,WAAW,EAAE,4DAA4D;iBAC1E;gBACD,OAAO,EAAE;oBACP,IAAI,EAAE,OAAO;oBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;oBACzB,WAAW,EAAE,6DAA6D;iBAC3E;gBACD,SAAS,EAAE;oBACT,IAAI,EAAE,QAAQ;oBACd,UAAU,EAAE;wBACV,KAAK,EAAE;4BACL,IAAI,EAAE,OAAO;4BACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;4BACzB,WAAW,EAAE,2CAA2C;yBACzD;qBACF;oBACD,WAAW,EAAE,mDAAmD;iBACjE;aACF;SACF;KACF;IACD;QACE,IAAI,EAAE,cAAc;QACpB,WAAW,EAAE;;;;;;;;;;wEAUuD;QACpE,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,IAAI,EAAE;oBACJ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,4BAA4B;iBAC1C;gBACD,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,wCAAwC;iBACtD;aACF;SACF;KACF;IACD;QACE,IAAI,EAAE,mBAAmB;QACzB,WAAW,EAAE;;;;;;;;;;;;gGAY+E;QAC5F,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,wFAAwF;iBACtG;aACF;SACF;KACF;IACD;QACE,IAAI,EAAE,cAAc;QACpB,WAAW,EAAE;;;;;;;;;;;;;uEAasD;QACnE,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,4EAA4E;iBAC1F;gBACD,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,mCAAmC;iBACjD;gBACD,OAAO,EAAE;oBACP,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,6DAA6D;iBAC3E;gBACD,MAAM,EAAE;oBACN,IAAI,EAAE,OAAO;oBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;oBACzB,WAAW,EAAE,mDAAmD;iBACjE;aACF;YACD,QAAQ,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC;SACnC;KACF;CACF,CAAC"}
package/dist/definitions/query-tools.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"query-tools.d.ts","sourceRoot":"","sources":["../../src/definitions/query-tools.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGjD,eAAO,MAAM,WAAW,EAAE,cAAc,EA+OvC,CAAC"}
1
+ {"version":3,"file":"query-tools.d.ts","sourceRoot":"","sources":["../../src/definitions/query-tools.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGjD,eAAO,MAAM,WAAW,EAAE,cAAc,EAqPvC,CAAC"}
package/dist/definitions/query-tools.js CHANGED
@@ -11,22 +11,28 @@ Set language to "cypher" for Cypher queries (e.g., MATCH (n:FUNCTION) RETURN n.n
11
11
  Default is Datalog.
12
12
 
13
13
  Available Datalog predicates:
14
- - type(Id, Type) - match nodes by type (alias: node)
14
+ - type(Id, Type) / node(Id, Type) - match nodes by type
15
15
  - edge(Src, Dst, Type) - match edges
16
16
  - attr(Id, Name, Value) - match node attributes (name, file, line, etc.)
17
+ - gt(Val, N), lt(Val, N), gte(Val, N), lte(Val, N) - numeric comparisons
18
+ - \\+ - negation (not)
17
19
 
18
20
  NODE TYPES:
19
21
  - MODULE, FUNCTION, METHOD, CLASS, VARIABLE, PARAMETER
20
22
  - CALL, PROPERTY_ACCESS, METHOD_CALL, CALL_SITE
23
+ - METRIC (performance metrics: value/unit/source in metadata, OBSERVES → MODULE)
24
+ - ISSUE (analysis problems: category/severity/message in metadata, CONTAINS ← MODULE)
21
25
  - http:route, http:request, db:query, socketio:emit, socketio:on
22
26
 
23
27
  EDGE TYPES:
24
28
  - CONTAINS, CALLS, DEPENDS_ON, ASSIGNED_FROM, INSTANCE_OF, PASSES_ARGUMENT
29
+ - OBSERVES (METRIC → MODULE, links performance metric to observed file)
25
30
 
26
31
  EXAMPLES:
27
32
  violation(X) :- node(X, "MODULE").
28
33
  violation(X) :- node(X, "FUNCTION"), attr(X, "file", "src/api.js").
29
- violation(X) :- node(X, "CALL"), \\+ edge(X, _, "CALLS").`,
34
+ violation(X) :- node(X, "CALL"), \\+ edge(X, _, "CALLS").
35
+ violation(F, Ms) :- node(M, "METRIC"), attr(M, "name", "parse_ms"), attr(M, "value", Ms), gte(Ms, 500), edge(M, Mod, "OBSERVES"), attr(Mod, "file", F).`,
30
36
  inputSchema: {
31
37
  type: 'object',
32
38
  properties: {
package/dist/definitions/query-tools.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"query-tools.js","sourceRoot":"","sources":["../../src/definitions/query-tools.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"query-tools.js","sourceRoot":"","sources":["../../src/definitions/query-tools.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAEvD,MAAM,CAAC,MAAM,WAAW,GAAqB;IAC3C;QACE,IAAI,EAAE,aAAa;QACnB,WAAW,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;0JA2ByI;QACtJ,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,gGAAgG;iBAC9G;gBACD,QAAQ,EAAE;oBACR,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,iDAAiD;oBAC9D,IAAI,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC;iBAC5B;gBACD,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,mCAAmC,aAAa,UAAU,SAAS,GAAG;iBACpF;gBACD,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,kDAAkD;iBAChE;gBACD,OAAO,EAAE;oBACP,IAAI,EAAE,SAAS;oBACf,WAAW,EAAE,0DAA0D;iBACxE;gBACD,KAAK,EAAE;oBACL,IAAI,EAAE,SAAS;oBACf,WAAW,EAAE,uFAAuF;iBACrG;aACF;YACD,QAAQ,EAAE,CAAC,OAAO,CAAC;SACpB;KACF;IACD;QACE,IAAI,EAAE,YAAY;QAClB,WAAW,EAAE;;;;;;;qGAOoF;QACjG,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,IAAI,EAAE;oBACJ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,2CAA2C;iBACzD;gBACD,SAAS,EAAE;oBACT,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,uCAAuC;iBACrD;gBACD,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,yBAAyB,aAAa,UAAU,SAAS,GAAG;iBAC1E;gBACD,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,mCAAmC;iBACjD;aACF;YACD,QAAQ,EAAE,CAAC,MAAM,CAAC;SACnB;KACF;IACD;QACE,IAAI,EAAE,YAAY;QAClB,WAAW,EAAE;;;;;;;;;;4EAU2D;QACxE,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,IAAI,EAAE;oBACJ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,4DAA4D;iBAC1E;gBACD,IAAI,EAAE;oBACJ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,mBAAmB;iBACjC;gBACD,IAAI,EAAE;oBACJ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,mBAAmB;iBACjC;gBACD,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,yBAAyB,aAAa,UAAU,SAAS,GAAG;iBAC1E;gBACD,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,mCAAmC;iBACjD;aACF;SACF;KACF;IACD;QACE,IAAI,EAAE,aAAa;QACnB,WAAW,EAAE;;0CAEyB;QACtC,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,YAAY,EAAE;oBACZ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,wBAAwB;iBACtC;gBACD,IAAI,EAAE;oBACJ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,yCAAyC;iBACvD;aACF;YACD,QAAQ,EAAE,CAAC,cAAc,EAAE,MAAM,CAAC;SACnC;KACF;IACD;QACE,IAAI,EAAE,gBAAgB;QACtB,WAAW,EAAE;;;;;;;;;;;;;;;;;;iDAkBgC;QAC7C,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,mCAAmC;iBACjD;gBACD,IAAI,EAAE;oBACJ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,WAAW;iBACzB;gBACD,SAAS,EAAE;oBACT,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,+CAA+C;oBAC5D,IAAI,EAAE,CAAC,SAAS,EAAE,UAAU,EAAE,MAAM,CAAC;iBACtC;gBACD,SAAS,EAAE;oBACT,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,mCAAmC;iBACjD;gBACD,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,yBAAyB,aAAa,GAAG;iBACvD;gBACD,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,8FAA8F;oBAC3G,IAAI,EAAE,CAAC,SAAS,EAAE,QAAQ,EAAE,MAAM,CAAC;iBACpC;aACF;YACD,QAAQ,EAAE,CAAC,QAAQ,CAAC;SACrB;KACF;IACD;QACE,IAAI,EAAE,iBAAiB;QACvB,WAAW,EAAE;;;;;;;;;;oEAUmD;QAChE,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,IAAI,EAAE;oBACJ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,mCAAmC;iBACjD;gBACD,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,4BAA4B;iBAC1C;gBACD,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,4BAA4B,aAAa,GAAG;iBAC1D;gBACD,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,sCAAsC;iBACpD;aACF;YACD,QAAQ,EAAE,CAAC,MAAM,CAAC;SACnB;KACF;CACF,CAAC"}
package/dist/handlers/documentation-handlers.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"documentation-handlers.d.ts","sourceRoot":"","sources":["../../src/handlers/documentation-handlers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EACV,UAAU,EACV,oBAAoB,EACrB,MAAM,aAAa,CAAC;AAIrB,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,UAAU,CAAC,CA+H5F"}
1
+ {"version":3,"file":"documentation-handlers.d.ts","sourceRoot":"","sources":["../../src/handlers/documentation-handlers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EACV,UAAU,EACV,oBAAoB,EACrB,MAAM,aAAa,CAAC;AAIrB,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,UAAU,CAAC,CAkO5F"}
package/dist/handlers/documentation-handlers.js CHANGED
@@ -33,15 +33,30 @@ violation(X) :- node(X, "TYPE"), attr(X, "name", "value").
33
33
  ## Available Predicates
34
34
  - type(Id, Type) - match nodes (alias: node)
35
35
  - edge(Src, Dst, Type) - match edges
36
- - attr(Id, Name, Value) - match attributes
36
+ - attr(Id, Name, Value) - match node attributes (name, file, line, etc.)
37
37
  - \\+ - negation (not)
38
38
 
39
+ ## Numeric Comparison Predicates
40
+ - gt(Value, Threshold) - greater than
41
+ - lt(Value, Threshold) - less than
42
+ - gte(Value, Threshold) - greater than or equal
43
+ - lte(Value, Threshold) - less than or equal
44
+
45
+ Values are parsed as floating-point numbers. Non-numeric values produce no matches.
46
+ Use with attr() to filter by metadata values (e.g., metrics, line numbers).
47
+
39
48
  ## Examples
40
49
  Find all functions:
41
50
  violation(X) :- node(X, "FUNCTION").
42
51
 
43
52
  Find unresolved calls:
44
53
  violation(X) :- node(X, "CALL"), \\+ edge(X, _, "CALLS").
54
+
55
+ Find files where parsing took > 500ms:
56
+ violation(File, Ms) :- node(M, "METRIC"), attr(M, "name", "parse_ms"), attr(M, "value", Ms), gte(Ms, 500), edge(M, Mod, "OBSERVES"), attr(Mod, "file", File).
57
+
58
+ Find functions with more than 100 lines:
59
+ violation(X, Lines) :- node(X, "FUNCTION"), attr(X, "line", Start), attr(X, "endLine", End), gt(End, Start).
45
60
  `,
46
61
  types: `
47
62
  # Node & Edge Types
@@ -50,12 +65,17 @@ Find unresolved calls:
50
65
  - MODULE, FUNCTION, CLASS, METHOD, VARIABLE
51
66
  - CALL, PROPERTY_ACCESS, IMPORT, EXPORT, PARAMETER
52
67
 
68
+ ## Diagnostic Node Types
69
+ - METRIC — per-file performance metrics (parse_ms, analyze_ms, file_size_bytes, ast_size_bytes, node_count, edge_count, total_ms). Metadata: value, unit, source. Query: find_nodes(type="METRIC") or Datalog with gte/lte for thresholds.
70
+ - ISSUE — analysis problems (oversized files, parse errors, analysis failures). Metadata: category (oversized_source, oversized_ast, parse_error, analysis_error), severity (warning/error), message.
71
+
53
72
  ## HTTP/Network
54
73
  - http:route, http:request, db:query
55
74
 
56
75
  ## Edge Types
57
76
  - CONTAINS, CALLS, DEPENDS_ON
58
77
  - ASSIGNED_FROM, INSTANCE_OF, PASSES_ARGUMENT
78
+ - OBSERVES (METRIC → MODULE, links performance metric to the file it measured)
59
79
  `,
60
80
  guarantees: `
61
81
  # Code Guarantees
@@ -125,6 +145,85 @@ summarized as \`+N more\`. Override with budget parameter.
125
145
  **CLI:** \`grafema describe "src/app.ts->FUNCTION->main" -d 1 --perspective security\`
126
146
 
127
147
  Target resolution order: semantic ID → file path (MODULE) → node name.
148
+ `,
149
+ metrics: `
150
+ # Performance Metrics & Analysis Issues
151
+
152
+ ## METRIC Nodes
153
+ After analysis, each file gets 7 METRIC nodes stored in the graph:
154
+ - parse_ms — time in parser (OXC for JS/TS)
155
+ - analyze_ms — time in analyzer daemon
156
+ - total_ms — wall-clock time for the file
157
+ - file_size_bytes — source file size on disk
158
+ - ast_size_bytes — AST JSON size (JS/TS only)
159
+ - node_count — graph nodes produced
160
+ - edge_count — graph edges produced
161
+
162
+ Each METRIC node has metadata: value (number), unit (ms/bytes/count), source ("orchestrator").
163
+ METRIC → MODULE via OBSERVES edge.
164
+
165
+ ## Querying Metrics
166
+ Find all metrics: find_nodes(type="METRIC")
167
+ Find metrics for a file: find_nodes(type="METRIC", file="src/app.ts")
168
+
169
+ Datalog with numeric comparison:
170
+ violation(File, Ms) :- node(M, "METRIC"), attr(M, "name", "parse_ms"), attr(M, "value", Ms), gte(Ms, 500), edge(M, Mod, "OBSERVES"), attr(Mod, "file", File).
171
+
172
+ ## ISSUE Nodes
173
+ Files that fail analysis get ISSUE nodes (instead of being silently skipped):
174
+ - oversized_source — file larger than maxFileSizeKb config (default: 1MB)
175
+ - oversized_ast — AST larger than maxAstSizeKb config (default: 50MB)
176
+ - parse_error — parser failed
177
+ - analysis_error — analyzer daemon failed
178
+
179
+ Each ISSUE node has metadata: category, severity (warning/error), message.
180
+ MODULE → ISSUE via CONTAINS edge. A MODULE stub is created for failed files.
181
+
182
+ Find issues: find_nodes(type="ISSUE")
183
+
184
+ ## Phase Metrics
185
+ Pipeline-level METRIC nodes on synthetic files (__grafema_perf/{phase}):
186
+ - analysis duration_ms, total_nodes, total_edges, total_files
187
+ - resolve duration_ms
188
+ - compact duration_ms
189
+
190
+ ## Profiler
191
+ Full profiling guide: _ai/profiling-guide.md
192
+ CLI: node scripts/profile-analyze.mjs .grafema/analysis-profile.jsonl
193
+ `,
194
+ effects: `
195
+ # Side-Effect Taxonomy & Manifests
196
+
197
+ ## Manifests
198
+ After analysis, grafema generates manifest.yaml — describes the package's exported API with side-effect annotations.
199
+
200
+ Contents:
201
+ - exports[]: each symbol with name, kind, semanticId, effects[], params[]
202
+ - imports[]: dependencies as Package URLs (pkg:npm/@scope/name)
203
+ - confidence: 0.0–1.0 (lower when many exports have UNKNOWN effects)
204
+
205
+ ## Effect Types (effects-db/taxonomy.yaml)
206
+ - PURE — deterministic, no side effects
207
+ - MUTATION — mutates arguments, receiver, or shared state
208
+ - IO — filesystem, network, database, device, environment
209
+ - THROW — may throw exceptions
210
+ - ASYNC — returns Promise, accepts callbacks
211
+ - NONDETERMINISTIC — output varies (internal randomness, timestamps)
212
+ - UNKNOWN — analysis could not determine (FFI, eval, dynamic require)
213
+
214
+ Propagation: A calls B → A inherits all of B's effects. UNKNOWN propagates transitively.
215
+
216
+ ## Effects-DB
217
+ Pre-built effect databases:
218
+ - effects-db/runtimes/node.yaml — Node.js builtins (fs, crypto, process, etc.)
219
+ - effects-db/packages/*.yaml — npm packages (commander, graphql, ajv, etc.)
220
+
221
+ ## ManifestResolver (programmatic)
222
+ import { ManifestResolver } from '@grafema/util';
223
+ const resolver = new ManifestResolver();
224
+ await resolver.loadFromNodeModules(projectPath);
225
+ const result = resolver.resolve('graphql', 'parse');
226
+ // returns: { name: 'parse', effects: ['THROW'], confidence: 1.0, ... }
128
227
  `,
129
228
  };
130
229
  const content = docs[topic] || docs.overview;
package/dist/handlers/documentation-handlers.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"documentation-handlers.js","sourceRoot":"","sources":["../../src/handlers/documentation-handlers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EACL,UAAU,GACX,MAAM,aAAa,CAAC;AAMrB,wBAAwB;AAExB,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,IAA0B;IACrE,MAAM,EAAE,KAAK,GAAG,UAAU,EAAE,GAAG,IAAI,CAAC;IAEpC,MAAM,IAAI,GAA2B;QACnC,UAAU,EAAE,wBAAwB,EAAE;QACtC,QAAQ,EAAE;;;;;;;;;;;;;;;CAeb;QACG,OAAO,EAAE;;;;;;;;;;;;;;;;;;CAkBZ;QACG,KAAK,EAAE;;;;;;;;;;;;;CAaV;QACG,UAAU,EAAE;;;;;;;;;;;;;;CAcf;QACG,QAAQ,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqDb;KACE,CAAC;IAEF,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC;IAC7C,OAAO,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;AACpC,CAAC"}
1
+ {"version":3,"file":"documentation-handlers.js","sourceRoot":"","sources":["../../src/handlers/documentation-handlers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EACL,UAAU,GACX,MAAM,aAAa,CAAC;AAMrB,wBAAwB;AAExB,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,IAA0B;IACrE,MAAM,EAAE,KAAK,GAAG,UAAU,EAAE,GAAG,IAAI,CAAC;IAEpC,MAAM,IAAI,GAA2B;QACnC,UAAU,EAAE,wBAAwB,EAAE;QACtC,QAAQ,EAAE;;;;;;;;;;;;;;;CAeb;QACG,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiCZ;QACG,KAAK,EAAE;;;;;;;;;;;;;;;;;;CAkBV;QACG,UAAU,EAAE;;;;;;;;;;;;;;CAcf;QACG,QAAQ,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqDb;QACG,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4CZ;QACG,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiCZ;KACE,CAAC;IAEF,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC;IAC7C,OAAO,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;AACpC,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@grafema/mcp",
3
- "version": "0.3.15",
3
+ "version": "0.3.17",
4
4
  "description": "MCP server for Grafema code analysis toolkit",
5
5
  "type": "module",
6
6
  "main": "./dist/server.js",
@@ -39,9 +39,15 @@
39
39
  "@modelcontextprotocol/sdk": "^1.25.1",
40
40
  "ajv": "^8.17.1",
41
41
  "yaml": "^2.8.2",
42
- "@grafema/api": "0.3.15",
43
- "@grafema/util": "0.3.15",
44
- "@grafema/types": "0.3.15"
42
+ "@grafema/api": "0.3.17",
43
+ "@grafema/types": "0.3.17",
44
+ "@grafema/util": "0.3.17"
45
+ },
46
+ "optionalDependencies": {
47
+ "@grafema/grafema-darwin-arm64": "0.3.16",
48
+ "@grafema/grafema-darwin-x64": "0.3.16",
49
+ "@grafema/grafema-linux-arm64": "0.3.16",
50
+ "@grafema/grafema-linux-x64": "0.3.16"
45
51
  },
46
52
  "devDependencies": {
47
53
  "@types/node": "^25.0.8",
package/src/definitions/project-tools.ts CHANGED
@@ -122,10 +122,12 @@ Use AFTER analyze_project when queries return unexpected empty results.`,
122
122
  description: `Get documentation about Grafema usage and query syntax.
123
123
 
124
124
  Topics available:
125
- - queries: Datalog query syntax and examples
126
- - types: Available node and edge types
125
+ - queries: Datalog query syntax, predicates (including numeric comparisons), and examples
126
+ - types: Available node and edge types (including METRIC and ISSUE diagnostic nodes)
127
127
  - guarantees: How to create and manage code guarantees
128
128
  - notation: DSL notation reference (archetypes, operators, LOD, perspectives)
129
+ - metrics: Performance metrics (METRIC nodes) and analysis issues (ISSUE nodes)
130
+ - effects: Side-effect taxonomy and manifest system
129
131
  - onboarding: Step-by-step guide for new projects
130
132
  - overview: High-level Grafema architecture
131
133
 
@@ -135,7 +137,7 @@ Use this when you need to learn Datalog syntax, DSL notation, or understand avai
135
137
  properties: {
136
138
  topic: {
137
139
  type: 'string',
138
- description: 'Topic: queries, types, guarantees, notation, onboarding, or overview',
140
+ description: 'Topic: queries, types, guarantees, notation, metrics, effects, onboarding, or overview',
139
141
  },
140
142
  },
141
143
  },
package/src/definitions/query-tools.ts CHANGED
@@ -14,22 +14,28 @@ Set language to "cypher" for Cypher queries (e.g., MATCH (n:FUNCTION) RETURN n.n
14
14
  Default is Datalog.
15
15
 
16
16
  Available Datalog predicates:
17
- - type(Id, Type) - match nodes by type (alias: node)
17
+ - type(Id, Type) / node(Id, Type) - match nodes by type
18
18
  - edge(Src, Dst, Type) - match edges
19
19
  - attr(Id, Name, Value) - match node attributes (name, file, line, etc.)
20
+ - gt(Val, N), lt(Val, N), gte(Val, N), lte(Val, N) - numeric comparisons
21
+ - \\+ - negation (not)
20
22
 
21
23
  NODE TYPES:
22
24
  - MODULE, FUNCTION, METHOD, CLASS, VARIABLE, PARAMETER
23
25
  - CALL, PROPERTY_ACCESS, METHOD_CALL, CALL_SITE
26
+ - METRIC (performance metrics: value/unit/source in metadata, OBSERVES → MODULE)
27
+ - ISSUE (analysis problems: category/severity/message in metadata, CONTAINS ← MODULE)
24
28
  - http:route, http:request, db:query, socketio:emit, socketio:on
25
29
 
26
30
  EDGE TYPES:
27
31
  - CONTAINS, CALLS, DEPENDS_ON, ASSIGNED_FROM, INSTANCE_OF, PASSES_ARGUMENT
32
+ - OBSERVES (METRIC → MODULE, links performance metric to observed file)
28
33
 
29
34
  EXAMPLES:
30
35
  violation(X) :- node(X, "MODULE").
31
36
  violation(X) :- node(X, "FUNCTION"), attr(X, "file", "src/api.js").
32
- violation(X) :- node(X, "CALL"), \\+ edge(X, _, "CALLS").`,
37
+ violation(X) :- node(X, "CALL"), \\+ edge(X, _, "CALLS").
38
+ violation(F, Ms) :- node(M, "METRIC"), attr(M, "name", "parse_ms"), attr(M, "value", Ms), gte(Ms, 500), edge(M, Mod, "OBSERVES"), attr(Mod, "file", F).`,
33
39
  inputSchema: {
34
40
  type: 'object',
35
41
  properties: {
package/src/handlers/documentation-handlers.ts CHANGED
@@ -43,15 +43,30 @@ violation(X) :- node(X, "TYPE"), attr(X, "name", "value").
43
43
  ## Available Predicates
44
44
  - type(Id, Type) - match nodes (alias: node)
45
45
  - edge(Src, Dst, Type) - match edges
46
- - attr(Id, Name, Value) - match attributes
46
+ - attr(Id, Name, Value) - match node attributes (name, file, line, etc.)
47
47
  - \\+ - negation (not)
48
48
 
49
+ ## Numeric Comparison Predicates
50
+ - gt(Value, Threshold) - greater than
51
+ - lt(Value, Threshold) - less than
52
+ - gte(Value, Threshold) - greater than or equal
53
+ - lte(Value, Threshold) - less than or equal
54
+
55
+ Values are parsed as floating-point numbers. Non-numeric values produce no matches.
56
+ Use with attr() to filter by metadata values (e.g., metrics, line numbers).
57
+
49
58
  ## Examples
50
59
  Find all functions:
51
60
  violation(X) :- node(X, "FUNCTION").
52
61
 
53
62
  Find unresolved calls:
54
63
  violation(X) :- node(X, "CALL"), \\+ edge(X, _, "CALLS").
64
+
65
+ Find files where parsing took > 500ms:
66
+ violation(File, Ms) :- node(M, "METRIC"), attr(M, "name", "parse_ms"), attr(M, "value", Ms), gte(Ms, 500), edge(M, Mod, "OBSERVES"), attr(Mod, "file", File).
67
+
68
+ Find functions with more than 100 lines:
69
+ violation(X, Lines) :- node(X, "FUNCTION"), attr(X, "line", Start), attr(X, "endLine", End), gt(End, Start).
55
70
  `,
56
71
  types: `
57
72
  # Node & Edge Types
@@ -60,12 +75,17 @@ Find unresolved calls:
60
75
  - MODULE, FUNCTION, CLASS, METHOD, VARIABLE
61
76
  - CALL, PROPERTY_ACCESS, IMPORT, EXPORT, PARAMETER
62
77
 
78
+ ## Diagnostic Node Types
79
+ - METRIC — per-file performance metrics (parse_ms, analyze_ms, file_size_bytes, ast_size_bytes, node_count, edge_count, total_ms). Metadata: value, unit, source. Query: find_nodes(type="METRIC") or Datalog with gte/lte for thresholds.
80
+ - ISSUE — analysis problems (oversized files, parse errors, analysis failures). Metadata: category (oversized_source, oversized_ast, parse_error, analysis_error), severity (warning/error), message.
81
+
63
82
  ## HTTP/Network
64
83
  - http:route, http:request, db:query
65
84
 
66
85
  ## Edge Types
67
86
  - CONTAINS, CALLS, DEPENDS_ON
68
87
  - ASSIGNED_FROM, INSTANCE_OF, PASSES_ARGUMENT
88
+ - OBSERVES (METRIC → MODULE, links performance metric to the file it measured)
69
89
  `,
70
90
  guarantees: `
71
91
  # Code Guarantees
@@ -135,6 +155,85 @@ summarized as \`+N more\`. Override with budget parameter.
135
155
  **CLI:** \`grafema describe "src/app.ts->FUNCTION->main" -d 1 --perspective security\`
136
156
 
137
157
  Target resolution order: semantic ID → file path (MODULE) → node name.
158
+ `,
159
+ metrics: `
160
+ # Performance Metrics & Analysis Issues
161
+
162
+ ## METRIC Nodes
163
+ After analysis, each file gets 7 METRIC nodes stored in the graph:
164
+ - parse_ms — time in parser (OXC for JS/TS)
165
+ - analyze_ms — time in analyzer daemon
166
+ - total_ms — wall-clock time for the file
167
+ - file_size_bytes — source file size on disk
168
+ - ast_size_bytes — AST JSON size (JS/TS only)
169
+ - node_count — graph nodes produced
170
+ - edge_count — graph edges produced
171
+
172
+ Each METRIC node has metadata: value (number), unit (ms/bytes/count), source ("orchestrator").
173
+ METRIC → MODULE via OBSERVES edge.
174
+
175
+ ## Querying Metrics
176
+ Find all metrics: find_nodes(type="METRIC")
177
+ Find metrics for a file: find_nodes(type="METRIC", file="src/app.ts")
178
+
179
+ Datalog with numeric comparison:
180
+ violation(File, Ms) :- node(M, "METRIC"), attr(M, "name", "parse_ms"), attr(M, "value", Ms), gte(Ms, 500), edge(M, Mod, "OBSERVES"), attr(Mod, "file", File).
181
+
182
+ ## ISSUE Nodes
183
+ Files that fail analysis get ISSUE nodes (instead of being silently skipped):
184
+ - oversized_source — file larger than maxFileSizeKb config (default: 1MB)
185
+ - oversized_ast — AST larger than maxAstSizeKb config (default: 50MB)
186
+ - parse_error — parser failed
187
+ - analysis_error — analyzer daemon failed
188
+
189
+ Each ISSUE node has metadata: category, severity (warning/error), message.
190
+ MODULE → ISSUE via CONTAINS edge. A MODULE stub is created for failed files.
191
+
192
+ Find issues: find_nodes(type="ISSUE")
193
+
194
+ ## Phase Metrics
195
+ Pipeline-level METRIC nodes on synthetic files (__grafema_perf/{phase}):
196
+ - analysis duration_ms, total_nodes, total_edges, total_files
197
+ - resolve duration_ms
198
+ - compact duration_ms
199
+
200
+ ## Profiler
201
+ Full profiling guide: _ai/profiling-guide.md
202
+ CLI: node scripts/profile-analyze.mjs .grafema/analysis-profile.jsonl
203
+ `,
204
+ effects: `
205
+ # Side-Effect Taxonomy & Manifests
206
+
207
+ ## Manifests
208
+ After analysis, grafema generates manifest.yaml — describes the package's exported API with side-effect annotations.
209
+
210
+ Contents:
211
+ - exports[]: each symbol with name, kind, semanticId, effects[], params[]
212
+ - imports[]: dependencies as Package URLs (pkg:npm/@scope/name)
213
+ - confidence: 0.0–1.0 (lower when many exports have UNKNOWN effects)
214
+
215
+ ## Effect Types (effects-db/taxonomy.yaml)
216
+ - PURE — deterministic, no side effects
217
+ - MUTATION — mutates arguments, receiver, or shared state
218
+ - IO — filesystem, network, database, device, environment
219
+ - THROW — may throw exceptions
220
+ - ASYNC — returns Promise, accepts callbacks
221
+ - NONDETERMINISTIC — output varies (internal randomness, timestamps)
222
+ - UNKNOWN — analysis could not determine (FFI, eval, dynamic require)
223
+
224
+ Propagation: A calls B → A inherits all of B's effects. UNKNOWN propagates transitively.
225
+
226
+ ## Effects-DB
227
+ Pre-built effect databases:
228
+ - effects-db/runtimes/node.yaml — Node.js builtins (fs, crypto, process, etc.)
229
+ - effects-db/packages/*.yaml — npm packages (commander, graphql, ajv, etc.)
230
+
231
+ ## ManifestResolver (programmatic)
232
+ import { ManifestResolver } from '@grafema/util';
233
+ const resolver = new ManifestResolver();
234
+ await resolver.loadFromNodeModules(projectPath);
235
+ const result = resolver.resolve('graphql', 'parse');
236
+ // returns: { name: 'parse', effects: ['THROW'], confidence: 1.0, ... }
138
237
  `,
139
238
  };
140
239