ts-knowledge-graph 0.1.2 → 0.1.4

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 (255) hide show
  1. package/README.md +74 -34
  2. package/contribs/web_visualisation/README.md +28 -0
  3. package/contribs/web_visualisation/web/css/style.css +104 -0
  4. package/contribs/web_visualisation/web/data/.gitignore +1 -0
  5. package/contribs/web_visualisation/web/data/kind_descriptions.js +38 -0
  6. package/contribs/web_visualisation/web/index.html +20 -4
  7. package/contribs/web_visualisation/web/js/app.js +581 -35
  8. package/contribs/web_visualisation/web/tsconfig.json +18 -0
  9. package/contribs/web_visualisation/web/types/app_globals.d.ts +146 -0
  10. package/dist/benchmark/benchmark_stats.d.ts +41 -0
  11. package/dist/benchmark/benchmark_stats.d.ts.map +1 -0
  12. package/dist/benchmark/benchmark_stats.js +61 -0
  13. package/dist/benchmark/benchmark_stats.js.map +1 -0
  14. package/dist/benchmark/node_benchmark.d.ts +78 -0
  15. package/dist/benchmark/node_benchmark.d.ts.map +1 -0
  16. package/dist/benchmark/node_benchmark.js +112 -0
  17. package/dist/benchmark/node_benchmark.js.map +1 -0
  18. package/dist/cli.d.ts.map +1 -1
  19. package/dist/cli.js +10 -2
  20. package/dist/cli.js.map +1 -1
  21. package/dist/commands/benchmark_command.d.ts +11 -0
  22. package/dist/commands/benchmark_command.d.ts.map +1 -0
  23. package/dist/commands/benchmark_command.js +91 -0
  24. package/dist/commands/benchmark_command.js.map +1 -0
  25. package/dist/commands/blast_radius_command.js +1 -1
  26. package/dist/commands/blast_radius_command.js.map +1 -1
  27. package/dist/commands/cost_command.d.ts +13 -0
  28. package/dist/commands/cost_command.d.ts.map +1 -0
  29. package/dist/commands/cost_command.js +122 -0
  30. package/dist/commands/cost_command.js.map +1 -0
  31. package/dist/commands/{load.d.ts → enrich_command.d.ts} +3 -2
  32. package/dist/commands/enrich_command.d.ts.map +1 -0
  33. package/dist/commands/enrich_command.js +62 -0
  34. package/dist/commands/enrich_command.js.map +1 -0
  35. package/dist/commands/hotspots_command.d.ts +7 -0
  36. package/dist/commands/hotspots_command.d.ts.map +1 -0
  37. package/dist/commands/hotspots_command.js +67 -0
  38. package/dist/commands/hotspots_command.js.map +1 -0
  39. package/dist/commands/install_command.d.ts +2 -3
  40. package/dist/commands/install_command.d.ts.map +1 -1
  41. package/dist/commands/install_command.js +7 -8
  42. package/dist/commands/install_command.js.map +1 -1
  43. package/dist/commands/load_command.d.ts.map +1 -1
  44. package/dist/commands/load_command.js +2 -0
  45. package/dist/commands/load_command.js.map +1 -1
  46. package/dist/commands/verify_command.d.ts +8 -0
  47. package/dist/commands/verify_command.d.ts.map +1 -0
  48. package/dist/commands/verify_command.js +57 -0
  49. package/dist/commands/verify_command.js.map +1 -0
  50. package/dist/commands/web_command.d.ts +27 -0
  51. package/dist/commands/web_command.d.ts.map +1 -1
  52. package/dist/commands/web_command.js +109 -3
  53. package/dist/commands/web_command.js.map +1 -1
  54. package/dist/enrich/cpu_profile.d.ts +127 -0
  55. package/dist/enrich/cpu_profile.d.ts.map +1 -0
  56. package/dist/enrich/cpu_profile.js +97 -0
  57. package/dist/enrich/cpu_profile.js.map +1 -0
  58. package/dist/enrich/runtime_enricher.d.ts +56 -0
  59. package/dist/enrich/runtime_enricher.d.ts.map +1 -0
  60. package/dist/enrich/runtime_enricher.js +80 -0
  61. package/dist/enrich/runtime_enricher.js.map +1 -0
  62. package/dist/enrich/runtime_join.d.ts +100 -0
  63. package/dist/enrich/runtime_join.d.ts.map +1 -0
  64. package/dist/enrich/runtime_join.js +227 -0
  65. package/dist/enrich/runtime_join.js.map +1 -0
  66. package/dist/extract/api_extractor.d.ts +24 -0
  67. package/dist/extract/api_extractor.d.ts.map +1 -0
  68. package/dist/extract/api_extractor.js +71 -0
  69. package/dist/extract/api_extractor.js.map +1 -0
  70. package/dist/extract/config_extractor.d.ts +22 -0
  71. package/dist/extract/config_extractor.d.ts.map +1 -0
  72. package/dist/extract/config_extractor.js +61 -0
  73. package/dist/extract/config_extractor.js.map +1 -0
  74. package/dist/extract/endpoint_extractor.d.ts +36 -0
  75. package/dist/extract/endpoint_extractor.d.ts.map +1 -0
  76. package/dist/extract/endpoint_extractor.js +117 -0
  77. package/dist/extract/endpoint_extractor.js.map +1 -0
  78. package/dist/extract/graph_builder.d.ts +8 -0
  79. package/dist/extract/graph_builder.d.ts.map +1 -1
  80. package/dist/extract/graph_builder.js +23 -1
  81. package/dist/extract/graph_builder.js.map +1 -1
  82. package/dist/extract/node_id.d.ts +16 -0
  83. package/dist/extract/node_id.d.ts.map +1 -1
  84. package/dist/extract/node_id.js +22 -0
  85. package/dist/extract/node_id.js.map +1 -1
  86. package/dist/extract/scope_resolver.d.ts +22 -0
  87. package/dist/extract/scope_resolver.d.ts.map +1 -0
  88. package/dist/extract/scope_resolver.js +53 -0
  89. package/dist/extract/scope_resolver.js.map +1 -0
  90. package/dist/extract/semantic_extractor.d.ts +25 -0
  91. package/dist/extract/semantic_extractor.d.ts.map +1 -1
  92. package/dist/extract/semantic_extractor.js +96 -2
  93. package/dist/extract/semantic_extractor.js.map +1 -1
  94. package/dist/extract/structural_extractor.d.ts +6 -0
  95. package/dist/extract/structural_extractor.d.ts.map +1 -1
  96. package/dist/extract/structural_extractor.js +22 -12
  97. package/dist/extract/structural_extractor.js.map +1 -1
  98. package/dist/project_root.d.ts +7 -0
  99. package/dist/project_root.d.ts.map +1 -0
  100. package/dist/project_root.js +9 -0
  101. package/dist/project_root.js.map +1 -0
  102. package/dist/query/graph_query.d.ts +234 -0
  103. package/dist/query/graph_query.d.ts.map +1 -1
  104. package/dist/query/graph_query.js +522 -11
  105. package/dist/query/graph_query.js.map +1 -1
  106. package/dist/schema/edge.d.ts +40 -5
  107. package/dist/schema/edge.d.ts.map +1 -1
  108. package/dist/schema/edge.js +70 -0
  109. package/dist/schema/edge.js.map +1 -1
  110. package/dist/schema/node.d.ts +20 -5
  111. package/dist/schema/node.d.ts.map +1 -1
  112. package/dist/schema/node.js +36 -0
  113. package/dist/schema/node.js.map +1 -1
  114. package/dist/schema/runtime_manifest.d.ts +36 -0
  115. package/dist/schema/runtime_manifest.d.ts.map +1 -0
  116. package/dist/schema/runtime_manifest.js +23 -0
  117. package/dist/schema/runtime_manifest.js.map +1 -0
  118. package/dist/store/kuzu_store.d.ts +46 -0
  119. package/dist/store/kuzu_store.d.ts.map +1 -1
  120. package/dist/store/kuzu_store.js +95 -5
  121. package/dist/store/kuzu_store.js.map +1 -1
  122. package/dist/verify/project_verifier.d.ts +85 -0
  123. package/dist/verify/project_verifier.d.ts.map +1 -0
  124. package/dist/verify/project_verifier.js +138 -0
  125. package/dist/verify/project_verifier.js.map +1 -0
  126. package/{skills/ts-knowledge-graph → dotclaude_folder/skills/code-graph-query}/SKILL.md +2 -2
  127. package/package.json +86 -7
  128. package/.env-sample +0 -34
  129. package/dist/agent/agent-tools.d.ts +0 -13
  130. package/dist/agent/agent-tools.d.ts.map +0 -1
  131. package/dist/agent/agent-tools.js +0 -153
  132. package/dist/agent/agent-tools.js.map +0 -1
  133. package/dist/agent/agent_tools.d.ts +0 -13
  134. package/dist/agent/agent_tools.d.ts.map +0 -1
  135. package/dist/agent/agent_tools.js +0 -153
  136. package/dist/agent/agent_tools.js.map +0 -1
  137. package/dist/agent/code-editor.d.ts +0 -18
  138. package/dist/agent/code-editor.d.ts.map +0 -1
  139. package/dist/agent/code-editor.js +0 -43
  140. package/dist/agent/code-editor.js.map +0 -1
  141. package/dist/agent/code_editor.d.ts +0 -18
  142. package/dist/agent/code_editor.d.ts.map +0 -1
  143. package/dist/agent/code_editor.js +0 -43
  144. package/dist/agent/code_editor.js.map +0 -1
  145. package/dist/agent/optimizer-agent.d.ts +0 -30
  146. package/dist/agent/optimizer-agent.d.ts.map +0 -1
  147. package/dist/agent/optimizer-agent.js +0 -97
  148. package/dist/agent/optimizer-agent.js.map +0 -1
  149. package/dist/agent/optimizer_agent.d.ts +0 -30
  150. package/dist/agent/optimizer_agent.d.ts.map +0 -1
  151. package/dist/agent/optimizer_agent.js +0 -97
  152. package/dist/agent/optimizer_agent.js.map +0 -1
  153. package/dist/agent/verifier.d.ts +0 -9
  154. package/dist/agent/verifier.d.ts.map +0 -1
  155. package/dist/agent/verifier.js +0 -19
  156. package/dist/agent/verifier.js.map +0 -1
  157. package/dist/commands/blast-radius.d.ts +0 -5
  158. package/dist/commands/blast-radius.d.ts.map +0 -1
  159. package/dist/commands/blast-radius.js +0 -18
  160. package/dist/commands/blast-radius.js.map +0 -1
  161. package/dist/commands/blast_radius.d.ts +0 -5
  162. package/dist/commands/blast_radius.d.ts.map +0 -1
  163. package/dist/commands/blast_radius.js +0 -18
  164. package/dist/commands/blast_radius.js.map +0 -1
  165. package/dist/commands/calls.d.ts +0 -5
  166. package/dist/commands/calls.d.ts.map +0 -1
  167. package/dist/commands/calls.js +0 -7
  168. package/dist/commands/calls.js.map +0 -1
  169. package/dist/commands/command-helpers.d.ts +0 -15
  170. package/dist/commands/command-helpers.d.ts.map +0 -1
  171. package/dist/commands/command-helpers.js +0 -61
  172. package/dist/commands/command-helpers.js.map +0 -1
  173. package/dist/commands/dead-exports.d.ts +0 -5
  174. package/dist/commands/dead-exports.d.ts.map +0 -1
  175. package/dist/commands/dead-exports.js +0 -7
  176. package/dist/commands/dead-exports.js.map +0 -1
  177. package/dist/commands/dead_exports.d.ts +0 -5
  178. package/dist/commands/dead_exports.d.ts.map +0 -1
  179. package/dist/commands/dead_exports.js +0 -7
  180. package/dist/commands/dead_exports.js.map +0 -1
  181. package/dist/commands/extract.d.ts +0 -8
  182. package/dist/commands/extract.d.ts.map +0 -1
  183. package/dist/commands/extract.js +0 -49
  184. package/dist/commands/extract.js.map +0 -1
  185. package/dist/commands/find.d.ts +0 -5
  186. package/dist/commands/find.d.ts.map +0 -1
  187. package/dist/commands/find.js +0 -7
  188. package/dist/commands/find.js.map +0 -1
  189. package/dist/commands/load.d.ts.map +0 -1
  190. package/dist/commands/load.js +0 -28
  191. package/dist/commands/load.js.map +0 -1
  192. package/dist/commands/neighbors.d.ts +0 -5
  193. package/dist/commands/neighbors.d.ts.map +0 -1
  194. package/dist/commands/neighbors.js +0 -17
  195. package/dist/commands/neighbors.js.map +0 -1
  196. package/dist/commands/optimize.d.ts +0 -6
  197. package/dist/commands/optimize.d.ts.map +0 -1
  198. package/dist/commands/optimize.js +0 -59
  199. package/dist/commands/optimize.js.map +0 -1
  200. package/dist/commands/optimize_command.d.ts +0 -6
  201. package/dist/commands/optimize_command.d.ts.map +0 -1
  202. package/dist/commands/optimize_command.js +0 -59
  203. package/dist/commands/optimize_command.js.map +0 -1
  204. package/dist/commands/references.d.ts +0 -5
  205. package/dist/commands/references.d.ts.map +0 -1
  206. package/dist/commands/references.js +0 -17
  207. package/dist/commands/references.js.map +0 -1
  208. package/dist/commands/web.d.ts +0 -19
  209. package/dist/commands/web.d.ts.map +0 -1
  210. package/dist/commands/web.js +0 -120
  211. package/dist/commands/web.js.map +0 -1
  212. package/dist/commands/who-calls.d.ts +0 -5
  213. package/dist/commands/who-calls.d.ts.map +0 -1
  214. package/dist/commands/who-calls.js +0 -7
  215. package/dist/commands/who-calls.js.map +0 -1
  216. package/dist/commands/who_calls.d.ts +0 -5
  217. package/dist/commands/who_calls.d.ts.map +0 -1
  218. package/dist/commands/who_calls.js +0 -7
  219. package/dist/commands/who_calls.js.map +0 -1
  220. package/dist/extract/graph-builder.d.ts +0 -16
  221. package/dist/extract/graph-builder.d.ts.map +0 -1
  222. package/dist/extract/graph-builder.js +0 -39
  223. package/dist/extract/graph-builder.js.map +0 -1
  224. package/dist/extract/node-id.d.ts +0 -8
  225. package/dist/extract/node-id.d.ts.map +0 -1
  226. package/dist/extract/node-id.js +0 -22
  227. package/dist/extract/node-id.js.map +0 -1
  228. package/dist/extract/project-loader.d.ts +0 -5
  229. package/dist/extract/project-loader.d.ts.map +0 -1
  230. package/dist/extract/project-loader.js +0 -19
  231. package/dist/extract/project-loader.js.map +0 -1
  232. package/dist/extract/semantic-extractor.d.ts +0 -22
  233. package/dist/extract/semantic-extractor.d.ts.map +0 -1
  234. package/dist/extract/semantic-extractor.js +0 -254
  235. package/dist/extract/semantic-extractor.js.map +0 -1
  236. package/dist/extract/structural-extractor.d.ts +0 -18
  237. package/dist/extract/structural-extractor.d.ts.map +0 -1
  238. package/dist/extract/structural-extractor.js +0 -97
  239. package/dist/extract/structural-extractor.js.map +0 -1
  240. package/dist/query/graph-query.d.ts +0 -28
  241. package/dist/query/graph-query.d.ts.map +0 -1
  242. package/dist/query/graph-query.js +0 -93
  243. package/dist/query/graph-query.js.map +0 -1
  244. package/dist/store/jsonl-reader.d.ts +0 -11
  245. package/dist/store/jsonl-reader.d.ts.map +0 -1
  246. package/dist/store/jsonl-reader.js +0 -19
  247. package/dist/store/jsonl-reader.js.map +0 -1
  248. package/dist/store/jsonl-store.d.ts +0 -7
  249. package/dist/store/jsonl-store.d.ts.map +0 -1
  250. package/dist/store/jsonl-store.js +0 -13
  251. package/dist/store/jsonl-store.js.map +0 -1
  252. package/dist/store/kuzu-store.d.ts +0 -14
  253. package/dist/store/kuzu-store.d.ts.map +0 -1
  254. package/dist/store/kuzu-store.js +0 -52
  255. package/dist/store/kuzu-store.js.map +0 -1
