@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,736 @@
1
+ import { displayName } from "./display-name";
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 type { DefinitionGraph, Element, SourceRef } from "./model";
10
+ import { interfaceMap, type PublicEntry } from "./interface-map";
11
+ export interface SourceArea {
12
+ id: string;
13
+ parent: string;
14
+ /** Retain a source namespace when its logical parts are regrouped. */
15
+ identityRoot?: string;
16
+ label: string;
17
+ description: string;
18
+ kind?: "block" | "interface";
19
+ /** False records module ownership only; annotated interactions remain authoritative. */
20
+ discoverMethods?: boolean;
21
+ matches: (file: string) => boolean;
22
+ /** Explicit import aliases supplied by the repository adapter; never guessed. */
23
+ aliases?: Record<string, string>;
24
+ }
25
+ const hash = (text: string) => createHash("sha256").update(text).digest("hex");
26
+ const isTest = (file: string) =>
27
+ /\.(?:test|spec|vitest)\.[cm]?[jt]sx?$/.test(file);
28
+ export function sourceReviewMap(
29
+ definition: DefinitionGraph,
30
+ files: Map<string, string>,
31
+ areas: SourceArea[],
32
+ revision?: string,
33
+ options: { legacySnapshot?: boolean } = {},
34
+ ): DefinitionGraph {
35
+ const graph = structuredClone(definition);
36
+ const areaIds = new Set(areas.map((area) => area.id));
37
+ const discoveredAreas = new Set(
38
+ areas
39
+ .filter((area) => area.discoverMethods !== false)
40
+ .map((area) => area.id),
41
+ );
42
+ // Rebuild this adapter's contribution, rather than accumulating stale leaves/edges
43
+ // when a generated inventory is supplemented again at another revision.
44
+ graph.elements = graph.elements.filter(
45
+ (n) =>
46
+ !(
47
+ n.provenance === "source" &&
48
+ (discoveredAreas.has(n.id) ||
49
+ (/\/[a-f0-9]{12}$/.test(n.id) &&
50
+ (discoveredAreas.has(n.parent || "") ||
51
+ discoveredAreas.has(
52
+ (n.parent || "").replace(/::exports$/, ""),
53
+ ))) ||
54
+ (areaIds.has(n.id) &&
55
+ n.source?.scope === "file" &&
56
+ n.sources?.every((source) => source.scope === "file")) ||
57
+ (n.kind === "interface" &&
58
+ n.id.endsWith("::exports") &&
59
+ areaIds.has(n.parent || "")))
60
+ ),
61
+ );
62
+ graph.elements = graph.elements.map((node) =>
63
+ !areaIds.has(node.id)
64
+ ? node
65
+ : {
66
+ ...node,
67
+ ...(node.source?.scope === "file" ? { source: undefined } : {}),
68
+ ...(node.sources
69
+ ? {
70
+ sources: node.sources.filter(
71
+ (source) => source.scope !== "file",
72
+ ),
73
+ }
74
+ : {}),
75
+ },
76
+ );
77
+ const retainedIds = new Set(graph.elements.map((n) => n.id));
78
+ graph.connections = graph.connections.filter(
79
+ (c) =>
80
+ !c.id.startsWith("source:") &&
81
+ retainedIds.has(c.source) &&
82
+ retainedIds.has(c.target),
83
+ );
84
+ graph.tests = graph.tests.filter((t) => !t.id.startsWith("source-test:"));
85
+ const owners = new Map<string, string>();
86
+ const refs = new Map<string, SourceRef>();
87
+ const parsed = new Map<string, ts.SourceFile>();
88
+ const byId = new Map(graph.elements.map((n) => [n.id, n]));
89
+ for (const node of graph.elements)
90
+ for (const source of node.sources || (node.source ? [node.source] : []))
91
+ if (files.has(source.file)) owners.set(source.file, node.id);
92
+ const active = new Set<string>();
93
+ const methods = new Map<string, string>();
94
+ for (const [file, text] of files) {
95
+ if (!/\.[cm]?[jt]sx?$/.test(file)) continue;
96
+ const area = areas.find((a) => a.matches(file));
97
+ const source: SourceRef = {
98
+ file,
99
+ line: 1,
100
+ digest: hash(text).slice(0, 16),
101
+ };
102
+ refs.set(file, source);
103
+ const ast = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
104
+ parsed.set(file, ast);
105
+ if (!area || isTest(file)) continue;
106
+ const owner = area.id;
107
+ active.add(owner);
108
+ owners.set(file, owner);
109
+ let node = byId.get(owner);
110
+ if (!node) {
111
+ node = {
112
+ id: area.id,
113
+ parent: area.parent,
114
+ label: area.label,
115
+ description: area.description,
116
+ kind: area.kind || "block",
117
+ provenance: "source",
118
+ sources: [],
119
+ };
120
+ graph.elements.push(node);
121
+ byId.set(node.id, node);
122
+ }
123
+ node.sources = [
124
+ ...(node.sources || []).filter(
125
+ (s) => s.file !== file || s.scope !== "file",
126
+ ),
127
+ { ...source, scope: "file" },
128
+ ];
129
+ node.source ||= { ...source, scope: "file" };
130
+ // Exported callable leaves are discovered, not maintained in another method list.
131
+ if (area.discoverMethods === false) continue;
132
+ for (const statement of ast.statements) {
133
+ if (
134
+ !ts.canHaveModifiers(statement) ||
135
+ !ts
136
+ .getModifiers(statement)
137
+ ?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)
138
+ )
139
+ continue;
140
+ const exports: {
141
+ symbol: string;
142
+ declaration:
143
+ | ts.FunctionDeclaration
144
+ | ts.FunctionExpression
145
+ | ts.ArrowFunction;
146
+ options?: ts.Expression;
147
+ }[] = [];
148
+ if (
149
+ ts.isFunctionDeclaration(statement) &&
150
+ statement.name &&
151
+ statement.body
152
+ )
153
+ exports.push({ symbol: statement.name.text, declaration: statement });
154
+ if (ts.isVariableStatement(statement))
155
+ for (const variable of statement.declarationList.declarations) {
156
+ if (!ts.isIdentifier(variable.name) || !variable.initializer)
157
+ continue;
158
+ const value = variable.initializer;
159
+ if (ts.isArrowFunction(value) || ts.isFunctionExpression(value))
160
+ exports.push({ symbol: variable.name.text, declaration: value });
161
+ else if (
162
+ ts.isCallExpression(value) &&
163
+ ts.isCallExpression(value.expression) &&
164
+ ts.isIdentifier(value.expression.expression) &&
165
+ value.arguments[0] &&
166
+ (ts.isFunctionExpression(value.arguments[0]) ||
167
+ ts.isArrowFunction(value.arguments[0]))
168
+ ) {
169
+ const imported = ast.statements.some(
170
+ (item) =>
171
+ ts.isImportDeclaration(item) &&
172
+ ts.isStringLiteral(item.moduleSpecifier) &&
173
+ [
174
+ "@granular-software/fractal/annotations",
175
+ "@granular-software/fractory/annotations",
176
+ ].includes(item.moduleSpecifier.text) &&
177
+ item.importClause?.namedBindings &&
178
+ ts.isNamedImports(item.importClause.namedBindings) &&
179
+ item.importClause.namedBindings.elements.some(
180
+ (name) =>
181
+ name.name.text ===
182
+ (
183
+ value.expression as ts.CallExpression
184
+ ).expression.getText(ast) &&
185
+ ["Method", "Process", "Block"].includes(
186
+ name.propertyName?.text || name.name.text,
187
+ ),
188
+ ),
189
+ );
190
+ if (imported)
191
+ exports.push({
192
+ symbol: variable.name.text,
193
+ declaration: value.arguments[0],
194
+ options: value.expression.arguments[1],
195
+ });
196
+ }
197
+ }
198
+ for (const { symbol, declaration, options } of exports) {
199
+ const ref = {
200
+ ...source,
201
+ line:
202
+ ast.getLineAndCharacterOfPosition(declaration.getStart(ast)).line +
203
+ 1,
204
+ symbol: declaration.name?.getText(ast) || symbol,
205
+ };
206
+ const id = `${area.identityRoot || area.id}/${hash(file + ":" + symbol).slice(0, 12)}`;
207
+ methods.set(file + ":" + symbol, id);
208
+ if (
209
+ statement.modifiers?.some(
210
+ (modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword,
211
+ )
212
+ )
213
+ methods.set(file + ":default", id);
214
+ const configuredDescription =
215
+ options && ts.isObjectLiteralExpression(options)
216
+ ? options.properties.find(
217
+ (item) =>
218
+ ts.isPropertyAssignment(item) &&
219
+ item.name.getText(ast) === "description",
220
+ )
221
+ : undefined;
222
+ const descriptionText =
223
+ configuredDescription &&
224
+ ts.isPropertyAssignment(configuredDescription) &&
225
+ ts.isStringLiteral(configuredDescription.initializer)
226
+ ? configuredDescription.initializer.text
227
+ : undefined;
228
+ const documentation = ts
229
+ .getJSDocCommentsAndTags(statement)
230
+ .find((node) => node.kind === ts.SyntaxKind.JSDoc) as
231
+ | ts.JSDoc
232
+ | undefined;
233
+ const docs =
234
+ typeof documentation?.comment === "string"
235
+ ? documentation.comment.trim()
236
+ : documentation?.comment
237
+ ?.map((part) => part.text)
238
+ .join("")
239
+ .trim();
240
+ const method: Element = {
241
+ id,
242
+ parent: area.id,
243
+ label: displayName(symbol),
244
+ kind: "method",
245
+ provenance: "source",
246
+ source: ref,
247
+ signature: declaration
248
+ .getText(ast)
249
+ .slice(
250
+ 0,
251
+ declaration.body!.getStart(ast) - declaration.getStart(ast),
252
+ )
253
+ .trim(),
254
+ description: descriptionText || docs || undefined,
255
+ };
256
+ if (!byId.has(id)) {
257
+ graph.elements.push(method);
258
+ byId.set(id, method);
259
+ }
260
+ }
261
+ }
262
+ }
263
+ // Materialize only ancestors of capabilities whose files actually exist at this revision.
264
+ for (let pending = true; pending; ) {
265
+ pending = false;
266
+ for (const area of areas)
267
+ if (active.has(area.id) && !byId.has(area.parent)) {
268
+ const parent = areas.find((a) => a.id === area.parent);
269
+ if (!parent)
270
+ throw Error(`Source area has no logical parent: ${area.parent}`);
271
+ const node: Element = {
272
+ id: parent.id,
273
+ parent: parent.parent,
274
+ label: parent.label,
275
+ kind: parent.kind || "block",
276
+ description: parent.description,
277
+ provenance: "source",
278
+ };
279
+ graph.elements.push(node);
280
+ byId.set(node.id, node);
281
+ active.add(node.id);
282
+ pending = true;
283
+ }
284
+ }
285
+ const resolveImport = (file: string, spec: string) => {
286
+ const aliases = areas.find((area) => area.matches(file))?.aliases || {};
287
+ const alias = Object.keys(aliases)
288
+ .sort((a, b) => b.length - a.length)
289
+ .find((prefix) => spec.startsWith(prefix));
290
+ const base = spec.startsWith(".")
291
+ ? posix.normalize(posix.join(posix.dirname(file), spec))
292
+ : alias
293
+ ? posix.normalize(aliases[alias] + spec.slice(alias.length))
294
+ : undefined;
295
+ if (!base) return;
296
+ return [
297
+ base,
298
+ base.replace(/\.js$/, ".ts"),
299
+ base + ".ts",
300
+ base + ".tsx",
301
+ base + "/index.ts",
302
+ base + "/index.tsx",
303
+ ].find((f) => files.has(f));
304
+ };
305
+ // Bind lexical symbols without loading dependencies or executing code. A local
306
+ // parameter named like an import must not become a fabricated cross-block call.
307
+ const compilerOptions: ts.CompilerOptions = {
308
+ noLib: true,
309
+ noResolve: true,
310
+ allowJs: true,
311
+ checkJs: false,
312
+ };
313
+ const host = ts.createCompilerHost(compilerOptions);
314
+ const clean = (path: string) => path.replace(/^\//, "");
315
+ host.getCurrentDirectory = () => "/";
316
+ host.getSourceFile = (file) => parsed.get(clean(file));
317
+ host.fileExists = (file) => parsed.has(clean(file));
318
+ host.readFile = (file) => files.get(clean(file));
319
+ const checker = ts
320
+ .createProgram([...parsed.keys()], compilerOptions, host)
321
+ .getTypeChecker();
322
+ const connections = new Map<string, DefinitionGraph["connections"][number]>();
323
+ const enclosingOwner = (node: ts.Node, file: string, fallback: string) => {
324
+ let current: ts.Node | undefined = node.parent;
325
+ while (current) {
326
+ if (ts.isFunctionDeclaration(current) && current.name) {
327
+ const owner = methods.get(file + ":" + current.name.text);
328
+ if (owner) return owner;
329
+ }
330
+ current = current.parent;
331
+ }
332
+ return fallback;
333
+ };
334
+ const link = (
335
+ file: string,
336
+ node: ts.Node,
337
+ from: string,
338
+ to: string,
339
+ relation: DefinitionGraph["connections"][number]["relation"],
340
+ label: string,
341
+ transport: string,
342
+ ) => {
343
+ if (from === to) return;
344
+ const ref = {
345
+ ...refs.get(file)!,
346
+ line:
347
+ node.getSourceFile().getLineAndCharacterOfPosition(node.getStart())
348
+ .line + 1,
349
+ symbol: node.getText().split("\n")[0],
350
+ };
351
+ const id = `source:${from}:${to}:${relation}`;
352
+ const existing = connections.get(id);
353
+ if (existing) existing.sources!.push(ref);
354
+ else
355
+ connections.set(id, {
356
+ id,
357
+ source: from,
358
+ target: to,
359
+ relation,
360
+ label: displayName(label),
361
+ transport,
362
+ provenance: "source",
363
+ sourceRef: ref,
364
+ sources: [ref],
365
+ });
366
+ };
367
+ const nextRoutes = new Map<string, string>();
368
+ const nextRoots = new Set<string>();
369
+ for (const [file, ast] of parsed) {
370
+ const match = file.match(
371
+ /^(.*?)(?:src\/)?app(\/api\/.*)\/route\.[cm]?[jt]s$/,
372
+ );
373
+ if (!match) continue;
374
+ for (const method of [
375
+ "GET",
376
+ "POST",
377
+ "PUT",
378
+ "PATCH",
379
+ "DELETE",
380
+ "HEAD",
381
+ "OPTIONS",
382
+ ]) {
383
+ const target = methods.get(file + ":" + method);
384
+ if (target) {
385
+ nextRoots.add(match[1]);
386
+ nextRoutes.set(match[1] + " " + method + " " + match[2], target);
387
+ }
388
+ }
389
+ }
390
+ for (const [file, ast] of parsed) {
391
+ const sourceOwner = owners.get(file);
392
+ const discoverInteractions =
393
+ areas.find((area) => area.matches(file))?.discoverMethods !== false;
394
+ const testTargets = new Set<string>();
395
+ if (
396
+ sourceOwner &&
397
+ active.has(sourceOwner) &&
398
+ discoverInteractions &&
399
+ !isTest(file)
400
+ ) {
401
+ // Same-file exported calls and JSX were previously invisible. Resolve the
402
+ // actual lexical declaration; matching a name alone would invent links.
403
+ const visitLocal = (node: ts.Node) => {
404
+ if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
405
+ const target = checker.getSymbolAtLocation(
406
+ node.expression,
407
+ )?.valueDeclaration;
408
+ if (
409
+ target &&
410
+ ts.isFunctionDeclaration(target) &&
411
+ target.getSourceFile() === ast &&
412
+ target.name
413
+ ) {
414
+ const id = methods.get(file + ":" + target.name.text);
415
+ if (id)
416
+ link(
417
+ file,
418
+ node,
419
+ enclosingOwner(node, file, sourceOwner),
420
+ id,
421
+ "calls",
422
+ node.expression.text,
423
+ "JavaScript call",
424
+ );
425
+ }
426
+ // Same-origin Next routes: require a literal path and a known HTTP
427
+ // method, and reject shadowed fetches or spread/unknown options.
428
+ if (
429
+ node.expression.text === "fetch" &&
430
+ !checker.getSymbolAtLocation(node.expression)?.declarations
431
+ ?.length &&
432
+ node.arguments[0] &&
433
+ ts.isStringLiteral(node.arguments[0])
434
+ ) {
435
+ const init = node.arguments[1];
436
+ let method: string | undefined = !init ? "GET" : undefined;
437
+ if (
438
+ init &&
439
+ ts.isObjectLiteralExpression(init) &&
440
+ !init.properties.some(ts.isSpreadAssignment)
441
+ ) {
442
+ const field = init.properties.find(
443
+ (p) => p.name?.getText().replace(/['"]/g, "") === "method",
444
+ );
445
+ method = !field
446
+ ? "GET"
447
+ : ts.isPropertyAssignment(field) &&
448
+ ts.isStringLiteral(field.initializer)
449
+ ? field.initializer.text.toUpperCase()
450
+ : undefined;
451
+ }
452
+ const route =
453
+ method &&
454
+ nextRoutes.get(
455
+ [...nextRoots]
456
+ .sort((a, b) => b.length - a.length)
457
+ .find(
458
+ (root) =>
459
+ file.startsWith(root + "src/") ||
460
+ file.startsWith(root + "app/"),
461
+ ) +
462
+ " " +
463
+ method +
464
+ " " +
465
+ node.arguments[0].text.split("?")[0],
466
+ );
467
+ if (route)
468
+ link(
469
+ file,
470
+ node,
471
+ enclosingOwner(node, file, sourceOwner),
472
+ route,
473
+ "calls",
474
+ method + " " + node.arguments[0].text.split("?")[0],
475
+ "HTTP",
476
+ );
477
+ }
478
+ }
479
+ ts.forEachChild(node, visitLocal);
480
+ };
481
+ visitLocal(ast);
482
+ }
483
+ for (const statement of ast.statements) {
484
+ if (
485
+ !ts.isImportDeclaration(statement) ||
486
+ !ts.isStringLiteral(statement.moduleSpecifier) ||
487
+ statement.importClause?.isTypeOnly
488
+ )
489
+ continue;
490
+ const targetFile = resolveImport(file, statement.moduleSpecifier.text);
491
+ const target = targetFile && owners.get(targetFile);
492
+ if (!target) continue;
493
+ if (isTest(file)) {
494
+ testTargets.add(target);
495
+ continue;
496
+ }
497
+ if (!sourceOwner || !active.has(sourceOwner) || !discoverInteractions)
498
+ continue;
499
+ const ref = {
500
+ ...refs.get(file)!,
501
+ line:
502
+ ast.getLineAndCharacterOfPosition(statement.getStart(ast)).line + 1,
503
+ };
504
+ const imports = statement.importClause?.namedBindings;
505
+ const names =
506
+ imports && ts.isNamedImports(imports)
507
+ ? imports.elements
508
+ .filter((e) => !e.isTypeOnly)
509
+ .map((e) => e.name.text)
510
+ : [];
511
+ if (imports && ts.isNamedImports(imports) && !names.length) continue;
512
+ const called = new Set<string>();
513
+ const visit = (node: ts.Node) => {
514
+ if (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) {
515
+ const name = ts.isIdentifier(node.tagName) ? node.tagName : undefined;
516
+ const named =
517
+ name && imports && ts.isNamedImports(imports)
518
+ ? imports.elements.find(
519
+ (e) =>
520
+ !e.isTypeOnly &&
521
+ checker.getSymbolAtLocation(e.name) ===
522
+ checker.getSymbolAtLocation(name),
523
+ )
524
+ : undefined;
525
+ const defaultName = statement.importClause?.name;
526
+ const isDefault = !!(
527
+ name &&
528
+ defaultName &&
529
+ checker.getSymbolAtLocation(defaultName) ===
530
+ checker.getSymbolAtLocation(name)
531
+ );
532
+ if (named || isDefault) {
533
+ const targetMethod = methods.get(
534
+ targetFile +
535
+ ":" +
536
+ (isDefault
537
+ ? "default"
538
+ : named!.propertyName?.text || named!.name.text),
539
+ );
540
+ link(
541
+ file,
542
+ node,
543
+ enclosingOwner(node, file, sourceOwner),
544
+ targetMethod || target,
545
+ "renders",
546
+ name!.text,
547
+ "React props",
548
+ );
549
+ called.add(name!.text);
550
+ }
551
+ }
552
+ if (
553
+ ts.isCallExpression(node) &&
554
+ ts.isIdentifier(node.expression) &&
555
+ names.includes(node.expression.text) &&
556
+ imports &&
557
+ ts.isNamedImports(imports) &&
558
+ imports.elements.some(
559
+ (e) =>
560
+ e.name.text === (node.expression as ts.Identifier).text &&
561
+ checker.getSymbolAtLocation(e.name) ===
562
+ checker.getSymbolAtLocation(node.expression),
563
+ )
564
+ ) {
565
+ called.add(node.expression.text);
566
+ const imported =
567
+ imports && ts.isNamedImports(imports)
568
+ ? imports.elements.find(
569
+ (e) =>
570
+ e.name.text === (node.expression as ts.Identifier).text,
571
+ )
572
+ : undefined;
573
+ const targetMethod = methods.get(
574
+ targetFile +
575
+ ":" +
576
+ (imported?.propertyName?.text || node.expression.text),
577
+ );
578
+ let enclosing: ts.Node | undefined = node.parent;
579
+ while (enclosing && !ts.isFunctionDeclaration(enclosing))
580
+ enclosing = enclosing.parent;
581
+ const sourceMethod =
582
+ enclosing && ts.isFunctionDeclaration(enclosing) && enclosing.name
583
+ ? methods.get(file + ":" + enclosing.name.text)
584
+ : undefined;
585
+ const from = sourceMethod || sourceOwner,
586
+ to = targetMethod || target;
587
+ if (from !== to) {
588
+ const id = `source:${from}:${to}:calls`;
589
+ const callRef = {
590
+ ...refs.get(file)!,
591
+ line:
592
+ ast.getLineAndCharacterOfPosition(node.expression.getStart(ast))
593
+ .line + 1,
594
+ symbol: node.expression.text,
595
+ };
596
+ const previous = connections.get(id);
597
+ if (previous) previous.sources!.push(callRef);
598
+ else
599
+ connections.set(id, {
600
+ id,
601
+ source: from,
602
+ target: to,
603
+ relation: "calls",
604
+ label: displayName(node.expression.text),
605
+ provenance: "source",
606
+ sourceRef: callRef,
607
+ sources: [callRef],
608
+ transport: "JavaScript call",
609
+ });
610
+ }
611
+ }
612
+ ts.forEachChild(node, visit);
613
+ };
614
+ visit(ast);
615
+ // Exact callable edges already project to their logical parents on the map.
616
+ if (called.size || sourceOwner === target) continue;
617
+ const relation = called.size ? "calls" : "requires";
618
+ const id = `source:${sourceOwner}:${target}:${relation}`;
619
+ const previous = connections.get(id);
620
+ if (previous) previous.sources!.push(ref);
621
+ else
622
+ connections.set(id, {
623
+ id,
624
+ source: sourceOwner,
625
+ target,
626
+ relation,
627
+ label: called.size
628
+ ? [...called].map(displayName).slice(0, 3).join(" · ")
629
+ : "Imports implementation",
630
+ provenance: "source",
631
+ sourceRef: ref,
632
+ sources: [ref],
633
+ transport: "JavaScript module",
634
+ });
635
+ }
636
+ if (testTargets.size && !graph.tests.some((t) => t.source.file === file))
637
+ graph.tests.push({
638
+ id: `source-test:${file}`,
639
+ name: posix.basename(file),
640
+ source: refs.get(file)!,
641
+ targets: [...testTargets],
642
+ association: "imports",
643
+ status: "not_run",
644
+ });
645
+ }
646
+ graph.connections.push(...connections.values());
647
+ const entries: PublicEntry[] = [];
648
+ for (const area of areas.filter(
649
+ (area) => active.has(area.id) && byId.get(area.id)?.kind !== "interface",
650
+ )) {
651
+ const members = [...parsed]
652
+ .filter(([file]) => owners.get(file) === area.id && !isTest(file))
653
+ .flatMap(([file, ast]) =>
654
+ ast.statements.flatMap((statement) => {
655
+ if (
656
+ ts.isInterfaceDeclaration(statement) ||
657
+ ts.isTypeAliasDeclaration(statement) ||
658
+ (ts.isExportDeclaration(statement) && statement.isTypeOnly)
659
+ )
660
+ return [];
661
+ const exported =
662
+ ts.isExportAssignment(statement) ||
663
+ ts.isExportDeclaration(statement) ||
664
+ (ts.canHaveModifiers(statement) &&
665
+ ts
666
+ .getModifiers(statement)
667
+ ?.some((item) => item.kind === ts.SyntaxKind.ExportKeyword));
668
+ // CommonJS exports are public module entries too; plain private functions are not.
669
+ const commonJS =
670
+ ts.isExpressionStatement(statement) &&
671
+ /^(module\.exports|exports\.)/.test(
672
+ statement.expression.getText(ast),
673
+ );
674
+ if (!exported && !commonJS) return [];
675
+ const source = {
676
+ ...refs.get(file)!,
677
+ line:
678
+ ast.getLineAndCharacterOfPosition(statement.getStart(ast)).line +
679
+ 1,
680
+ };
681
+ const signature =
682
+ ts.isFunctionDeclaration(statement) && statement.body
683
+ ? statement
684
+ .getText(ast)
685
+ .slice(
686
+ 0,
687
+ statement.body.getStart(ast) - statement.getStart(ast),
688
+ )
689
+ .trim()
690
+ : statement.getText(ast).split("\n")[0].slice(0, 240);
691
+ return [{ source, signature }];
692
+ }),
693
+ );
694
+ if (!members.length) continue;
695
+ const id = `${area.id}::exports`;
696
+ const api: Element = {
697
+ id,
698
+ parent: area.id,
699
+ label: `${area.label} API`,
700
+ kind: "interface",
701
+ provenance: "source",
702
+ description: `Exported contracts of ${area.label}. Open to inspect the public entries and their implementation.`,
703
+ source: { ...members[0].source, scope: "contract" },
704
+ sources: members.map((member) => ({
705
+ ...member.source,
706
+ scope: "contract",
707
+ })),
708
+ contract: { id, input: { language: "typescript", members } },
709
+ };
710
+ // Public functions live in their interface; their source ownership remains exact.
711
+ for (const method of graph.elements.filter(
712
+ (node) =>
713
+ node.kind === "method" &&
714
+ node.parent === area.id &&
715
+ node.provenance === "source",
716
+ ))
717
+ method.parent = id;
718
+ entries.push({ implementation: area.id, interface: api });
719
+ }
720
+ const surfaced = interfaceMap(graph, entries, {
721
+ exposeAncestors: true,
722
+ validate: !options.legacySnapshot,
723
+ });
724
+ graph.revision = hash(
725
+ JSON.stringify({
726
+ base: definition.revision,
727
+ revision,
728
+ elements: surfaced.elements,
729
+ connections: surfaced.connections,
730
+ tests: surfaced.tests,
731
+ }),
732
+ );
733
+ surfaced.revision = graph.revision;
734
+ surfaced.codeRevision = revision;
735
+ return surfaced;
736
+ }