@granular-software/fractory 0.0.0-stage → 0.1.25

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 (285) hide show
  1. package/LICENSE +4 -0
  2. package/README.md +28 -2
  3. package/dist/activity-volume.d.ts +18 -0
  4. package/dist/activity-volume.js +94 -0
  5. package/dist/annotations.d.ts +122 -0
  6. package/dist/annotations.js +304 -0
  7. package/dist/benchmark-cli.d.ts +1 -0
  8. package/dist/benchmark-cli.js +95 -0
  9. package/dist/benchmark-worker.d.ts +2 -0
  10. package/dist/benchmark-worker.js +22 -0
  11. package/dist/benchmarks.d.ts +19 -0
  12. package/dist/benchmarks.js +414 -0
  13. package/dist/bin.d.ts +2 -0
  14. package/dist/bin.js +63 -0
  15. package/dist/block-cli.d.ts +1 -0
  16. package/dist/block-cli.js +88 -0
  17. package/dist/block-documents.d.ts +35 -0
  18. package/dist/block-documents.js +84 -0
  19. package/dist/change-impact.d.ts +55 -0
  20. package/dist/change-impact.js +223 -0
  21. package/dist/check-source.d.ts +2 -0
  22. package/dist/check-source.js +66 -0
  23. package/dist/checks-model.d.ts +64 -0
  24. package/dist/checks-model.js +36 -0
  25. package/dist/cli.d.ts +2 -0
  26. package/dist/cli.js +359 -0
  27. package/dist/code-model.d.ts +38 -0
  28. package/dist/code-model.js +94 -0
  29. package/dist/code-store.d.ts +9 -0
  30. package/dist/code-store.js +79 -0
  31. package/dist/compare-artifact.d.ts +6 -0
  32. package/dist/compare-artifact.js +277 -0
  33. package/dist/compare.d.ts +81 -0
  34. package/dist/compare.js +291 -0
  35. package/dist/compiler.d.ts +10 -0
  36. package/dist/compiler.js +1240 -0
  37. package/dist/compose.d.ts +9 -0
  38. package/dist/compose.js +72 -0
  39. package/dist/core.d.ts +87 -0
  40. package/dist/core.js +207 -0
  41. package/dist/coverage-cli.d.ts +1 -0
  42. package/dist/coverage-cli.js +42 -0
  43. package/dist/declaration-sources.d.ts +3 -0
  44. package/dist/declaration-sources.js +51 -0
  45. package/dist/declared-graph.d.ts +3 -0
  46. package/dist/declared-graph.js +67 -0
  47. package/dist/display-name.d.ts +2 -0
  48. package/dist/display-name.js +8 -0
  49. package/dist/error-heat.d.ts +58 -0
  50. package/dist/error-heat.js +96 -0
  51. package/dist/evidence.d.ts +3 -0
  52. package/dist/evidence.js +68 -0
  53. package/dist/factory-graph.d.ts +7 -0
  54. package/dist/factory-graph.js +389 -0
  55. package/dist/factory-model.d.ts +111 -0
  56. package/dist/factory-model.js +1 -0
  57. package/dist/git-code.d.ts +47 -0
  58. package/dist/git-code.js +352 -0
  59. package/dist/git-refs.d.ts +4 -0
  60. package/dist/git-refs.js +37 -0
  61. package/dist/history-activity.d.ts +4 -0
  62. package/dist/history-activity.js +129 -0
  63. package/dist/history-churn.d.ts +36 -0
  64. package/dist/history-churn.js +302 -0
  65. package/dist/history-git.d.ts +21 -0
  66. package/dist/history-git.js +125 -0
  67. package/dist/history-ledger.d.ts +43 -0
  68. package/dist/history-ledger.js +450 -0
  69. package/dist/history-ownership.d.ts +10 -0
  70. package/dist/history-ownership.js +75 -0
  71. package/dist/history-source.d.ts +13 -0
  72. package/dist/history-source.js +100 -0
  73. package/dist/integrations-cli.d.ts +2 -0
  74. package/dist/integrations-cli.js +159 -0
  75. package/dist/interface-map.d.ts +15 -0
  76. package/dist/interface-map.js +125 -0
  77. package/dist/issue-cache.d.ts +9 -0
  78. package/dist/issue-cache.js +68 -0
  79. package/dist/issue-cli.d.ts +1 -0
  80. package/dist/issue-cli.js +89 -0
  81. package/dist/issue-links.d.ts +15 -0
  82. package/dist/issue-links.js +125 -0
  83. package/dist/linear-issues.d.ts +19 -0
  84. package/dist/linear-issues.js +124 -0
  85. package/dist/local-runtime.d.ts +8 -0
  86. package/dist/local-runtime.js +59 -0
  87. package/dist/map-activity.d.ts +73 -0
  88. package/dist/map-activity.js +234 -0
  89. package/dist/map-model.d.ts +5 -0
  90. package/dist/map-model.js +166 -0
  91. package/dist/map-quality.d.ts +20 -0
  92. package/dist/map-quality.js +61 -0
  93. package/dist/mapping-coverage.d.ts +87 -0
  94. package/dist/mapping-coverage.js +404 -0
  95. package/dist/model.d.ts +186 -0
  96. package/dist/model.js +66 -0
  97. package/dist/operation-benchmark-worker.d.ts +2 -0
  98. package/dist/operation-benchmark-worker.js +60 -0
  99. package/dist/operation-benchmark.d.ts +29 -0
  100. package/dist/operation-benchmark.js +1 -0
  101. package/dist/otel-metrics.d.ts +21 -0
  102. package/dist/otel-metrics.js +146 -0
  103. package/dist/performance-model.d.ts +185 -0
  104. package/dist/performance-model.js +396 -0
  105. package/dist/product-map.d.ts +71 -0
  106. package/dist/product-map.js +197 -0
  107. package/dist/provider-access.cjs +207 -0
  108. package/dist/provider-access.d.cts +14 -0
  109. package/dist/public-boundaries.d.ts +13 -0
  110. package/dist/public-boundaries.js +115 -0
  111. package/dist/reports-cli.d.ts +1 -0
  112. package/dist/reports-cli.js +111 -0
  113. package/dist/reports-model.d.ts +27 -0
  114. package/dist/reports-model.js +39 -0
  115. package/dist/reports.d.ts +23 -0
  116. package/dist/reports.js +223 -0
  117. package/dist/repository-map.d.ts +22 -0
  118. package/dist/repository-map.js +153 -0
  119. package/dist/resource-cache.d.ts +17 -0
  120. package/dist/resource-cache.js +65 -0
  121. package/dist/review-cli.d.ts +19 -0
  122. package/dist/review-cli.js +224 -0
  123. package/dist/review.d.ts +48 -0
  124. package/dist/review.js +289 -0
  125. package/dist/runtime-metrics.d.ts +26 -0
  126. package/dist/runtime-metrics.js +290 -0
  127. package/dist/scope.d.ts +14 -0
  128. package/dist/scope.js +168 -0
  129. package/dist/sentry-activity.d.ts +39 -0
  130. package/dist/sentry-activity.js +174 -0
  131. package/dist/sentry.d.ts +130 -0
  132. package/dist/sentry.js +369 -0
  133. package/dist/service-release.d.ts +16 -0
  134. package/dist/service-release.js +14 -0
  135. package/dist/setup-cli.d.ts +2 -0
  136. package/dist/setup-cli.js +52 -0
  137. package/dist/setup-kit.cjs +163 -0
  138. package/dist/setup-kit.d.cts +32 -0
  139. package/dist/source-index.d.ts +37 -0
  140. package/dist/source-index.js +170 -0
  141. package/dist/source-review-git.d.ts +7 -0
  142. package/dist/source-review-git.js +105 -0
  143. package/dist/source-review.d.ts +18 -0
  144. package/dist/source-review.js +573 -0
  145. package/dist/telemetry.d.ts +17 -0
  146. package/dist/telemetry.js +51 -0
  147. package/dist/time-window.d.ts +9 -0
  148. package/dist/time-window.js +35 -0
  149. package/dist/trace-evidence.d.ts +23 -0
  150. package/dist/trace-evidence.js +55 -0
  151. package/dist/trace-model.d.ts +26 -0
  152. package/dist/trace-model.js +1 -0
  153. package/dist/tracing.d.ts +44 -0
  154. package/dist/tracing.js +123 -0
  155. package/dist/work-check.d.ts +18 -0
  156. package/dist/work-check.js +115 -0
  157. package/dist/work-cli.d.ts +1 -0
  158. package/dist/work-cli.js +176 -0
  159. package/dist/work-context.d.ts +59 -0
  160. package/dist/work-context.js +594 -0
  161. package/dist/work-intents.d.ts +6 -0
  162. package/dist/work-intents.js +140 -0
  163. package/dist/work-items.d.ts +58 -0
  164. package/dist/work-items.js +86 -0
  165. package/dist/work-lock-check.d.ts +12 -0
  166. package/dist/work-lock-check.js +339 -0
  167. package/dist/work-locks.d.ts +10 -0
  168. package/dist/work-locks.js +98 -0
  169. package/dist/work-model.d.ts +119 -0
  170. package/dist/work-model.js +310 -0
  171. package/dist/work-review-git.d.ts +8 -0
  172. package/dist/work-review-git.js +111 -0
  173. package/dist/work-review.d.ts +26 -0
  174. package/dist/work-review.js +426 -0
  175. package/dist/work-switcher-model.d.ts +43 -0
  176. package/dist/work-switcher-model.js +79 -0
  177. package/dist/work-switcher.d.ts +6 -0
  178. package/dist/work-switcher.js +171 -0
  179. package/dist/working-cli.d.ts +1 -0
  180. package/dist/working-cli.js +33 -0
  181. package/dist/working-code.d.ts +74 -0
  182. package/dist/working-code.js +421 -0
  183. package/dist/workspace-notes.d.ts +71 -0
  184. package/dist/workspace-notes.js +177 -0
  185. package/dist/workspace-tests.d.ts +21 -0
  186. package/dist/workspace-tests.js +573 -0
  187. package/package.json +547 -4
  188. package/src/activity-volume.ts +149 -0
  189. package/src/annotations.ts +485 -0
  190. package/src/benchmark-cli.ts +118 -0
  191. package/src/benchmark-worker.ts +22 -0
  192. package/src/benchmarks.ts +493 -0
  193. package/src/bin.ts +54 -0
  194. package/src/block-cli.ts +106 -0
  195. package/src/block-documents.ts +117 -0
  196. package/src/change-impact.ts +280 -0
  197. package/src/check-source.ts +82 -0
  198. package/src/checks-model.ts +108 -0
  199. package/src/cli.ts +440 -0
  200. package/src/code-model.ts +159 -0
  201. package/src/code-store.ts +98 -0
  202. package/src/compare-artifact.ts +314 -0
  203. package/src/compare.ts +440 -0
  204. package/src/compiler.ts +1512 -0
  205. package/src/compose.ts +94 -0
  206. package/src/core.ts +361 -0
  207. package/src/coverage-cli.ts +52 -0
  208. package/src/declaration-sources.ts +69 -0
  209. package/src/declared-graph.ts +75 -0
  210. package/src/display-name.ts +8 -0
  211. package/src/error-heat.ts +161 -0
  212. package/src/evidence.ts +94 -0
  213. package/src/factory-graph.ts +462 -0
  214. package/src/factory-model.ts +82 -0
  215. package/src/git-code.ts +461 -0
  216. package/src/git-refs.ts +43 -0
  217. package/src/history-activity.ts +146 -0
  218. package/src/history-churn.ts +416 -0
  219. package/src/history-git.ts +163 -0
  220. package/src/history-ledger.ts +636 -0
  221. package/src/history-ownership.ts +116 -0
  222. package/src/history-source.ts +117 -0
  223. package/src/integrations-cli.ts +187 -0
  224. package/src/interface-map.ts +166 -0
  225. package/src/issue-cache.ts +96 -0
  226. package/src/issue-cli.ts +137 -0
  227. package/src/issue-links.ts +153 -0
  228. package/src/linear-issues.ts +154 -0
  229. package/src/local-runtime.ts +70 -0
  230. package/src/map-activity.ts +309 -0
  231. package/src/map-model.ts +213 -0
  232. package/src/map-quality.ts +66 -0
  233. package/src/mapping-coverage.ts +570 -0
  234. package/src/model.ts +228 -0
  235. package/src/operation-benchmark-worker.ts +60 -0
  236. package/src/operation-benchmark.ts +28 -0
  237. package/src/otel-metrics.ts +176 -0
  238. package/src/performance-model.ts +575 -0
  239. package/src/product-map.ts +271 -0
  240. package/src/provider-access.cjs +207 -0
  241. package/src/provider-access.d.cts +14 -0
  242. package/src/public-boundaries.ts +143 -0
  243. package/src/reports-cli.ts +125 -0
  244. package/src/reports-model.ts +73 -0
  245. package/src/reports.ts +276 -0
  246. package/src/repository-map.ts +191 -0
  247. package/src/resource-cache.ts +76 -0
  248. package/src/review-cli.ts +256 -0
  249. package/src/review.ts +376 -0
  250. package/src/runtime-metrics.ts +386 -0
  251. package/src/scope.ts +192 -0
  252. package/src/sentry-activity.ts +234 -0
  253. package/src/sentry.ts +545 -0
  254. package/src/service-release.ts +18 -0
  255. package/src/setup-cli.ts +58 -0
  256. package/src/setup-kit.cjs +163 -0
  257. package/src/setup-kit.d.cts +32 -0
  258. package/src/source-index.ts +208 -0
  259. package/src/source-review-git.ts +131 -0
  260. package/src/source-review.ts +736 -0
  261. package/src/telemetry.ts +68 -0
  262. package/src/time-window.ts +51 -0
  263. package/src/trace-evidence.ts +80 -0
  264. package/src/trace-model.ts +26 -0
  265. package/src/tracing.ts +165 -0
  266. package/src/work-check.ts +149 -0
  267. package/src/work-cli.ts +229 -0
  268. package/src/work-context.ts +753 -0
  269. package/src/work-intents.ts +196 -0
  270. package/src/work-items.ts +151 -0
  271. package/src/work-lock-check.ts +549 -0
  272. package/src/work-locks.ts +108 -0
  273. package/src/work-model.ts +466 -0
  274. package/src/work-review-git.ts +130 -0
  275. package/src/work-review.ts +573 -0
  276. package/src/work-switcher-model.ts +121 -0
  277. package/src/work-switcher.ts +191 -0
  278. package/src/working-cli.ts +38 -0
  279. package/src/working-code.ts +582 -0
  280. package/src/workspace-notes.ts +203 -0
  281. package/src/workspace-tests.ts +654 -0
  282. package/toolkit/GUIDE.md +354 -0
  283. package/toolkit/SKILL.md +142 -0
  284. package/toolkit/bin/fractory +2 -0
  285. package/toolkit/build.json +1 -0