@@ -15,16 +15,16 @@ export class StructuralExtractor {
15
15
  StructuralExtractor.extractInterface(iface, moduleId, rootPath, nodes, edges);
16
16
  }
17
17
  for (const alias of sourceFile.getTypeAliases()) {
18
- StructuralExtractor.push(alias, 'TypeAlias', moduleId, rootPath, nodes, edges);
18
+ StructuralExtractor.push(alias, 'TypeAlias', moduleId, moduleId, rootPath, nodes, edges);
19
19
  }
20
20
  for (const en of sourceFile.getEnums()) {
21
- StructuralExtractor.push(en, 'Enum', moduleId, rootPath, nodes, edges);
21
+ StructuralExtractor.push(en, 'Enum', moduleId, moduleId, rootPath, nodes, edges);
22
22
  }
23
23
  for (const fn of sourceFile.getFunctions()) {
24
- StructuralExtractor.push(fn, 'Function', moduleId, rootPath, nodes, edges);
24
+ StructuralExtractor.push(fn, 'Function', moduleId, moduleId, rootPath, nodes, edges);
25
25
  }
26
26
  for (const variable of sourceFile.getVariableDeclarations()) {
27
- StructuralExtractor.push(variable, 'Variable', moduleId, rootPath, nodes, edges);
27
+ StructuralExtractor.push(variable, 'Variable', moduleId, moduleId, rootPath, nodes, edges);
28
28
  }
