@grafema/util 0.3.0-beta

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 (324) hide show
  1. package/LICENSE +190 -0
  2. package/dist/api/GraphAPI.d.ts +87 -0
  3. package/dist/api/GraphAPI.d.ts.map +1 -0
  4. package/dist/api/GraphAPI.js +212 -0
  5. package/dist/api/GraphAPI.js.map +1 -0
  6. package/dist/api/GuaranteeAPI.d.ts +147 -0
  7. package/dist/api/GuaranteeAPI.d.ts.map +1 -0
  8. package/dist/api/GuaranteeAPI.js +290 -0
  9. package/dist/api/GuaranteeAPI.js.map +1 -0
  10. package/dist/config/ConfigLoader.d.ts +214 -0
  11. package/dist/config/ConfigLoader.d.ts.map +1 -0
  12. package/dist/config/ConfigLoader.js +441 -0
  13. package/dist/config/ConfigLoader.js.map +1 -0
  14. package/dist/config/index.d.ts +6 -0
  15. package/dist/config/index.d.ts.map +1 -0
  16. package/dist/config/index.js +5 -0
  17. package/dist/config/index.js.map +1 -0
  18. package/dist/core/CoverageAnalyzer.d.ts +65 -0
  19. package/dist/core/CoverageAnalyzer.d.ts.map +1 -0
  20. package/dist/core/CoverageAnalyzer.js +199 -0
  21. package/dist/core/CoverageAnalyzer.js.map +1 -0
  22. package/dist/core/FileExplainer.d.ts +101 -0
  23. package/dist/core/FileExplainer.d.ts.map +1 -0
  24. package/dist/core/FileExplainer.js +140 -0
  25. package/dist/core/FileExplainer.js.map +1 -0
  26. package/dist/core/FileOverview.d.ts +124 -0
  27. package/dist/core/FileOverview.d.ts.map +1 -0
  28. package/dist/core/FileOverview.js +279 -0
  29. package/dist/core/FileOverview.js.map +1 -0
  30. package/dist/core/GrafemaUri.d.ts +66 -0
  31. package/dist/core/GrafemaUri.d.ts.map +1 -0
  32. package/dist/core/GrafemaUri.js +191 -0
  33. package/dist/core/GrafemaUri.js.map +1 -0
  34. package/dist/core/GraphBackend.d.ts +158 -0
  35. package/dist/core/GraphBackend.d.ts.map +1 -0
  36. package/dist/core/GraphBackend.js +85 -0
  37. package/dist/core/GraphBackend.js.map +1 -0
  38. package/dist/core/GraphFreshnessChecker.d.ts +33 -0
  39. package/dist/core/GraphFreshnessChecker.d.ts.map +1 -0
  40. package/dist/core/GraphFreshnessChecker.js +104 -0
  41. package/dist/core/GraphFreshnessChecker.js.map +1 -0
  42. package/dist/core/GuaranteeManager.d.ts +254 -0
  43. package/dist/core/GuaranteeManager.d.ts.map +1 -0
  44. package/dist/core/GuaranteeManager.js +447 -0
  45. package/dist/core/GuaranteeManager.js.map +1 -0
  46. package/dist/core/HashUtils.d.ts +24 -0
  47. package/dist/core/HashUtils.d.ts.map +1 -0
  48. package/dist/core/HashUtils.js +46 -0
  49. package/dist/core/HashUtils.js.map +1 -0
  50. package/dist/core/IncrementalReanalyzer.d.ts +33 -0
  51. package/dist/core/IncrementalReanalyzer.d.ts.map +1 -0
  52. package/dist/core/IncrementalReanalyzer.js +67 -0
  53. package/dist/core/IncrementalReanalyzer.js.map +1 -0
  54. package/dist/core/ResourceRegistry.d.ts +17 -0
  55. package/dist/core/ResourceRegistry.d.ts.map +1 -0
  56. package/dist/core/ResourceRegistry.js +32 -0
  57. package/dist/core/ResourceRegistry.js.map +1 -0
  58. package/dist/core/SemanticId.d.ts +159 -0
  59. package/dist/core/SemanticId.d.ts.map +1 -0
  60. package/dist/core/SemanticId.js +291 -0
  61. package/dist/core/SemanticId.js.map +1 -0
  62. package/dist/core/VersionManager.d.ts +166 -0
  63. package/dist/core/VersionManager.d.ts.map +1 -0
  64. package/dist/core/VersionManager.js +239 -0
  65. package/dist/core/VersionManager.js.map +1 -0
  66. package/dist/core/brandNodeInternal.d.ts +14 -0
  67. package/dist/core/brandNodeInternal.d.ts.map +1 -0
  68. package/dist/core/brandNodeInternal.js +4 -0
  69. package/dist/core/brandNodeInternal.js.map +1 -0
  70. package/dist/core/nodes/GuaranteeNode.d.ts +76 -0
  71. package/dist/core/nodes/GuaranteeNode.d.ts.map +1 -0
  72. package/dist/core/nodes/GuaranteeNode.js +118 -0
  73. package/dist/core/nodes/GuaranteeNode.js.map +1 -0
  74. package/dist/core/nodes/IssueNode.d.ts +73 -0
  75. package/dist/core/nodes/IssueNode.d.ts.map +1 -0
  76. package/dist/core/nodes/IssueNode.js +130 -0
  77. package/dist/core/nodes/IssueNode.js.map +1 -0
  78. package/dist/core/nodes/NodeKind.d.ts +104 -0
  79. package/dist/core/nodes/NodeKind.d.ts.map +1 -0
  80. package/dist/core/nodes/NodeKind.js +166 -0
  81. package/dist/core/nodes/NodeKind.js.map +1 -0
  82. package/dist/diagnostics/DiagnosticCollector.d.ts +103 -0
  83. package/dist/diagnostics/DiagnosticCollector.d.ts.map +1 -0
  84. package/dist/diagnostics/DiagnosticCollector.js +133 -0
  85. package/dist/diagnostics/DiagnosticCollector.js.map +1 -0
  86. package/dist/diagnostics/DiagnosticReporter.d.ts +122 -0
  87. package/dist/diagnostics/DiagnosticReporter.d.ts.map +1 -0
  88. package/dist/diagnostics/DiagnosticReporter.js +300 -0
  89. package/dist/diagnostics/DiagnosticReporter.js.map +1 -0
  90. package/dist/diagnostics/DiagnosticWriter.d.ts +31 -0
  91. package/dist/diagnostics/DiagnosticWriter.d.ts.map +1 -0
  92. package/dist/diagnostics/DiagnosticWriter.js +44 -0
  93. package/dist/diagnostics/DiagnosticWriter.js.map +1 -0
  94. package/dist/diagnostics/categories.d.ts +57 -0
  95. package/dist/diagnostics/categories.d.ts.map +1 -0
  96. package/dist/diagnostics/categories.js +71 -0
  97. package/dist/diagnostics/categories.js.map +1 -0
  98. package/dist/diagnostics/index.d.ts +17 -0
  99. package/dist/diagnostics/index.d.ts.map +1 -0
  100. package/dist/diagnostics/index.js +15 -0
  101. package/dist/diagnostics/index.js.map +1 -0
  102. package/dist/errors/GrafemaError.d.ts +200 -0
  103. package/dist/errors/GrafemaError.d.ts.map +1 -0
  104. package/dist/errors/GrafemaError.js +209 -0
  105. package/dist/errors/GrafemaError.js.map +1 -0
  106. package/dist/index.d.ts +75 -0
  107. package/dist/index.d.ts.map +1 -0
  108. package/dist/index.js +76 -0
  109. package/dist/index.js.map +1 -0
  110. package/dist/instructions/index.d.ts +8 -0
  111. package/dist/instructions/index.d.ts.map +1 -0
  112. package/dist/instructions/index.js +20 -0
  113. package/dist/instructions/index.js.map +1 -0
  114. package/dist/instructions/onboarding.md +133 -0
  115. package/dist/knowledge/KnowledgeBase.d.ts +113 -0
  116. package/dist/knowledge/KnowledgeBase.d.ts.map +1 -0
  117. package/dist/knowledge/KnowledgeBase.js +420 -0
  118. package/dist/knowledge/KnowledgeBase.js.map +1 -0
  119. package/dist/knowledge/SemanticAddressResolver.d.ts +59 -0
  120. package/dist/knowledge/SemanticAddressResolver.d.ts.map +1 -0
  121. package/dist/knowledge/SemanticAddressResolver.js +160 -0
  122. package/dist/knowledge/SemanticAddressResolver.js.map +1 -0
  123. package/dist/knowledge/git-ingest.d.ts +58 -0
  124. package/dist/knowledge/git-ingest.d.ts.map +1 -0
  125. package/dist/knowledge/git-ingest.js +301 -0
  126. package/dist/knowledge/git-ingest.js.map +1 -0
  127. package/dist/knowledge/git-queries.d.ts +86 -0
  128. package/dist/knowledge/git-queries.d.ts.map +1 -0
  129. package/dist/knowledge/git-queries.js +177 -0
  130. package/dist/knowledge/git-queries.js.map +1 -0
  131. package/dist/knowledge/index.d.ts +14 -0
  132. package/dist/knowledge/index.d.ts.map +1 -0
  133. package/dist/knowledge/index.js +10 -0
  134. package/dist/knowledge/index.js.map +1 -0
  135. package/dist/knowledge/parser.d.ts +39 -0
  136. package/dist/knowledge/parser.d.ts.map +1 -0
  137. package/dist/knowledge/parser.js +292 -0
  138. package/dist/knowledge/parser.js.map +1 -0
  139. package/dist/knowledge/types.d.ts +133 -0
  140. package/dist/knowledge/types.d.ts.map +1 -0
  141. package/dist/knowledge/types.js +8 -0
  142. package/dist/knowledge/types.js.map +1 -0
  143. package/dist/logging/Logger.d.ts +98 -0
  144. package/dist/logging/Logger.d.ts.map +1 -0
  145. package/dist/logging/Logger.js +274 -0
  146. package/dist/logging/Logger.js.map +1 -0
  147. package/dist/notation/archetypes.d.ts +36 -0
  148. package/dist/notation/archetypes.d.ts.map +1 -0
  149. package/dist/notation/archetypes.js +173 -0
  150. package/dist/notation/archetypes.js.map +1 -0
  151. package/dist/notation/fold.d.ts +25 -0
  152. package/dist/notation/fold.d.ts.map +1 -0
  153. package/dist/notation/fold.js +598 -0
  154. package/dist/notation/fold.js.map +1 -0
  155. package/dist/notation/index.d.ts +18 -0
  156. package/dist/notation/index.d.ts.map +1 -0
  157. package/dist/notation/index.js +16 -0
  158. package/dist/notation/index.js.map +1 -0
  159. package/dist/notation/lodExtractor.d.ts +32 -0
  160. package/dist/notation/lodExtractor.d.ts.map +1 -0
  161. package/dist/notation/lodExtractor.js +149 -0
  162. package/dist/notation/lodExtractor.js.map +1 -0
  163. package/dist/notation/nameShortener.d.ts +22 -0
  164. package/dist/notation/nameShortener.d.ts.map +1 -0
  165. package/dist/notation/nameShortener.js +24 -0
  166. package/dist/notation/nameShortener.js.map +1 -0
  167. package/dist/notation/perspectives.d.ts +11 -0
  168. package/dist/notation/perspectives.d.ts.map +1 -0
  169. package/dist/notation/perspectives.js +16 -0
  170. package/dist/notation/perspectives.js.map +1 -0
  171. package/dist/notation/renderer.d.ts +31 -0
  172. package/dist/notation/renderer.d.ts.map +1 -0
  173. package/dist/notation/renderer.js +315 -0
  174. package/dist/notation/renderer.js.map +1 -0
  175. package/dist/notation/traceRenderer.d.ts +39 -0
  176. package/dist/notation/traceRenderer.d.ts.map +1 -0
  177. package/dist/notation/traceRenderer.js +358 -0
  178. package/dist/notation/traceRenderer.js.map +1 -0
  179. package/dist/notation/types.d.ts +66 -0
  180. package/dist/notation/types.d.ts.map +1 -0
  181. package/dist/notation/types.js +10 -0
  182. package/dist/notation/types.js.map +1 -0
  183. package/dist/queries/NodeContext.d.ts +81 -0
  184. package/dist/queries/NodeContext.d.ts.map +1 -0
  185. package/dist/queries/NodeContext.js +196 -0
  186. package/dist/queries/NodeContext.js.map +1 -0
  187. package/dist/queries/findCallsInFunction.d.ts +62 -0
  188. package/dist/queries/findCallsInFunction.d.ts.map +1 -0
  189. package/dist/queries/findCallsInFunction.js +169 -0
  190. package/dist/queries/findCallsInFunction.js.map +1 -0
  191. package/dist/queries/findContainingFunction.d.ts +57 -0
  192. package/dist/queries/findContainingFunction.d.ts.map +1 -0
  193. package/dist/queries/findContainingFunction.js +91 -0
  194. package/dist/queries/findContainingFunction.js.map +1 -0
  195. package/dist/queries/index.d.ts +18 -0
  196. package/dist/queries/index.d.ts.map +1 -0
  197. package/dist/queries/index.js +14 -0
  198. package/dist/queries/index.js.map +1 -0
  199. package/dist/queries/traceDataflow.d.ts +65 -0
  200. package/dist/queries/traceDataflow.d.ts.map +1 -0
  201. package/dist/queries/traceDataflow.js +754 -0
  202. package/dist/queries/traceDataflow.js.map +1 -0
  203. package/dist/queries/traceValues.d.ts +70 -0
  204. package/dist/queries/traceValues.d.ts.map +1 -0
  205. package/dist/queries/traceValues.js +373 -0
  206. package/dist/queries/traceValues.js.map +1 -0
  207. package/dist/queries/types.d.ts +166 -0
  208. package/dist/queries/types.d.ts.map +1 -0
  209. package/dist/queries/types.js +10 -0
  210. package/dist/queries/types.js.map +1 -0
  211. package/dist/schema/GraphSchemaExtractor.d.ts +53 -0
  212. package/dist/schema/GraphSchemaExtractor.d.ts.map +1 -0
  213. package/dist/schema/GraphSchemaExtractor.js +125 -0
  214. package/dist/schema/GraphSchemaExtractor.js.map +1 -0
  215. package/dist/schema/InterfaceSchemaExtractor.d.ts +73 -0
  216. package/dist/schema/InterfaceSchemaExtractor.d.ts.map +1 -0
  217. package/dist/schema/InterfaceSchemaExtractor.js +113 -0
  218. package/dist/schema/InterfaceSchemaExtractor.js.map +1 -0
  219. package/dist/schema/index.d.ts +5 -0
  220. package/dist/schema/index.d.ts.map +1 -0
  221. package/dist/schema/index.js +3 -0
  222. package/dist/schema/index.js.map +1 -0
  223. package/dist/storage/backends/RFDBServerBackend.d.ts +356 -0
  224. package/dist/storage/backends/RFDBServerBackend.d.ts.map +1 -0
  225. package/dist/storage/backends/RFDBServerBackend.js +748 -0
  226. package/dist/storage/backends/RFDBServerBackend.js.map +1 -0
  227. package/dist/storage/backends/typeValidation.d.ts +47 -0
  228. package/dist/storage/backends/typeValidation.d.ts.map +1 -0
  229. package/dist/storage/backends/typeValidation.js +141 -0
  230. package/dist/storage/backends/typeValidation.js.map +1 -0
  231. package/dist/utils/findRfdbBinary.d.ts +67 -0
  232. package/dist/utils/findRfdbBinary.d.ts.map +1 -0
  233. package/dist/utils/findRfdbBinary.js +261 -0
  234. package/dist/utils/findRfdbBinary.js.map +1 -0
  235. package/dist/utils/lazyDownload.d.ts +43 -0
  236. package/dist/utils/lazyDownload.d.ts.map +1 -0
  237. package/dist/utils/lazyDownload.js +175 -0
  238. package/dist/utils/lazyDownload.js.map +1 -0
  239. package/dist/utils/moduleResolution.d.ts +134 -0
  240. package/dist/utils/moduleResolution.d.ts.map +1 -0
  241. package/dist/utils/moduleResolution.js +189 -0
  242. package/dist/utils/moduleResolution.js.map +1 -0
  243. package/dist/utils/resolveNodeFile.d.ts +13 -0
  244. package/dist/utils/resolveNodeFile.d.ts.map +1 -0
  245. package/dist/utils/resolveNodeFile.js +18 -0
  246. package/dist/utils/resolveNodeFile.js.map +1 -0
  247. package/dist/utils/startRfdbServer.d.ts +63 -0
  248. package/dist/utils/startRfdbServer.d.ts.map +1 -0
  249. package/dist/utils/startRfdbServer.js +142 -0
  250. package/dist/utils/startRfdbServer.js.map +1 -0
  251. package/dist/validation/PathValidator.d.ts +80 -0
  252. package/dist/validation/PathValidator.d.ts.map +1 -0
  253. package/dist/validation/PathValidator.js +252 -0
  254. package/dist/validation/PathValidator.js.map +1 -0
  255. package/dist/version.d.ts +11 -0
  256. package/dist/version.d.ts.map +1 -0
  257. package/dist/version.js +26 -0
  258. package/dist/version.js.map +1 -0
  259. package/package.json +50 -0
  260. package/src/api/GraphAPI.ts +307 -0
  261. package/src/api/GuaranteeAPI.ts +402 -0
  262. package/src/config/ConfigLoader.ts +653 -0
  263. package/src/config/index.ts +13 -0
  264. package/src/core/CoverageAnalyzer.ts +243 -0
  265. package/src/core/FileExplainer.ts +179 -0
  266. package/src/core/FileOverview.ts +397 -0
  267. package/src/core/GrafemaUri.ts +216 -0
  268. package/src/core/GraphBackend.ts +266 -0
  269. package/src/core/GraphFreshnessChecker.ts +145 -0
  270. package/src/core/GuaranteeManager.ts +684 -0
  271. package/src/core/HashUtils.ts +48 -0
  272. package/src/core/IncrementalReanalyzer.ts +106 -0
  273. package/src/core/ResourceRegistry.ts +39 -0
  274. package/src/core/SemanticId.ts +423 -0
  275. package/src/core/VersionManager.ts +405 -0
  276. package/src/core/brandNodeInternal.ts +16 -0
  277. package/src/core/nodes/GuaranteeNode.ts +162 -0
  278. package/src/core/nodes/IssueNode.ts +177 -0
  279. package/src/core/nodes/NodeKind.ts +192 -0
  280. package/src/diagnostics/DiagnosticCollector.ts +170 -0
  281. package/src/diagnostics/DiagnosticReporter.ts +395 -0
  282. package/src/diagnostics/DiagnosticWriter.ts +50 -0
  283. package/src/diagnostics/categories.ts +104 -0
  284. package/src/diagnostics/index.ts +30 -0
  285. package/src/errors/GrafemaError.ts +297 -0
  286. package/src/index.ts +261 -0
  287. package/src/instructions/index.ts +21 -0
  288. package/src/instructions/onboarding.md +133 -0
  289. package/src/knowledge/KnowledgeBase.ts +486 -0
  290. package/src/knowledge/SemanticAddressResolver.ts +191 -0
  291. package/src/knowledge/git-ingest.ts +402 -0
  292. package/src/knowledge/git-queries.ts +269 -0
  293. package/src/knowledge/index.ts +29 -0
  294. package/src/knowledge/parser.ts +294 -0
  295. package/src/knowledge/types.ts +146 -0
  296. package/src/logging/Logger.ts +303 -0
  297. package/src/notation/archetypes.ts +189 -0
  298. package/src/notation/fold.ts +696 -0
  299. package/src/notation/index.ts +27 -0
  300. package/src/notation/lodExtractor.ts +177 -0
  301. package/src/notation/nameShortener.ts +24 -0
  302. package/src/notation/perspectives.ts +18 -0
  303. package/src/notation/renderer.ts +394 -0
  304. package/src/notation/traceRenderer.ts +458 -0
  305. package/src/notation/types.ts +79 -0
  306. package/src/queries/NodeContext.ts +280 -0
  307. package/src/queries/findCallsInFunction.ts +249 -0
  308. package/src/queries/findContainingFunction.ts +124 -0
  309. package/src/queries/index.ts +44 -0
  310. package/src/queries/traceDataflow.ts +838 -0
  311. package/src/queries/traceValues.ts +531 -0
  312. package/src/queries/types.ts +191 -0
  313. package/src/schema/GraphSchemaExtractor.ts +177 -0
  314. package/src/schema/InterfaceSchemaExtractor.ts +173 -0
  315. package/src/schema/index.ts +5 -0
  316. package/src/storage/backends/RFDBServerBackend.ts +895 -0
  317. package/src/storage/backends/typeValidation.ts +154 -0
  318. package/src/utils/findRfdbBinary.ts +288 -0
  319. package/src/utils/lazyDownload.ts +206 -0
  320. package/src/utils/moduleResolution.ts +271 -0
  321. package/src/utils/resolveNodeFile.ts +18 -0
  322. package/src/utils/startRfdbServer.ts +197 -0
  323. package/src/validation/PathValidator.ts +334 -0
  324. package/src/version.ts +28 -0