@@ -0,0 +1,573 @@
1
+ import { displayName } from "./display-name.js";
2
+ /** Supplement a reviewed logical map with source-backed capabilities.
3
+ * This is a source association map, never a captured historical contract or runtime trace.
4
+ * The adapter supplies immutable blobs (Git) or current files; no application is executed.
5
+ */
6
+ import { createHash } from "node:crypto";
7
+ import { posix } from "node:path";
8
+ import ts from "typescript";
9
+ import { interfaceMap } from "./interface-map.js";
10
+ const hash = (text) => createHash("sha256").update(text).digest("hex");
11
+ const isTest = (file) => /\.(?:test|spec|vitest)\.[cm]?[jt]sx?$/.test(file);
12
+ export function sourceReviewMap(definition, files, areas, revision, options = {}) {
13
+ const graph = structuredClone(definition);
14
+ const areaIds = new Set(areas.map((area) => area.id));
15
+ const discoveredAreas = new Set(areas
16
+ .filter((area) => area.discoverMethods !== false)
17
+ .map((area) => area.id));
18
+ // Rebuild this adapter's contribution, rather than accumulating stale leaves/edges
19
+ // when a generated inventory is supplemented again at another revision.
20
+ graph.elements = graph.elements.filter((n) => !(n.provenance === "source" &&
21
+ (discoveredAreas.has(n.id) ||
22
+ (/\/[a-f0-9]{12}$/.test(n.id) &&
23
+ (discoveredAreas.has(n.parent || "") ||
24
+ discoveredAreas.has((n.parent || "").replace(/::exports$/, "")))) ||
25
+ (areaIds.has(n.id) &&
26
+ n.source?.scope === "file" &&
27
+ n.sources?.every((source) => source.scope === "file")) ||
28
+ (n.kind === "interface" &&
29
+ n.id.endsWith("::exports") &&
30
+ areaIds.has(n.parent || "")))));
31
+ graph.elements = graph.elements.map((node) => !areaIds.has(node.id)
32
+ ? node
33
+ : {
34
+ ...node,
35
+ ...(node.source?.scope === "file" ? { source: undefined } : {}),
36
+ ...(node.sources
37
+ ? {
38
+ sources: node.sources.filter((source) => source.scope !== "file"),
39
+ }
40
+ : {}),
41
+ });
42
+ const retainedIds = new Set(graph.elements.map((n) => n.id));
43
+ graph.connections = graph.connections.filter((c) => !c.id.startsWith("source:") &&
44
+ retainedIds.has(c.source) &&
45
+ retainedIds.has(c.target));
46
+ graph.tests = graph.tests.filter((t) => !t.id.startsWith("source-test:"));
47
+ const owners = new Map();
48
+ const refs = new Map();
49
+ const parsed = new Map();
50
+ const byId = new Map(graph.elements.map((n) => [n.id, n]));
51
+ for (const node of graph.elements)
52
+ for (const source of node.sources || (node.source ? [node.source] : []))
53
+ if (files.has(source.file))
54
+ owners.set(source.file, node.id);
55
+ const active = new Set();
56
+ const methods = new Map();
57
+ for (const [file, text] of files) {
58
+ if (!/\.[cm]?[jt]sx?$/.test(file))
59
+ continue;
60
+ const area = areas.find((a) => a.matches(file));
61
+ const source = {
62
+ file,
63
+ line: 1,
64
+ digest: hash(text).slice(0, 16),
65
+ };
66
+ refs.set(file, source);
67
+ const ast = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
68
+ parsed.set(file, ast);
69
+ if (!area || isTest(file))
70
+ continue;
71
+ const owner = area.id;
72
+ active.add(owner);
73
+ owners.set(file, owner);
74
+ let node = byId.get(owner);
75
+ if (!node) {
76
+ node = {
77
+ id: area.id,
78
+ parent: area.parent,
79
+ label: area.label,
80
+ description: area.description,
81
+ kind: area.kind || "block",
82
+ provenance: "source",
83
+ sources: [],
84
+ };
85
+ graph.elements.push(node);
86
+ byId.set(node.id, node);
87
+ }
88
+ node.sources = [
89
+ ...(node.sources || []).filter((s) => s.file !== file || s.scope !== "file"),
90
+ { ...source, scope: "file" },
91
+ ];
92
+ node.source ||= { ...source, scope: "file" };
93
+ // Exported callable leaves are discovered, not maintained in another method list.
94
+ if (area.discoverMethods === false)
95
+ continue;
96
+ for (const statement of ast.statements) {
97
+ if (!ts.canHaveModifiers(statement) ||
98
+ !ts
99
+ .getModifiers(statement)
100
+ ?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword))
101
+ continue;
102
+ const exports = [];
103
+ if (ts.isFunctionDeclaration(statement) &&
104
+ statement.name &&
105
+ statement.body)
106
+ exports.push({ symbol: statement.name.text, declaration: statement });
107
+ if (ts.isVariableStatement(statement))
108
+ for (const variable of statement.declarationList.declarations) {
109
+ if (!ts.isIdentifier(variable.name) || !variable.initializer)
110
+ continue;
111
+ const value = variable.initializer;
112
+ if (ts.isArrowFunction(value) || ts.isFunctionExpression(value))
113
+ exports.push({ symbol: variable.name.text, declaration: value });
114
+ else if (ts.isCallExpression(value) &&
115
+ ts.isCallExpression(value.expression) &&
116
+ ts.isIdentifier(value.expression.expression) &&
117
+ value.arguments[0] &&
118
+ (ts.isFunctionExpression(value.arguments[0]) ||
119
+ ts.isArrowFunction(value.arguments[0]))) {
120
+ const imported = ast.statements.some((item) => ts.isImportDeclaration(item) &&
121
+ ts.isStringLiteral(item.moduleSpecifier) &&
122
+ [
123
+ "@granular-software/fractal/annotations",
124
+ "@granular-software/fractory/annotations",
125
+ ].includes(item.moduleSpecifier.text) &&
126
+ item.importClause?.namedBindings &&
127
+ ts.isNamedImports(item.importClause.namedBindings) &&
128
+ item.importClause.namedBindings.elements.some((name) => name.name.text ===
129
+ value.expression.expression.getText(ast) &&
130
+ ["Method", "Process", "Block"].includes(name.propertyName?.text || name.name.text)));
131
+ if (imported)
132
+ exports.push({
133
+ symbol: variable.name.text,
134
+ declaration: value.arguments[0],
135
+ options: value.expression.arguments[1],
136
+ });
137
+ }
138
+ }
139
+ for (const { symbol, declaration, options } of exports) {
140
+ const ref = {
141
+ ...source,
142
+ line: ast.getLineAndCharacterOfPosition(declaration.getStart(ast)).line +
143
+ 1,
144
+ symbol: declaration.name?.getText(ast) || symbol,
145
+ };
146
+ const id = `${area.identityRoot || area.id}/${hash(file + ":" + symbol).slice(0, 12)}`;
147
+ methods.set(file + ":" + symbol, id);
148
+ if (statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword))
149
+ methods.set(file + ":default", id);
150
+ const configuredDescription = options && ts.isObjectLiteralExpression(options)
151
+ ? options.properties.find((item) => ts.isPropertyAssignment(item) &&
152
+ item.name.getText(ast) === "description")
153
+ : undefined;
154
+ const descriptionText = configuredDescription &&
155
+ ts.isPropertyAssignment(configuredDescription) &&
156
+ ts.isStringLiteral(configuredDescription.initializer)
157
+ ? configuredDescription.initializer.text
158
+ : undefined;
159
+ const documentation = ts
160
+ .getJSDocCommentsAndTags(statement)
161
+ .find((node) => node.kind === ts.SyntaxKind.JSDoc);
162
+ const docs = typeof documentation?.comment === "string"
163
+ ? documentation.comment.trim()
164
+ : documentation?.comment
165
+ ?.map((part) => part.text)
166
+ .join("")
167
+ .trim();
168
+ const method = {
169
+ id,
170
+ parent: area.id,
171
+ label: displayName(symbol),
172
+ kind: "method",
173
+ provenance: "source",
174
+ source: ref,
175
+ signature: declaration
176
+ .getText(ast)
177
+ .slice(0, declaration.body.getStart(ast) - declaration.getStart(ast))
178
+ .trim(),
179
+ description: descriptionText || docs || undefined,
180
+ };
181
+ if (!byId.has(id)) {
182
+ graph.elements.push(method);
183
+ byId.set(id, method);
184
+ }
185
+ }
186
+ }
187
+ }
188
+ // Materialize only ancestors of capabilities whose files actually exist at this revision.
189
+ for (let pending = true; pending;) {
190
+ pending = false;
191
+ for (const area of areas)
192
+ if (active.has(area.id) && !byId.has(area.parent)) {
193
+ const parent = areas.find((a) => a.id === area.parent);
194
+ if (!parent)
195
+ throw Error(`Source area has no logical parent: ${area.parent}`);
196
+ const node = {
197
+ id: parent.id,
198
+ parent: parent.parent,
199
+ label: parent.label,
200
+ kind: parent.kind || "block",
201
+ description: parent.description,
202
+ provenance: "source",
203
+ };
204
+ graph.elements.push(node);
205
+ byId.set(node.id, node);
206
+ active.add(node.id);
207
+ pending = true;
208
+ }
209
+ }
210
+ const resolveImport = (file, spec) => {
211
+ const aliases = areas.find((area) => area.matches(file))?.aliases || {};
212
+ const alias = Object.keys(aliases)
213
+ .sort((a, b) => b.length - a.length)
214
+ .find((prefix) => spec.startsWith(prefix));
215
+ const base = spec.startsWith(".")
216
+ ? posix.normalize(posix.join(posix.dirname(file), spec))
217
+ : alias
218
+ ? posix.normalize(aliases[alias] + spec.slice(alias.length))
219
+ : undefined;
220
+ if (!base)
221
+ return;
222
+ return [
223
+ base,
224
+ base.replace(/\.js$/, ".ts"),
225
+ base + ".ts",
226
+ base + ".tsx",
227
+ base + "/index.ts",
228
+ base + "/index.tsx",
229
+ ].find((f) => files.has(f));
230
+ };
231
+ // Bind lexical symbols without loading dependencies or executing code. A local
232
+ // parameter named like an import must not become a fabricated cross-block call.
233
+ const compilerOptions = {
234
+ noLib: true,
235
+ noResolve: true,
236
+ allowJs: true,
237
+ checkJs: false,
238
+ };
239
+ const host = ts.createCompilerHost(compilerOptions);
240
+ const clean = (path) => path.replace(/^\//, "");
241
+ host.getCurrentDirectory = () => "/";
242
+ host.getSourceFile = (file) => parsed.get(clean(file));
243
+ host.fileExists = (file) => parsed.has(clean(file));
244
+ host.readFile = (file) => files.get(clean(file));
245
+ const checker = ts
246
+ .createProgram([...parsed.keys()], compilerOptions, host)
247
+ .getTypeChecker();
248
+ const connections = new Map();
249
+ const enclosingOwner = (node, file, fallback) => {
250
+ let current = node.parent;
251
+ while (current) {
252
+ if (ts.isFunctionDeclaration(current) && current.name) {
253
+ const owner = methods.get(file + ":" + current.name.text);
254
+ if (owner)
255
+ return owner;
256
+ }
257
+ current = current.parent;
258
+ }
259
+ return fallback;
260
+ };
261
+ const link = (file, node, from, to, relation, label, transport) => {
262
+ if (from === to)
263
+ return;
264
+ const ref = {
265
+ ...refs.get(file),
266
+ line: node.getSourceFile().getLineAndCharacterOfPosition(node.getStart())
267
+ .line + 1,
268
+ symbol: node.getText().split("\n")[0],
269
+ };
270
+ const id = `source:${from}:${to}:${relation}`;
271
+ const existing = connections.get(id);
272
+ if (existing)
273
+ existing.sources.push(ref);
274
+ else
275
+ connections.set(id, {
276
+ id,
277
+ source: from,
278
+ target: to,
279
+ relation,
280
+ label: displayName(label),
281
+ transport,
282
+ provenance: "source",
283
+ sourceRef: ref,
284
+ sources: [ref],
285
+ });
286
+ };
287
+ const nextRoutes = new Map();
288
+ const nextRoots = new Set();
289
+ for (const [file, ast] of parsed) {
290
+ const match = file.match(/^(.*?)(?:src\/)?app(\/api\/.*)\/route\.[cm]?[jt]s$/);
291
+ if (!match)
292
+ continue;
293
+ for (const method of [
294
+ "GET",
295
+ "POST",
296
+ "PUT",
297
+ "PATCH",
298
+ "DELETE",
299
+ "HEAD",
300
+ "OPTIONS",
301
+ ]) {
302
+ const target = methods.get(file + ":" + method);
303
+ if (target) {
304
+ nextRoots.add(match[1]);
305
+ nextRoutes.set(match[1] + " " + method + " " + match[2], target);
306
+ }
307
+ }
308
+ }
309
+ for (const [file, ast] of parsed) {
310
+ const sourceOwner = owners.get(file);
311
+ const discoverInteractions = areas.find((area) => area.matches(file))?.discoverMethods !== false;
312
+ const testTargets = new Set();
313
+ if (sourceOwner &&
314
+ active.has(sourceOwner) &&
315
+ discoverInteractions &&
316
+ !isTest(file)) {
317
+ // Same-file exported calls and JSX were previously invisible. Resolve the
318
+ // actual lexical declaration; matching a name alone would invent links.
319
+ const visitLocal = (node) => {
320
+ if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
321
+ const target = checker.getSymbolAtLocation(node.expression)?.valueDeclaration;
322
+ if (target &&
323
+ ts.isFunctionDeclaration(target) &&
324
+ target.getSourceFile() === ast &&
325
+ target.name) {
326
+ const id = methods.get(file + ":" + target.name.text);
327
+ if (id)
328
+ link(file, node, enclosingOwner(node, file, sourceOwner), id, "calls", node.expression.text, "JavaScript call");
329
+ }
330
+ // Same-origin Next routes: require a literal path and a known HTTP
331
+ // method, and reject shadowed fetches or spread/unknown options.
332
+ if (node.expression.text === "fetch" &&
333
+ !checker.getSymbolAtLocation(node.expression)?.declarations
334
+ ?.length &&
335
+ node.arguments[0] &&
336
+ ts.isStringLiteral(node.arguments[0])) {
337
+ const init = node.arguments[1];
338
+ let method = !init ? "GET" : undefined;
339
+ if (init &&
340
+ ts.isObjectLiteralExpression(init) &&
341
+ !init.properties.some(ts.isSpreadAssignment)) {
342
+ const field = init.properties.find((p) => p.name?.getText().replace(/['"]/g, "") === "method");
343
+ method = !field
344
+ ? "GET"
345
+ : ts.isPropertyAssignment(field) &&
346
+ ts.isStringLiteral(field.initializer)
347
+ ? field.initializer.text.toUpperCase()
348
+ : undefined;
349
+ }
350
+ const route = method &&
351
+ nextRoutes.get([...nextRoots]
352
+ .sort((a, b) => b.length - a.length)
353
+ .find((root) => file.startsWith(root + "src/") ||
354
+ file.startsWith(root + "app/")) +
355
+ " " +
356
+ method +
357
+ " " +
358
+ node.arguments[0].text.split("?")[0]);
359
+ if (route)
360
+ link(file, node, enclosingOwner(node, file, sourceOwner), route, "calls", method + " " + node.arguments[0].text.split("?")[0], "HTTP");
361
+ }
362
+ }
363
+ ts.forEachChild(node, visitLocal);
364
+ };
365
+ visitLocal(ast);
366
+ }
367
+ for (const statement of ast.statements) {
368
+ if (!ts.isImportDeclaration(statement) ||
369
+ !ts.isStringLiteral(statement.moduleSpecifier) ||
370
+ statement.importClause?.isTypeOnly)
371
+ continue;
372
+ const targetFile = resolveImport(file, statement.moduleSpecifier.text);
373
+ const target = targetFile && owners.get(targetFile);
374
+ if (!target)
375
+ continue;
376
+ if (isTest(file)) {
377
+ testTargets.add(target);
378
+ continue;
379
+ }
380
+ if (!sourceOwner || !active.has(sourceOwner) || !discoverInteractions)
381
+ continue;
382
+ const ref = {
383
+ ...refs.get(file),
384
+ line: ast.getLineAndCharacterOfPosition(statement.getStart(ast)).line + 1,
385
+ };
386
+ const imports = statement.importClause?.namedBindings;
387
+ const names = imports && ts.isNamedImports(imports)
388
+ ? imports.elements
389
+ .filter((e) => !e.isTypeOnly)
390
+ .map((e) => e.name.text)
391
+ : [];
392
+ if (imports && ts.isNamedImports(imports) && !names.length)
393
+ continue;
394
+ const called = new Set();
395
+ const visit = (node) => {
396
+ if (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) {
397
+ const name = ts.isIdentifier(node.tagName) ? node.tagName : undefined;
398
+ const named = name && imports && ts.isNamedImports(imports)
399
+ ? imports.elements.find((e) => !e.isTypeOnly &&
400
+ checker.getSymbolAtLocation(e.name) ===
401
+ checker.getSymbolAtLocation(name))
402
+ : undefined;
403
+ const defaultName = statement.importClause?.name;
404
+ const isDefault = !!(name &&
405
+ defaultName &&
406
+ checker.getSymbolAtLocation(defaultName) ===
407
+ checker.getSymbolAtLocation(name));
408
+ if (named || isDefault) {
409
+ const targetMethod = methods.get(targetFile +
410
+ ":" +
411
+ (isDefault
412
+ ? "default"
413
+ : named.propertyName?.text || named.name.text));
414
+ link(file, node, enclosingOwner(node, file, sourceOwner), targetMethod || target, "renders", name.text, "React props");
415
+ called.add(name.text);
416
+ }
417
+ }
418
+ if (ts.isCallExpression(node) &&
419
+ ts.isIdentifier(node.expression) &&
420
+ names.includes(node.expression.text) &&
421
+ imports &&
422
+ ts.isNamedImports(imports) &&
423
+ imports.elements.some((e) => e.name.text === node.expression.text &&
424
+ checker.getSymbolAtLocation(e.name) ===
425
+ checker.getSymbolAtLocation(node.expression))) {
426
+ called.add(node.expression.text);
427
+ const imported = imports && ts.isNamedImports(imports)
428
+ ? imports.elements.find((e) => e.name.text === node.expression.text)
429
+ : undefined;
430
+ const targetMethod = methods.get(targetFile +
431
+ ":" +
432
+ (imported?.propertyName?.text || node.expression.text));
433
+ let enclosing = node.parent;
434
+ while (enclosing && !ts.isFunctionDeclaration(enclosing))
435
+ enclosing = enclosing.parent;
436
+ const sourceMethod = enclosing && ts.isFunctionDeclaration(enclosing) && enclosing.name
437
+ ? methods.get(file + ":" + enclosing.name.text)
438
+ : undefined;
439
+ const from = sourceMethod || sourceOwner, to = targetMethod || target;
440
+ if (from !== to) {
441
+ const id = `source:${from}:${to}:calls`;
442
+ const callRef = {
443
+ ...refs.get(file),
444
+ line: ast.getLineAndCharacterOfPosition(node.expression.getStart(ast))
445
+ .line + 1,
446
+ symbol: node.expression.text,
447
+ };
448
+ const previous = connections.get(id);
449
+ if (previous)
450
+ previous.sources.push(callRef);
451
+ else
452
+ connections.set(id, {
453
+ id,
454
+ source: from,
455
+ target: to,
456
+ relation: "calls",
457
+ label: displayName(node.expression.text),
458
+ provenance: "source",
459
+ sourceRef: callRef,
460
+ sources: [callRef],
461
+ transport: "JavaScript call",
462
+ });
463
+ }
464
+ }
465
+ ts.forEachChild(node, visit);
466
+ };
467
+ visit(ast);
468
+ // Exact callable edges already project to their logical parents on the map.
469
+ if (called.size || sourceOwner === target)
470
+ continue;
471
+ const relation = called.size ? "calls" : "requires";
472
+ const id = `source:${sourceOwner}:${target}:${relation}`;
473
+ const previous = connections.get(id);
474
+ if (previous)
475
+ previous.sources.push(ref);
476
+ else
477
+ connections.set(id, {
478
+ id,
479
+ source: sourceOwner,
480
+ target,
481
+ relation,
482
+ label: called.size
483
+ ? [...called].map(displayName).slice(0, 3).join(" · ")
484
+ : "Imports implementation",
485
+ provenance: "source",
486
+ sourceRef: ref,
487
+ sources: [ref],
488
+ transport: "JavaScript module",
489
+ });
490
+ }
491
+ if (testTargets.size && !graph.tests.some((t) => t.source.file === file))
492
+ graph.tests.push({
493
+ id: `source-test:${file}`,
494
+ name: posix.basename(file),
495
+ source: refs.get(file),
496
+ targets: [...testTargets],
497
+ association: "imports",
498
+ status: "not_run",
499
+ });
500
+ }
501
+ graph.connections.push(...connections.values());
502
+ const entries = [];
503
+ for (const area of areas.filter((area) => active.has(area.id) && byId.get(area.id)?.kind !== "interface")) {
504
+ const members = [...parsed]
505
+ .filter(([file]) => owners.get(file) === area.id && !isTest(file))
506
+ .flatMap(([file, ast]) => ast.statements.flatMap((statement) => {
507
+ if (ts.isInterfaceDeclaration(statement) ||
508
+ ts.isTypeAliasDeclaration(statement) ||
509
+ (ts.isExportDeclaration(statement) && statement.isTypeOnly))
510
+ return [];
511
+ const exported = ts.isExportAssignment(statement) ||
512
+ ts.isExportDeclaration(statement) ||
513
+ (ts.canHaveModifiers(statement) &&
514
+ ts
515
+ .getModifiers(statement)
516
+ ?.some((item) => item.kind === ts.SyntaxKind.ExportKeyword));
517
+ // CommonJS exports are public module entries too; plain private functions are not.
518
+ const commonJS = ts.isExpressionStatement(statement) &&
519
+ /^(module\.exports|exports\.)/.test(statement.expression.getText(ast));
520
+ if (!exported && !commonJS)
521
+ return [];
522
+ const source = {
523
+ ...refs.get(file),
524
+ line: ast.getLineAndCharacterOfPosition(statement.getStart(ast)).line +
525
+ 1,
526
+ };
527
+ const signature = ts.isFunctionDeclaration(statement) && statement.body
528
+ ? statement
529
+ .getText(ast)
530
+ .slice(0, statement.body.getStart(ast) - statement.getStart(ast))
531
+ .trim()
532
+ : statement.getText(ast).split("\n")[0].slice(0, 240);
533
+ return [{ source, signature }];
534
+ }));
535
+ if (!members.length)
536
+ continue;
537
+ const id = `${area.id}::exports`;
538
+ const api = {
539
+ id,
540
+ parent: area.id,
541
+ label: `${area.label} API`,
542
+ kind: "interface",
543
+ provenance: "source",
544
+ description: `Exported contracts of ${area.label}. Open to inspect the public entries and their implementation.`,
545
+ source: { ...members[0].source, scope: "contract" },
546
+ sources: members.map((member) => ({
547
+ ...member.source,
548
+ scope: "contract",
549
+ })),
550
+ contract: { id, input: { language: "typescript", members } },
551
+ };
552
+ // Public functions live in their interface; their source ownership remains exact.
553
+ for (const method of graph.elements.filter((node) => node.kind === "method" &&
554
+ node.parent === area.id &&
555
+ node.provenance === "source"))
556
+ method.parent = id;
557
+ entries.push({ implementation: area.id, interface: api });
558
+ }
559
+ const surfaced = interfaceMap(graph, entries, {
560
+ exposeAncestors: true,
561
+ validate: !options.legacySnapshot,
562
+ });
563
+ graph.revision = hash(JSON.stringify({
564
+ base: definition.revision,
565
+ revision,
566
+ elements: surfaced.elements,
567
+ connections: surfaced.connections,
568
+ tests: surfaced.tests,
569
+ }));
570
+ surfaced.revision = graph.revision;
571
+ surfaced.codeRevision = revision;
572
+ return surfaced;
573
+ }
@@ -0,0 +1,17 @@
1
+ import { type FactoryEvent } from "./annotations.js";
2
+ interface MetricOptions {
3
+ attributes: Record<string, string>;
4
+ }
5
+ export declare function installFactoryTelemetry(options: {
6
+ service: string;
7
+ context?: () => unknown;
8
+ codeRevision?: () => string | undefined;
9
+ count(name: string, value: number, options: MetricOptions): void;
10
+ distribution(name: string, value: number, options: MetricOptions & {
11
+ unit: string;
12
+ }): void;
13
+ /** Detailed traces can be sampled independently of aggregate counters. */
14
+ trace?: (event: FactoryEvent) => void;
15
+ metrics?: (event: FactoryEvent) => void;
16
+ }): () => void;
17
+ export {};
@@ -0,0 +1,51 @@
1
+ /** Node/Cloudflare nodejs_compat host adapter. The annotation SDK itself stays portable. */
2
+ import { AsyncLocalStorage } from "node:async_hooks";
3
+ import { installFactoryHost, } from "./annotations.js";
4
+ import { commitFromRelease } from "./code-model.js";
5
+ export function installFactoryTelemetry(options) {
6
+ const scope = new AsyncLocalStorage();
7
+ return installFactoryHost({
8
+ current: () => scope.getStore(),
9
+ run: (frame, execute) => scope.run(frame, execute),
10
+ context: options.context,
11
+ codeRevision: () => commitFromRelease(options.codeRevision?.()),
12
+ emit(event) {
13
+ try {
14
+ options.metrics?.(event);
15
+ }
16
+ catch {
17
+ /* aggregate metrics never affect execution */
18
+ }
19
+ const attributes = {
20
+ service: options.service,
21
+ block: event.blockId,
22
+ interface: event.interfaceId || "",
23
+ method: event.method,
24
+ outcome: event.status,
25
+ };
26
+ try {
27
+ options.count(`fractal.boundary.${event.status}`, 1, { attributes });
28
+ }
29
+ catch {
30
+ /* independent sink */
31
+ }
32
+ if (event.durationMs !== undefined) {
33
+ try {
34
+ options.distribution("fractal.boundary.duration", event.durationMs, {
35
+ attributes,
36
+ unit: "millisecond",
37
+ });
38
+ }
39
+ catch {
40
+ /* independent sink */
41
+ }
42
+ }
43
+ try {
44
+ options.trace?.(event);
45
+ }
46
+ catch {
47
+ /* observational */
48
+ }
49
+ },
50
+ });
51
+ }
@@ -0,0 +1,9 @@
1
+ /** Shared UTC, half-open time interval: from inclusive, to exclusive. */
2
+ export interface TimeWindow {
3
+ from: string;
4
+ to: string;
5
+ }
6
+ export declare const DAY_MS = 86400000;
7
+ export declare function recentWindow(days?: number, now?: number): TimeWindow;
8
+ export declare function parseTimeWindow(params: Pick<URLSearchParams, "get">, now?: number, maxDays?: number): TimeWindow | undefined;
9
+ export declare function inTimeWindow(at: string | undefined, window: TimeWindow): boolean;