@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,277 @@
1
+ import { z } from "zod";
2
+ const sha = z.string().regex(/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/);
3
+ const id = z
4
+ .string()
5
+ .min(1)
6
+ .max(1000)
7
+ .refine((value) => !["__proto__", "constructor", "prototype"].includes(value));
8
+ const source = z.object({
9
+ file: z.string(),
10
+ line: z.number().int().positive(),
11
+ digest: z.string(),
12
+ symbol: z.string().optional(),
13
+ scope: z.literal("file").optional(),
14
+ });
15
+ const artifact = z.object({
16
+ id,
17
+ label: z.string(),
18
+ description: z.string().optional(),
19
+ source: source.optional(),
20
+ sources: z.array(source).optional(),
21
+ });
22
+ const element = z.object({
23
+ id,
24
+ label: z.string(),
25
+ kind: z.enum(["block", "interface", "method", "process"]),
26
+ parent: id.optional(),
27
+ provenance: z.enum(["declared", "source", "inferred", "observed"]),
28
+ description: z.string().optional(),
29
+ signature: z.string().optional(),
30
+ source: source.optional(),
31
+ sources: z.array(source).optional(),
32
+ hosting: z.string().optional(),
33
+ implementationBlock: id.optional(),
34
+ contract: z
35
+ .object({
36
+ id: z.string(),
37
+ input: z.unknown().optional(),
38
+ output: z.unknown().optional(),
39
+ })
40
+ .optional(),
41
+ attachments: z
42
+ .object({
43
+ docs: z.array(z.string()),
44
+ tests: z.array(z.string()),
45
+ benchmarks: z.array(z.string()).optional(),
46
+ description: z.string().optional(),
47
+ auth: z.object({ symbol: z.string(), source }).optional(),
48
+ })
49
+ .optional(),
50
+ resources: z.array(artifact).optional(),
51
+ outputs: z.array(artifact).optional(),
52
+ });
53
+ const edge = z.object({
54
+ id,
55
+ source: id,
56
+ target: id,
57
+ relation: z.enum([
58
+ "exposes",
59
+ "flows",
60
+ "calls",
61
+ "renders",
62
+ "callbacks",
63
+ "delegates",
64
+ "resumes",
65
+ "requires",
66
+ "reads",
67
+ "writes",
68
+ "produces",
69
+ "loads",
70
+ ]),
71
+ label: z.string(),
72
+ displayLabel: z.string().optional(),
73
+ provenance: z.enum(["declared", "source", "inferred", "observed"]),
74
+ sourceRef: source.optional(),
75
+ sources: z.array(source).optional(),
76
+ transport: z.string().optional(),
77
+ bidirectional: z.boolean().optional(),
78
+ condition: z.string().optional(),
79
+ overview: z.boolean().optional(),
80
+ artifacts: z.array(artifact).optional(),
81
+ exchange: z
82
+ .object({
83
+ inputs: z.array(z.object({ name: z.string(), type: z.string() })),
84
+ output: z.string().optional(),
85
+ })
86
+ .optional(),
87
+ });
88
+ const kind = z.enum(["added", "removed", "modified"]);
89
+ const schema = z.object({
90
+ schema: z.literal("fractal.comparison.v1"),
91
+ context: z
92
+ .object({
93
+ title: z.string().max(500),
94
+ url: z
95
+ .string()
96
+ .url()
97
+ .refine((url) => url.startsWith("https://"))
98
+ .optional(),
99
+ })
100
+ .optional(),
101
+ before: z.object({ commit: sha, id: z.string(), at: z.string() }),
102
+ after: z.object({ commit: sha, id: z.string(), at: z.string() }),
103
+ graph: z.object({
104
+ schema: z.literal("fractal.definition.v1"),
105
+ id,
106
+ revision: z.string(),
107
+ codeRevision: sha.optional(),
108
+ generatedAt: z.string(),
109
+ scope: z.string(),
110
+ basis: z.literal("repository-review").optional(),
111
+ elements: z.array(element).max(20000),
112
+ connections: z.array(edge).max(100000),
113
+ tests: z
114
+ .array(z.object({
115
+ id,
116
+ name: z.string(),
117
+ source,
118
+ targets: z.array(id),
119
+ association: z.enum(["imports", "contract-reference", "attachment"]),
120
+ status: z.literal("not_run"),
121
+ }))
122
+ .max(20000),
123
+ failures: z.array(z.unknown()).transform(() => []),
124
+ gaps: z.array(z.unknown()).transform(() => []),
125
+ }),
126
+ elements: z.record(id, z.object({
127
+ kind,
128
+ fields: z.array(z.string()),
129
+ before: element.optional(),
130
+ after: element.optional(),
131
+ source: z.array(z.object({
132
+ side: z.enum(["before", "after"]),
133
+ file: z.string(),
134
+ start: z.number().int().nonnegative(),
135
+ count: z.number().int().nonnegative(),
136
+ digest: z.string().max(128).optional(),
137
+ matches: z.array(z.object({ status: z.string(), elementIds: z.array(id) })),
138
+ })),
139
+ })),
140
+ connections: z.record(id, z.object({ kind, before: edge.optional(), after: edge.optional() })),
141
+ marks: z.record(id, z.object({
142
+ kind,
143
+ added: z.number().nonnegative(),
144
+ removed: z.number().nonnegative(),
145
+ modified: z.number().nonnegative(),
146
+ own: z.boolean(),
147
+ connections: z.number().nonnegative().optional(),
148
+ })),
149
+ summary: z.object({
150
+ added: z.number(),
151
+ removed: z.number(),
152
+ modified: z.number(),
153
+ interfaces: z.number(),
154
+ connections: z.number(),
155
+ }),
156
+ evidence: z.object({
157
+ source: z.enum(["git-hunks", "unavailable"]),
158
+ ambiguous: z.number(),
159
+ unmapped: z.number(),
160
+ snapshotGaps: z.number(),
161
+ }),
162
+ range: z
163
+ .object({
164
+ base: sha,
165
+ head: sha,
166
+ mode: z.enum(["commits", "pr"]),
167
+ mergeBase: sha.optional(),
168
+ })
169
+ .optional(),
170
+ });
171
+ /** CI reports contain data only. Strip unknown fields and never execute imported code. */
172
+ export function readComparisonReport(value) {
173
+ const result = schema.parse(value);
174
+ const ids = new Set(result.graph.elements.map((node) => node.id));
175
+ if (ids.size !== result.graph.elements.length || !ids.has(result.graph.id))
176
+ throw Error("Invalid factory identities in comparison report");
177
+ const byId = new Map(result.graph.elements.map((node) => [node.id, node]));
178
+ for (const node of byId.values()) {
179
+ let current = node;
180
+ const seen = new Set();
181
+ while (current) {
182
+ if (seen.has(current.id))
183
+ throw Error("Cyclic block nesting in report");
184
+ seen.add(current.id);
185
+ if (seen.size > 128)
186
+ throw Error("Block nesting exceeds the report depth limit");
187
+ if (current.parent && !ids.has(current.parent))
188
+ throw Error("Missing parent in report");
189
+ current = byId.get(current.parent || "");
190
+ }
191
+ }
192
+ if (result.graph.connections.some((connection) => !ids.has(connection.source) || !ids.has(connection.target)))
193
+ throw Error("Missing connection endpoint in report");
194
+ if (Object.keys(result.elements).some((key) => !ids.has(key)) ||
195
+ Object.keys(result.marks).some((key) => !ids.has(key)))
196
+ throw Error("Unknown changed block in report");
197
+ return result;
198
+ }
199
+ /** File-only reports never pretend to contain a historical factory. Reuse the graph safety checks. */
200
+ export function readFootprintReport(value) {
201
+ const result = z
202
+ .object({
203
+ schema: z.literal("fractal.footprint.v1"),
204
+ mappingRevision: sha.optional(),
205
+ concepts: z
206
+ .object({
207
+ basis: z.literal("saved-code"),
208
+ historicalOwnership: z.boolean(),
209
+ unassigned: z.array(z.string().max(4000)).max(20000),
210
+ changes: z
211
+ .array(z.object({
212
+ kind: z.enum([
213
+ "implementation",
214
+ "interface",
215
+ "connection",
216
+ "mapping",
217
+ "support",
218
+ ]),
219
+ block: z.string().max(1000),
220
+ file: z.string().max(4000),
221
+ label: z.string().max(500),
222
+ before: z.string().max(1800).optional(),
223
+ after: z.string().max(1800).optional(),
224
+ connection: schema.shape.graph.shape.connections.element.optional(),
225
+ change: z.enum(["added", "removed", "modified"]).optional(),
226
+ }))
227
+ .max(100000),
228
+ })
229
+ .optional(),
230
+ graph: schema.shape.graph,
231
+ base: sha,
232
+ head: sha,
233
+ title: z.string().max(500).optional(),
234
+ url: z
235
+ .string()
236
+ .url()
237
+ .refine((url) => url.startsWith("https://"))
238
+ .optional(),
239
+ files: z
240
+ .array(z.object({
241
+ path: z.string().min(1).max(4000),
242
+ status: z.enum(["added", "removed", "modified"]),
243
+ digest: z.string().max(150).optional(),
244
+ }))
245
+ .max(20000),
246
+ })
247
+ .parse(value);
248
+ readComparisonReport({
249
+ schema: "fractal.comparison.v1",
250
+ before: { commit: result.base, id: "validation", at: "" },
251
+ after: { commit: result.head, id: "validation", at: "" },
252
+ graph: result.graph,
253
+ elements: {},
254
+ connections: {},
255
+ marks: {},
256
+ summary: {
257
+ added: 0,
258
+ removed: 0,
259
+ modified: 0,
260
+ interfaces: 0,
261
+ connections: 0,
262
+ },
263
+ evidence: {
264
+ source: "unavailable",
265
+ ambiguous: 0,
266
+ unmapped: 0,
267
+ snapshotGaps: 0,
268
+ },
269
+ });
270
+ if (result.mappingRevision &&
271
+ (result.mappingRevision !== result.head ||
272
+ result.graph.codeRevision !== result.head))
273
+ throw Error("Source review must identify the same head revision as its source graph");
274
+ if (new Set(result.files.map((file) => file.path)).size !== result.files.length)
275
+ throw Error("Duplicate footprint paths");
276
+ return result;
277
+ }
@@ -0,0 +1,81 @@
1
+ import type { CodeSnapshot } from "./code-model.js";
2
+ import type { Connection, Element, DefinitionGraph } from "./model.js";
3
+ export type ChangeKind = "added" | "removed" | "modified";
4
+ export type SourceChange = {
5
+ /** Hash of the hunk body; review progress survives unrelated commits without storing raw code. */
6
+ digest?: string;
7
+ attachments?: {
8
+ file: string;
9
+ kind: "notes" | "tests" | "auth";
10
+ elementId: string;
11
+ }[];
12
+ side: "before" | "after";
13
+ file: string;
14
+ start: number;
15
+ count: number;
16
+ matches: {
17
+ status: string;
18
+ elementIds: string[];
19
+ }[];
20
+ };
21
+ export type ElementChange = {
22
+ kind: ChangeKind;
23
+ fields: string[];
24
+ before?: Element;
25
+ after?: Element;
26
+ source: SourceChange[];
27
+ };
28
+ export type ConnectionChange = {
29
+ kind: ChangeKind;
30
+ before?: Connection;
31
+ after?: Connection;
32
+ };
33
+ export interface FactoryComparison {
34
+ schema: "fractal.comparison.v1";
35
+ context?: {
36
+ title: string;
37
+ url?: string;
38
+ };
39
+ before: {
40
+ commit: string;
41
+ id: string;
42
+ at: string;
43
+ };
44
+ after: {
45
+ commit: string;
46
+ id: string;
47
+ at: string;
48
+ };
49
+ graph: DefinitionGraph;
50
+ elements: Record<string, ElementChange>;
51
+ connections: Record<string, ConnectionChange>;
52
+ marks: Record<string, {
53
+ kind: ChangeKind;
54
+ added: number;
55
+ removed: number;
56
+ modified: number;
57
+ own: boolean;
58
+ connections?: number;
59
+ }>;
60
+ summary: {
61
+ added: number;
62
+ removed: number;
63
+ modified: number;
64
+ interfaces: number;
65
+ connections: number;
66
+ };
67
+ evidence: {
68
+ source: "git-hunks" | "unavailable";
69
+ ambiguous: number;
70
+ unmapped: number;
71
+ snapshotGaps: number;
72
+ };
73
+ range?: {
74
+ base: string;
75
+ head: string;
76
+ mode: "commits" | "pr";
77
+ mergeBase?: string;
78
+ };
79
+ }
80
+ export declare function compareFactory(before: CodeSnapshot, after: CodeSnapshot, sourceChanges?: SourceChange[]): FactoryComparison;
81
+ export declare function comparisonReport(comparison: FactoryComparison): string;
@@ -0,0 +1,291 @@
1
+ import { logicalMap } from "./map-model.js";
2
+ import { graphIndex } from "./change-impact.js";
3
+ // Locations and whole-file hashes are evidence, not conceptual changes. Arrays
4
+ // represent unordered attachments/members here; argument order stays explicit.
5
+ function semantic(value) {
6
+ if (Array.isArray(value))
7
+ return value.map(semantic);
8
+ if (!value || typeof value !== "object")
9
+ return value;
10
+ return Object.fromEntries(Object.entries(value)
11
+ .filter(([key]) => ![
12
+ "source",
13
+ "sources",
14
+ "sourceRef",
15
+ "digest",
16
+ "line",
17
+ "definitionRevision",
18
+ "typeSources",
19
+ ].includes(key))
20
+ .sort(([a], [b]) => a.localeCompare(b))
21
+ .map(([key, item]) => [key, semantic(item)]));
22
+ }
23
+ const equal = (a, b) => JSON.stringify(semantic(a)) === JSON.stringify(semantic(b));
24
+ const set = (values) => [...new Set(values.map((value) => JSON.stringify(semantic(value))))].sort();
25
+ const types = (value) => {
26
+ if (!value || typeof value !== "object")
27
+ return [];
28
+ if (Array.isArray(value))
29
+ return value.flatMap(types);
30
+ return Object.entries(value).flatMap(([key, item]) => key === "typeSources" && Array.isArray(item)
31
+ ? item.map((source) => `${source.file}:${source.digest}`).sort()
32
+ : types(item));
33
+ };
34
+ const contract = (node) => {
35
+ const input = node.contract?.input;
36
+ if (input &&
37
+ typeof input === "object" &&
38
+ "members" in input &&
39
+ Array.isArray(input.members))
40
+ return {
41
+ ...node.contract,
42
+ input: {
43
+ ...input,
44
+ members: [...input.members].sort((a, b) => String(a.name).localeCompare(String(b.name))),
45
+ },
46
+ };
47
+ return node.contract;
48
+ };
49
+ const connectionKey = (edge) => JSON.stringify([
50
+ edge.source,
51
+ edge.target,
52
+ edge.relation,
53
+ ["callbacks", "delegates"].includes(edge.relation) ? edge.label : "",
54
+ ]);
55
+ function conceptualConnections(graph) {
56
+ const groups = new Map();
57
+ for (const edge of graph.connections) {
58
+ const key = connectionKey(edge);
59
+ groups.set(key, [...(groups.get(key) || []), edge]);
60
+ }
61
+ return new Map([...groups].map(([key, edges]) => [
62
+ key,
63
+ {
64
+ ...edges[0],
65
+ id: key,
66
+ members: edges,
67
+ sources: edges.flatMap((edge) => edge.sources || (edge.sourceRef ? [edge.sourceRef] : [])),
68
+ exchange: edges.find((edge) => edge.exchange)?.exchange,
69
+ },
70
+ ]));
71
+ }
72
+ export function compareFactory(before, after, sourceChanges) {
73
+ if (!before.commit || !after.commit)
74
+ throw Error("Compare two committed revisions; a dirty checkout is not HEAD.");
75
+ const left = logicalMap(before.graph), right = logicalMap(after.graph);
76
+ if (left.id !== right.id)
77
+ throw Error("These snapshots describe different factories.");
78
+ const a = new Map(left.elements.map((node) => [node.id, node])), b = new Map(right.elements.map((node) => [node.id, node]));
79
+ const elements = {};
80
+ for (const id of new Set([...a.keys(), ...b.keys()])) {
81
+ const old = a.get(id), next = b.get(id);
82
+ const source = (sourceChanges || []).filter((change) => change.matches.some((match) => match.elementIds.some((owner) => (change.side === "before"
83
+ ? left.aliases?.[owner]
84
+ : right.aliases?.[owner]) === id || owner === id)));
85
+ const shared = (sourceChanges || []).filter((change) => change.matches.some((match) => match.status === "unmapped") &&
86
+ (change.side === "before" ? left : right).connections.some((edge) => edge.source === id &&
87
+ edge.id.startsWith("call-site:") &&
88
+ (edge.sources || (edge.sourceRef ? [edge.sourceRef] : [])).some((ref) => ref.file === change.file)));
89
+ const attached = (sourceChanges || []).filter((change) => change.attachments?.some((item) => item.elementId === id));
90
+ if (!old || !next) {
91
+ elements[id] = {
92
+ kind: old ? "removed" : "added",
93
+ fields: [],
94
+ before: old,
95
+ after: next,
96
+ source: [...new Set([...source, ...shared, ...attached])],
97
+ };
98
+ continue;
99
+ }
100
+ const fields = [];
101
+ for (const [label, one, two] of [
102
+ ["Name", old.label, next.label],
103
+ ["Placement", old.parent, next.parent],
104
+ ["Kind", old.kind, next.kind],
105
+ ["Contract", contract(old), contract(next)],
106
+ [
107
+ "Purpose",
108
+ old.description || old.attachments?.description,
109
+ next.description || next.attachments?.description,
110
+ ],
111
+ ["Auth", old.attachments?.auth?.symbol, next.attachments?.auth?.symbol],
112
+ [
113
+ "Notes",
114
+ set(old.attachments?.docs || []),
115
+ set(next.attachments?.docs || []),
116
+ ],
117
+ ["Resources", set(old.resources || []), set(next.resources || [])],
118
+ ["Benchmarks", set(old.attachments?.benchmarks || []), set(next.attachments?.benchmarks || [])],
119
+ [
120
+ "Tests",
121
+ set(left.tests
122
+ .filter((test) => test.targets.includes(id))
123
+ .map((test) => ({
124
+ file: test.source.file,
125
+ association: test.association,
126
+ }))),
127
+ set(right.tests
128
+ .filter((test) => test.targets.includes(id))
129
+ .map((test) => ({
130
+ file: test.source.file,
131
+ association: test.association,
132
+ }))),
133
+ ],
134
+ ])
135
+ if (!equal(one, two))
136
+ fields.push(label);
137
+ if (!equal([...new Set(types(old.contract))].sort(), [...new Set(types(next.contract))].sort()))
138
+ fields.push("Contract types");
139
+ if (source.length)
140
+ fields.push("Code");
141
+ if (shared.length)
142
+ fields.push("Shared source");
143
+ for (const [kind, label] of [
144
+ ["notes", "Notes"],
145
+ ["tests", "Tests"],
146
+ ["auth", "Auth source"],
147
+ ])
148
+ if (attached.some((change) => change.attachments?.some((item) => item.elementId === id && item.kind === kind)) &&
149
+ !fields.includes(label))
150
+ fields.push(label);
151
+ if (fields.length)
152
+ elements[id] = {
153
+ kind: "modified",
154
+ fields,
155
+ before: old,
156
+ after: next,
157
+ source: [...new Set([...source, ...shared, ...attached])],
158
+ };
159
+ }
160
+ const oldEdges = conceptualConnections(left), newEdges = conceptualConnections(right);
161
+ const connections = {}, union = [];
162
+ for (const key of new Set([...oldEdges.keys(), ...newEdges.keys()])) {
163
+ const old = oldEdges.get(key), next = newEdges.get(key);
164
+ // Public IDs and source line movements are deliberately excluded.
165
+ const shape = (edge) => ({
166
+ label: edge.label,
167
+ displayLabel: edge.displayLabel,
168
+ exchange: edge.exchange,
169
+ artifacts: edge.artifacts,
170
+ transport: edge.transport,
171
+ bidirectional: edge.bidirectional,
172
+ condition: edge.condition,
173
+ variants: set((edge.members || [edge]).map((member) => ({
174
+ label: member.label,
175
+ exchange: member.exchange,
176
+ artifacts: member.artifacts,
177
+ transport: member.transport,
178
+ }))),
179
+ });
180
+ const id = `comparison:${key}`;
181
+ union.push({ ...(next || old), id, members: undefined });
182
+ if (!old || !next)
183
+ connections[id] = {
184
+ kind: old ? "removed" : "added",
185
+ before: old,
186
+ after: next,
187
+ };
188
+ else if (!equal(shape(old), shape(next)))
189
+ connections[id] = { kind: "modified", before: old, after: next };
190
+ }
191
+ const graph = {
192
+ ...right,
193
+ revision: `compare:${before.id}:${after.id}`,
194
+ elements: [
195
+ ...right.elements,
196
+ ...left.elements.filter((node) => !b.has(node.id)),
197
+ ],
198
+ connections: union,
199
+ tests: [],
200
+ failures: [],
201
+ gaps: [...left.gaps, ...right.gaps],
202
+ };
203
+ const { byId, within } = graphIndex(graph);
204
+ const { within: wasWithin } = graphIndex(left);
205
+ const marks = {};
206
+ for (const node of graph.elements) {
207
+ const changes = Object.entries(elements).filter(([id]) => within(id, node.id) || wasWithin(id, node.id));
208
+ if (!changes.length)
209
+ continue;
210
+ const added = changes.filter(([, change]) => change.kind === "added").length, removed = changes.filter(([, change]) => change.kind === "removed").length, modified = changes.filter(([, change]) => change.kind === "modified").length;
211
+ marks[node.id] = {
212
+ kind: elements[node.id]?.kind || "modified",
213
+ added,
214
+ removed,
215
+ modified,
216
+ own: !!elements[node.id],
217
+ };
218
+ }
219
+ // Count a wire once per containing block, even when both endpoints are inside.
220
+ for (const change of Object.values(connections)) {
221
+ const reached = new Set();
222
+ for (const endpoint of [
223
+ change.after?.source || change.before.source,
224
+ change.after?.target || change.before.target,
225
+ ]) {
226
+ let node = byId.get(endpoint);
227
+ const seen = new Set();
228
+ while (node && !seen.has(node.id)) {
229
+ seen.add(node.id);
230
+ if (!reached.has(node.id)) {
231
+ reached.add(node.id);
232
+ const mark = (marks[node.id] ||= {
233
+ kind: "modified",
234
+ added: 0,
235
+ removed: 0,
236
+ modified: 0,
237
+ own: false,
238
+ });
239
+ mark.connections = (mark.connections || 0) + 1;
240
+ }
241
+ node = byId.get(node.parent || "");
242
+ }
243
+ }
244
+ }
245
+ const values = Object.values(elements);
246
+ return {
247
+ schema: "fractal.comparison.v1",
248
+ before: { commit: before.commit, id: before.id, at: before.capturedAt },
249
+ after: { commit: after.commit, id: after.id, at: after.capturedAt },
250
+ graph,
251
+ elements,
252
+ connections,
253
+ marks,
254
+ summary: {
255
+ added: values.filter((change) => change.kind === "added").length,
256
+ removed: values.filter((change) => change.kind === "removed").length,
257
+ modified: values.filter((change) => change.kind === "modified").length,
258
+ interfaces: values.filter((change) => (change.after || change.before)?.kind === "interface").length,
259
+ connections: Object.keys(connections).length,
260
+ },
261
+ evidence: {
262
+ source: sourceChanges ? "git-hunks" : "unavailable",
263
+ ambiguous: (sourceChanges || []).filter((change) => change.matches.some((match) => match.status === "ambiguous")).length,
264
+ unmapped: (sourceChanges || []).filter((change) => !change.attachments?.length &&
265
+ change.matches.some((match) => match.status === "unmapped")).length,
266
+ snapshotGaps: before.gaps.length + after.gaps.length,
267
+ },
268
+ };
269
+ }
270
+ export function comparisonReport(comparison) {
271
+ const { summary } = comparison;
272
+ const escape = (value) => value.replace(/[\r\n]/g, " ").replace(/[\\`*_[\]<>|]/g, "\\$&");
273
+ const entries = Object.entries(comparison.elements);
274
+ const preferred = entries.filter(([, change]) => (change.after || change.before)?.kind !== "method");
275
+ const shown = (preferred.length ? preferred : entries).slice(0, 40);
276
+ return [
277
+ `# Factory comparison`,
278
+ ``,
279
+ `${comparison.before.commit} → ${comparison.after.commit}`,
280
+ ``,
281
+ `+${summary.added} added · −${summary.removed} removed · ${summary.modified} changed · ${summary.interfaces} interfaces · ${summary.connections} connections`,
282
+ ``,
283
+ ...shown.map(([id, change]) => `- ${change.kind}: ${escape((change.after || change.before).label)}${change.fields.length ? ` (${change.fields.join(", ")})` : ""} — \`${escape(id)}\``),
284
+ ``,
285
+ ...(entries.length > shown.length
286
+ ? [`Open the report for all ${entries.length} changed parts.`]
287
+ : []),
288
+ `Code changes use captured source ownership. Contract changes are not automatic proof of compatibility.`,
289
+ ``,
290
+ ].join("\n");
291
+ }
@@ -0,0 +1,10 @@
1
+ import type { FactoryModel } from "./factory-model.js";
2
+ /** Incremental build entry discovery: inspect source text, never import app modules. */
3
+ export declare function annotatedFiles(root: string, directories?: string[]): string[];
4
+ export declare function compileFactory(options: {
5
+ root: string;
6
+ files: string[];
7
+ /** Canonical annotation source shipped beside the standalone desktop CLI. */
8
+ sdkSource?: string;
9
+ }): FactoryModel;
10
+ export { factoryGraph } from "./factory-graph.js";