@@ -0,0 +1,75 @@
1
+ /**
2
+ * @grafema/util - Query, config, and guarantee utilities for Grafema
3
+ *
4
+ * This package contains the live query layer, configuration, diagnostics,
5
+ * and guarantee management. Analysis is handled by grafema-orchestrator (Rust).
6
+ */
7
+ export { GrafemaError, ConfigError, FileAccessError, LanguageError, DatabaseError, PluginError, AnalysisError, ValidationError, StrictModeError, StrictModeFailure, } from './errors/GrafemaError.js';
8
+ export type { ErrorContext, GrafemaErrorJSON, ResolutionStep, ResolutionFailureReason, } from './errors/GrafemaError.js';
9
+ export { ConsoleLogger, FileLogger, MultiLogger, createLogger } from './logging/Logger.js';
10
+ export type { Logger, LogLevel } from './logging/Logger.js';
11
+ export { DiagnosticCollector, DiagnosticReporter, DiagnosticWriter } from './diagnostics/index.js';
12
+ export type { Diagnostic, DiagnosticInput, ReportOptions, SummaryStats } from './diagnostics/index.js';
13
+ export { DIAGNOSTIC_CATEGORIES, CODE_TO_CATEGORY, getCategoryForCode, getCodesForCategory } from './diagnostics/index.js';
14
+ export type { DiagnosticCategory, DiagnosticCategoryKey, CodeCategoryInfo } from './diagnostics/index.js';
15
+ export { loadConfig, DEFAULT_CONFIG, validateVersion, validateServices, validatePatterns, validateWorkspace, validateRouting, } from './config/index.js';
16
+ export type { GrafemaConfig } from './config/index.js';
17
+ export { GRAFEMA_VERSION, getSchemaVersion } from './version.js';
18
+ export { getOnboardingInstruction } from './instructions/index.js';
19
+ export { GraphBackend, typeToKind, edgeTypeToNumber } from './core/GraphBackend.js';
20
+ export type { Node, Edge, EdgeType, AttrQuery, GraphStats, GraphExport } from './core/GraphBackend.js';
21
+ export { RFDBClient } from '@grafema/rfdb-client';
22
+ export { RFDBServerBackend } from './storage/backends/RFDBServerBackend.js';
23
+ export { computeSemanticId, parseSemanticId, computeDiscriminator, computeSemanticIdV2, parseSemanticIdV2, computeContentHash } from './core/SemanticId.js';
24
+ export type { Location, ScopeContext, SemanticIdOptions, ParsedSemanticId, LocatedItem, ParsedSemanticIdV2, ContentHashHints } from './core/SemanticId.js';
25
+ export { isGrafemaUri, encodeFragment, decodeFragment, toGrafemaUri, parseGrafemaUri, toCompactSemanticId, normalizeSemanticId } from './core/GrafemaUri.js';
26
+ export type { ParsedGrafemaUri } from './core/GrafemaUri.js';
27
+ export { GuaranteeManager } from './core/GuaranteeManager.js';
28
+ export type { GuaranteeGraph } from './core/GuaranteeManager.js';
29
+ export { calculateFileHash, calculateFileHashAsync, calculateContentHash } from './core/HashUtils.js';
30
+ export { findBinary, findAnalyzerBinary, findRfdbBinary, findOrchestratorBinary, getBinaryNotFoundMessage, getPlatformDir, getPlatformPackageName } from './utils/findRfdbBinary.js';
31
+ export type { FindBinaryOptions, BinaryName } from './utils/findRfdbBinary.js';
32
+ export { ensureBinary, downloadBinary, isDownloadable, findInGrafemaBin, getGrafemaBinDir } from './utils/lazyDownload.js';
33
+ export { startRfdbServer, checkExistingServer } from './utils/startRfdbServer.js';
34
+ export type { StartRfdbServerOptions } from './utils/startRfdbServer.js';
35
+ export { resolveModulePath, isRelativeImport, resolveRelativeSpecifier, DEFAULT_EXTENSIONS, DEFAULT_INDEX_FILES } from './utils/moduleResolution.js';
36
+ export type { ModuleResolutionOptions } from './utils/moduleResolution.js';
37
+ export { resolveNodeFile } from './utils/resolveNodeFile.js';
38
+ export { levenshtein, checkTypoAgainstKnownTypes, resetKnownNodeTypes, getKnownNodeTypes } from './storage/backends/typeValidation.js';
39
+ export { PathValidator } from './validation/PathValidator.js';
40
+ export type { PathValidationResult, EndpointDiff } from './validation/PathValidator.js';
41
+ export { VersionManager, versionManager } from './core/VersionManager.js';
42
+ export type { VersionedNode, VersionConstants, EnrichOptions, ModifiedNodeInfo, ChangesSummary, ClassifyChangesResult } from './core/VersionManager.js';
43
+ export { GraphFreshnessChecker } from './core/GraphFreshnessChecker.js';
44
+ export type { FreshnessGraph, FreshnessResult, StaleModule } from './core/GraphFreshnessChecker.js';
45
+ export { IncrementalReanalyzer } from './core/IncrementalReanalyzer.js';
46
+ export type { ReanalysisOptions, ReanalysisProgress, ReanalysisResult } from './core/IncrementalReanalyzer.js';
47
+ export { CoverageAnalyzer } from './core/CoverageAnalyzer.js';
48
+ export type { CoverageResult } from './core/CoverageAnalyzer.js';
49
+ export { FileExplainer } from './core/FileExplainer.js';
50
+ export type { FileExplainResult, EnhancedNode } from './core/FileExplainer.js';
51
+ export { FileOverview } from './core/FileOverview.js';
52
+ export type { FileOverviewResult, ImportInfo, ExportInfo, FunctionOverview, ClassOverview, VariableOverview, } from './core/FileOverview.js';
53
+ export { ResourceRegistryImpl } from './core/ResourceRegistry.js';
54
+ export { GraphAPI } from './api/GraphAPI.js';
55
+ export { GuaranteeAPI } from './api/GuaranteeAPI.js';
56
+ export type { GuaranteeGraphBackend } from './api/GuaranteeAPI.js';
57
+ export { isGuaranteeType, isGrafemaType } from './core/nodes/NodeKind.js';
58
+ export { IssueNode, type IssueNodeRecord, type IssueSeverity, type IssueType } from './core/nodes/IssueNode.js';
59
+ export { GuaranteeNode } from './core/nodes/GuaranteeNode.js';
60
+ export type { GuaranteeNodeRecord, GuaranteeNodeOptions, GuaranteePriority, GuaranteeStatus, GuaranteeType, } from './core/nodes/GuaranteeNode.js';
61
+ export { InterfaceSchemaExtractor, GraphSchemaExtractor } from './schema/index.js';
62
+ export type { InterfaceSchema, PropertySchema, ExtractOptions, GraphSchema, NodeTypeSchema, EdgeTypeSchema, GraphExtractOptions, } from './schema/index.js';
63
+ export { KnowledgeBase, SemanticAddressResolver, parseSemanticAddress, parseFrontmatter, parseKBNode, serializeKBNode, parseEdgesFile, appendEdge, parseYamlArrayFile, GitIngest, parseGitLog, normalizeAuthors, getChurn, getCoChanges, getOwnership, getArchaeology } from './knowledge/index.js';
64
+ export type { ResolverBackend } from './knowledge/index.js';
65
+ export type { KBNodeType, KBLifecycle, KBScope, KBNodeBase, KBDecision, KBFact, KBSession, KBNode, KBEdge, KBStats, KBQueryFilter, ParsedSemanticAddress, ResolvedAddress, DanglingCodeRef, } from './knowledge/index.js';
66
+ export type { RawCommit, FileChange, AuthorEntry, CommitEntry, IngestResult, Meta } from './knowledge/index.js';
67
+ export type { ChurnEntry, CoChangeEntry, OwnershipEntry, ArchaeologyEntry } from './knowledge/index.js';
68
+ export { findCallsInFunction, findContainingFunction, traceValues, aggregateValues, NONDETERMINISTIC_PATTERNS, NONDETERMINISTIC_OBJECTS } from './queries/index.js';
69
+ export { traceDataflow, traceForwardBFS, traceBackwardBFS } from './queries/index.js';
70
+ export { buildNodeContext, getNodeDisplayName, formatEdgeMetadata, STRUCTURAL_EDGE_TYPES } from './queries/index.js';
71
+ export type { CallInfo, CallerInfo, FindCallsOptions, TracedValue, ValueSource, UnknownReason, TraceValuesOptions, ValueSetResult, TraceValuesGraphBackend, NondeterministicPattern, EdgeWithNode, EdgeGroup, SourcePreview, NodeContext, BuildNodeContextOptions, DataflowNode, DataflowEdge, DataflowBackend, TraceDataflowOptions, TraceDataflowResult, } from './queries/index.js';
72
+ export { EDGE_ARCHETYPE_MAP, lookupEdge, generateLegend, PERSPECTIVES, renderNotation, extractSubgraph, shortenName, renderTraceNarrative } from './notation/index.js';
73
+ export type { Archetype, EdgeMapping, DescribeOptions, SubgraphData, NotationBlock, NotationLine, TraceDetail, TraceNarrativeOptions, } from './notation/index.js';
74
+ export type * from '@grafema/types';
75
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EACL,YAAY,EACZ,WAAW,EACX,eAAe,EACf,aAAa,EACb,aAAa,EACb,WAAW,EACX,aAAa,EACb,eAAe,EACf,eAAe,EACf,iBAAiB,GAClB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,uBAAuB,GACxB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAC3F,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAG5D,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AACnG,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACvG,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC1H,YAAY,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG1G,OAAO,EACL,UAAU,EACV,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGvD,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGjE,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AAGnE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AACpF,YAAY,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGvG,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yCAAyC,CAAC;AAG5E,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,QAAQ,EACR,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EAChB,WAAW,EACX,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,YAAY,EACZ,cAAc,EACd,cAAc,EACd,YAAY,EACZ,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACpB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAC9D,YAAY,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAGjE,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAGtG,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,cAAc,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACrL,YAAY,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAG/E,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAG3H,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAClF,YAAY,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAGzE,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,wBAAwB,EACxB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,6BAA6B,CAAC;AACrC,YAAY,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAG3E,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAG7D,OAAO,EACL,WAAW,EACX,0BAA0B,EAC1B,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,YAAY,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAGxF,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1E,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,aAAa,EAAE,gBAAgB,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAGxJ,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AACxE,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AACpG,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AACxE,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAG/G,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAC9D,YAAY,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAGjE,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC/E,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,YAAY,EACV,kBAAkB,EAClB,UAAU,EACV,UAAU,EACV,gBAAgB,EAChB,aAAa,EACb,gBAAgB,GACjB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAGlE,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,YAAY,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAGnE,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAG1E,OAAO,EAAE,SAAS,EAAE,KAAK,eAAe,EAAE,KAAK,aAAa,EAAE,KAAK,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAGhH,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,eAAe,EACf,aAAa,GACd,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACnF,YAAY,EACV,eAAe,EACf,cAAc,EACd,cAAc,EACd,WAAW,EACX,cAAc,EACd,cAAc,EACd,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,aAAa,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,WAAW,EAAE,eAAe,EAAE,cAAc,EAAE,UAAU,EAAE,kBAAkB,EAAE,SAAS,EAAE,WAAW,EAAE,gBAAgB,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACpS,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,YAAY,EACV,UAAU,EACV,WAAW,EACX,OAAO,EACP,UAAU,EACV,UAAU,EACV,MAAM,EACN,SAAS,EACT,MAAM,EACN,MAAM,EACN,OAAO,EACP,aAAa,EACb,qBAAqB,EACrB,eAAe,EACf,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAChH,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAGxG,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,WAAW,EAAE,eAAe,EAAE,yBAAyB,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AACpK,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtF,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AACrH,YAAY,EACV,QAAQ,EACR,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,uBAAuB,EACvB,uBAAuB,EACvB,YAAY,EACZ,SAAS,EACT,aAAa,EACb,WAAW,EACX,uBAAuB,EACvB,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,kBAAkB,EAAE,UAAU,EAAE,cAAc,EAAE,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AACvK,YAAY,EACV,SAAS,EACT,WAAW,EACX,eAAe,EACf,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,WAAW,EACX,qBAAqB,GACtB,MAAM,qBAAqB,CAAC;AAG7B,mBAAmB,gBAAgB,CAAC"}
package/dist/index.js ADDED
@@ -0,0 +1,76 @@
1
+ /**
2
+ * @grafema/util - Query, config, and guarantee utilities for Grafema
3
+ *
4
+ * This package contains the live query layer, configuration, diagnostics,
5
+ * and guarantee management. Analysis is handled by grafema-orchestrator (Rust).
6
+ */
7
+ // Error types
8
+ export { GrafemaError, ConfigError, FileAccessError, LanguageError, DatabaseError, PluginError, AnalysisError, ValidationError, StrictModeError, StrictModeFailure, } from './errors/GrafemaError.js';
9
+ // Logging
10
+ export { ConsoleLogger, FileLogger, MultiLogger, createLogger } from './logging/Logger.js';
11
+ // Diagnostics
12
+ export { DiagnosticCollector, DiagnosticReporter, DiagnosticWriter } from './diagnostics/index.js';
13
+ export { DIAGNOSTIC_CATEGORIES, CODE_TO_CATEGORY, getCategoryForCode, getCodesForCategory } from './diagnostics/index.js';
14
+ // Config
15
+ export { loadConfig, DEFAULT_CONFIG, validateVersion, validateServices, validatePatterns, validateWorkspace, validateRouting, } from './config/index.js';
16
+ // Version
17
+ export { GRAFEMA_VERSION, getSchemaVersion } from './version.js';
18
+ // Instructions (for AI agents)
19
+ export { getOnboardingInstruction } from './instructions/index.js';
20
+ // Graph backend
21
+ export { GraphBackend, typeToKind, edgeTypeToNumber } from './core/GraphBackend.js';
22
+ // RFDB
23
+ export { RFDBClient } from '@grafema/rfdb-client';
24
+ export { RFDBServerBackend } from './storage/backends/RFDBServerBackend.js';
25
+ // Core utilities
26
+ export { computeSemanticId, parseSemanticId, computeDiscriminator, computeSemanticIdV2, parseSemanticIdV2, computeContentHash } from './core/SemanticId.js';
27
+ // URI format
28
+ export { isGrafemaUri, encodeFragment, decodeFragment, toGrafemaUri, parseGrafemaUri, toCompactSemanticId, normalizeSemanticId } from './core/GrafemaUri.js';
29
+ export { GuaranteeManager } from './core/GuaranteeManager.js';
30
+ // Hash utilities
31
+ export { calculateFileHash, calculateFileHashAsync, calculateContentHash } from './core/HashUtils.js';
32
+ // Binary finder utilities
33
+ export { findBinary, findAnalyzerBinary, findRfdbBinary, findOrchestratorBinary, getBinaryNotFoundMessage, getPlatformDir, getPlatformPackageName } from './utils/findRfdbBinary.js';
34
+ // Lazy download
35
+ export { ensureBinary, downloadBinary, isDownloadable, findInGrafemaBin, getGrafemaBinDir } from './utils/lazyDownload.js';
36
+ // RFDB server lifecycle
37
+ export { startRfdbServer, checkExistingServer } from './utils/startRfdbServer.js';
38
+ // Module resolution utilities
39
+ export { resolveModulePath, isRelativeImport, resolveRelativeSpecifier, DEFAULT_EXTENSIONS, DEFAULT_INDEX_FILES } from './utils/moduleResolution.js';
40
+ // Node file path resolution
41
+ export { resolveNodeFile } from './utils/resolveNodeFile.js';
42
+ // Type validation and path validation
43
+ export { levenshtein, checkTypoAgainstKnownTypes, resetKnownNodeTypes, getKnownNodeTypes } from './storage/backends/typeValidation.js';
44
+ export { PathValidator } from './validation/PathValidator.js';
45
+ // Version management
46
+ export { VersionManager, versionManager } from './core/VersionManager.js';
47
+ // Freshness checking and incremental reanalysis
48
+ export { GraphFreshnessChecker } from './core/GraphFreshnessChecker.js';
49
+ export { IncrementalReanalyzer } from './core/IncrementalReanalyzer.js';
50
+ // Coverage
51
+ export { CoverageAnalyzer } from './core/CoverageAnalyzer.js';
52
+ // File analysis utilities
53
+ export { FileExplainer } from './core/FileExplainer.js';
54
+ export { FileOverview } from './core/FileOverview.js';
55
+ // Resource system
56
+ export { ResourceRegistryImpl } from './core/ResourceRegistry.js';
57
+ // API
58
+ export { GraphAPI } from './api/GraphAPI.js';
59
+ export { GuaranteeAPI } from './api/GuaranteeAPI.js';
60
+ // Node kinds
61
+ export { isGuaranteeType, isGrafemaType } from './core/nodes/NodeKind.js';
62
+ // Issue nodes (detected problems)
63
+ export { IssueNode } from './core/nodes/IssueNode.js';
64
+ // Guarantee nodes (contract-based)
65
+ export { GuaranteeNode } from './core/nodes/GuaranteeNode.js';
66
+ // Schema extraction
67
+ export { InterfaceSchemaExtractor, GraphSchemaExtractor } from './schema/index.js';
68
+ // Knowledge Base
69
+ export { KnowledgeBase, SemanticAddressResolver, parseSemanticAddress, parseFrontmatter, parseKBNode, serializeKBNode, parseEdgesFile, appendEdge, parseYamlArrayFile, GitIngest, parseGitLog, normalizeAuthors, getChurn, getCoChanges, getOwnership, getArchaeology } from './knowledge/index.js';
70
+ // Graph Query Utilities
71
+ export { findCallsInFunction, findContainingFunction, traceValues, aggregateValues, NONDETERMINISTIC_PATTERNS, NONDETERMINISTIC_OBJECTS } from './queries/index.js';
72
+ export { traceDataflow, traceForwardBFS, traceBackwardBFS } from './queries/index.js';
73
+ export { buildNodeContext, getNodeDisplayName, formatEdgeMetadata, STRUCTURAL_EDGE_TYPES } from './queries/index.js';
74
+ // Notation — DSL rendering engine
75
+ export { EDGE_ARCHETYPE_MAP, lookupEdge, generateLegend, PERSPECTIVES, renderNotation, extractSubgraph, shortenName, renderTraceNarrative } from './notation/index.js';
76
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Get the onboarding instruction document.
3
+ *
4
+ * Returns the full markdown text of the onboarding procedure
5
+ * that guides an AI agent through project study and configuration.
6
+ */
7
+ export declare function getOnboardingInstruction(): string;
8
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/instructions/index.ts"],"names":[],"mappings":"AAYA;;;;;GAKG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,CAEjD"}
@@ -0,0 +1,20 @@
1
+ /**
2
+ * Grafema instruction documents for AI agents.
3
+ *
4
+ * Instructions are markdown documents that guide agent behavior.
5
+ * They are read at runtime from the installed package.
6
+ */
7
+ import { readFileSync } from 'fs';
8
+ import { join, dirname } from 'path';
9
+ import { fileURLToPath } from 'url';
10
+ const __dirname = dirname(fileURLToPath(import.meta.url));
11
+ /**
12
+ * Get the onboarding instruction document.
13
+ *
14
+ * Returns the full markdown text of the onboarding procedure
15
+ * that guides an AI agent through project study and configuration.
16
+ */
17
+ export function getOnboardingInstruction() {
18
+ return readFileSync(join(__dirname, 'onboarding.md'), 'utf-8');
19
+ }
20
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/instructions/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAEpC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB;IACtC,OAAO,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,eAAe,CAAC,EAAE,OAAO,CAAC,CAAC;AACjE,CAAC"}
@@ -0,0 +1,133 @@
1
+ # Grafema Project Onboarding
2
+
3
+ ## Goal
4
+ Study the target project and create a `.grafema/config.yaml` that correctly
5
+ describes its services, entry points, and analysis configuration.
6
+
7
+ ## Prerequisites
8
+ - The project directory exists and contains source code
9
+ - Node.js 18+ installed
10
+ - Run `grafema init` to create `.grafema/` directory if it doesn't exist
11
+
12
+ ## Step 1: Initial Reconnaissance
13
+
14
+ Use `read_project_structure` to get the directory tree.
15
+
16
+ Look for:
17
+ - `package.json` in root and subdirectories (indicates JS/TS packages)
18
+ - `pnpm-workspace.yaml`, `lerna.json`, root `package.json` with `workspaces`
19
+ field (workspace/monorepo indicators)
20
+ - `tsconfig.json` files (TypeScript project)
21
+ - `Dockerfile`, `docker-compose.yml`, `k8s/`, `apps.json` (deployment configs
22
+ that may reveal service boundaries)
23
+ - Directories named `apps/`, `packages/`, `services/`, `pkg/`, `modules/`
24
+ (common monorepo structures)
25
+
26
+ ## Step 2: Identify Services
27
+
28
+ A "service" in Grafema is an independently analyzable unit of code with its
29
+ own entry point. Typically:
30
+ - A standalone application (API server, web app, CLI tool)
31
+ - A package in a monorepo that other packages depend on
32
+ - A microservice in a deployment configuration
33
+
34
+ For each potential service, determine:
35
+ 1. **Name** — human-readable identifier (e.g., "backend", "dashboard")
36
+ 2. **Path** — directory path relative to project root
37
+ 3. **Entry point** — the main source file (prefer TypeScript source over
38
+ compiled output)
39
+
40
+ ### How to find entry points
41
+ Check in order:
42
+ 1. `package.json` "source" field (TypeScript source entry)
43
+ 2. `package.json` "main" field, but look for `.ts` equivalent in `src/`
44
+ 3. Common patterns: `src/index.ts`, `src/main.ts`, `src/app.ts`,
45
+ `src/server.ts`, `index.ts`
46
+ 4. For React apps: `src/App.tsx`, `src/index.tsx`
47
+ 5. Check `bin` field in package.json for CLI tools
48
+
49
+ ### When to ask the user
50
+ - "I found [X] that looks like [description]. Should I include it as a
51
+ service?"
52
+ - "This directory has multiple potential entry points: [list].
53
+ Which should I use?"
54
+ - "I found deployment configuration mentioning services not visible in
55
+ the code structure. Should I investigate?"
56
+
57
+ ## Step 3: Run Auto-Discovery (Optional)
58
+
59
+ Use `discover_services` to see what Grafema's built-in detection finds.
60
+ Compare with your own findings from Steps 1-2. Note discrepancies —
61
+ auto-discovery may miss services or misidentify entry points.
62
+
63
+ ## Step 4: Configure File Patterns
64
+
65
+ The Rust orchestrator has a built-in analysis pipeline — no plugin
66
+ configuration needed. Focus on:
67
+
68
+ - **`include`** — glob patterns for source files to analyze
69
+ (e.g., `src/**/*.{ts,tsx,js,jsx}`)
70
+ - **`exclude`** — patterns to skip (tests, generated code, dist)
71
+ - **`services`** — for monorepos, explicit service definitions
72
+
73
+ The minimal config generated by `grafema init` works for most projects.
74
+
75
+ ## Step 5: Write Configuration
76
+
77
+ Edit `.grafema/config.yaml` directly. Minimal format:
78
+
79
+ ```yaml
80
+ version: "0.3"
81
+ root: ".."
82
+ include:
83
+ - "src/**/*.{ts,tsx,js,jsx}"
84
+ exclude:
85
+ - "**/*.test.*"
86
+ - "**/node_modules/**"
87
+ - "**/dist/**"
88
+ ```
89
+
90
+ For monorepos, add services:
91
+
92
+ ```yaml
93
+ services:
94
+ - name: "api"
95
+ path: "packages/api"
96
+ entryPoint: "src/index.ts"
97
+ - name: "web"
98
+ path: "packages/web"
99
+ ```
100
+
101
+ Note: `root` is relative to `.grafema/` directory, so `".."` points to
102
+ the project root.
103
+
104
+ ## Step 6: Verify
105
+
106
+ Run `analyze_project` to build the graph. Then check:
107
+ - `get_stats` — are node/edge counts reasonable for the project size?
108
+ - `get_coverage` — are the expected files analyzed?
109
+
110
+ If coverage is low or results are unexpected, iterate:
111
+ revisit services, entry points, or include/exclude patterns.
112
+
113
+ ## Common Patterns
114
+
115
+ ### Monorepo with workspaces
116
+ Look for `pnpm-workspace.yaml` or `workspaces` in root `package.json`.
117
+ Each workspace package is typically a service. Use `read_project_structure`
118
+ with depth=2 to see the package layout.
119
+
120
+ ### Legacy project with multiple entry points
121
+ Look for `scripts` in `package.json`, `bin` field, or multiple files
122
+ in `src/` that look like entry points (contain `app.listen()`,
123
+ `createServer()`, `express()`).
124
+
125
+ ### Microservices with shared deployment
126
+ Look for `docker-compose.yml`, Kubernetes configs, or similar
127
+ deployment manifests that list services. Cross-reference with
128
+ code directories.
129
+
130
+ ### Single-package project
131
+ If there is only one `package.json` at the root and no monorepo
132
+ structure, the project is likely a single service. The service path
133
+ is `.` (root), and the entry point is determined from `package.json`.
@@ -0,0 +1,113 @@
1
+ /**
2
+ * KnowledgeBase — in-memory index over git-tracked knowledge files.
3
+ *
4
+ * Scans knowledge/ directory, parses markdown files with YAML frontmatter,
5
+ * builds an in-memory index for fast lookups. All mutations also write to disk.
6
+ */
7
+ import type { KBNode, KBNodeType, KBDecision, KBFact, KBEdge, KBStats, KBQueryFilter, ResolvedAddress, DanglingCodeRef } from './types.js';
8
+ import type { ResolverBackend } from './SemanticAddressResolver.js';
9
+ export declare class KnowledgeBase {
10
+ private knowledgeDir;
11
+ private nodes;
12
+ private edges;
13
+ private loaded;
14
+ private resolver;
15
+ constructor(knowledgeDir: string);
16
+ /**
17
+ * Wire up a code graph backend for resolving semantic addresses.
18
+ * Creates a SemanticAddressResolver that lazily resolves `relates_to`
19
+ * and `applies_to` addresses to current code node IDs.
20
+ */
21
+ setBackend(backend: ResolverBackend): void;
22
+ /**
23
+ * Bump the resolver's generation counter, marking all cached resolutions stale.
24
+ * Call after re-analysis so next resolve() re-queries the code graph.
25
+ */
26
+ invalidateResolutionCache(): void;
27
+ /**
28
+ * Resolve all code addresses in a node's relates_to (and applies_to for decisions).
29
+ * KB-internal addresses (kb:...) pass through without backend query.
30
+ * Returns empty array if no resolver is set.
31
+ */
32
+ resolveReferences(node: KBNode): Promise<ResolvedAddress[]>;
33
+ /**
34
+ * Find all KB nodes with code addresses that don't resolve to graph nodes.
35
+ * Returns pairs of (KB node ID, dangling address).
36
+ */
37
+ getDanglingCodeRefs(): Promise<DanglingCodeRef[]>;
38
+ /**
39
+ * Scan knowledge directory recursively, parse all .md files, build index.
40
+ * Malformed files are skipped with console.warn, don't crash.
41
+ * Missing directory succeeds with empty index.
42
+ */
43
+ load(): Promise<void>;
44
+ /**
45
+ * Get a node by its semantic ID.
46
+ */
47
+ getNode(id: string): KBNode | undefined;
48
+ /**
49
+ * Query nodes with filters. All filters are AND-combined.
50
+ * When include_dangling_only is true, only returns nodes with dangling code refs.
51
+ * Note: include_dangling_only requires a resolver backend; without one it returns empty.
52
+ */
53
+ queryNodes(filter: KBQueryFilter): Promise<KBNode[]>;
54
+ /**
55
+ * Find active decisions that apply to a given module/semantic address.
56
+ * Uses string includes matching on applies_to entries.
57
+ */
58
+ activeDecisionsFor(module: string): Promise<KBDecision[]>;
59
+ /**
60
+ * Add a new node to the knowledge base.
61
+ * Creates the .md file on disk and updates the in-memory index.
62
+ *
63
+ * @param params - Node properties. `id` and `filePath` are auto-generated.
64
+ * @returns The created node.
65
+ */
66
+ addNode(params: {
67
+ type: KBNodeType;
68
+ content: string;
69
+ slug?: string;
70
+ subtype?: string;
71
+ scope?: 'global' | 'project' | 'module';
72
+ projections?: string[];
73
+ source?: string;
74
+ relates_to?: string[];
75
+ status?: KBDecision['status'];
76
+ effective_from?: string;
77
+ applies_to?: string[];
78
+ confidence?: KBFact['confidence'];
79
+ task_id?: string;
80
+ session_path?: string;
81
+ produced?: string[];
82
+ }): Promise<KBNode>;
83
+ /**
84
+ * Supersede an existing fact with a new version.
85
+ * Creates new fact, updates old fact with superseded_by.
86
+ */
87
+ supersedeFact(oldId: string, newContent: string, newSlug?: string): Promise<{
88
+ old: KBFact;
89
+ new: KBFact;
90
+ }>;
91
+ /**
92
+ * Add an edge to the knowledge graph.
93
+ */
94
+ addEdge(edge: KBEdge): void;
95
+ /**
96
+ * Get edges, optionally filtered by node ID (from or to).
97
+ */
98
+ getEdges(nodeId?: string): KBEdge[];
99
+ /**
100
+ * Get statistics about the knowledge base.
101
+ * Includes dangling code references if a resolver backend is available.
102
+ */
103
+ getStats(): Promise<KBStats>;
104
+ /**
105
+ * Recursively scan directory for files with given extension.
106
+ */
107
+ private scanFiles;
108
+ /**
109
+ * Generate a slug from content (first line, simplified).
110
+ */
111
+ private generateSlug;
112
+ }
113
+ //# sourceMappingURL=KnowledgeBase.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"KnowledgeBase.d.ts","sourceRoot":"","sources":["../../src/knowledge/KnowledgeBase.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAe,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAExJ,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAcpE,qBAAa,aAAa;IACxB,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,KAAK,CAAkC;IAC/C,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAwC;gBAE5C,YAAY,EAAE,MAAM;IAIhC;;;;OAIG;IACH,UAAU,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAI1C;;;OAGG;IACH,yBAAyB,IAAI,IAAI;IAIjC;;;;OAIG;IACG,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAiBjE;;;OAGG;IACG,mBAAmB,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IAiBvD;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAmE3B;;OAEG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIvC;;;;OAIG;IACG,UAAU,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAqC1D;;;OAGG;IACG,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAO/D;;;;;;OAMG;IACG,OAAO,CAAC,MAAM,EAAE;QACpB,IAAI,EAAE,UAAU,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;QACxC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QACvB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;QAEtB,MAAM,CAAC,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;QAC9B,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;QAEtB,UAAU,CAAC,EAAE,MAAM,CAAC,YAAY,CAAC,CAAC;QAElC,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,GAAG,OAAO,CAAC,MAAM,CAAC;IAgFnB;;;OAGG;IACG,aAAa,CACjB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAqCxC;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAM3B;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE;IAKnC;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,OAAO,CAAC;IA0ClC;;OAEG;IACH,OAAO,CAAC,SAAS;IA0BjB;;OAEG;IACH,OAAO,CAAC,YAAY;CAUrB"}