@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
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
/** Small time buckets for the range picker; never a source/stack history scan. */
|
|
2
|
+
import { execFile } from "node:child_process";
|
|
3
|
+
import { promisify } from "node:util";
|
|
4
|
+
import { DAY_MS, inTimeWindow, type TimeWindow } from "./time-window";
|
|
5
|
+
const execute = promisify(execFile);
|
|
6
|
+
export interface ActivityVolume {
|
|
7
|
+
warnings?: import("./sentry").SentryProjectWarning[];
|
|
8
|
+
window: TimeWindow;
|
|
9
|
+
label: string;
|
|
10
|
+
unit: string;
|
|
11
|
+
buckets: { from: number; to: number; value: number }[];
|
|
12
|
+
total: number;
|
|
13
|
+
partial: boolean;
|
|
14
|
+
latestAt?: string;
|
|
15
|
+
}
|
|
16
|
+
export function activityVolume(
|
|
17
|
+
window: TimeWindow,
|
|
18
|
+
times: (string | undefined)[],
|
|
19
|
+
label: string,
|
|
20
|
+
unit: string,
|
|
21
|
+
partial = false,
|
|
22
|
+
): ActivityVolume {
|
|
23
|
+
const start = Date.parse(window.from),
|
|
24
|
+
end = Date.parse(window.to);
|
|
25
|
+
const step =
|
|
26
|
+
end - start <= 2 * DAY_MS
|
|
27
|
+
? 3600000
|
|
28
|
+
: end - start <= 14 * DAY_MS
|
|
29
|
+
? 21600000
|
|
30
|
+
: Math.ceil((end - start) / DAY_MS / 160) * DAY_MS;
|
|
31
|
+
const buckets = Array.from(
|
|
32
|
+
{ length: Math.ceil((end - start) / step) },
|
|
33
|
+
(_, i) => ({
|
|
34
|
+
from: start + i * step,
|
|
35
|
+
to: Math.min(end, start + (i + 1) * step),
|
|
36
|
+
value: 0,
|
|
37
|
+
}),
|
|
38
|
+
);
|
|
39
|
+
let total = 0;
|
|
40
|
+
for (const at of times)
|
|
41
|
+
if (at && inTimeWindow(at, window)) {
|
|
42
|
+
buckets[
|
|
43
|
+
Math.min(
|
|
44
|
+
buckets.length - 1,
|
|
45
|
+
Math.floor((Date.parse(at) - start) / step),
|
|
46
|
+
)
|
|
47
|
+
].value++;
|
|
48
|
+
total++;
|
|
49
|
+
}
|
|
50
|
+
return { window, label, unit, buckets, total, partial };
|
|
51
|
+
}
|
|
52
|
+
const gitOptions = (root: string) => ({
|
|
53
|
+
cwd: root,
|
|
54
|
+
encoding: "utf8" as const,
|
|
55
|
+
timeout: 8000,
|
|
56
|
+
maxBuffer: 512000,
|
|
57
|
+
env: { ...process.env, GIT_OPTIONAL_LOCKS: "0", GIT_LITERAL_PATHSPECS: "1" },
|
|
58
|
+
});
|
|
59
|
+
function validate(files: string[], anchor: string) {
|
|
60
|
+
if (anchor !== "HEAD" && !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(anchor))
|
|
61
|
+
throw Error("Use a full commit SHA");
|
|
62
|
+
if (
|
|
63
|
+
files.length > 2000 ||
|
|
64
|
+
files.join("").length > 180000 ||
|
|
65
|
+
files.some(
|
|
66
|
+
(p) =>
|
|
67
|
+
p.startsWith("/") ||
|
|
68
|
+
p.split(/[\\/]/).includes("..") ||
|
|
69
|
+
p.includes("\0"),
|
|
70
|
+
)
|
|
71
|
+
)
|
|
72
|
+
throw Error("Mapped files exceed the activity read budget");
|
|
73
|
+
}
|
|
74
|
+
export async function latestHistoryAt(
|
|
75
|
+
root: string,
|
|
76
|
+
files: string[],
|
|
77
|
+
anchor = "HEAD",
|
|
78
|
+
allFiles = false,
|
|
79
|
+
) {
|
|
80
|
+
validate(files, anchor);
|
|
81
|
+
if (!files.length && !allFiles) return;
|
|
82
|
+
const { stdout } = await execute(
|
|
83
|
+
"git",
|
|
84
|
+
[
|
|
85
|
+
"--no-pager",
|
|
86
|
+
"-c",
|
|
87
|
+
"core.fsmonitor=false",
|
|
88
|
+
"log",
|
|
89
|
+
"--first-parent",
|
|
90
|
+
"-1",
|
|
91
|
+
"--format=%ct",
|
|
92
|
+
anchor,
|
|
93
|
+
"--",
|
|
94
|
+
...files,
|
|
95
|
+
],
|
|
96
|
+
gitOptions(root),
|
|
97
|
+
);
|
|
98
|
+
return /^\d+\s*$/.test(stdout)
|
|
99
|
+
? new Date(Number(stdout.trim()) * 1000).toISOString()
|
|
100
|
+
: undefined;
|
|
101
|
+
}
|
|
102
|
+
export async function historyVolume(
|
|
103
|
+
root: string,
|
|
104
|
+
files: string[],
|
|
105
|
+
window: TimeWindow,
|
|
106
|
+
anchor = "HEAD",
|
|
107
|
+
allFiles = false,
|
|
108
|
+
) {
|
|
109
|
+
validate(files, anchor);
|
|
110
|
+
if (!files.length && !allFiles)
|
|
111
|
+
return activityVolume(window, [], "Mapped code commits", "commits");
|
|
112
|
+
const [{ stdout }, latestAt] = await Promise.all([
|
|
113
|
+
execute(
|
|
114
|
+
"git",
|
|
115
|
+
[
|
|
116
|
+
"--no-pager",
|
|
117
|
+
"-c",
|
|
118
|
+
"core.fsmonitor=false",
|
|
119
|
+
"log",
|
|
120
|
+
"--first-parent",
|
|
121
|
+
`--since-as-filter=${window.from}`,
|
|
122
|
+
`--until=${window.to}`,
|
|
123
|
+
"--format=%ct",
|
|
124
|
+
"--max-count=10001",
|
|
125
|
+
anchor,
|
|
126
|
+
"--",
|
|
127
|
+
...files,
|
|
128
|
+
],
|
|
129
|
+
gitOptions(root),
|
|
130
|
+
),
|
|
131
|
+
latestHistoryAt(root, files, anchor, allFiles),
|
|
132
|
+
]);
|
|
133
|
+
const stamps = stdout
|
|
134
|
+
.trim()
|
|
135
|
+
.split(/\s+/)
|
|
136
|
+
.filter((t) => /^\d+$/.test(t));
|
|
137
|
+
return {
|
|
138
|
+
...activityVolume(
|
|
139
|
+
window,
|
|
140
|
+
stamps
|
|
141
|
+
.slice(0, 10000)
|
|
142
|
+
.map((t) => new Date(Number(t) * 1000).toISOString()),
|
|
143
|
+
allFiles ? "Repository commits" : "Mapped code commits",
|
|
144
|
+
"commits",
|
|
145
|
+
stamps.length > 10000,
|
|
146
|
+
),
|
|
147
|
+
latestAt,
|
|
148
|
+
};
|
|
149
|
+
}
|
|
@@ -0,0 +1,481 @@
|
|
|
1
|
+
/** Application annotations. No construction, DI, graph registry or host imports. */
|
|
2
|
+
export interface Attachments {
|
|
3
|
+
benchmarks?: readonly string[];
|
|
4
|
+
docs?: string | readonly string[];
|
|
5
|
+
tests?: readonly string[];
|
|
6
|
+
description?: string;
|
|
7
|
+
}
|
|
8
|
+
type Callable = (this: any, ...args: any[]) => any;
|
|
9
|
+
export interface Invocation {
|
|
10
|
+
readonly receiver: unknown;
|
|
11
|
+
readonly args: readonly unknown[];
|
|
12
|
+
/** Trusted host context, never decoded from a caller's payload. */
|
|
13
|
+
readonly context: unknown;
|
|
14
|
+
}
|
|
15
|
+
export interface RuntimeContract {
|
|
16
|
+
args?: { parse(value: unknown): unknown };
|
|
17
|
+
result?: { parse(value: unknown): unknown };
|
|
18
|
+
}
|
|
19
|
+
export interface InterfaceOptions extends Attachments {
|
|
20
|
+
/** Optional stable identity when adopting an existing mapped interface. */
|
|
21
|
+
id?: string;
|
|
22
|
+
label?: string;
|
|
23
|
+
auth?: (invocation: Invocation) => boolean | void | Promise<boolean | void>;
|
|
24
|
+
}
|
|
25
|
+
const interfaceBrand: unique symbol = Symbol("fractal.interface");
|
|
26
|
+
export interface InterfaceRef {
|
|
27
|
+
readonly [interfaceBrand]: true;
|
|
28
|
+
readonly id: string;
|
|
29
|
+
readonly blockId: string;
|
|
30
|
+
readonly name: string;
|
|
31
|
+
readonly options: InterfaceOptions;
|
|
32
|
+
}
|
|
33
|
+
export interface BlockOptions extends Attachments {
|
|
34
|
+
/** Display names only; shapes still come from actual parameters and props. */
|
|
35
|
+
inputLabel?: string;
|
|
36
|
+
eventLabel?: string;
|
|
37
|
+
id: string;
|
|
38
|
+
label?: string;
|
|
39
|
+
parent?: () => object;
|
|
40
|
+
}
|
|
41
|
+
export interface MethodOptions extends Attachments {
|
|
42
|
+
label?: string;
|
|
43
|
+
contract?: RuntimeContract;
|
|
44
|
+
/** Normally inferred from the declaration; useful for anonymous dynamic functions. */
|
|
45
|
+
name?: string;
|
|
46
|
+
}
|
|
47
|
+
export interface FactoryEvent {
|
|
48
|
+
targetId?: string;
|
|
49
|
+
callerId?: string;
|
|
50
|
+
id: string;
|
|
51
|
+
traceId: string;
|
|
52
|
+
codeRevision?: string;
|
|
53
|
+
parentId?: string;
|
|
54
|
+
runId?: string;
|
|
55
|
+
linkedSpanId?: string;
|
|
56
|
+
linkedTraceId?: string;
|
|
57
|
+
blockId: string;
|
|
58
|
+
interfaceId?: string;
|
|
59
|
+
method: string;
|
|
60
|
+
timestamp: number;
|
|
61
|
+
status: "started" | "completed" | "failed";
|
|
62
|
+
durationMs?: number;
|
|
63
|
+
failure?: "auth" | "input" | "output" | "execution";
|
|
64
|
+
}
|
|
65
|
+
export interface FactoryFrame {
|
|
66
|
+
targetId?: string;
|
|
67
|
+
id: string;
|
|
68
|
+
traceId: string;
|
|
69
|
+
runId?: string;
|
|
70
|
+
linkedSpanId?: string;
|
|
71
|
+
linkedTraceId?: string;
|
|
72
|
+
finished?: boolean;
|
|
73
|
+
}
|
|
74
|
+
export interface FactoryHost {
|
|
75
|
+
current(): FactoryFrame | undefined;
|
|
76
|
+
run<T>(frame: FactoryFrame, execute: () => T): T;
|
|
77
|
+
context?(): unknown;
|
|
78
|
+
codeRevision?(): string | undefined;
|
|
79
|
+
emit(event: FactoryEvent): void;
|
|
80
|
+
}
|
|
81
|
+
const blocks = new WeakMap<object, BlockOptions>();
|
|
82
|
+
const wrappers = new WeakMap<
|
|
83
|
+
Callable,
|
|
84
|
+
{
|
|
85
|
+
original: Callable;
|
|
86
|
+
reference?: () => InterfaceRef;
|
|
87
|
+
process?: BlockOptions;
|
|
88
|
+
options: MethodOptions;
|
|
89
|
+
}
|
|
90
|
+
>();
|
|
91
|
+
const listeners = new Set<(event: FactoryEvent) => void>();
|
|
92
|
+
let host: FactoryHost | undefined;
|
|
93
|
+
/** Host adapters install async context once; application methods need no binding. */
|
|
94
|
+
export function installFactoryHost(adapter: FactoryHost) {
|
|
95
|
+
const previous = host;
|
|
96
|
+
host = adapter;
|
|
97
|
+
return () => {
|
|
98
|
+
if (host === adapter) host = previous;
|
|
99
|
+
};
|
|
100
|
+
}
|
|
101
|
+
export function observeFactory(listener: (event: FactoryEvent) => void) {
|
|
102
|
+
listeners.add(listener);
|
|
103
|
+
return () => {
|
|
104
|
+
listeners.delete(listener);
|
|
105
|
+
};
|
|
106
|
+
}
|
|
107
|
+
function publish(event: FactoryEvent, adapter?: FactoryHost) {
|
|
108
|
+
try {
|
|
109
|
+
adapter?.emit(event);
|
|
110
|
+
} catch {
|
|
111
|
+
/* telemetry cannot affect execution */
|
|
112
|
+
}
|
|
113
|
+
for (const listener of listeners) {
|
|
114
|
+
try {
|
|
115
|
+
listener(event);
|
|
116
|
+
} catch {
|
|
117
|
+
/* telemetry only */
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
function identity(value: string) {
|
|
122
|
+
if (!value.trim()) throw new Error("Fractal identity must not be empty");
|
|
123
|
+
return value;
|
|
124
|
+
}
|
|
125
|
+
export function Block(
|
|
126
|
+
id: string | BlockOptions,
|
|
127
|
+
options: Omit<BlockOptions, "id"> = {},
|
|
128
|
+
) {
|
|
129
|
+
const definition =
|
|
130
|
+
typeof id === "string"
|
|
131
|
+
? { ...options, id: identity(id) }
|
|
132
|
+
: { ...id, id: identity(id.id) };
|
|
133
|
+
return <T extends object>(target: T, _context?: ClassDecoratorContext): T => {
|
|
134
|
+
blocks.set(target, definition);
|
|
135
|
+
return target;
|
|
136
|
+
};
|
|
137
|
+
}
|
|
138
|
+
function makeInterface(
|
|
139
|
+
owner: () => object,
|
|
140
|
+
name: string,
|
|
141
|
+
options: InterfaceOptions,
|
|
142
|
+
): InterfaceRef {
|
|
143
|
+
return Object.freeze({
|
|
144
|
+
[interfaceBrand]: true as const,
|
|
145
|
+
name,
|
|
146
|
+
options: Object.freeze({ ...options }),
|
|
147
|
+
get blockId() {
|
|
148
|
+
const definition = blocks.get(owner());
|
|
149
|
+
if (!definition)
|
|
150
|
+
throw new Error(`Interface ${name} needs an annotated block`);
|
|
151
|
+
return definition.id;
|
|
152
|
+
},
|
|
153
|
+
get id() {
|
|
154
|
+
return options.id || `${this.blockId}::${name}`;
|
|
155
|
+
},
|
|
156
|
+
});
|
|
157
|
+
}
|
|
158
|
+
/** A static field is the single declaration and typed reference for an interface. */
|
|
159
|
+
export interface StandaloneInterfaceOptions extends InterfaceOptions {
|
|
160
|
+
id: string;
|
|
161
|
+
parent: () => object;
|
|
162
|
+
}
|
|
163
|
+
export function Interface(
|
|
164
|
+
id: string,
|
|
165
|
+
options?: InterfaceOptions & { parent?: () => object },
|
|
166
|
+
): InterfaceRef;
|
|
167
|
+
export function Interface(options: StandaloneInterfaceOptions): InterfaceRef;
|
|
168
|
+
export function Interface(
|
|
169
|
+
options?: InterfaceOptions,
|
|
170
|
+
): ReturnType<typeof interfaceDecorator>;
|
|
171
|
+
export function Interface(
|
|
172
|
+
options: string | InterfaceOptions | StandaloneInterfaceOptions = {},
|
|
173
|
+
details: InterfaceOptions & { parent?: () => object } = {},
|
|
174
|
+
) {
|
|
175
|
+
if (typeof options === "string") {
|
|
176
|
+
const id = identity(options),
|
|
177
|
+
name = id.split("/").slice(-1)[0]!;
|
|
178
|
+
if (details.parent)
|
|
179
|
+
return makeInterface(details.parent, name, { ...details, id });
|
|
180
|
+
return Object.freeze({
|
|
181
|
+
[interfaceBrand]: true as const,
|
|
182
|
+
id,
|
|
183
|
+
name,
|
|
184
|
+
blockId: id.includes("/") ? id.slice(0, id.lastIndexOf("/")) : "factory",
|
|
185
|
+
options: Object.freeze({ ...details, id }),
|
|
186
|
+
});
|
|
187
|
+
}
|
|
188
|
+
if ("parent" in options)
|
|
189
|
+
return makeInterface(
|
|
190
|
+
options.parent,
|
|
191
|
+
identity(options.id).split("/").slice(-1)[0]!,
|
|
192
|
+
options,
|
|
193
|
+
);
|
|
194
|
+
return interfaceDecorator(options);
|
|
195
|
+
}
|
|
196
|
+
function interfaceDecorator(options: InterfaceOptions) {
|
|
197
|
+
function decorate<T>(
|
|
198
|
+
_: undefined,
|
|
199
|
+
context: ClassFieldDecoratorContext<T, InterfaceRef>,
|
|
200
|
+
): (this: T, value: InterfaceRef) => InterfaceRef;
|
|
201
|
+
function decorate(target: Function, key: string | symbol): void;
|
|
202
|
+
function decorate(
|
|
203
|
+
target: unknown,
|
|
204
|
+
context: ClassFieldDecoratorContext | string | symbol,
|
|
205
|
+
): unknown {
|
|
206
|
+
if (typeof context === "object") {
|
|
207
|
+
if (!context.static || context.private)
|
|
208
|
+
throw new Error("@Interface requires a public static field");
|
|
209
|
+
context.addInitializer(function (this: unknown) {
|
|
210
|
+
const owner = this as Function & Record<string | symbol, unknown>;
|
|
211
|
+
if (
|
|
212
|
+
!(owner[context.name] as InterfaceRef | undefined)?.[interfaceBrand]
|
|
213
|
+
)
|
|
214
|
+
Object.defineProperty(owner, context.name, {
|
|
215
|
+
value: makeInterface(() => owner, String(context.name), options),
|
|
216
|
+
writable: false,
|
|
217
|
+
configurable: true,
|
|
218
|
+
});
|
|
219
|
+
});
|
|
220
|
+
return function (this: Function) {
|
|
221
|
+
return makeInterface(() => this, String(context.name), options);
|
|
222
|
+
};
|
|
223
|
+
}
|
|
224
|
+
// Bun's legacy field decorators execute after class fields initialize.
|
|
225
|
+
const value = makeInterface(
|
|
226
|
+
() => target as Function,
|
|
227
|
+
String(context),
|
|
228
|
+
options,
|
|
229
|
+
);
|
|
230
|
+
Object.defineProperty(target, context, {
|
|
231
|
+
value,
|
|
232
|
+
writable: false,
|
|
233
|
+
configurable: true,
|
|
234
|
+
});
|
|
235
|
+
return undefined;
|
|
236
|
+
}
|
|
237
|
+
return decorate;
|
|
238
|
+
}
|
|
239
|
+
export class FactoryViolation extends Error {
|
|
240
|
+
constructor(
|
|
241
|
+
readonly phase: "auth" | "input" | "output",
|
|
242
|
+
readonly cause: unknown,
|
|
243
|
+
) {
|
|
244
|
+
super(`Fractal ${phase} requirement failed`);
|
|
245
|
+
this.name = "FactoryViolation";
|
|
246
|
+
}
|
|
247
|
+
}
|
|
248
|
+
function validate(
|
|
249
|
+
parser: { parse(value: unknown): unknown } | undefined,
|
|
250
|
+
value: unknown,
|
|
251
|
+
) {
|
|
252
|
+
const result = parser?.parse(value);
|
|
253
|
+
if (result && typeof (result as PromiseLike<unknown>).then === "function") {
|
|
254
|
+
void Promise.resolve(result).catch(() => {});
|
|
255
|
+
throw new Error("Fractal runtime validators must be synchronous");
|
|
256
|
+
}
|
|
257
|
+
}
|
|
258
|
+
function wrap<F extends Callable>(
|
|
259
|
+
fn: F,
|
|
260
|
+
name: string,
|
|
261
|
+
reference?: () => InterfaceRef,
|
|
262
|
+
process?: BlockOptions,
|
|
263
|
+
options: MethodOptions = {},
|
|
264
|
+
): F {
|
|
265
|
+
const previous = wrappers.get(fn);
|
|
266
|
+
if (previous) {
|
|
267
|
+
fn = previous.original as F;
|
|
268
|
+
reference ||= previous.reference;
|
|
269
|
+
process ||= previous.process;
|
|
270
|
+
options = { ...previous.options, ...options };
|
|
271
|
+
}
|
|
272
|
+
const wrapped = function (this: unknown, ...args: unknown[]) {
|
|
273
|
+
const api = reference?.();
|
|
274
|
+
if (reference && (!api || api[interfaceBrand] !== true))
|
|
275
|
+
throw new Error(
|
|
276
|
+
"@Method requires an initialized typed interface reference",
|
|
277
|
+
);
|
|
278
|
+
const adapter = host;
|
|
279
|
+
// Public SDK/browser packages bundle only this portable module. Without an
|
|
280
|
+
// observer or an explicit policy/validator, preserve the original call path.
|
|
281
|
+
if (!adapter && !listeners.size && !options.contract && !api?.options.auth)
|
|
282
|
+
return fn.apply(this, args);
|
|
283
|
+
const parent = adapter?.current();
|
|
284
|
+
const id = crypto.randomUUID();
|
|
285
|
+
const frame: FactoryFrame = {
|
|
286
|
+
targetId:
|
|
287
|
+
process?.id ||
|
|
288
|
+
`${api!.id}#${options.name || name || fn.name || "call"}`,
|
|
289
|
+
id,
|
|
290
|
+
traceId: parent && !parent.finished ? parent.traceId : id,
|
|
291
|
+
runId: parent?.runId || parent?.traceId || id,
|
|
292
|
+
};
|
|
293
|
+
let codeRevision: string | undefined;
|
|
294
|
+
try {
|
|
295
|
+
codeRevision = adapter?.codeRevision?.();
|
|
296
|
+
} catch {
|
|
297
|
+
/* metadata is observational */
|
|
298
|
+
}
|
|
299
|
+
const started = performance.now();
|
|
300
|
+
let terminal = false;
|
|
301
|
+
const base = {
|
|
302
|
+
targetId: frame.targetId,
|
|
303
|
+
...(parent?.targetId && !parent.finished
|
|
304
|
+
? { callerId: parent.targetId }
|
|
305
|
+
: {}),
|
|
306
|
+
id,
|
|
307
|
+
traceId: frame.traceId,
|
|
308
|
+
...(codeRevision ? { codeRevision } : {}),
|
|
309
|
+
runId: frame.runId,
|
|
310
|
+
...(parent?.id && !parent.finished ? { parentId: parent.id } : {}),
|
|
311
|
+
...(parent?.finished
|
|
312
|
+
? { linkedSpanId: parent.id, linkedTraceId: parent.traceId }
|
|
313
|
+
: !parent?.id && parent?.linkedSpanId
|
|
314
|
+
? {
|
|
315
|
+
linkedSpanId: parent.linkedSpanId,
|
|
316
|
+
linkedTraceId: parent.linkedTraceId,
|
|
317
|
+
}
|
|
318
|
+
: {}),
|
|
319
|
+
blockId: process?.id || api!.blockId,
|
|
320
|
+
...(api ? { interfaceId: api.id } : {}),
|
|
321
|
+
method: options.name || name || fn.name || "call",
|
|
322
|
+
};
|
|
323
|
+
const emit = (
|
|
324
|
+
status: FactoryEvent["status"],
|
|
325
|
+
failure?: FactoryEvent["failure"],
|
|
326
|
+
) => {
|
|
327
|
+
if (status !== "started") {
|
|
328
|
+
if (terminal) return;
|
|
329
|
+
terminal = true;
|
|
330
|
+
frame.finished = true;
|
|
331
|
+
}
|
|
332
|
+
publish(
|
|
333
|
+
{
|
|
334
|
+
...base,
|
|
335
|
+
timestamp: Date.now(),
|
|
336
|
+
status,
|
|
337
|
+
...(status !== "started"
|
|
338
|
+
? { durationMs: performance.now() - started }
|
|
339
|
+
: {}),
|
|
340
|
+
...(failure ? { failure } : {}),
|
|
341
|
+
},
|
|
342
|
+
adapter,
|
|
343
|
+
);
|
|
344
|
+
};
|
|
345
|
+
const execute = () => {
|
|
346
|
+
emit("started");
|
|
347
|
+
let phase: FactoryEvent["failure"] = "auth";
|
|
348
|
+
const failed = (error: unknown): never => {
|
|
349
|
+
emit("failed", phase);
|
|
350
|
+
throw error;
|
|
351
|
+
};
|
|
352
|
+
const invoke = () => {
|
|
353
|
+
phase = "input";
|
|
354
|
+
// Validate without replacing live handles, object identity or caller arguments.
|
|
355
|
+
validate(options.contract?.args, args);
|
|
356
|
+
phase = "execution";
|
|
357
|
+
const value = fn.apply(this, args);
|
|
358
|
+
const complete = (result: unknown) => {
|
|
359
|
+
phase = "output";
|
|
360
|
+
validate(options.contract?.result, result);
|
|
361
|
+
emit("completed");
|
|
362
|
+
return result;
|
|
363
|
+
};
|
|
364
|
+
if (value && typeof value.then === "function") {
|
|
365
|
+
if (options.contract?.result)
|
|
366
|
+
return Promise.resolve(value).then(complete).catch(failed);
|
|
367
|
+
// Pure observation must not delay existing promise settlement or recovery scheduling.
|
|
368
|
+
void Promise.resolve(value).then(
|
|
369
|
+
() => emit("completed"),
|
|
370
|
+
() => emit("failed", "execution"),
|
|
371
|
+
);
|
|
372
|
+
return value;
|
|
373
|
+
}
|
|
374
|
+
return complete(value);
|
|
375
|
+
};
|
|
376
|
+
try {
|
|
377
|
+
const authorized = api?.options.auth?.({
|
|
378
|
+
receiver: this,
|
|
379
|
+
args,
|
|
380
|
+
context: adapter?.context?.(),
|
|
381
|
+
});
|
|
382
|
+
if (
|
|
383
|
+
authorized &&
|
|
384
|
+
typeof authorized === "object" &&
|
|
385
|
+
typeof authorized.then === "function"
|
|
386
|
+
) {
|
|
387
|
+
if (fn.constructor.name !== "AsyncFunction") {
|
|
388
|
+
void authorized.catch(() => {});
|
|
389
|
+
throw new Error("Async auth requires an async method");
|
|
390
|
+
}
|
|
391
|
+
return authorized
|
|
392
|
+
.then((allowed) => {
|
|
393
|
+
if (allowed === false) throw new FactoryViolation("auth", false);
|
|
394
|
+
return invoke();
|
|
395
|
+
})
|
|
396
|
+
.catch(failed);
|
|
397
|
+
}
|
|
398
|
+
if (authorized === false) throw new FactoryViolation("auth", false);
|
|
399
|
+
return invoke();
|
|
400
|
+
} catch (error) {
|
|
401
|
+
return failed(error);
|
|
402
|
+
}
|
|
403
|
+
};
|
|
404
|
+
const run = () => (adapter ? adapter.run(frame, execute) : execute());
|
|
405
|
+
// Preserve native async rejection semantics even when auth/input validation throws.
|
|
406
|
+
try {
|
|
407
|
+
return run();
|
|
408
|
+
} catch (error) {
|
|
409
|
+
if (fn.constructor.name === "AsyncFunction") return Promise.reject(error);
|
|
410
|
+
throw error;
|
|
411
|
+
}
|
|
412
|
+
};
|
|
413
|
+
Object.defineProperty(wrapped, "name", {
|
|
414
|
+
value: options.name || name || fn.name,
|
|
415
|
+
configurable: true,
|
|
416
|
+
});
|
|
417
|
+
Object.defineProperty(wrapped, "length", {
|
|
418
|
+
value: fn.length,
|
|
419
|
+
configurable: true,
|
|
420
|
+
});
|
|
421
|
+
if (process) blocks.set(wrapped, process);
|
|
422
|
+
wrappers.set(wrapped, { original: fn, reference, process, options });
|
|
423
|
+
return wrapped as F;
|
|
424
|
+
}
|
|
425
|
+
function callableDecorator(
|
|
426
|
+
reference?: () => InterfaceRef,
|
|
427
|
+
process?: BlockOptions,
|
|
428
|
+
options: MethodOptions = {},
|
|
429
|
+
) {
|
|
430
|
+
function decorate<F extends Callable>(fn: F): F;
|
|
431
|
+
function decorate<This, A extends any[], R>(
|
|
432
|
+
fn: (this: This, ...args: A) => R,
|
|
433
|
+
context: ClassMethodDecoratorContext<This, (this: This, ...args: A) => R>,
|
|
434
|
+
): (this: This, ...args: A) => R;
|
|
435
|
+
function decorate(
|
|
436
|
+
target: object,
|
|
437
|
+
key: string | symbol,
|
|
438
|
+
descriptor: PropertyDescriptor,
|
|
439
|
+
): PropertyDescriptor;
|
|
440
|
+
function decorate(
|
|
441
|
+
target: Callable | object,
|
|
442
|
+
context?: ClassMethodDecoratorContext | string | symbol,
|
|
443
|
+
descriptor?: PropertyDescriptor,
|
|
444
|
+
): unknown {
|
|
445
|
+
if (descriptor) {
|
|
446
|
+
descriptor.value = wrap(
|
|
447
|
+
descriptor.value,
|
|
448
|
+
String(context),
|
|
449
|
+
reference,
|
|
450
|
+
process,
|
|
451
|
+
options,
|
|
452
|
+
);
|
|
453
|
+
return descriptor;
|
|
454
|
+
}
|
|
455
|
+
const fn = target as Callable;
|
|
456
|
+
return wrap(
|
|
457
|
+
fn,
|
|
458
|
+
typeof context === "object" ? String(context.name) : fn.name,
|
|
459
|
+
reference,
|
|
460
|
+
process,
|
|
461
|
+
options,
|
|
462
|
+
);
|
|
463
|
+
}
|
|
464
|
+
return decorate;
|
|
465
|
+
}
|
|
466
|
+
export function Method(
|
|
467
|
+
reference: () => InterfaceRef,
|
|
468
|
+
options: MethodOptions = {},
|
|
469
|
+
) {
|
|
470
|
+
return callableDecorator(reference, undefined, options);
|
|
471
|
+
}
|
|
472
|
+
export function Process(
|
|
473
|
+
id: string | BlockOptions,
|
|
474
|
+
options: Omit<BlockOptions, "id"> = {},
|
|
475
|
+
) {
|
|
476
|
+
const definition =
|
|
477
|
+
typeof id === "string"
|
|
478
|
+
? { ...options, id: identity(id) }
|
|
479
|
+
: { ...id, id: identity(id.id) };
|
|
480
|
+
return callableDecorator(undefined, definition);
|
|
481
|
+
}
|