@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,185 @@
1
+ import type { DefinitionGraph } from "./model.js";
2
+ import type { ActivityCell } from "./map-activity.js";
3
+ import type { TimeWindow } from "./time-window.js";
4
+ export interface MetricBoundary {
5
+ target: string;
6
+ caller?: string;
7
+ calls: number;
8
+ callsKnown?: boolean;
9
+ errors: number;
10
+ buckets: {
11
+ le: number;
12
+ count: number;
13
+ }[];
14
+ trend: {
15
+ at: number;
16
+ value: number;
17
+ }[];
18
+ failedTrend?: {
19
+ at: number;
20
+ value: number;
21
+ }[];
22
+ latencyTrend?: {
23
+ at: number;
24
+ buckets: {
25
+ le: number;
26
+ count: number;
27
+ }[];
28
+ }[];
29
+ }
30
+ export interface MetricGauge {
31
+ id: string;
32
+ label: string;
33
+ unit: string;
34
+ aggregation: "sum" | "max";
35
+ description?: string;
36
+ chart?: "line" | "bar";
37
+ sources?: {
38
+ block: string;
39
+ query: string;
40
+ }[];
41
+ status?: "ready" | "empty" | "error";
42
+ error?: string;
43
+ values: {
44
+ block: string;
45
+ value: number;
46
+ trend: {
47
+ at: number;
48
+ value: number;
49
+ }[];
50
+ }[];
51
+ }
52
+ export interface RuntimeMetrics {
53
+ source: "prometheus";
54
+ configured: boolean;
55
+ window: TimeWindow;
56
+ environment: string;
57
+ checkedAt: string;
58
+ lastSampleAt?: string;
59
+ boundaries: MetricBoundary[];
60
+ gauges: MetricGauge[];
61
+ warnings: string[];
62
+ }
63
+ export interface BlockMetric {
64
+ callsKnown?: boolean;
65
+ failedTrend?: {
66
+ at: number;
67
+ value: number;
68
+ }[];
69
+ latencyTrend?: {
70
+ at: number;
71
+ value: number;
72
+ }[];
73
+ calls: number;
74
+ errors: number;
75
+ errorRate: number | null;
76
+ p95Ms: number | null;
77
+ buckets: {
78
+ le: number;
79
+ count: number;
80
+ }[];
81
+ trend: {
82
+ at: number;
83
+ value: number;
84
+ }[];
85
+ }
86
+ export declare function histogramPercentile(buckets: {
87
+ le: number;
88
+ count: number;
89
+ }[], q?: number): number | null;
90
+ export declare function metricRollup(graph: DefinitionGraph, source: RuntimeMetrics): {
91
+ blocks: Record<string, BlockMetric>;
92
+ links: Record<string, {
93
+ count: number;
94
+ label: string;
95
+ }>;
96
+ gauges: Record<string, Record<string, {
97
+ value: number;
98
+ trend: {
99
+ at: number;
100
+ value: number;
101
+ }[];
102
+ }>>;
103
+ unmapped: number;
104
+ };
105
+ export declare function formatNumber(value: number): string;
106
+ export declare function durationLabel(ms: number): string;
107
+ export declare function metricCells(graph: DefinitionGraph, source: RuntimeMetrics, metric: string): {
108
+ blocks: Record<string, BlockMetric>;
109
+ links: Record<string, {
110
+ count: number;
111
+ label: string;
112
+ }>;
113
+ gauges: Record<string, Record<string, {
114
+ value: number;
115
+ trend: {
116
+ at: number;
117
+ value: number;
118
+ }[];
119
+ }>>;
120
+ unmapped: number;
121
+ cells: Record<string, ActivityCell>;
122
+ };
123
+ export interface BenchmarkCase {
124
+ name: string;
125
+ samples: number;
126
+ meanMs: number;
127
+ marginMs: number;
128
+ p95Ms: number;
129
+ hz: number;
130
+ attemptsMs?: number[];
131
+ attemptPhases?: Record<string, number>[];
132
+ }
133
+ export interface BenchmarkRun {
134
+ runnerPid?: number;
135
+ heartbeatAt?: number;
136
+ kind?: "function" | "operation";
137
+ fixture?: string;
138
+ fixtureVersion?: string;
139
+ fixtureDescription?: string;
140
+ target?: {
141
+ name: string;
142
+ url: string;
143
+ revision: string;
144
+ measurement: "client" | "server";
145
+ };
146
+ id: string;
147
+ file: string;
148
+ blockIds: string[];
149
+ at: string;
150
+ status: "queued" | "running" | "passed" | "failed";
151
+ commit: string | null;
152
+ baseCommit: string;
153
+ codeDigest: string;
154
+ scenario: string;
155
+ environment: string;
156
+ machine: string;
157
+ cases: BenchmarkCase[];
158
+ output: string;
159
+ error?: string;
160
+ durationMs?: number;
161
+ }
162
+ export interface BenchmarkView {
163
+ plans: {
164
+ file: string;
165
+ blocks: string[];
166
+ label: string;
167
+ kind?: "function" | "operation";
168
+ fixture?: string;
169
+ description?: string;
170
+ startsWhen?: string;
171
+ endsWhen?: string;
172
+ attempts?: number;
173
+ }[];
174
+ runs: BenchmarkRun[];
175
+ baselines: Record<string, string>;
176
+ }
177
+ /** A reason is preferable to silently comparing unrelated workloads or a run with itself. */
178
+ export declare function benchmarkComparisonReason(current: BenchmarkRun, baseline: BenchmarkRun | undefined, name: string): string | undefined;
179
+ export declare function benchmarkReference(view: BenchmarkView, current: BenchmarkRun): BenchmarkRun | undefined;
180
+ export declare function compareBenchmark(current: BenchmarkRun, baseline: BenchmarkRun | undefined, name: string): {
181
+ readonly percent: number;
182
+ readonly significant: boolean;
183
+ readonly direction: "slower" | "faster" | "similar";
184
+ } | null;
185
+ export declare function benchmarkCells(graph: DefinitionGraph, view: BenchmarkView): Record<string, ActivityCell>;
@@ -0,0 +1,396 @@
1
+ export function histogramPercentile(buckets, q = 0.95) {
2
+ const sorted = [...buckets].sort((a, b) => a.le - b.le);
3
+ const total = sorted.at(-1)?.count || 0;
4
+ if (!(total > 0) ||
5
+ sorted.some((bucket, i) => bucket.count < (sorted[i - 1]?.count || 0)))
6
+ return null;
7
+ let previous = 0, lower = 0;
8
+ for (const bucket of sorted) {
9
+ if (bucket.count >= total * q) {
10
+ if (!Number.isFinite(bucket.le) || bucket.le === Number.MAX_VALUE)
11
+ return null;
12
+ return (lower +
13
+ ((bucket.le - lower) * (total * q - previous)) /
14
+ Math.max(1e-12, bucket.count - previous));
15
+ }
16
+ previous = bucket.count;
17
+ lower = bucket.le;
18
+ }
19
+ return null;
20
+ }
21
+ function mergeBuckets(rows) {
22
+ if (!rows.length)
23
+ return [];
24
+ rows = rows.map((row) => ({
25
+ ...row,
26
+ buckets: [...row.buckets].sort((a, b) => a.le - b.le),
27
+ }));
28
+ const first = rows[0].buckets.map((bucket) => bucket.le).join(",");
29
+ if (rows.some((row) => row.buckets.map((bucket) => bucket.le).join(",") !== first))
30
+ return [];
31
+ return rows[0].buckets.map((bucket, i) => ({
32
+ le: bucket.le,
33
+ count: rows.reduce((sum, row) => sum + row.buckets[i].count, 0),
34
+ }));
35
+ }
36
+ export function metricRollup(graph, source) {
37
+ const byId = new Map(graph.elements.map((node) => [node.id, node]));
38
+ const identity = (id) => (id ? graph.aliases?.[id] || id : "");
39
+ const ancestry = new Map();
40
+ const ancestors = (id) => {
41
+ if (ancestry.has(id))
42
+ return ancestry.get(id);
43
+ const result = new Set();
44
+ let node = byId.get(identity(id));
45
+ while (node && !result.has(node.id)) {
46
+ result.add(node.id);
47
+ node = byId.get(node.parent || "");
48
+ }
49
+ ancestry.set(id, result);
50
+ return result;
51
+ };
52
+ const entries = new Map();
53
+ let unmapped = 0;
54
+ for (const row of source.boundaries) {
55
+ const target = ancestors(row.target), caller = ancestors(row.caller || "");
56
+ if (!target.size) {
57
+ unmapped++;
58
+ continue;
59
+ }
60
+ for (const id of target)
61
+ if (!caller.has(id))
62
+ entries.set(id, [...(entries.get(id) || []), row]);
63
+ }
64
+ const blocks = {};
65
+ for (const [id, rows] of entries) {
66
+ const calls = rows.reduce((sum, row) => sum + row.calls, 0), errors = rows.reduce((sum, row) => sum + row.errors, 0);
67
+ const buckets = mergeBuckets(rows), points = new Map();
68
+ for (const row of rows)
69
+ for (const point of row.trend)
70
+ points.set(point.at, (points.get(point.at) || 0) + point.value);
71
+ const failed = new Map();
72
+ const latency = new Map();
73
+ for (const row of rows) {
74
+ for (const point of row.failedTrend || [])
75
+ failed.set(point.at, (failed.get(point.at) || 0) + point.value);
76
+ for (const point of row.latencyTrend || [])
77
+ latency.set(point.at, [
78
+ ...(latency.get(point.at) || []),
79
+ { ...row, buckets: point.buckets },
80
+ ]);
81
+ }
82
+ blocks[id] = {
83
+ failedTrend: [...points]
84
+ .flatMap(([at, calls]) => calls > 0
85
+ ? [{ at, value: (100 * (failed.get(at) || 0)) / calls }]
86
+ : [])
87
+ .sort((a, b) => a.at - b.at),
88
+ latencyTrend: [...latency]
89
+ .flatMap(([at, rows]) => {
90
+ const value = rows.length === entries.get(id)?.length
91
+ ? histogramPercentile(mergeBuckets(rows))
92
+ : null;
93
+ return value === null ? [] : [{ at, value: value * 1000 }];
94
+ })
95
+ .sort((a, b) => a.at - b.at),
96
+ calls,
97
+ errors,
98
+ callsKnown: rows.every((row) => row.callsKnown !== false),
99
+ errorRate: rows.every((row) => row.callsKnown !== false) && calls > 0
100
+ ? (errors / calls) * 100
101
+ : null,
102
+ p95Ms: histogramPercentile(buckets) === null
103
+ ? null
104
+ : histogramPercentile(buckets) * 1000,
105
+ buckets,
106
+ trend: [...points]
107
+ .map(([at, value]) => ({ at, value }))
108
+ .sort((a, b) => a.at - b.at),
109
+ };
110
+ }
111
+ const links = {};
112
+ const pairKey = (caller, target) => JSON.stringify([caller, target]);
113
+ const pairs = new Map();
114
+ for (const row of source.boundaries) {
115
+ const key = pairKey(identity(row.caller), identity(row.target));
116
+ pairs.set(key, (pairs.get(key) || 0) + row.calls);
117
+ }
118
+ const assigned = new Set();
119
+ for (const edge of graph.connections) {
120
+ if (edge.relation !== "calls")
121
+ continue;
122
+ const key = pairKey(edge.source, edge.target);
123
+ if (assigned.has(key))
124
+ continue;
125
+ assigned.add(key);
126
+ // Counters identify boundary pairs, not individual source call sites.
127
+ // Assign once so collapsed duplicate call sites cannot multiply traffic.
128
+ const count = pairs.get(key) || 0;
129
+ if (count > 0)
130
+ links[edge.id] = {
131
+ count,
132
+ label: `${formatNumber(count)} measured calls`,
133
+ };
134
+ }
135
+ const gauges = {};
136
+ for (const gauge of source.gauges) {
137
+ const candidates = new Map();
138
+ for (const row of gauge.values)
139
+ for (const id of ancestors(row.block))
140
+ candidates.set(id, [...(candidates.get(id) || []), row]);
141
+ gauges[gauge.id] = {};
142
+ for (const [id, rows] of candidates) {
143
+ const points = new Map();
144
+ for (const row of rows)
145
+ for (const point of row.trend)
146
+ points.set(point.at, [...(points.get(point.at) || []), point.value]);
147
+ const reduce = (values) => gauge.aggregation === "sum"
148
+ ? values.reduce((a, b) => a + b, 0)
149
+ : Math.max(...values);
150
+ gauges[gauge.id][id] = {
151
+ value: reduce(rows.map((row) => row.value)),
152
+ trend: [...points]
153
+ .filter(([, values]) => values.length === rows.length)
154
+ .map(([at, values]) => ({ at, value: reduce(values) }))
155
+ .sort((a, b) => a.at - b.at),
156
+ };
157
+ }
158
+ }
159
+ return { blocks, links, gauges, unmapped };
160
+ }
161
+ export function formatNumber(value) {
162
+ return new Intl.NumberFormat("en", {
163
+ notation: value >= 10000 ? "compact" : "standard",
164
+ ...(Math.abs(value) > 0 && Math.abs(value) < 1
165
+ ? { maximumSignificantDigits: 3 }
166
+ : { maximumFractionDigits: 1 }),
167
+ }).format(value);
168
+ }
169
+ export function durationLabel(ms) {
170
+ return ms < 1
171
+ ? `${formatNumber(ms * 1000)} µs`
172
+ : ms < 1000
173
+ ? `${formatNumber(ms)} ms`
174
+ : `${formatNumber(ms / 1000)} s`;
175
+ }
176
+ export function metricCells(graph, source, metric) {
177
+ const rolled = metricRollup(graph, source), cells = {};
178
+ if (metric === "block") {
179
+ for (const node of graph.elements) {
180
+ const measurements = source.gauges.flatMap((gauge) => {
181
+ const row = rolled.gauges[gauge.id]?.[node.id];
182
+ return row ? [{ gauge, row }] : [];
183
+ });
184
+ if (measurements.length === 1) {
185
+ const { gauge, row } = measurements[0];
186
+ cells[node.id] = {
187
+ count: row.value,
188
+ intensity: 0,
189
+ label: gauge.label,
190
+ displayValue: `${formatNumber(row.value)} ${gauge.unit}`,
191
+ summary: gauge.label,
192
+ series: row.trend.map((p) => p.value),
193
+ };
194
+ }
195
+ else if (measurements.length > 1) {
196
+ cells[node.id] = {
197
+ count: measurements.length,
198
+ intensity: 0,
199
+ label: "Measurements",
200
+ measurements: measurements.map(({ gauge, row }) => ({
201
+ label: gauge.label,
202
+ value: `${formatNumber(row.value)} ${gauge.unit}`,
203
+ series: row.trend.map((p) => p.value),
204
+ })),
205
+ displayValue: String(measurements.length),
206
+ summary: measurements
207
+ .map(({ gauge, row }) => `${gauge.label}: ${formatNumber(row.value)} ${gauge.unit}`)
208
+ .join(" · "),
209
+ };
210
+ }
211
+ }
212
+ return { cells, ...rolled };
213
+ }
214
+ const minutes = (Date.parse(source.window.to) - Date.parse(source.window.from)) / 60000;
215
+ for (const [id, row] of Object.entries(rolled.blocks)) {
216
+ if (row.callsKnown === false &&
217
+ (metric === "traffic" || metric === "errors"))
218
+ continue;
219
+ if (!["traffic", "errors", "latency"].includes(metric))
220
+ continue;
221
+ const value = metric === "traffic"
222
+ ? row.calls / minutes
223
+ : metric === "errors"
224
+ ? row.errorRate
225
+ : row.p95Ms;
226
+ if (value === null)
227
+ continue;
228
+ cells[id] = {
229
+ count: value,
230
+ intensity: 0,
231
+ displayValue: metric === "traffic"
232
+ ? `${formatNumber(value)}/min`
233
+ : metric === "errors"
234
+ ? `${formatNumber(value)}%`
235
+ : durationLabel(value),
236
+ label: metric === "traffic"
237
+ ? "calls"
238
+ : metric === "errors"
239
+ ? "failures"
240
+ : "p95",
241
+ summary: `${row.callsKnown === false ? "Unknown" : formatNumber(row.calls)} boundary calls · ${formatNumber(row.errors)} failed${metric === "latency" ? " · histogram estimate" : ""}`,
242
+ ...(metric === "traffic"
243
+ ? { series: row.trend.map((point) => point.value) }
244
+ : {}),
245
+ };
246
+ }
247
+ const gauge = source.gauges.find((item) => item.id === metric);
248
+ if (gauge)
249
+ for (const [id, row] of Object.entries(rolled.gauges[metric] || {}))
250
+ cells[id] = {
251
+ count: row.value,
252
+ intensity: 0,
253
+ displayValue: `${formatNumber(row.value)} ${gauge.unit}`,
254
+ label: gauge.label,
255
+ summary: `Latest measured gauge · ${gauge.aggregation} across distinct attached sources`,
256
+ series: row.trend.map((point) => point.value),
257
+ };
258
+ return { cells, ...rolled };
259
+ }
260
+ /** A reason is preferable to silently comparing unrelated workloads or a run with itself. */
261
+ export function benchmarkComparisonReason(current, baseline, name) {
262
+ if (!baseline)
263
+ return "Choose a reference run.";
264
+ if (current.id === baseline.id)
265
+ return "Choose two different runs.";
266
+ if (current.file !== baseline.file || current.kind !== baseline.kind)
267
+ return "Different benchmark operations.";
268
+ if (current.status !== "passed" || baseline.status !== "passed")
269
+ return "Both runs must finish successfully.";
270
+ if (current.scenario !== baseline.scenario)
271
+ return "The workload or fixture changed.";
272
+ if (current.environment !== baseline.environment)
273
+ return "Different test environment or timing conditions.";
274
+ if (current.target?.url !== baseline.target?.url ||
275
+ current.target?.measurement !== baseline.target?.measurement)
276
+ return "Different deployment target or timing source.";
277
+ const value = current.cases.find((item) => item.name === name), before = baseline.cases.find((item) => item.name === name);
278
+ if (!value || !before)
279
+ return "This measurement is missing from one run.";
280
+ if (value.samples < (current.kind === "operation" ? 3 : 20) ||
281
+ before.samples < (current.kind === "operation" ? 3 : 20))
282
+ return "Too few successful samples to compare.";
283
+ if (!(before.meanMs > 0))
284
+ return "The reference duration must be greater than zero.";
285
+ }
286
+ export function benchmarkReference(view, current) {
287
+ const name = current.cases[0]?.name || "";
288
+ const pinned = view.runs.find((run) => run.id === view.baselines[current.file]);
289
+ if (pinned && !benchmarkComparisonReason(current, pinned, name))
290
+ return pinned;
291
+ return view.runs.find((run) => run.at < current.at && !benchmarkComparisonReason(current, run, name));
292
+ }
293
+ export function compareBenchmark(current, baseline, name) {
294
+ const value = current.cases.find((item) => item.name === name), before = baseline?.cases.find((item) => item.name === name);
295
+ if (benchmarkComparisonReason(current, baseline, name) || !value || !before)
296
+ return null;
297
+ const percent = (value.meanMs / before.meanMs - 1) * 100;
298
+ const slower = value.meanMs - value.marginMs > before.meanMs + before.marginMs;
299
+ const faster = value.meanMs + value.marginMs < before.meanMs - before.marginMs;
300
+ return {
301
+ percent,
302
+ significant: (percent > 5 && slower) || (percent < -5 && faster),
303
+ direction: slower && percent > 5
304
+ ? "slower"
305
+ : faster && percent < -5
306
+ ? "faster"
307
+ : "similar",
308
+ };
309
+ }
310
+ export function benchmarkCells(graph, view) {
311
+ const byId = new Map(graph.elements.map((n) => [n.id, n]));
312
+ const owned = new Map();
313
+ for (const plan of view.plans.filter((p) => p.kind === "operation")) {
314
+ const history = view.runs.filter((r) => r.file === plan.file), latest = history[0], passing = history.find((r) => r.status === "passed");
315
+ const reference = passing ? benchmarkReference(view, passing) : undefined;
316
+ const cases = passing?.cases.length ? passing.cases : [undefined];
317
+ for (const item of cases) {
318
+ const change = passing && item
319
+ ? compareBenchmark(passing, reference, item.name)
320
+ : null;
321
+ const pending = latest && ["running", "queued", "failed"].includes(latest.status);
322
+ const row = {
323
+ label: item?.name || plan.label,
324
+ value: pending
325
+ ? latest.status === "failed"
326
+ ? "Failed"
327
+ : "Running"
328
+ : item
329
+ ? durationLabel(item.meanMs)
330
+ : "Not run",
331
+ count: pending ? 0 : item?.meanMs || 0,
332
+ series: pending
333
+ ? []
334
+ : history
335
+ .filter((r) => r.status === "passed" &&
336
+ r.environment === passing?.environment &&
337
+ r.scenario === passing.scenario)
338
+ .slice(0, 24)
339
+ .reverse()
340
+ .flatMap((r) => r.cases
341
+ .filter((c) => c.name === item?.name)
342
+ .map((c) => c.meanMs)),
343
+ tone: (pending && latest.status === "failed"
344
+ ? "regression"
345
+ : change?.direction === "slower"
346
+ ? "regression"
347
+ : change?.direction === "faster"
348
+ ? "improvement"
349
+ : "neutral"),
350
+ summary: pending
351
+ ? latest.error || `Measuring ${plan.label}`
352
+ : item
353
+ ? `${item.name} · mean of ${item.samples} attempts · deployed ${passing?.target?.revision.slice(0, 8) || "revision unknown"}${change ? ` · ${formatNumber(Math.abs(change.percent))}% ${change.direction}` : ""}`
354
+ : `${plan.label} has not been measured`,
355
+ };
356
+ for (const block of plan.blocks) {
357
+ let node = byId.get(block);
358
+ const seen = new Set();
359
+ while (node && !seen.has(node.id)) {
360
+ seen.add(node.id);
361
+ if (!owned.has(node.id))
362
+ owned.set(node.id, new Map());
363
+ owned
364
+ .get(node.id)
365
+ .set(plan.file + "#" + (item?.name || plan.label), row);
366
+ node = byId.get(node.parent || "");
367
+ }
368
+ }
369
+ }
370
+ }
371
+ const cells = {};
372
+ for (const [id, rows] of owned) {
373
+ const values = [...rows.values()], first = values[0];
374
+ cells[id] =
375
+ values.length === 1
376
+ ? {
377
+ count: first.count,
378
+ intensity: 0,
379
+ displayValue: first.value,
380
+ label: first.label,
381
+ summary: first.summary,
382
+ series: first.series,
383
+ tone: first.tone,
384
+ }
385
+ : {
386
+ count: values.length,
387
+ intensity: 0,
388
+ displayValue: String(values.length),
389
+ label: "Product benchmarks",
390
+ summary: values.map((v) => v.summary).join(" · "),
391
+ measurements: values,
392
+ tone: "neutral",
393
+ };
394
+ }
395
+ return cells;
396
+ }
@@ -0,0 +1,71 @@
1
+ import type { DefinitionGraph } from "./model.js";
2
+ export interface CatalogPart {
3
+ /** Explicit reviewed public surface for this existing implementation ID. */
4
+ entryFor?: string;
5
+ /** Stable identity: a local slug, or a qualified ID retained when a part moves. */
6
+ id?: string;
7
+ name: string;
8
+ kind?: string;
9
+ summary: string;
10
+ signature?: string;
11
+ evidence: string[];
12
+ parts?: CatalogPart[];
13
+ resources?: {
14
+ id: string;
15
+ name: string;
16
+ summary?: string;
17
+ evidence: string[];
18
+ }[];
19
+ outputs?: {
20
+ id: string;
21
+ name: string;
22
+ summary?: string;
23
+ evidence: string[];
24
+ }[];
25
+ }
26
+ export interface ProductMapCatalog {
27
+ id: string;
28
+ name: string;
29
+ date: string;
30
+ basis: string;
31
+ systems: {
32
+ id: string;
33
+ name: string;
34
+ purpose: string;
35
+ hosting: string;
36
+ external: string[];
37
+ parts: CatalogPart[];
38
+ }[];
39
+ connections: {
40
+ id: string;
41
+ source: string;
42
+ target: string;
43
+ label: string;
44
+ transport: string;
45
+ evidence: string[];
46
+ bidirectional: boolean;
47
+ relation?: string;
48
+ condition?: string;
49
+ path?: string;
50
+ backbone?: boolean;
51
+ artifacts?: {
52
+ id: string;
53
+ name: string;
54
+ summary?: string;
55
+ evidence: string[];
56
+ }[];
57
+ }[];
58
+ support: {
59
+ name: string;
60
+ paths: string[];
61
+ scope: string;
62
+ }[];
63
+ evidence: Record<string, {
64
+ file: string;
65
+ line: number;
66
+ anchor: string;
67
+ digest: string;
68
+ }>;
69
+ }
70
+ /** Convert a reviewed inventory into the same graph used by the runtime viewer. */
71
+ export declare function buildProductMap(catalog: ProductMapCatalog): DefinitionGraph;