29
29
  return { nodes, edges };
30
30
  }
@@ -43,25 +43,32 @@ export class StructuralExtractor {
43
43
  }
44
44
  }
45
45
  static extractClass(cls, moduleId, rootPath, nodes, edges) {
46
- const classId = StructuralExtractor.push(cls, 'Class', moduleId, rootPath, nodes, edges);
46
+ const classId = StructuralExtractor.push(cls, 'Class', moduleId, moduleId, rootPath, nodes, edges);
47
47
  for (const method of cls.getMethods()) {
48
- StructuralExtractor.push(method, 'Method', classId, rootPath, nodes, edges);
48
+ StructuralExtractor.push(method, 'Method', classId, moduleId, rootPath, nodes, edges);
49
49
  }
50
50
  for (const property of cls.getProperties()) {
51
- StructuralExtractor.push(property, 'Property', classId, rootPath, nodes, edges);
51
+ StructuralExtractor.push(property, 'Property', classId, moduleId, rootPath, nodes, edges);
52
52
  }
53
53
  }
54
54
  static extractInterface(iface, moduleId, rootPath, nodes, edges) {
55
- const ifaceId = StructuralExtractor.push(iface, 'Interface', moduleId, rootPath, nodes, edges);
55
+ const ifaceId = StructuralExtractor.push(iface, 'Interface', moduleId, moduleId, rootPath, nodes, edges);
56
56
  for (const method of iface.getMethods()) {
57
- StructuralExtractor.push(method, 'Method', ifaceId, rootPath, nodes, edges);
57
+ StructuralExtractor.push(method, 'Method', ifaceId, moduleId, rootPath, nodes, edges);
58
58
  }
59
59
  for (const property of iface.getProperties()) {
60
- StructuralExtractor.push(property, 'Property', ifaceId, rootPath, nodes, edges);
60
+ StructuralExtractor.push(property, 'Property', ifaceId, moduleId, rootPath, nodes, edges);
61
61
  }
62
62
  }
