@granular-software/fractory 0.0.0-stage → 0.1.24
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.
- package/LICENSE +4 -0
- package/README.md +28 -2
- package/dist/activity-volume.d.ts +18 -0
- package/dist/activity-volume.js +94 -0
- package/dist/annotations.d.ts +118 -0
- package/dist/annotations.js +304 -0
- package/dist/benchmark-cli.d.ts +1 -0
- package/dist/benchmark-cli.js +95 -0
- package/dist/benchmark-worker.d.ts +2 -0
- package/dist/benchmark-worker.js +22 -0
- package/dist/benchmarks.d.ts +19 -0
- package/dist/benchmarks.js +414 -0
- package/dist/bin.d.ts +2 -0
- package/dist/bin.js +63 -0
- package/dist/block-cli.d.ts +1 -0
- package/dist/block-cli.js +88 -0
- package/dist/block-documents.d.ts +35 -0
- package/dist/block-documents.js +84 -0
- package/dist/change-impact.d.ts +55 -0
- package/dist/change-impact.js +223 -0
- package/dist/check-source.d.ts +2 -0
- package/dist/check-source.js +66 -0
- package/dist/checks-model.d.ts +64 -0
- package/dist/checks-model.js +36 -0
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +359 -0
- package/dist/code-model.d.ts +38 -0
- package/dist/code-model.js +94 -0
- package/dist/code-store.d.ts +9 -0
- package/dist/code-store.js +79 -0
- package/dist/compare-artifact.d.ts +6 -0
- package/dist/compare-artifact.js +277 -0
- package/dist/compare.d.ts +81 -0
- package/dist/compare.js +291 -0
- package/dist/compiler.d.ts +10 -0
- package/dist/compiler.js +1083 -0
- package/dist/compose.d.ts +9 -0
- package/dist/compose.js +72 -0
- package/dist/core.d.ts +86 -0
- package/dist/core.js +206 -0
- package/dist/coverage-cli.d.ts +1 -0
- package/dist/coverage-cli.js +42 -0
- package/dist/declaration-sources.d.ts +3 -0
- package/dist/declaration-sources.js +51 -0
- package/dist/declared-graph.d.ts +3 -0
- package/dist/declared-graph.js +66 -0
- package/dist/display-name.d.ts +2 -0
- package/dist/display-name.js +8 -0
- package/dist/error-heat.d.ts +58 -0
- package/dist/error-heat.js +96 -0
- package/dist/evidence.d.ts +3 -0
- package/dist/evidence.js +68 -0
- package/dist/factory-graph.d.ts +4 -0
- package/dist/factory-graph.js +318 -0
- package/dist/factory-model.d.ts +97 -0
- package/dist/factory-model.js +1 -0
- package/dist/git-code.d.ts +47 -0
- package/dist/git-code.js +352 -0
- package/dist/git-refs.d.ts +4 -0
- package/dist/git-refs.js +37 -0
- package/dist/history-activity.d.ts +4 -0
- package/dist/history-activity.js +129 -0
- package/dist/history-churn.d.ts +36 -0
- package/dist/history-churn.js +302 -0
- package/dist/history-git.d.ts +21 -0
- package/dist/history-git.js +125 -0
- package/dist/history-ledger.d.ts +43 -0
- package/dist/history-ledger.js +450 -0
- package/dist/history-ownership.d.ts +10 -0
- package/dist/history-ownership.js +75 -0
- package/dist/history-source.d.ts +13 -0
- package/dist/history-source.js +100 -0
- package/dist/integrations-cli.d.ts +2 -0
- package/dist/integrations-cli.js +159 -0
- package/dist/issue-cache.d.ts +9 -0
- package/dist/issue-cache.js +68 -0
- package/dist/issue-cli.d.ts +1 -0
- package/dist/issue-cli.js +89 -0
- package/dist/issue-links.d.ts +15 -0
- package/dist/issue-links.js +125 -0
- package/dist/linear-issues.d.ts +19 -0
- package/dist/linear-issues.js +124 -0
- package/dist/local-runtime.d.ts +8 -0
- package/dist/local-runtime.js +59 -0
- package/dist/map-activity.d.ts +73 -0
- package/dist/map-activity.js +234 -0
- package/dist/map-model.d.ts +5 -0
- package/dist/map-model.js +166 -0
- package/dist/map-quality.d.ts +14 -0
- package/dist/map-quality.js +56 -0
- package/dist/mapping-coverage.d.ts +87 -0
- package/dist/mapping-coverage.js +404 -0
- package/dist/model.d.ts +182 -0
- package/dist/model.js +66 -0
- package/dist/operation-benchmark-worker.d.ts +2 -0
- package/dist/operation-benchmark-worker.js +60 -0
- package/dist/operation-benchmark.d.ts +29 -0
- package/dist/operation-benchmark.js +1 -0
- package/dist/otel-metrics.d.ts +21 -0
- package/dist/otel-metrics.js +146 -0
- package/dist/performance-model.d.ts +185 -0
- package/dist/performance-model.js +396 -0
- package/dist/product-map.d.ts +69 -0
- package/dist/product-map.js +168 -0
- package/dist/provider-access.cjs +207 -0
- package/dist/provider-access.d.cts +14 -0
- package/dist/reports-cli.d.ts +1 -0
- package/dist/reports-cli.js +111 -0
- package/dist/reports-model.d.ts +27 -0
- package/dist/reports-model.js +39 -0
- package/dist/reports.d.ts +23 -0
- package/dist/reports.js +223 -0
- package/dist/repository-map.d.ts +22 -0
- package/dist/repository-map.js +151 -0
- package/dist/resource-cache.d.ts +17 -0
- package/dist/resource-cache.js +65 -0
- package/dist/review-cli.d.ts +19 -0
- package/dist/review-cli.js +224 -0
- package/dist/review.d.ts +48 -0
- package/dist/review.js +289 -0
- package/dist/runtime-metrics.d.ts +26 -0
- package/dist/runtime-metrics.js +290 -0
- package/dist/scope.d.ts +12 -0
- package/dist/scope.js +94 -0
- package/dist/sentry-activity.d.ts +39 -0
- package/dist/sentry-activity.js +174 -0
- package/dist/sentry.d.ts +130 -0
- package/dist/sentry.js +369 -0
- package/dist/service-release.d.ts +16 -0
- package/dist/service-release.js +14 -0
- package/dist/setup-cli.d.ts +2 -0
- package/dist/setup-cli.js +52 -0
- package/dist/setup-kit.cjs +163 -0
- package/dist/setup-kit.d.cts +32 -0
- package/dist/source-index.d.ts +37 -0
- package/dist/source-index.js +166 -0
- package/dist/source-review-git.d.ts +7 -0
- package/dist/source-review-git.js +103 -0
- package/dist/source-review.d.ts +16 -0
- package/dist/source-review.js +493 -0
- package/dist/telemetry.d.ts +17 -0
- package/dist/telemetry.js +51 -0
- package/dist/time-window.d.ts +9 -0
- package/dist/time-window.js +35 -0
- package/dist/trace-evidence.d.ts +23 -0
- package/dist/trace-evidence.js +55 -0
- package/dist/trace-model.d.ts +26 -0
- package/dist/trace-model.js +1 -0
- package/dist/tracing.d.ts +44 -0
- package/dist/tracing.js +123 -0
- package/dist/work-check.d.ts +17 -0
- package/dist/work-check.js +110 -0
- package/dist/work-cli.d.ts +1 -0
- package/dist/work-cli.js +148 -0
- package/dist/work-context.d.ts +57 -0
- package/dist/work-context.js +568 -0
- package/dist/work-intents.d.ts +6 -0
- package/dist/work-intents.js +140 -0
- package/dist/work-items.d.ts +58 -0
- package/dist/work-items.js +86 -0
- package/dist/work-model.d.ts +110 -0
- package/dist/work-model.js +261 -0
- package/dist/work-review-git.d.ts +8 -0
- package/dist/work-review-git.js +111 -0
- package/dist/work-review.d.ts +26 -0
- package/dist/work-review.js +426 -0
- package/dist/work-switcher-model.d.ts +43 -0
- package/dist/work-switcher-model.js +79 -0
- package/dist/work-switcher.d.ts +6 -0
- package/dist/work-switcher.js +171 -0
- package/dist/working-cli.d.ts +1 -0
- package/dist/working-cli.js +33 -0
- package/dist/working-code.d.ts +74 -0
- package/dist/working-code.js +421 -0
- package/dist/workspace-notes.d.ts +71 -0
- package/dist/workspace-notes.js +177 -0
- package/dist/workspace-tests.d.ts +21 -0
- package/dist/workspace-tests.js +573 -0
- package/package.json +547 -4
- package/src/activity-volume.ts +149 -0
- package/src/annotations.ts +481 -0
- package/src/benchmark-cli.ts +118 -0
- package/src/benchmark-worker.ts +22 -0
- package/src/benchmarks.ts +493 -0
- package/src/bin.ts +54 -0
- package/src/block-cli.ts +106 -0
- package/src/block-documents.ts +117 -0
- package/src/change-impact.ts +280 -0
- package/src/check-source.ts +82 -0
- package/src/checks-model.ts +108 -0
- package/src/cli.ts +440 -0
- package/src/code-model.ts +159 -0
- package/src/code-store.ts +98 -0
- package/src/compare-artifact.ts +314 -0
- package/src/compare.ts +440 -0
- package/src/compiler.ts +1326 -0
- package/src/compose.ts +94 -0
- package/src/core.ts +357 -0
- package/src/coverage-cli.ts +52 -0
- package/src/declaration-sources.ts +69 -0
- package/src/declared-graph.ts +74 -0
- package/src/display-name.ts +8 -0
- package/src/error-heat.ts +161 -0
- package/src/evidence.ts +94 -0
- package/src/factory-graph.ts +378 -0
- package/src/factory-model.ts +73 -0
- package/src/git-code.ts +461 -0
- package/src/git-refs.ts +43 -0
- package/src/history-activity.ts +146 -0
- package/src/history-churn.ts +416 -0
- package/src/history-git.ts +163 -0
- package/src/history-ledger.ts +636 -0
- package/src/history-ownership.ts +116 -0
- package/src/history-source.ts +117 -0
- package/src/integrations-cli.ts +187 -0
- package/src/issue-cache.ts +96 -0
- package/src/issue-cli.ts +137 -0
- package/src/issue-links.ts +153 -0
- package/src/linear-issues.ts +154 -0
- package/src/local-runtime.ts +70 -0
- package/src/map-activity.ts +309 -0
- package/src/map-model.ts +213 -0
- package/src/map-quality.ts +61 -0
- package/src/mapping-coverage.ts +570 -0
- package/src/model.ts +221 -0
- package/src/operation-benchmark-worker.ts +60 -0
- package/src/operation-benchmark.ts +28 -0
- package/src/otel-metrics.ts +176 -0
- package/src/performance-model.ts +575 -0
- package/src/product-map.ts +236 -0
- package/src/provider-access.cjs +207 -0
- package/src/provider-access.d.cts +14 -0
- package/src/reports-cli.ts +125 -0
- package/src/reports-model.ts +73 -0
- package/src/reports.ts +276 -0
- package/src/repository-map.ts +189 -0
- package/src/resource-cache.ts +76 -0
- package/src/review-cli.ts +256 -0
- package/src/review.ts +376 -0
- package/src/runtime-metrics.ts +386 -0
- package/src/scope.ts +103 -0
- package/src/sentry-activity.ts +234 -0
- package/src/sentry.ts +545 -0
- package/src/service-release.ts +18 -0
- package/src/setup-cli.ts +58 -0
- package/src/setup-kit.cjs +163 -0
- package/src/setup-kit.d.cts +32 -0
- package/src/source-index.ts +205 -0
- package/src/source-review-git.ts +129 -0
- package/src/source-review.ts +637 -0
- package/src/telemetry.ts +68 -0
- package/src/time-window.ts +51 -0
- package/src/trace-evidence.ts +80 -0
- package/src/trace-model.ts +26 -0
- package/src/tracing.ts +165 -0
- package/src/work-check.ts +143 -0
- package/src/work-cli.ts +195 -0
- package/src/work-context.ts +713 -0
- package/src/work-intents.ts +196 -0
- package/src/work-items.ts +151 -0
- package/src/work-model.ts +400 -0
- package/src/work-review-git.ts +130 -0
- package/src/work-review.ts +573 -0
- package/src/work-switcher-model.ts +121 -0
- package/src/work-switcher.ts +191 -0
- package/src/working-cli.ts +38 -0
- package/src/working-code.ts +582 -0
- package/src/workspace-notes.ts +203 -0
- package/src/workspace-tests.ts +654 -0
- package/toolkit/GUIDE.md +305 -0
- package/toolkit/SKILL.md +131 -0
- package/toolkit/bin/fractory +2 -0
- package/toolkit/build.json +1 -0
package/src/model.ts
ADDED
|
@@ -0,0 +1,221 @@
|
|
|
1
|
+
/** A definition graph is separate from execution evidence. No payloads or credentials belong here. */
|
|
2
|
+
export type ElementKind =
|
|
3
|
+
| "factory"
|
|
4
|
+
| "deployment"
|
|
5
|
+
| "system"
|
|
6
|
+
| "interface"
|
|
7
|
+
| "process"
|
|
8
|
+
| "method"
|
|
9
|
+
| "block"
|
|
10
|
+
| "operation"
|
|
11
|
+
| "resource"
|
|
12
|
+
| "artifact";
|
|
13
|
+
export type Provenance = "declared" | "source" | "inferred" | "observed" | "proposed";
|
|
14
|
+
/** The four logical shapes. Older snapshots may still contain the legacy kinds above. */
|
|
15
|
+
export type LogicalKind = "block" | "interface" | "method" | "process";
|
|
16
|
+
export interface SourceRef {
|
|
17
|
+
/** Explicit implementation-module ownership; does not claim a method boundary. */
|
|
18
|
+
scope?: "file";
|
|
19
|
+
file: string;
|
|
20
|
+
line: number;
|
|
21
|
+
symbol?: string;
|
|
22
|
+
digest: string;
|
|
23
|
+
}
|
|
24
|
+
export interface ResourceAttachment {
|
|
25
|
+
id: string;
|
|
26
|
+
label: string;
|
|
27
|
+
description?: string;
|
|
28
|
+
source?: SourceRef;
|
|
29
|
+
sources?: SourceRef[];
|
|
30
|
+
provenance?: Provenance;
|
|
31
|
+
/** Existing dependency evidence, retained when an older resource node is folded away. */
|
|
32
|
+
connections?: Connection[];
|
|
33
|
+
}
|
|
34
|
+
export interface FlowArtifact {
|
|
35
|
+
id: string;
|
|
36
|
+
label: string;
|
|
37
|
+
description?: string;
|
|
38
|
+
source?: SourceRef;
|
|
39
|
+
sources?: SourceRef[];
|
|
40
|
+
provenance?: Provenance;
|
|
41
|
+
}
|
|
42
|
+
export interface Element {
|
|
43
|
+
id: string;
|
|
44
|
+
label: string;
|
|
45
|
+
kind: ElementKind;
|
|
46
|
+
parent?: string;
|
|
47
|
+
provenance: Provenance;
|
|
48
|
+
/** Original definition fingerprint when mounted in a larger factory. */
|
|
49
|
+
definitionRevision?: string;
|
|
50
|
+
source?: SourceRef;
|
|
51
|
+
sources?: SourceRef[];
|
|
52
|
+
hosting?: string;
|
|
53
|
+
externalBoundaries?: string[];
|
|
54
|
+
signature?: string;
|
|
55
|
+
contract?: { id: string; input?: unknown; output?: unknown };
|
|
56
|
+
description?: string;
|
|
57
|
+
attachments?: import("./factory-model").FactoryAttachments;
|
|
58
|
+
/** An interface entry can expose a process while source ownership stays on that process. */
|
|
59
|
+
implementationBlock?: string;
|
|
60
|
+
resources?: ResourceAttachment[];
|
|
61
|
+
/** Known outputs; only mapped transfers get a wire on the canvas. */
|
|
62
|
+
outputs?: FlowArtifact[];
|
|
63
|
+
}
|
|
64
|
+
export type Relation =
|
|
65
|
+
| "exposes"
|
|
66
|
+
| "flows"
|
|
67
|
+
| "calls"
|
|
68
|
+
| "renders"
|
|
69
|
+
| "callbacks"
|
|
70
|
+
| "delegates"
|
|
71
|
+
| "resumes"
|
|
72
|
+
| "requires"
|
|
73
|
+
| "reads"
|
|
74
|
+
| "writes"
|
|
75
|
+
| "produces"
|
|
76
|
+
| "loads";
|
|
77
|
+
export interface Connection {
|
|
78
|
+
id: string;
|
|
79
|
+
source: string;
|
|
80
|
+
target: string;
|
|
81
|
+
relation: Relation;
|
|
82
|
+
label: string;
|
|
83
|
+
displayLabel?: string;
|
|
84
|
+
provenance: Provenance;
|
|
85
|
+
sourceRef?: SourceRef;
|
|
86
|
+
sources?: SourceRef[];
|
|
87
|
+
transport?: string;
|
|
88
|
+
exchange?: { inputs: { name: string; type: string }[]; output?: string };
|
|
89
|
+
bidirectional?: boolean;
|
|
90
|
+
condition?: string;
|
|
91
|
+
path?: "failure" | "retry";
|
|
92
|
+
overview?: boolean;
|
|
93
|
+
artifacts?: FlowArtifact[];
|
|
94
|
+
/** Original transfers grouped onto one visible wire. Presentation only. */
|
|
95
|
+
members?: Connection[];
|
|
96
|
+
}
|
|
97
|
+
export interface Verification {
|
|
98
|
+
id: string;
|
|
99
|
+
name: string;
|
|
100
|
+
source: SourceRef;
|
|
101
|
+
targets: string[];
|
|
102
|
+
association: "imports" | "contract-reference" | "attachment";
|
|
103
|
+
status: "not_run";
|
|
104
|
+
}
|
|
105
|
+
export interface DefinitionGraph {
|
|
106
|
+
schema: "fractal.definition.v1";
|
|
107
|
+
id: string;
|
|
108
|
+
revision: string;
|
|
109
|
+
/** Full source commit, when a build artifact proves it. Distinct from definition shape. */
|
|
110
|
+
codeRevision?: string;
|
|
111
|
+
generatedAt: string;
|
|
112
|
+
scope: string;
|
|
113
|
+
basis?: "repository-review";
|
|
114
|
+
supportingAreas?: { name: string; paths: string[]; scope: string }[];
|
|
115
|
+
elements: Element[];
|
|
116
|
+
connections: Connection[];
|
|
117
|
+
tests: Verification[];
|
|
118
|
+
failures: {
|
|
119
|
+
operationId: string;
|
|
120
|
+
source: SourceRef;
|
|
121
|
+
kind: "throw" | "catch";
|
|
122
|
+
description: string;
|
|
123
|
+
}[];
|
|
124
|
+
gaps: { source: SourceRef; expression: string; reason: string }[];
|
|
125
|
+
/** Presentation redirects for resource/artifact IDs from older snapshots and activity links. */
|
|
126
|
+
aliases?: Record<string, string>;
|
|
127
|
+
}
|
|
128
|
+
export interface ExecutionEvidence {
|
|
129
|
+
schema: "fractal.evidence.v1";
|
|
130
|
+
jobId: string;
|
|
131
|
+
status: string;
|
|
132
|
+
runtime?: string;
|
|
133
|
+
startIntent?: { state: string; attempt: number };
|
|
134
|
+
unresolved: { operationId: string; commit: "unknown"; reason: string }[];
|
|
135
|
+
failures: { code: string; origin: string; commit: string }[];
|
|
136
|
+
observations: { elementId: string; label: string; confidence: "recorded" }[];
|
|
137
|
+
definitionRevision?: string;
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
/** Lift a connection to the nearest visible ancestor, preserving its original identity. */
|
|
141
|
+
export function projectGraph(
|
|
142
|
+
graph: DefinitionGraph,
|
|
143
|
+
expanded: ReadonlySet<string>,
|
|
144
|
+
) {
|
|
145
|
+
const byId = new Map(graph.elements.map((n) => [n.id, n]));
|
|
146
|
+
const visible = (node: Element): boolean =>
|
|
147
|
+
!node.parent ||
|
|
148
|
+
(expanded.has(node.parent) &&
|
|
149
|
+
!!byId.get(node.parent) &&
|
|
150
|
+
visible(byId.get(node.parent)!));
|
|
151
|
+
const nodes = graph.elements.filter(visible);
|
|
152
|
+
const shown = new Set(nodes.map((n) => n.id));
|
|
153
|
+
const ancestor = (id: string): string | undefined => {
|
|
154
|
+
const seen = new Set<string>();
|
|
155
|
+
while (!shown.has(id)) {
|
|
156
|
+
if (seen.has(id)) return;
|
|
157
|
+
seen.add(id);
|
|
158
|
+
const parent = byId.get(id)?.parent;
|
|
159
|
+
if (!parent) return;
|
|
160
|
+
id = parent;
|
|
161
|
+
}
|
|
162
|
+
return id;
|
|
163
|
+
};
|
|
164
|
+
const edges = graph.connections.flatMap((edge) => {
|
|
165
|
+
const source = ancestor(edge.source),
|
|
166
|
+
target = ancestor(edge.target);
|
|
167
|
+
return source && target && source !== target
|
|
168
|
+
? [
|
|
169
|
+
{
|
|
170
|
+
...edge,
|
|
171
|
+
source,
|
|
172
|
+
target,
|
|
173
|
+
originalSource: edge.source,
|
|
174
|
+
originalTarget: edge.target,
|
|
175
|
+
},
|
|
176
|
+
]
|
|
177
|
+
: [];
|
|
178
|
+
});
|
|
179
|
+
return { nodes, edges };
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
export function relatedTests(
|
|
183
|
+
graph: DefinitionGraph,
|
|
184
|
+
elementId: string,
|
|
185
|
+
): Verification[] {
|
|
186
|
+
const descendants = new Set([elementId]);
|
|
187
|
+
let changed = true;
|
|
188
|
+
while (changed) {
|
|
189
|
+
changed = false;
|
|
190
|
+
for (const node of graph.elements)
|
|
191
|
+
if (
|
|
192
|
+
node.parent &&
|
|
193
|
+
descendants.has(node.parent) &&
|
|
194
|
+
!descendants.has(node.id)
|
|
195
|
+
) {
|
|
196
|
+
descendants.add(node.id);
|
|
197
|
+
changed = true;
|
|
198
|
+
}
|
|
199
|
+
}
|
|
200
|
+
// A suite attached to an interface or process is also useful inside its box.
|
|
201
|
+
// Inherit the nearest attachment, without claiming line or branch coverage.
|
|
202
|
+
const byId = new Map(graph.elements.map((node) => [node.id, node]));
|
|
203
|
+
let parent = byId.get(elementId)?.parent;
|
|
204
|
+
const visited = new Set<string>();
|
|
205
|
+
while (parent && !visited.has(parent)) {
|
|
206
|
+
visited.add(parent);
|
|
207
|
+
if (
|
|
208
|
+
graph.tests.some(
|
|
209
|
+
(test) =>
|
|
210
|
+
test.association === "attachment" && test.targets.includes(parent!),
|
|
211
|
+
)
|
|
212
|
+
) {
|
|
213
|
+
descendants.add(parent);
|
|
214
|
+
break;
|
|
215
|
+
}
|
|
216
|
+
parent = byId.get(parent)?.parent;
|
|
217
|
+
}
|
|
218
|
+
return graph.tests.filter((test) =>
|
|
219
|
+
test.targets.some((id) => descendants.has(id)),
|
|
220
|
+
);
|
|
221
|
+
}
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
/** Isolated worker source, bundled with the desktop just like function benchmarks. */
|
|
2
|
+
export const operationBenchmarkWorker = `
|
|
3
|
+
import {writeFileSync} from 'node:fs';
|
|
4
|
+
import {pathToFileURL} from 'node:url';
|
|
5
|
+
import {createHash} from 'node:crypto';
|
|
6
|
+
const [file,report]=process.argv.slice(1);
|
|
7
|
+
const cancellation=new AbortController();
|
|
8
|
+
process.on('SIGTERM',()=>cancellation.abort());
|
|
9
|
+
const bounded=(task,signal)=>new Promise((resolve,reject)=>{
|
|
10
|
+
const aborted=()=>reject(Error(signal.reason?.name==='TimeoutError'?'Operation exceeded its time budget.':'Benchmark stopped.'));
|
|
11
|
+
if(signal.aborted)return aborted();
|
|
12
|
+
signal.addEventListener('abort',aborted,{once:true});
|
|
13
|
+
Promise.resolve(task).then(resolve,reject).finally(()=>signal.removeEventListener('abort',aborted));
|
|
14
|
+
});
|
|
15
|
+
try {
|
|
16
|
+
const {default: plan}=await import(pathToFileURL(file).href);
|
|
17
|
+
if(plan?.kind!=='operation'||typeof plan.name!=='string'||!plan.fixture?.name||!plan.fixture?.version||typeof plan.prepare!=='function'||typeof plan.run!=='function'||typeof plan.cleanup!=='function') throw Error('Export an operation benchmark with a name, versioned fixture, prepare, run and cleanup.');
|
|
18
|
+
const count=plan.attempts??5;
|
|
19
|
+
if(!Number.isSafeInteger(count)||count<1||count>10) throw Error('Choose between 1 and 10 product-operation attempts.');
|
|
20
|
+
const timeout=Math.min(120000,Math.max(5000,plan.timeoutMs||120000));
|
|
21
|
+
const values=[]; const phases=[]; let target;
|
|
22
|
+
for(let attempt=0;attempt<count;attempt++) {
|
|
23
|
+
if(cancellation.signal.aborted) throw Error('Benchmark stopped.');
|
|
24
|
+
const signal=AbortSignal.any([cancellation.signal,AbortSignal.timeout(timeout)]);
|
|
25
|
+
console.log('Preparing attempt '+(attempt+1)+'/'+count);
|
|
26
|
+
const state=await bounded(plan.prepare(signal,attempt),signal);
|
|
27
|
+
try {
|
|
28
|
+
const start=performance.now();
|
|
29
|
+
console.log('Measuring attempt '+(attempt+1)+'/'+count);
|
|
30
|
+
const result=await bounded(plan.run(state,signal),signal);
|
|
31
|
+
const elapsed=performance.now()-start;
|
|
32
|
+
if(signal.aborted) throw Error('Operation did not complete within its measurement budget.');
|
|
33
|
+
const measured=result?.target;
|
|
34
|
+
if(!measured?.name||!measured.url||!measured.revision||!['client','server'].includes(measured.measurement)) throw Error('Identify the measured test environment, deployed revision and timing source.');
|
|
35
|
+
const url=new URL(measured.url);
|
|
36
|
+
if(url.protocol!=='https:'||url.username||url.password||url.search||url.hash) throw Error('Use the dedicated HTTPS test environment.');
|
|
37
|
+
if(target&&JSON.stringify(target)!==JSON.stringify(measured)) throw Error('The target deployment changed during this run. Run again on one stable revision.');
|
|
38
|
+
target=measured;
|
|
39
|
+
const value=measured.measurement==='server'?result.durationMs:elapsed;
|
|
40
|
+
if(!Number.isFinite(value)||value<0) throw Error('The operation did not return a valid measured duration.');
|
|
41
|
+
values.push(value);
|
|
42
|
+
if(result.phases) {
|
|
43
|
+
if(Object.keys(result.phases).length>8||Object.values(result.phases).some(n=>!Number.isFinite(n)||n<0)||Object.values(result.phases).reduce((sum,n)=>sum+n,0)>value+Math.max(1,value*.01)) throw Error('Invalid operation phase durations.');
|
|
44
|
+
phases.push(result.phases);
|
|
45
|
+
}
|
|
46
|
+
console.log('Attempt '+(attempt+1)+'/'+count+' completed');
|
|
47
|
+
} finally { await bounded(plan.cleanup(state),AbortSignal.timeout(35000)); }
|
|
48
|
+
}
|
|
49
|
+
const mean=values.reduce((a,b)=>a+b,0)/values.length;
|
|
50
|
+
const critical=[0,12.706,4.303,3.182,2.776,2.571,2.447,2.365,2.306,2.262][values.length-1]||0;
|
|
51
|
+
const deviation=values.length>1?Math.sqrt(values.reduce((sum,value)=>sum+(value-mean)**2,0)/(values.length-1)):0;
|
|
52
|
+
const sorted=[...values].sort((a,b)=>a-b);
|
|
53
|
+
writeFileSync(report,JSON.stringify({kind:'operation',fixture:plan.fixture.name,fixtureVersion:plan.fixture.version,fixtureDescription:plan.fixture.condition,
|
|
54
|
+
fixtureDigest:createHash('sha256').update(JSON.stringify(plan.fixture)).digest('hex'),target,
|
|
55
|
+
runtime:Bun.version,cases:[{name:plan.name,samples:values.length,meanMs:mean,
|
|
56
|
+
marginMs:values.length>1?critical*deviation/Math.sqrt(values.length):mean,
|
|
57
|
+
p95Ms:sorted[Math.min(sorted.length-1,Math.ceil(sorted.length*.95)-1)],hz:mean>0?1000/mean:0,attemptsMs:values,attemptPhases:phases}]}));
|
|
58
|
+
process.exit(0);
|
|
59
|
+
} catch(error) { console.error(error instanceof Error?error.message:'Operation benchmark failed.');process.exit(1); }
|
|
60
|
+
`;
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/** An ordinary async product operation, with setup/cleanup outside its timing. */
|
|
2
|
+
export interface OperationBenchmark<State> {
|
|
3
|
+
kind: "operation";
|
|
4
|
+
name: string;
|
|
5
|
+
description?: string;
|
|
6
|
+
startsWhen?: string;
|
|
7
|
+
endsWhen?: string;
|
|
8
|
+
fixture: { name: string; version: string; [key: string]: unknown };
|
|
9
|
+
attempts?: number;
|
|
10
|
+
timeoutMs?: number;
|
|
11
|
+
prepare: (signal: AbortSignal, attempt: number) => Promise<State>;
|
|
12
|
+
run: (
|
|
13
|
+
state: State,
|
|
14
|
+
signal: AbortSignal,
|
|
15
|
+
) => Promise<{
|
|
16
|
+
/** Omit for client-observed wall time; supply only a measured server duration. */
|
|
17
|
+
durationMs?: number;
|
|
18
|
+
/** Measured, non-overlapping phases of this operation, in milliseconds. */
|
|
19
|
+
phases?: Record<string, number>;
|
|
20
|
+
target: {
|
|
21
|
+
name: string;
|
|
22
|
+
url: string;
|
|
23
|
+
revision: string;
|
|
24
|
+
measurement: "client" | "server";
|
|
25
|
+
};
|
|
26
|
+
}>;
|
|
27
|
+
cleanup: (state: State) => Promise<void>;
|
|
28
|
+
}
|
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
/** Aggregate OTel instruments. No invocation IDs, payloads or per-object retention. */
|
|
2
|
+
import type { Meter } from "@opentelemetry/api";
|
|
3
|
+
import {
|
|
4
|
+
MeterProvider,
|
|
5
|
+
MetricReader,
|
|
6
|
+
AggregationType,
|
|
7
|
+
type ResourceMetrics,
|
|
8
|
+
} from "@opentelemetry/sdk-metrics";
|
|
9
|
+
import { resourceFromAttributes } from "@opentelemetry/resources";
|
|
10
|
+
import { JsonMetricsSerializer } from "@opentelemetry/otlp-transformer";
|
|
11
|
+
import type { FactoryEvent } from "./annotations";
|
|
12
|
+
export function factoryMetricRecorder(
|
|
13
|
+
meter: Meter,
|
|
14
|
+
environment = "production",
|
|
15
|
+
) {
|
|
16
|
+
const calls = meter.createCounter("fractory.calls", {
|
|
17
|
+
unit: "{call}",
|
|
18
|
+
description: "Completed boundary invocations, including failures",
|
|
19
|
+
});
|
|
20
|
+
const duration = meter.createHistogram("fractory.duration", {
|
|
21
|
+
unit: "s",
|
|
22
|
+
description: "Boundary wall time",
|
|
23
|
+
});
|
|
24
|
+
return (event: FactoryEvent) => {
|
|
25
|
+
if (event.status === "started" || !event.targetId) return;
|
|
26
|
+
const attributes = {
|
|
27
|
+
"fractory.target": event.targetId,
|
|
28
|
+
"fractory.caller": event.callerId || "external",
|
|
29
|
+
"fractory.environment": environment,
|
|
30
|
+
"fractory.outcome": event.status === "failed" ? "error" : "ok",
|
|
31
|
+
};
|
|
32
|
+
calls.add(1, attributes);
|
|
33
|
+
if (
|
|
34
|
+
event.durationMs !== undefined &&
|
|
35
|
+
Number.isFinite(event.durationMs) &&
|
|
36
|
+
event.durationMs >= 0
|
|
37
|
+
)
|
|
38
|
+
duration.record(event.durationMs / 1000, attributes);
|
|
39
|
+
};
|
|
40
|
+
}
|
|
41
|
+
class FlushReader extends MetricReader {
|
|
42
|
+
constructor(private send: (metrics: ResourceMetrics) => Promise<void>) {
|
|
43
|
+
super({ cardinalitySelector: () => 1000 });
|
|
44
|
+
}
|
|
45
|
+
protected async onForceFlush() {
|
|
46
|
+
const { resourceMetrics } = await this.collect();
|
|
47
|
+
await this.send(resourceMetrics);
|
|
48
|
+
}
|
|
49
|
+
protected async onShutdown() {}
|
|
50
|
+
}
|
|
51
|
+
export interface OtlpMetricOptions {
|
|
52
|
+
intervalMs?: number;
|
|
53
|
+
service: string;
|
|
54
|
+
configuration: () => {
|
|
55
|
+
endpoint?: string;
|
|
56
|
+
headers?: string;
|
|
57
|
+
environment?: string;
|
|
58
|
+
};
|
|
59
|
+
waitUntil: (task: Promise<unknown>) => void;
|
|
60
|
+
fetch?: typeof fetch;
|
|
61
|
+
}
|
|
62
|
+
/** Lazy, bounded SDK export scheduled by the host's waitUntil, including Durable Objects.
|
|
63
|
+
* No global timers and no request waits. Missing configuration is a zero-network no-op. */
|
|
64
|
+
export function createOtlpMetrics(options: OtlpMetricOptions) {
|
|
65
|
+
let provider: MeterProvider | undefined,
|
|
66
|
+
record: ReturnType<typeof factoryMetricRecorder> | undefined;
|
|
67
|
+
let pending: Promise<void> | undefined,
|
|
68
|
+
dirty = false;
|
|
69
|
+
const flush = () =>
|
|
70
|
+
provider?.forceFlush({ timeoutMillis: 8000 }) || Promise.resolve();
|
|
71
|
+
const emit = (event: FactoryEvent) => {
|
|
72
|
+
if (event.status === "started") return;
|
|
73
|
+
try {
|
|
74
|
+
if (!provider) {
|
|
75
|
+
const config = options.configuration();
|
|
76
|
+
if (!config.endpoint) return;
|
|
77
|
+
const endpoint = new URL(config.endpoint);
|
|
78
|
+
if (
|
|
79
|
+
endpoint.username ||
|
|
80
|
+
endpoint.password ||
|
|
81
|
+
(endpoint.protocol !== "https:" &&
|
|
82
|
+
!(
|
|
83
|
+
endpoint.protocol === "http:" &&
|
|
84
|
+
["127.0.0.1", "localhost", "[::1]"].includes(endpoint.hostname)
|
|
85
|
+
))
|
|
86
|
+
)
|
|
87
|
+
return;
|
|
88
|
+
const headers: Record<string, string> = {
|
|
89
|
+
"Content-Type": "application/json",
|
|
90
|
+
};
|
|
91
|
+
for (const pair of (config.headers || "").split(",").filter(Boolean)) {
|
|
92
|
+
const equal = pair.indexOf("=");
|
|
93
|
+
if (equal <= 0) continue;
|
|
94
|
+
headers[pair.slice(0, equal).trim()] = decodeURIComponent(
|
|
95
|
+
pair.slice(equal + 1).trim(),
|
|
96
|
+
);
|
|
97
|
+
}
|
|
98
|
+
const reader = new FlushReader(async (metrics) => {
|
|
99
|
+
if (!metrics.scopeMetrics.some((scope) => scope.metrics.length))
|
|
100
|
+
return;
|
|
101
|
+
const body = JsonMetricsSerializer.serializeRequest(metrics);
|
|
102
|
+
if (!body || body.byteLength > 2 * 1024 * 1024) return;
|
|
103
|
+
const response = await (options.fetch || fetch)(endpoint, {
|
|
104
|
+
method: "POST",
|
|
105
|
+
headers,
|
|
106
|
+
body: body as BodyInit,
|
|
107
|
+
redirect: "error",
|
|
108
|
+
signal: AbortSignal.timeout(6000),
|
|
109
|
+
});
|
|
110
|
+
if (!response.ok) throw Error("Metric export failed");
|
|
111
|
+
});
|
|
112
|
+
provider = new MeterProvider({
|
|
113
|
+
resource: resourceFromAttributes({
|
|
114
|
+
"service.name": options.service,
|
|
115
|
+
"service.instance.id": crypto.randomUUID(),
|
|
116
|
+
...(event.codeRevision
|
|
117
|
+
? { "service.version": event.codeRevision }
|
|
118
|
+
: {}),
|
|
119
|
+
"deployment.environment.name": config.environment || "production",
|
|
120
|
+
}),
|
|
121
|
+
readers: [reader],
|
|
122
|
+
views: [
|
|
123
|
+
{
|
|
124
|
+
instrumentName: "fractory.duration",
|
|
125
|
+
aggregation: {
|
|
126
|
+
type: AggregationType.EXPLICIT_BUCKET_HISTOGRAM,
|
|
127
|
+
options: {
|
|
128
|
+
boundaries: [
|
|
129
|
+
0.00001, 0.00005, 0.0001, 0.0005, 0.001, 0.005, 0.01, 0.025,
|
|
130
|
+
0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60, 300, 900, 3600,
|
|
131
|
+
],
|
|
132
|
+
},
|
|
133
|
+
},
|
|
134
|
+
},
|
|
135
|
+
],
|
|
136
|
+
});
|
|
137
|
+
record = factoryMetricRecorder(
|
|
138
|
+
provider.getMeter("fractory", "1"),
|
|
139
|
+
config.environment || "production",
|
|
140
|
+
);
|
|
141
|
+
}
|
|
142
|
+
record!(event);
|
|
143
|
+
dirty = true;
|
|
144
|
+
if (!pending) {
|
|
145
|
+
pending = (async () => {
|
|
146
|
+
await new Promise((resolve) =>
|
|
147
|
+
setTimeout(
|
|
148
|
+
resolve,
|
|
149
|
+
Math.max(100, Math.min(10000, options.intervalMs || 5000)),
|
|
150
|
+
),
|
|
151
|
+
);
|
|
152
|
+
for (let cycle = 0; dirty && cycle < 4; cycle++) {
|
|
153
|
+
dirty = false;
|
|
154
|
+
try {
|
|
155
|
+
await flush();
|
|
156
|
+
} catch {
|
|
157
|
+
/* cumulative SDK state survives for the next flush */
|
|
158
|
+
}
|
|
159
|
+
}
|
|
160
|
+
})().finally(() => {
|
|
161
|
+
pending = undefined;
|
|
162
|
+
});
|
|
163
|
+
options.waitUntil(pending);
|
|
164
|
+
}
|
|
165
|
+
} catch {
|
|
166
|
+
/* instrumentation is observational */
|
|
167
|
+
}
|
|
168
|
+
};
|
|
169
|
+
return {
|
|
170
|
+
emit,
|
|
171
|
+
flush: async () => {
|
|
172
|
+
if (pending) await pending;
|
|
173
|
+
await flush();
|
|
174
|
+
},
|
|
175
|
+
};
|
|
176
|
+
}
|