@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,462 @@
1
+ import { displayName } from "./display-name";
2
+ import type { FactoryModel, FactoryAttachments } from "./factory-model";
3
+ import type { DefinitionGraph, SourceRef } from "./model";
4
+ import { interfaceMap, type PublicEntry } from "./interface-map";
5
+ function digest(value: string) {
6
+ let hash = BigInt("14695981039346656037");
7
+ for (const byte of new TextEncoder().encode(value))
8
+ hash = BigInt.asUintN(64, (hash ^ BigInt(byte)) * BigInt("1099511628211"));
9
+ return hash.toString(16).padStart(16, "0");
10
+ }
11
+
12
+ /** Compatibility projection only. The v2 model retains interface/member semantics. */
13
+ export function factoryGraph(
14
+ model: FactoryModel,
15
+ base?: DefinitionGraph,
16
+ options: { legacySnapshot?: boolean; exposeAncestors?: boolean } = {},
17
+ ): DefinitionGraph {
18
+ if (model.diagnostics.length)
19
+ throw new Error(
20
+ model.diagnostics
21
+ .map((d) => `${d.file}:${d.line}: ${d.message}`)
22
+ .join("\n"),
23
+ );
24
+ const graph: DefinitionGraph = base
25
+ ? structuredClone(base)
26
+ : {
27
+ schema: "fractal.definition.v1",
28
+ id: "factory",
29
+ revision: "",
30
+ generatedAt: "compiled",
31
+ scope: "Annotated factory",
32
+ elements: [
33
+ {
34
+ id: "factory",
35
+ label: "Factory",
36
+ kind: "block",
37
+ provenance: "declared",
38
+ },
39
+ ],
40
+ connections: [],
41
+ tests: [],
42
+ failures: [],
43
+ gaps: [],
44
+ };
45
+ // Reviewed inventories describe product areas, not executable control flow.
46
+ // Retire their handwritten process internals when source declarations take over.
47
+ const declaredIds = new Set(
48
+ [...model.blocks, ...model.interfaces, ...model.methods].map(
49
+ (item) => item.id,
50
+ ),
51
+ );
52
+ for (const process of model.processes)
53
+ declaredIds.add(`${process.blockId}::entry`);
54
+ const processIds = new Set(model.processes.map((item) => item.blockId));
55
+ const oldById = new Map(graph.elements.map((item) => [item.id, item]));
56
+ // Incremental adoption: an ID names a logical area, never a source folder.
57
+ // Keep unowned declarations inside the nearest existing inventory block.
58
+ // An explicit typed parent always wins; no parallel parent/child registry.
59
+ const inventoryParent = (id: string) =>
60
+ [...oldById.values()]
61
+ .filter(
62
+ (node) =>
63
+ kept.has(node.id) &&
64
+ id.startsWith(`${node.id}/`) &&
65
+ ![
66
+ "resource",
67
+ "artifact",
68
+ "method",
69
+ "operation",
70
+ "interface",
71
+ ].includes(node.kind),
72
+ )
73
+ .sort((a, b) => b.id.length - a.id.length)[0]?.id;
74
+ const inProcess = (id: string) => {
75
+ const seen = new Set<string>();
76
+ while (id && !seen.has(id)) {
77
+ if (processIds.has(id)) return true;
78
+ seen.add(id);
79
+ id = oldById.get(id)?.parent || "";
80
+ }
81
+ return false;
82
+ };
83
+ // A reviewed leaf may describe the exact method now supplied by an annotation.
84
+ // Collapse only unambiguous matches inside the same logical owner; never infer
85
+ // ownership from a file alone or replace a capability group with its helper.
86
+ const ownedBy = (id: string, owner: string) => {
87
+ const seen = new Set<string>();
88
+ while (id && !seen.has(id)) {
89
+ if (id === owner) return true;
90
+ seen.add(id);
91
+ id = oldById.get(id)?.parent || "";
92
+ }
93
+ return false;
94
+ };
95
+ const adopted = new Map<string, string>();
96
+ for (const node of graph.elements) {
97
+ if (
98
+ node.kind !== "method" ||
99
+ node.provenance === "declared" ||
100
+ declaredIds.has(node.id) ||
101
+ graph.elements.some((child) => child.parent === node.id)
102
+ )
103
+ continue;
104
+ const candidates = model.methods.filter(
105
+ (method) =>
106
+ method.source.file === node.source?.file &&
107
+ ownedBy(node.parent || "", method.blockId) &&
108
+ (node.source?.symbol === method.name ||
109
+ new RegExp(
110
+ "\\b" +
111
+ method.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") +
112
+ "\\s*\\(",
113
+ ).test(node.source?.symbol || "")),
114
+ );
115
+ if (candidates.length === 1) {
116
+ const method = candidates[0],
117
+ process = model.processes.find((p) => p.entryMethodId === method.id);
118
+ adopted.set(node.id, process?.blockId || method.id);
119
+ }
120
+ }
121
+ graph.aliases = { ...graph.aliases, ...Object.fromEntries(adopted) };
122
+ graph.elements = graph.elements.filter(
123
+ (item) =>
124
+ (!inProcess(item.id) || declaredIds.has(item.id)) &&
125
+ !adopted.has(item.id),
126
+ );
127
+ graph.connections = graph.connections.map((edge) => ({
128
+ ...edge,
129
+ source: adopted.get(edge.source) || edge.source,
130
+ target: adopted.get(edge.target) || edge.target,
131
+ }));
132
+ graph.tests = graph.tests.map((test) => ({
133
+ ...test,
134
+ targets: [...new Set(test.targets.map((id) => adopted.get(id) || id))],
135
+ }));
136
+ const kept = new Set([
137
+ ...graph.elements.map((item) => item.id),
138
+ ...declaredIds,
139
+ ]);
140
+ graph.connections = graph.connections.filter(
141
+ (edge) =>
142
+ !edge.path &&
143
+ kept.has(edge.source) &&
144
+ kept.has(edge.target) &&
145
+ !(
146
+ edge.id.startsWith("flow:") &&
147
+ (inProcess(edge.source) || inProcess(edge.target))
148
+ ),
149
+ );
150
+ graph.tests = graph.tests
151
+ .map((test) => ({
152
+ ...test,
153
+ targets: test.targets.filter((id) => kept.has(id)),
154
+ }))
155
+ .filter((test) => test.targets.length);
156
+ const put = (element: DefinitionGraph["elements"][number]) => {
157
+ element.definitionRevision = model.revision;
158
+ const index = graph.elements.findIndex((node) => node.id === element.id);
159
+ if (index < 0) graph.elements.push(element);
160
+ else
161
+ graph.elements[index] = {
162
+ ...graph.elements[index],
163
+ ...element,
164
+ sources: [
165
+ ...(element.sources || (element.source ? [element.source] : [])),
166
+ ...(graph.elements[index].sources || []).filter(
167
+ (source) => source.scope === "file",
168
+ ),
169
+ ].filter(
170
+ (source, at, all) =>
171
+ all.findIndex(
172
+ (other) => JSON.stringify(other) === JSON.stringify(source),
173
+ ) === at,
174
+ ),
175
+ description: element.description ?? graph.elements[index].description,
176
+ parent: element.parent || graph.elements[index].parent,
177
+ };
178
+ };
179
+ const attach = (
180
+ id: string,
181
+ attachments: FactoryAttachments,
182
+ source: SourceRef,
183
+ ) => {
184
+ for (const file of attachments.tests) {
185
+ const testId = `attachment:${id}:${file}`;
186
+ if (!graph.tests.some((test) => test.id === testId))
187
+ graph.tests.push({
188
+ id: testId,
189
+ name: file,
190
+ source: { ...source, file, line: 1 },
191
+ targets: [id],
192
+ association: "attachment",
193
+ status: "not_run",
194
+ });
195
+ }
196
+ };
197
+ for (const block of model.blocks) {
198
+ const existing = graph.elements.find((node) => node.id === block.id);
199
+ const label =
200
+ block.label === block.id.split("/").at(-1)
201
+ ? existing?.label || block.label
202
+ : block.label;
203
+ const entry = model.methods.find((method) =>
204
+ model.processes.some(
205
+ (process) =>
206
+ process.blockId === block.id && process.entryMethodId === method.id,
207
+ ),
208
+ );
209
+ put({
210
+ id: block.id,
211
+ label,
212
+ parent:
213
+ block.parent ||
214
+ existing?.parent ||
215
+ inventoryParent(block.id) ||
216
+ (block.id !== graph.id ? graph.id : undefined),
217
+ kind: model.processes.some((process) => process.blockId === block.id)
218
+ ? "process"
219
+ : "block",
220
+ provenance: "declared",
221
+ source: block.source,
222
+ sources: [block.source],
223
+ description: block.attachments.description,
224
+ attachments: block.attachments,
225
+ ...(entry
226
+ ? {
227
+ signature: entry.signature,
228
+ contract: {
229
+ id: block.id,
230
+ input: {
231
+ language: "typescript",
232
+ args: entry.contract.args,
233
+ typeSources: entry.contract.typeSources,
234
+ runtimeValidation: entry.contract.runtimeValidation,
235
+ },
236
+ output: { language: "typescript", type: entry.contract.result },
237
+ },
238
+ }
239
+ : {}),
240
+ });
241
+ attach(block.id, block.attachments, block.source);
242
+ }
243
+ for (const api of model.interfaces) {
244
+ const previous = `${api.blockId}::${api.name}`;
245
+ if (api.id !== previous) {
246
+ graph.aliases = { ...graph.aliases, [previous]: api.id };
247
+ for (const method of model.methods.filter(
248
+ (method) => method.interfaceId === api.id,
249
+ ))
250
+ graph.aliases[`${previous}#${method.name}`] = method.id;
251
+ }
252
+ put({
253
+ id: api.id,
254
+ // A source inventory may supply the prefix owner during incremental
255
+ // adoption. With a smaller inventory, use its nearest known owner rather
256
+ // than emitting an orphan or manufacturing intermediate blocks.
257
+ parent: kept.has(api.blockId)
258
+ ? api.blockId
259
+ : inventoryParent(api.id) || graph.id,
260
+ kind: "interface",
261
+ label:
262
+ api.label ||
263
+ api.name
264
+ .replace(/([a-z])([A-Z])/g, "$1 $2")
265
+ .replace(/^./, (letter) => letter.toUpperCase()),
266
+ provenance: "declared",
267
+ source: { ...api.source, scope: "contract" },
268
+ sources: [{ ...api.source, scope: "contract" }],
269
+ attachments: api.attachments,
270
+ description: api.attachments.description,
271
+ signature: api.constructorContract?.signature,
272
+ contract: {
273
+ id: api.id,
274
+ input: {
275
+ language: "typescript",
276
+ ...(api.constructorContract
277
+ ? { args: api.constructorContract.args }
278
+ : {}),
279
+ members: model.methods
280
+ .filter((method) => method.interfaceId === api.id)
281
+ .map((method) => ({ name: method.name, ...method.contract })),
282
+ },
283
+ },
284
+ });
285
+ attach(api.id, api.attachments, api.source);
286
+ for (const owner of [
287
+ ...(api.exposedBy || []),
288
+ ...(model.blocks.find((block) => block.id === api.blockId)?.exposedBy ||
289
+ []),
290
+ ])
291
+ graph.connections.push({
292
+ id: `public-exposure:${owner}:${api.id}`,
293
+ source: owner,
294
+ target: api.id,
295
+ relation: "exposes",
296
+ label: api.label || api.name,
297
+ provenance: "declared",
298
+ sourceRef: api.source,
299
+ });
300
+ }
301
+ for (const method of model.methods) {
302
+ // A process entry is the implementation of its process box, not an extra method box.
303
+ const processEntry = model.processes.some(
304
+ (process) => process.entryMethodId === method.id,
305
+ );
306
+ if (processEntry && !method.interfaceId) continue;
307
+ if (processEntry && method.interfaceId)
308
+ graph.connections.push({
309
+ id: `interface-entry:${method.id}`,
310
+ source: method.blockId,
311
+ target: method.interfaceId!,
312
+ relation: "exposes",
313
+ label: method.name,
314
+ provenance: "declared",
315
+ sourceRef: method.source,
316
+ });
317
+ put({
318
+ id: method.id,
319
+ parent: method.interfaceId || method.blockId,
320
+ kind: "method",
321
+ label: method.label || displayName(method.name),
322
+ provenance: "declared",
323
+ source: method.source,
324
+ sources: [method.source],
325
+ signature: method.endpoint
326
+ ? `${method.endpoint.method} ${method.endpoint.path}`
327
+ : method.signature,
328
+ ...(processEntry ? { implementationBlock: method.blockId } : {}),
329
+ contract: {
330
+ id: method.id,
331
+ input: {
332
+ language: "typescript",
333
+ ...(method.endpoint ? { endpoint: method.endpoint } : {}),
334
+ args: method.contract.args,
335
+ typeSources: method.contract.typeSources,
336
+ runtimeValidation: method.contract.runtimeValidation,
337
+ },
338
+ output: { language: "typescript", type: method.contract.result },
339
+ },
340
+ attachments: method.attachments,
341
+ });
342
+ attach(method.id, method.attachments, method.source);
343
+ }
344
+ for (const dependency of model.dependencies) {
345
+ const id = `call-site:${dependency.source}->${dependency.target}:${dependency.at.file}:${dependency.at.line}:${dependency.relation || "calls"}:${dependency.label || ""}`;
346
+ if (!graph.connections.some((edge) => edge.id === id))
347
+ graph.connections.push({
348
+ id,
349
+ source: dependency.source,
350
+ target: dependency.target,
351
+ relation: dependency.relation || "calls",
352
+ label:
353
+ dependency.label ||
354
+ graph.elements.find((node) => node.id === dependency.target)?.label ||
355
+ dependency.target,
356
+ provenance: "source",
357
+ sourceRef: dependency.at,
358
+ ...(dependency.transport ? { transport: dependency.transport } : {}),
359
+ ...(dependency.via?.length
360
+ ? { sources: [...dependency.via, dependency.at] }
361
+ : {}),
362
+ ...(dependency.exchange ? { exchange: dependency.exchange } : {}),
363
+ ...(dependency.displayLabel
364
+ ? { displayLabel: dependency.displayLabel }
365
+ : {}),
366
+ });
367
+ }
368
+ // A bootstrap capability can be broader than the declared caller. Prefer the
369
+ // exact compiled owner for each identical call site, retaining uncovered sites.
370
+ const covered = new Set(
371
+ model.dependencies.map(
372
+ (edge) =>
373
+ `${edge.target}:${edge.at.file}:${edge.at.line}:${edge.relation || "calls"}`,
374
+ ),
375
+ );
376
+ graph.connections = graph.connections.flatMap((edge) => {
377
+ if (!edge.id.startsWith("source:")) return [edge];
378
+ const refs = edge.sources || (edge.sourceRef ? [edge.sourceRef] : []);
379
+ const remaining = refs.filter(
380
+ (ref) =>
381
+ !covered.has(`${edge.target}:${ref.file}:${ref.line}:${edge.relation}`),
382
+ );
383
+ if (remaining.length === refs.length) return [edge];
384
+ return remaining.length
385
+ ? [{ ...edge, sourceRef: remaining[0], sources: remaining }]
386
+ : [];
387
+ });
388
+ graph.gaps.push(...(model.interactionGaps || []));
389
+ // Call sites are explicitly source evidence; actual traversal comes only from traces.
390
+ graph.revision = digest(
391
+ JSON.stringify({
392
+ elements: graph.elements,
393
+ connections: graph.connections,
394
+ tests: graph.tests,
395
+ failures: graph.failures,
396
+ gaps: graph.gaps,
397
+ }),
398
+ ).slice(0, 16);
399
+ const entries: PublicEntry[] = model.interfaces
400
+ .filter((api) => api.constructorContract || api.entrypoint)
401
+ .map((api) => ({
402
+ implementation: api.blockId,
403
+ interface: graph.elements.find((node) => node.id === api.id)!,
404
+ }));
405
+ entries.push(
406
+ ...model.processes.flatMap<PublicEntry>((process) => {
407
+ const method = model.methods.find(
408
+ (item) => item.id === process.entryMethodId,
409
+ );
410
+ if (
411
+ !method ||
412
+ !graph.elements.some((item) => item.id === process.blockId)
413
+ )
414
+ return [];
415
+ const id = `${process.blockId}::entry`;
416
+ for (const owner of model.blocks.find(
417
+ (block) => block.id === process.blockId,
418
+ )?.exposedBy || [])
419
+ graph.connections.push({
420
+ id: `public-exposure:${owner}:${id}`,
421
+ source: owner,
422
+ target: id,
423
+ relation: "exposes",
424
+ label: method.name,
425
+ provenance: "declared",
426
+ sourceRef: method.source,
427
+ });
428
+ return [
429
+ {
430
+ implementation: process.blockId,
431
+ interface: {
432
+ id,
433
+ parent: process.blockId,
434
+ kind: "interface",
435
+ provenance: "declared",
436
+ label: method.label || displayName(method.name),
437
+ description:
438
+ method.attachments.description ||
439
+ `Public entry to ${graph.elements.find((item) => item.id === process.blockId)!.label}.`,
440
+ source: { ...method.source, scope: "contract" },
441
+ sources: [{ ...method.source, scope: "contract" }],
442
+ signature: method.signature,
443
+ contract: {
444
+ id,
445
+ input: { language: "typescript", args: method.contract.args },
446
+ output: { language: "typescript", type: method.contract.result },
447
+ },
448
+ },
449
+ },
450
+ ];
451
+ }),
452
+ );
453
+ const result = interfaceMap(graph, entries, {
454
+ exposeAncestors: options.exposeAncestors,
455
+ validate: !options.legacySnapshot,
456
+ });
457
+ result.revision = digest(JSON.stringify({ ...result, revision: "" })).slice(
458
+ 0,
459
+ 16,
460
+ );
461
+ return result;
462
+ }
@@ -0,0 +1,82 @@
1
+ import type { SourceRef } from "./model";
2
+
3
+ export interface FactoryAttachments {
4
+ benchmarks?: string[];
5
+ docs: string[];
6
+ tests: string[];
7
+ description?: string;
8
+ /** A policy is enforced by its runtime function, not by a descriptive label. */
9
+ auth?: { symbol: string; source: SourceRef };
10
+ }
11
+ export interface FactoryBlock {
12
+ exposedBy?: string[];
13
+ inputLabel?: string;
14
+ eventLabel?: string;
15
+ id: string;
16
+ label: string;
17
+ parent?: string;
18
+ source: SourceRef;
19
+ attachments: FactoryAttachments;
20
+ }
21
+ export interface FactoryInterface {
22
+ /** A callable block or class constructor is implemented by its owning box. */
23
+ entrypoint?: boolean;
24
+ exposedBy?: string[];
25
+ constructorContract?: {
26
+ signature: string;
27
+ args: { name: string; type: string; optional: boolean; rest: boolean }[];
28
+ result: string;
29
+ };
30
+ id: string;
31
+ blockId: string;
32
+ name: string;
33
+ label?: string;
34
+ source: SourceRef;
35
+ attachments: FactoryAttachments;
36
+ methods: string[];
37
+ }
38
+ export interface FactoryMethod {
39
+ label?: string;
40
+ endpoint?: { method: string; path: string };
41
+ id: string;
42
+ blockId: string;
43
+ interfaceId?: string;
44
+ name: string;
45
+ source: SourceRef;
46
+ signature: string;
47
+ contract: {
48
+ args: { name: string; type: string; optional: boolean; rest: boolean }[];
49
+ result: string;
50
+ /** Fingerprinted type dependencies; these files are not owned executable code. */
51
+ typeSources?: SourceRef[];
52
+ /** Type information is not a claim that a runtime validator exists. */
53
+ runtimeValidation: boolean;
54
+ };
55
+ attachments: FactoryAttachments;
56
+ }
57
+ export interface FactoryProcess {
58
+ blockId: string;
59
+ entryMethodId: string;
60
+ }
61
+ export interface FactoryModel {
62
+ schema: "fractal.factory.v2";
63
+ revision: string;
64
+ blocks: FactoryBlock[];
65
+ interfaces: FactoryInterface[];
66
+ methods: FactoryMethod[];
67
+ processes: FactoryProcess[];
68
+ /** Source-backed interactions. Helpers retain their evidence without becoming boxes. */
69
+ dependencies: {
70
+ source: string;
71
+ target: string;
72
+ at: SourceRef;
73
+ relation?: "calls" | "renders" | "callbacks" | "delegates" | "exposes";
74
+ label?: string;
75
+ displayLabel?: string;
76
+ transport?: string;
77
+ via?: SourceRef[];
78
+ exchange?: { inputs: { name: string; type: string }[]; output?: string };
79
+ }[];
80
+ interactionGaps?: { source: SourceRef; expression: string; reason: string }[];
81
+ diagnostics: { file: string; line: number; message: string }[];
82
+ }