63
- static push(node, kind, parentId, rootPath, nodes, edges) {
63
+ /**
64
+ * Pushes a declaration node, its `CONTAINS` edge from `parentId`, and — when the
65
+ * declaration is exported — an `EXPORTS` edge from `moduleId`. Only top-level
66
+ * declarations are ever exported, so `EXPORTS` always originates at the module;
67
+ * nested members (methods, properties) carry `exported === false` and get none.
68
+ */
69
+ static push(node, kind, parentId, moduleId, rootPath, nodes, edges) {
64
70
  const id = NodeId.forDeclaration(node, rootPath);
71
+ const exported = StructuralExtractor.isExported(node);
65
72
  nodes.push({
66
73
  id,
67
74
  kind,
@@ -73,9 +80,12 @@ export class StructuralExtractor {
73
80
  endLine: node.getEndLineNumber(),
74
81
  endColumn: 0,
75
82
  },
76
- exported: StructuralExtractor.isExported(node),
83
+ exported,
77
84
  });
78
85
  edges.push(StructuralExtractor.edge('CONTAINS', parentId, id));
86
+ if (exported === true) {
87
+ edges.push(StructuralExtractor.edge('EXPORTS', moduleId, id));
88
+ }
79
89
  return id;
80
90
  }
81
91
  static isInternal(sourceFile) {
@@ -1 +1 @@
1
- {"version":3,"file":"structural_extractor.js","sourceRoot":"","sources":["../../src/extract/structural_extractor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AASrC,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAOtC,MAAM,OAAO,mBAAmB;IAC/B,MAAM,CAAC,OAAO,CAAC,UAAsB,EAAE,QAAgB;QACtD,MAAM,KAAK,GAAgB,EAAE,CAAC;QAC9B,MAAM,KAAK,GAAgB,EAAE,CAAC;QAC9B,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC;QAC9D,MAAM,QAAQ,GAAG,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,WAAW,EAAE,EAAE,QAAQ,CAAC,CAAC;QAEtE,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC;QAEvE,mBAAmB,CAAC,cAAc,CAAC,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QAEjF,KAAK,MAAM,GAAG,IAAI,UAAU,CAAC,UAAU,EAAE,EAAE,CAAC;YAC3C,mBAAmB,CAAC,YAAY,CAAC,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QACzE,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,UAAU,CAAC,aAAa,EAAE,EAAE,CAAC;YAChD,mBAAmB,CAAC,gBAAgB,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QAC/E,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,UAAU,CAAC,cAAc,EAAE,EAAE,CAAC;YACjD,mBAAmB,CAAC,IAAI,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QAChF,CAAC;QACD,KAAK,MAAM,EAAE,IAAI,UAAU,CAAC,QAAQ,EAAE,EAAE,CAAC;YACxC,mBAAmB,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QACxE,CAAC;QACD,KAAK,MAAM,EAAE,IAAI,UAAU,CAAC,YAAY,EAAE,EAAE,CAAC;YAC5C,mBAAmB,CAAC,IAAI,CAAC,EAAE,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QAC5E,CAAC;QACD,KAAK,MAAM,QAAQ,IAAI,UAAU,CAAC,uBAAuB,EAAE,EAAE,CAAC;YAC7D,mBAAmB,CAAC,IAAI,CAAC,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QAClF,CAAC;QAED,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IACzB,CAAC;IAEO,MAAM,CAAC,cAAc,CAC5B,UAAsB,EACtB,QAAgB,EAChB,QAAgB,EAChB,KAAkB,EAClB,KAAkB;QAElB,KAAK,MAAM,IAAI,IAAI,UAAU,CAAC,qBAAqB,EAAE,EAAE,CAAC;YACvD,MAAM,SAAS,GAAG,IAAI,CAAC,uBAAuB,EAAE,CAAC;YACjD,MAAM,MAAM,GAAG,IAAI,CAAC,4BAA4B,EAAE,CAAC;YACnD,IAAI,MAAM,KAAK,SAAS,IAAI,mBAAmB,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC;gBAC7E,MAAM,QAAQ,GAAG,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,WAAW,EAAE,EAAE,QAAQ,CAAC,CAAC;gBAClE,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC;gBACnF,SAAS;YACV,CAAC;YACD,MAAM,UAAU,GAAG,MAAM,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC;YACvD,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC;YAC7F,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC;QACtF,CAAC;IACF,CAAC;IAEO,MAAM,CAAC,YAAY,CAC1B,GAAqB,EACrB,QAAgB,EAChB,QAAgB,EAChB,KAAkB,EAClB,KAAkB;QAElB,MAAM,OAAO,GAAG,mBAAmB,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QACzF,KAAK,MAAM,MAAM,IAAI,GAAG,CAAC,UAAU,EAAE,EAAE,CAAC;YACvC,mBAAmB,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QAC7E,CAAC;QACD,KAAK,MAAM,QAAQ,IAAI,GAAG,CAAC,aAAa,EAAE,EAAE,CAAC;YAC5C,mBAAmB,CAAC,IAAI,CAAC,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QACjF,CAAC;IACF,CAAC;IAEO,MAAM,CAAC,gBAAgB,CAC9B,KAA2B,EAC3B,QAAgB,EAChB,QAAgB,EAChB,KAAkB,EAClB,KAAkB;QAElB,MAAM,OAAO,GAAG,mBAAmB,CAAC,IAAI,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QAC/F,KAAK,MAAM,MAAM,IAAI,KAAK,CAAC,UAAU,EAAE,EAAE,CAAC;YACzC,mBAAmB,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QAC7E,CAAC;QACD,KAAK,MAAM,QAAQ,IAAI,KAAK,CAAC,aAAa,EAAE,EAAE,CAAC;YAC9C,mBAAmB,CAAC,IAAI,CAAC,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QACjF,CAAC;IACF,CAAC;IAEO,MAAM,CAAC,IAAI,CAClB,IAAU,EACV,IAAc,EACd,QAAgB,EAChB,QAAgB,EAChB,KAAkB,EAClB,KAAkB;QAElB,MAAM,EAAE,GAAG,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACjD,KAAK,CAAC,IAAI,CAAC;YACV,EAAE;YACF,IAAI;YACJ,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;YACzB,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,aAAa,EAAE,CAAC,WAAW,EAAE,CAAC;YAChE,KAAK,EAAE;gBACN,SAAS,EAAE,IAAI,CAAC,kBAAkB,EAAE;gBACpC,WAAW,EAAE,CAAC;gBACd,OAAO,EAAE,IAAI,CAAC,gBAAgB,EAAE;gBAChC,SAAS,EAAE,CAAC;aACZ;YACD,QAAQ,EAAE,mBAAmB,CAAC,UAAU,CAAC,IAAI,CAAC;SAC9C,CAAC,CAAC;QACH,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC;QAC/D,OAAO,EAAE,CAAC;IACX,CAAC;IAEO,MAAM,CAAC,UAAU,CAAC,UAAsB;QAC/C,OAAO,UAAU,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,gBAAgB,CAAC,KAAK,KAAK;eAChE,UAAU,CAAC,iBAAiB,EAAE,KAAK,KAAK,CAAC;IAC9C,CAAC;IAEO,MAAM,CAAC,UAAU,CAAC,IAAU;QACnC,MAAM,KAAK,GAAG,IAAsC,CAAC;QACrD,OAAO,OAAO,KAAK,CAAC,UAAU,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;IAC5E,CAAC;IAEO,MAAM,CAAC,IAAI,CAClB,IAAuB,EACvB,IAAY,EACZ,EAAU,EACV,QAAkC;QAElC,MAAM,IAAI,GAAc,EAAE,EAAE,EAAE,GAAG,IAAI,IAAI,IAAI,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;QACzE,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC5B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QAC1B,CAAC;QACD,OAAO,IAAI,CAAC;IACb,CAAC;CACD"}
1
+ {"version":3,"file":"structural_extractor.js","sourceRoot":"","sources":["../../src/extract/structural_extractor.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,7 @@
1
+ /**
2
+ * Absolute path to the package root. This module sits at the top of `src`
3
+ * (and of the built `dist`), so a single `..` hop reaches the package root
4
+ * whether running via tsx from `src` or from the compiled `dist` output.
5
+ */
6
+ export declare const PROJECT_ROOT: string;
7
+ //# sourceMappingURL=project_root.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"project_root.d.ts","sourceRoot":"","sources":["../src/project_root.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,eAAO,MAAM,YAAY,QAAyD,CAAC"}
@@ -0,0 +1,9 @@
1
+ import { dirname, resolve } from 'node:path';
2
+ import { fileURLToPath } from 'node:url';
3
+ /**
4
+ * Absolute path to the package root. This module sits at the top of `src`
5
+ * (and of the built `dist`), so a single `..` hop reaches the package root
6
+ * whether running via tsx from `src` or from the compiled `dist` output.
7
+ */
8
+ export const PROJECT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
9
+ //# sourceMappingURL=project_root.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"project_root.js","sourceRoot":"","sources":["../src/project_root.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC"}
@@ -5,11 +5,138 @@ export type SymbolRef = {
5
5
  name: string;
6
6
  filePath: string;
7
7
  startLine: number;
8
+ metadata: Record<string, unknown>;
8
9
  };
9
10
  export type NeighborRef = SymbolRef & {
10
11
  edgeKind: string;
12
+ edgeMetadata: Record<string, unknown>;
11
13
  direction: 'in' | 'out';
12
14
  };
15
+ /**
16
+ * The metric a {@link GraphQuery.hotspots} ranking is computed against.
17
+ *
18
+ * - `self-time` / `samples` — measured runtime from `metadata.runtime`, present
19
+ * only after `enrich`.
20
+ * - `callers` — inbound `CALLS` edge count (static fan-in / centrality).
21
+ * - `call-count` — sum of inbound `CALLS` edge `metadata.count` (how often a
22
+ * symbol is actually invoked across all call sites in source).
23
+ * - `blast-radius` — transitive inbound `CALLS` size (change-risk / centrality).
24
+ */
25
+ export type HotspotMetric = 'self-time' | 'samples' | 'callers' | 'call-count' | 'blast-radius';
26
+ /** A ranked node, carrying the score it earned and the metric it was scored by. */
27
+ export type HotspotRef = SymbolRef & {
28
+ score: number;
29
+ metric: HotspotMetric;
30
+ };
31
+ export type HotspotOptions = {
32
+ /** Metric to rank by. Defaults to `self-time` when the graph is enriched, `callers` otherwise. */
33
+ by?: HotspotMetric;
34
+ /** Maximum number of hotspots to return. Defaults to 20, clamped to [1, 1000]. */
35
+ limit?: number;
36
+ /** Restrict ranking to nodes that carry `metadata.runtime`. */
37
+ measuredOnly?: boolean;
38
+ };
39
+ /**
40
+ * The result of a hotspot ranking: the top-N nodes plus the context needed to
41
+ * interpret them — the metric actually used, what was requested, and whether a
42
+ * runtime metric fell back to a static one because the graph is un-enriched.
43
+ */
44
+ export type HotspotReport = {
45
+ /** The metric actually used to rank (differs from `requested` only after a fallback). */
46
+ metric: HotspotMetric;
47
+ /** The metric the caller asked for, or the resolved default when none was given. */
48
+ requested: HotspotMetric;
49
+ /** Whether any node in the graph carries `metadata.runtime`. */
50
+ enriched: boolean;
51
+ /** True when a runtime metric was requested on an un-enriched graph, so `metric` fell back to `callers`. */
52
+ fellBack: boolean;
53
+ /** Whether ranking was restricted to measured nodes. */
54
+ measuredOnly: boolean;
55
+ /** Top-N nodes by `metric`, descending, each carrying its `score`. */
56
+ hotspots: HotspotRef[];
57
+ };
58
+ /**
59
+ * The measured weight {@link GraphQuery.costRanking} and
60
+ * {@link GraphQuery.costAttribution} propagate along `CALLS` edges. Both read
61
+ * `metadata.runtime`, present only after `enrich`:
62
+ * - `self-time` — `metadata.runtime.selfMs`.
63
+ * - `samples` — `metadata.runtime.samples`.
64
+ */
65
+ export type CostMetric = 'self-time' | 'samples';
66
+ /**
67
+ * A node carrying its propagated cost. `selfCost` is the measured *exclusive*
68
+ * cost (time in the node itself); `inclusiveCost` adds the cost attributed from
69
+ * everything it transitively calls; `shareOfTotal` is `inclusiveCost` as a
70
+ * fraction of the graph's total self cost — the "responsible for X% of total"
71
+ * number. `cyclic`/`cycleSize` flag membership in a call cycle, whose members
72
+ * share the cycle's total inclusive cost.
73
+ */
74
+ export type CostRef = SymbolRef & {
75
+ selfCost: number;
76
+ inclusiveCost: number;
77
+ shareOfTotal: number;
78
+ cyclic: boolean;
79
+ cycleSize: number;
80
+ };
81
+ export type CostOptions = {
82
+ /** Metric to propagate. Defaults to `self-time`. */
83
+ by?: CostMetric;
84
+ /** Maximum number of ranked nodes to return. Defaults to 20, clamped to [1, 1000]. */
85
+ limit?: number;
86
+ };
87
+ /**
88
+ * A ranking of nodes by inclusive cost, with the context needed to read it: the
89
+ * metric propagated, whether the graph is enriched at all, and the total self
90
+ * cost that `shareOfTotal` is a fraction of.
91
+ */
92
+ export type CostReport = {
93
+ /** The metric propagated. */
94
+ metric: CostMetric;
95
+ /** Whether any node in the graph carries `metadata.runtime`. */
96
+ enriched: boolean;
97
+ /** Σ self cost over every node — the denominator behind `shareOfTotal`. */
98
+ totalSelf: number;
99
+ /** Count of nodes that carry runtime metrics. */
100
+ measuredNodes: number;
101
+ /**
102
+ * Fraction of the profiled cost (in `metric`) that the join attributed to graph
103
+ * nodes, from the `enrich` manifest — the share of total measured cost this
104
+ * attribution actually accounts for. `null` when the graph carries no manifest
105
+ * (never enriched, or enriched before manifests were recorded).
106
+ */
107
+ coverage: number | null;
108
+ /** Nodes by `inclusiveCost`, descending, top-N, zero-cost nodes omitted. */
109
+ nodes: CostRef[];
110
+ };
111
+ /**
112
+ * One edge of a {@link CostAttribution}: a caller or callee of the focal node,
113
+ * carrying the cost attributed across that edge and its share of the focal
114
+ * node's inclusive cost.
115
+ */
116
+ export type CostFlow = SymbolRef & {
117
+ /** Cost attributed along this edge, in the report's metric. */
118
+ amount: number;
119
+ /** `amount` as a fraction of the focal node's inclusive cost, in [0, 1]. */
120
+ share: number;
121
+ /** The `CALLS` edge's call-site count — the propagation weight. */
122
+ callCount: number;
123
+ };
124
+ /**
125
+ * A per-node causal breakdown. `callees` is where the focal node's inclusive
126
+ * cost goes (the cost each callee's subtree contributes); `callers` is who is
127
+ * responsible for the focal node's cost (how it is attributed upward). `node` is
128
+ * null when the id resolves to no graph node.
129
+ */
130
+ export type CostAttribution = {
131
+ metric: CostMetric;
132
+ enriched: boolean;
133
+ totalSelf: number;
134
+ /** Fraction of profiled cost attributed to graph nodes, or `null` without a manifest (see {@link CostReport.coverage}). */
135
+ coverage: number | null;
136
+ node: CostRef | null;
137
+ callees: CostFlow[];
138
+ callers: CostFlow[];
139
+ };
13
140
  export declare class GraphQuery {
14
141
  private readonly store;
15
142
  constructor(store: KuzuStore);
@@ -19,10 +146,117 @@ export declare class GraphQuery {
19
146
  deadExports(): Promise<SymbolRef[]>;
20
147
  references(id: string): Promise<NeighborRef[]>;
21
148
  neighborhood(id: string): Promise<NeighborRef[]>;
149
+ /**
150
+ * Resolves a search pattern to nodes, matching either a substring of the node
151
+ * name or an exact (case-insensitive) node kind. The kind match makes the
152
+ * system-level kinds discoverable as a set — `find Endpoint`, `find ConfigFlag`,
153
+ * `find ExternalAPI` — since their names are values (a route path, a host) rather
154
+ * than the kind itself. `Module` nodes are always excluded.
155
+ */
22
156
  find(pattern: string): Promise<SymbolRef[]>;
157
+ /**
158
+ * Ranks nodes by optimization leverage, returning the top-N for a chosen
159
+ * metric alongside the context needed to read the result.
160
+ *
161
+ * Runtime metrics (`self-time`, `samples`) read `metadata.runtime`; static
162
+ * metrics (`callers`, `call-count`, `blast-radius`) are derived from the
163
+ * inbound `CALLS` graph. The whole graph is read once (nodes, and the call
164
+ * edges when a static metric is used) and ranked in memory rather than per
165
+ * node, so `blast-radius` does not fan out into one traversal per node.
166
+ *
167
+ * The default metric is `self-time` on an enriched graph and `callers`
168
+ * otherwise. Asking for a runtime metric on an un-enriched graph does not
169
+ * return empty: it falls back to `callers` and flags `fellBack` so the caller
170
+ * can say so. Nodes that score zero on the chosen metric are omitted — a
171
+ * symbol nothing calls is not a fan-in hotspot.
172
+ */
173
+ hotspots(options?: HotspotOptions): Promise<HotspotReport>;
174
+ /**
175
+ * Ranks nodes by **inclusive cost** — self cost plus the cost attributed from
176
+ * everything a node transitively calls — and reports each node's share of the
177
+ * graph's total self cost. This is the causal counterpart to {@link hotspots}'
178
+ * `self-time` ranking: where hotspots asks "where is time spent?", this asks
179
+ * "who is *responsible* for the time spent?".
180
+ *
181
+ * Cost propagates along `CALLS` edges, each callee's inclusive cost partitioned
182
+ * among its callers in proportion to call-site `count`, so cost is conserved (a
183
+ * diamond is not double-counted) and `shareOfTotal` is a true fraction. Call
184
+ * cycles are collapsed and their members share the cycle's total. The whole
185
+ * graph is read once and propagated in memory.
186
+ *
187
+ * Cost is inherently a runtime quantity: on an un-enriched graph there is no
188
+ * self cost to propagate, so `nodes` is empty and `enriched` is false — there is
189
+ * no static fallback (unlike {@link hotspots}).
190
+ */
191
+ costRanking(options?: CostOptions): Promise<CostReport>;
192
+ /**
193
+ * Breaks one node's cost down causally: where its inclusive cost goes
194
+ * (`callees`, each carrying the cost its subtree contributes) and who is
195
+ * responsible for it (`callers`, how the node's cost is attributed upward by
196
+ * call-count share). Both are derived from the same propagation
197
+ * {@link costRanking} uses. Returns `node: null` when the id resolves to no node.
198
+ */
199
+ costAttribution(id: string, options?: CostOptions): Promise<CostAttribution>;
200
+ /**
201
+ * Reads the runtime ingest manifest `enrich` records at the graph level, or
202
+ * null when the graph carries none (never enriched, or enriched before manifests
203
+ * were recorded). A stored value that fails validation is treated as absent.
204
+ */
205
+ private readRuntimeManifest;
206
+ /** Builds a node-id → score map for the chosen metric, reading call edges only when a static metric needs them. */
207
+ private scoreNodes;
208
+ /** Reads every `CALLS` edge with its call-site `count` decoded from edge metadata. */
209
+ private readCallEdges;
210
+ /** Sums a per-edge weight onto each edge's target, yielding inbound fan-in (`weight = 1`) or call-count (`weight = count`). */
211
+ private static sumInbound;
212
+ /** Computes, for every node, the number of distinct nodes that transitively reach it through inbound `CALLS`. */
213
+ private static blastRadiusSizes;
214
+ /** Counts the distinct ancestors of `start` over the reverse-call adjacency, cycle-safe and excluding `start` itself. */
215
+ private static reachableCount;
216
+ /**
217
+ * Propagates self cost into inclusive cost over the whole graph in one pass.
218
+ *
219
+ * Self-edges and edges touching unknown nodes are dropped. Strongly-connected
220
+ * components (call cycles) are collapsed with Tarjan's algorithm, which numbers
221
+ * them in reverse-topological order (a callee's component before its caller's);
222
+ * processing components in that order lets each caller read its callees'
223
+ * already-computed inclusive cost. A callee's inclusive cost is partitioned
224
+ * among its callers by call-site `count` over the inbound weight from *outside*
225
+ * its component, so cost is conserved on the acyclic part and a cycle's members
226
+ * share the cycle's total.
227
+ */
228
+ private static computeCostModel;
229
+ /**
230
+ * Tarjan's strongly-connected components over the index-based successor lists,
231
+ * iterative so a deep call chain cannot overflow the stack. Components are
232
+ * numbered in the order they are finalized, which is reverse-topological: every
233
+ * cross-component edge runs from a higher-numbered component to a lower one.
234
+ */
235
+ private static stronglyConnectedComponents;
236
+ private static toCostRef;
237
+ private static symbolOf;
238
+ /**
239
+ * The fraction of profiled cost (in `metric`) the join attributed to graph
240
+ * nodes, from the manifest: matched ÷ total. Null when there is no manifest or
241
+ * the profile measured nothing in that metric.
242
+ */
243
+ private static coverageFor;
244
+ private static toHotspot;
245
+ private static isRuntimeMetric;
246
+ /** Reads a numeric metric out of `metadata.runtime`, defaulting to 0 when absent or non-numeric. */
247
+ private static runtimeValue;
248
+ private static hasRuntime;
249
+ /** Decodes an edge's call-site `count`, defaulting to 1 (the minimum the builder records). */
250
+ private static callCount;
251
+ private static clampLimit;
23
252
  private static toRefs;
24
253
  private static toRef;
25
254
  private static toNeighbor;
255
+ /**
256
+ * Decodes the JSON `metadata` column back into a record. A missing, empty, or
257
+ * malformed value decodes to an empty object so callers always receive a record.
258
+ */
259
+ private static parseMetadata;
26
260
  private static clampDepth;
27
261
  }
28
262
  //# sourceMappingURL=graph_query.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"graph_query.d.ts","sourceRoot":"","sources":["../../src/query/graph_query.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAEnD,MAAM,MAAM,SAAS,GAAG;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,IAAI,GAAG,KAAK,CAAC;CACxB,CAAC;AAOF,qBAAa,UAAU;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAY;gBAEtB,KAAK,EAAE,SAAS;IAItB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAW1C,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAWvC,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAW5D,WAAW,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAiBnC,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAW9C,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAiBhD,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAYjD,OAAO,CAAC,MAAM,CAAC,MAAM;IAIrB,OAAO,CAAC,MAAM,CAAC,KAAK;IAUpB,OAAO,CAAC,MAAM,CAAC,UAAU;IAIzB,OAAO,CAAC,MAAM,CAAC,UAAU;CAUzB"}
1
+ {"version":3,"file":"graph_query.d.ts","sourceRoot":"","sources":["../../src/query/graph_query.ts"],"names":[],"mappings":"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"}