@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,9 @@
1
+ import type { DefinitionGraph } from "./model.js";
2
+ export interface DefinitionMount {
3
+ at: string;
4
+ definition: DefinitionGraph;
5
+ /** Mount the contents of this scope. Defaults to the definition's root. */
6
+ root?: string;
7
+ }
8
+ /** Compose independently versioned definitions without changing their element identities. */
9
+ export declare function composeDefinitions(base: DefinitionGraph, mounts: DefinitionMount[]): DefinitionGraph;
@@ -0,0 +1,72 @@
1
+ /** Compose independently versioned definitions without changing their element identities. */
2
+ export function composeDefinitions(base, mounts) {
3
+ const graph = structuredClone(base);
4
+ const occupied = new Set(graph.elements.map((node) => node.id));
5
+ for (const { at, definition, root = definition.id } of mounts) {
6
+ if (!occupied.has(at))
7
+ throw new Error(`Unknown mount target: ${at}`);
8
+ if (!definition.elements.some((node) => node.id === root))
9
+ throw new Error(`Unknown definition scope: ${root}`);
10
+ const included = new Set([root]);
11
+ let changed = true;
12
+ while (changed) {
13
+ changed = false;
14
+ for (const node of definition.elements)
15
+ if (node.parent &&
16
+ included.has(node.parent) &&
17
+ !included.has(node.id)) {
18
+ included.add(node.id);
19
+ changed = true;
20
+ }
21
+ }
22
+ const remap = (id) => (id === root ? at : id);
23
+ for (const node of definition.elements) {
24
+ if (node.id === root || !included.has(node.id))
25
+ continue;
26
+ if (occupied.has(node.id))
27
+ throw new Error(`Duplicate element identity: ${node.id}`);
28
+ occupied.add(node.id);
29
+ graph.elements.push({
30
+ ...node,
31
+ parent: node.parent ? remap(node.parent) : at,
32
+ definitionRevision: node.definitionRevision || definition.revision,
33
+ });
34
+ }
35
+ graph.connections.push(...definition.connections
36
+ .filter((edge) => included.has(edge.source) && included.has(edge.target))
37
+ .map((edge) => ({
38
+ ...edge,
39
+ source: remap(edge.source),
40
+ target: remap(edge.target),
41
+ })));
42
+ graph.tests.push(...definition.tests
43
+ .filter((test) => test.targets.some((id) => included.has(id)))
44
+ .map((test) => ({
45
+ ...test,
46
+ targets: test.targets.filter((id) => included.has(id)).map(remap),
47
+ })));
48
+ graph.failures.push(...definition.failures
49
+ .filter((failure) => included.has(failure.operationId))
50
+ .map((failure) => ({
51
+ ...failure,
52
+ operationId: remap(failure.operationId),
53
+ })));
54
+ graph.gaps.push(...definition.gaps);
55
+ }
56
+ for (const collection of [graph.connections, graph.tests]) {
57
+ const ids = collection.map((entry) => entry.id);
58
+ if (new Set(ids).size !== ids.length)
59
+ throw new Error("Duplicate composed relationship or test identity");
60
+ }
61
+ let hash = BigInt("14695981039346656037");
62
+ for (const byte of new TextEncoder().encode(JSON.stringify({
63
+ elements: graph.elements,
64
+ connections: graph.connections,
65
+ tests: graph.tests,
66
+ failures: graph.failures,
67
+ gaps: graph.gaps,
68
+ })))
69
+ hash = BigInt.asUintN(64, (hash ^ BigInt(byte)) * BigInt("1099511628211"));
70
+ graph.revision = hash.toString(16).padStart(16, "0");
71
+ return graph;
72
+ }
package/dist/core.d.ts ADDED
@@ -0,0 +1,87 @@
1
+ /** Browser/Worker-safe decorators. Discovery never imports an application to execute it. */
2
+ export { assertPublicConnections, publicConnectionError, } from "./public-boundaries.js";
3
+ export { Block, Interface, Method, Process, observeFactory, installFactoryHost, } from "./annotations.js";
4
+ export type { InterfaceRef, FactoryEvent, FactoryHost } from "./annotations.js";
5
+ export interface Schema<T> {
6
+ parse(value: unknown): T;
7
+ readonly jsonSchema?: unknown;
8
+ }
9
+ export interface Contract<I, O> {
10
+ id: string;
11
+ input: Schema<I>;
12
+ output: Schema<O>;
13
+ }
14
+ export type Input<C> = C extends Contract<infer I, unknown> ? I : never;
15
+ export type Output<C> = C extends Contract<unknown, infer O> ? O : never;
16
+ export declare function contract<I, O>(id: string, schemas: {
17
+ input: Schema<I>;
18
+ output: Schema<O>;
19
+ }): Contract<I, O>;
20
+ export declare class ContractViolation extends Error {
21
+ readonly contractId: string;
22
+ readonly phase: "input" | "output";
23
+ readonly cause: unknown;
24
+ constructor(contractId: string, phase: "input" | "output", cause: unknown);
25
+ }
26
+ type Constructor<T extends object = object> = new () => T;
27
+ type AnnotatedClass = abstract new (...args: never[]) => object;
28
+ type Definition = {
29
+ id: string;
30
+ title?: string;
31
+ docs?: string;
32
+ kind?: "factory" | "deployment" | "system" | "interface" | "process" | "block" | "resource" | "artifact";
33
+ };
34
+ type Operation = {
35
+ name: string;
36
+ contract: Contract<unknown, unknown>;
37
+ };
38
+ export interface OperationRuntime {
39
+ invoke<T>(boundary: {
40
+ elementId: string;
41
+ operation: string;
42
+ contract: string;
43
+ }, execute: () => Promise<T>): Promise<T>;
44
+ }
45
+ export interface BoundaryEvent {
46
+ elementId?: string;
47
+ invocationId: string;
48
+ operation: string;
49
+ contract: string;
50
+ timestamp: number;
51
+ durationMs?: number;
52
+ status: "started" | "completed" | "failed";
53
+ }
54
+ export declare function block(definition: Definition): <T extends AnnotatedClass>(target: T, _context?: ClassDecoratorContext<T>) => void;
55
+ export declare function own<T extends object, Args extends unknown[]>(type: new (...args: Args) => T, ...args: Args): T;
56
+ export declare function use<I, O>(definition: Contract<I, O>): (input: I) => Promise<O>;
57
+ export declare function operation<I, O>(definition: Contract<I, O>): {
58
+ <This extends object>(method: (this: This, input: I) => Promise<O>, context: ClassMethodDecoratorContext<This, (this: This, input: I) => Promise<O>>): (this: This, input: I) => Promise<O>;
59
+ <This extends object>(target: This, key: string | symbol, descriptor: TypedPropertyDescriptor<(this: This, input: I) => Promise<O>>): TypedPropertyDescriptor<(this: This, input: I) => Promise<O>>;
60
+ };
61
+ export interface InstanceDefinition {
62
+ id: string;
63
+ title: string;
64
+ parent?: string;
65
+ operations: {
66
+ name: string;
67
+ contract: string;
68
+ }[];
69
+ requires: string[];
70
+ }
71
+ export declare function describe(root: object): InstanceDefinition[];
72
+ export interface BindOptions {
73
+ bindings?: ReadonlyMap<string, (input: unknown) => Promise<unknown>>;
74
+ observe?: (event: BoundaryEvent) => void;
75
+ runtime?: OperationRuntime;
76
+ }
77
+ /** Bind actual owned providers; ambiguous providers require an explicit binding. */
78
+ export declare function bind<T extends object>(instance: T, options?: BindOptions): T;
79
+ export declare function create<T extends object>(type: Constructor<T>, options?: BindOptions): T;
80
+ /** Read declarations from actual ownership; schemas come from the enforced contracts. */
81
+ export declare function declarations(root: object): {
82
+ id: string;
83
+ parent?: string;
84
+ definition: Definition;
85
+ operations: Operation[];
86
+ requires: string[];
87
+ }[];
package/dist/core.js ADDED
@@ -0,0 +1,207 @@
1
+ /** Browser/Worker-safe decorators. Discovery never imports an application to execute it. */
2
+ export { assertPublicConnections, publicConnectionError, } from "./public-boundaries.js";
3
+ export { Block, Interface, Method, Process, observeFactory, installFactoryHost, } from "./annotations.js";
4
+ export function contract(id, schemas) {
5
+ if (!id.trim())
6
+ throw new Error("Contract identity is required");
7
+ return Object.freeze({ id, ...schemas });
8
+ }
9
+ export class ContractViolation extends Error {
10
+ contractId;
11
+ phase;
12
+ cause;
13
+ constructor(contractId, phase, cause) {
14
+ super(`Invalid ${phase} for contract ${contractId}`);
15
+ this.contractId = contractId;
16
+ this.phase = phase;
17
+ this.cause = cause;
18
+ this.name = "ContractViolation";
19
+ }
20
+ }
21
+ function validate(definition, phase, value) {
22
+ try {
23
+ return definition[phase].parse(value);
24
+ }
25
+ catch (error) {
26
+ throw new ContractViolation(definition.id, phase, error);
27
+ }
28
+ }
29
+ const definitions = new WeakMap();
30
+ const operations = new WeakMap();
31
+ const owned = new WeakSet();
32
+ const ports = new WeakMap();
33
+ const executionBindings = new WeakMap();
34
+ const observers = new WeakMap();
35
+ export function block(definition) {
36
+ return (target, _context) => {
37
+ definitions.set(target, Object.freeze({ ...definition }));
38
+ };
39
+ }
40
+ export function own(type, ...args) {
41
+ const instance = new type(...args);
42
+ owned.add(instance);
43
+ return instance;
44
+ }
45
+ export function use(definition) {
46
+ const port = async (input) => {
47
+ const bound = ports.get(port);
48
+ if (!bound.provider)
49
+ throw new Error(`Unbound capability: ${definition.id}`);
50
+ return validate(definition, "output", await bound.provider(validate(definition, "input", input)));
51
+ };
52
+ ports.set(port, { contract: definition });
53
+ return port;
54
+ }
55
+ export function operation(definition) {
56
+ function wrap(method, name) {
57
+ return async function (input) {
58
+ const execute = async () => {
59
+ const invocationId = crypto.randomUUID(), startedAt = performance.now();
60
+ const emit = (status) => {
61
+ // An observer failure must never change an operation's result.
62
+ try {
63
+ observers.get(this)?.({
64
+ invocationId,
65
+ operation: name,
66
+ contract: definition.id,
67
+ timestamp: Date.now(),
68
+ durationMs: status === "started"
69
+ ? undefined
70
+ : performance.now() - startedAt,
71
+ status,
72
+ });
73
+ }
74
+ catch {
75
+ /* observer only */
76
+ }
77
+ };
78
+ emit("started");
79
+ try {
80
+ const output = validate(definition, "output", await method.call(this, validate(definition, "input", input)));
81
+ emit("completed");
82
+ return output;
83
+ }
84
+ catch (error) {
85
+ emit("failed");
86
+ throw error;
87
+ }
88
+ };
89
+ const binding = executionBindings.get(this);
90
+ return binding?.runtime
91
+ ? binding.runtime.invoke({
92
+ elementId: `${binding.id}#${name}`,
93
+ operation: name,
94
+ contract: definition.id,
95
+ }, execute)
96
+ : execute();
97
+ };
98
+ }
99
+ function decorate(target, context, descriptor) {
100
+ const register = (instance, name) => {
101
+ const list = operations.get(instance) || [];
102
+ list.push({ name, contract: definition });
103
+ operations.set(instance, list);
104
+ };
105
+ if (typeof context === "object") {
106
+ context.addInitializer(function () {
107
+ register(this, String(context.name));
108
+ });
109
+ return wrap(target, String(context.name));
110
+ }
111
+ // Bun 1.3 emits legacy decorators; TypeScript emits the standard proposal.
112
+ if (!descriptor?.value)
113
+ throw new Error("@operation requires an async method");
114
+ register(target, String(context));
115
+ descriptor.value = wrap(descriptor.value, String(context));
116
+ return descriptor;
117
+ }
118
+ return decorate;
119
+ }
120
+ function blockOperations(instance) {
121
+ const result = new Map();
122
+ for (let current = instance; current; current = Object.getPrototypeOf(current)) {
123
+ for (const item of operations.get(current) || [])
124
+ if (!result.has(item.name))
125
+ result.set(item.name, item);
126
+ }
127
+ return [...result.values()];
128
+ }
129
+ function walk(root, visit) {
130
+ const seen = new Set();
131
+ const next = (instance, parent, field) => {
132
+ if (seen.has(instance))
133
+ throw new Error("A block must have one owner; use a capability for shared dependencies");
134
+ seen.add(instance);
135
+ const definition = definitions.get(instance.constructor);
136
+ if (!definition)
137
+ throw new Error(`Undeclared block: ${instance.constructor.name}`);
138
+ const id = parent ? `${parent}/${field}` : definition.id;
139
+ visit(instance, id, parent);
140
+ for (const [key, value] of Object.entries(instance))
141
+ if (value && typeof value === "object" && owned.has(value))
142
+ next(value, id, key);
143
+ };
144
+ next(root);
145
+ }
146
+ export function describe(root) {
147
+ const result = [];
148
+ walk(root, (instance, id, parent) => result.push({
149
+ id,
150
+ title: definitions.get(instance.constructor).title ||
151
+ instance.constructor.name,
152
+ parent,
153
+ operations: blockOperations(instance).map((op) => ({
154
+ name: op.name,
155
+ contract: op.contract.id,
156
+ })),
157
+ requires: Object.values(instance).flatMap((value) => typeof value === "function" && ports.has(value)
158
+ ? [ports.get(value).contract.id]
159
+ : []),
160
+ }));
161
+ return result;
162
+ }
163
+ /** Bind actual owned providers; ambiguous providers require an explicit binding. */
164
+ export function bind(instance, options = {}) {
165
+ const providers = new Map();
166
+ walk(instance, (block) => {
167
+ for (const op of blockOperations(block)) {
168
+ const list = providers.get(op.contract.id) || [];
169
+ list.push((input) => block[op.name](input));
170
+ providers.set(op.contract.id, list);
171
+ }
172
+ });
173
+ walk(instance, (block, id) => {
174
+ executionBindings.set(block, { id, runtime: options.runtime });
175
+ if (options.observe)
176
+ observers.set(block, (event) => options.observe({ ...event, elementId: `${id}#${event.operation}` }));
177
+ for (const value of Object.values(block))
178
+ if (typeof value === "function" && ports.has(value)) {
179
+ const port = ports.get(value);
180
+ const candidates = providers.get(port.contract.id) || [];
181
+ port.provider = options.bindings?.get(port.contract.id);
182
+ if (!port.provider && candidates.length > 1)
183
+ throw new Error(`Ambiguous capability: ${port.contract.id}`);
184
+ port.provider ||= candidates[0];
185
+ if (!port.provider)
186
+ throw new Error(`Unbound capability: ${port.contract.id}`);
187
+ }
188
+ });
189
+ return instance;
190
+ }
191
+ export function create(type, options = {}) {
192
+ return bind(new type(), options);
193
+ }
194
+ /** Read declarations from actual ownership; schemas come from the enforced contracts. */
195
+ export function declarations(root) {
196
+ const result = [];
197
+ walk(root, (instance, id, parent) => result.push({
198
+ id,
199
+ parent,
200
+ definition: definitions.get(instance.constructor),
201
+ operations: blockOperations(instance),
202
+ requires: Object.values(instance).flatMap((value) => typeof value === "function" && ports.has(value)
203
+ ? [ports.get(value).contract.id]
204
+ : []),
205
+ }));
206
+ return result;
207
+ }
@@ -0,0 +1 @@
1
+ export declare function runCoverage(args: string[]): Promise<string>;
@@ -0,0 +1,42 @@
1
+ import { readRepositoryMap } from "./repository-map.js";
2
+ import { readFileSync } from "node:fs";
3
+ import { join, resolve } from "node:path";
4
+ import { mappingCoverage, coverageSummary } from "./mapping-coverage.js";
5
+ export async function runCoverage(args) {
6
+ if (args.includes("--help"))
7
+ return "fractal coverage [--missing | --discarded] [--json] [--root PATH] [--definition PATH]\nVerified TS/JS source ownership in the current checkout; not test coverage. --excluded is an alias for --discarded.";
8
+ const option = (name) => {
9
+ const index = args.indexOf(name);
10
+ if (index < 0)
11
+ return undefined;
12
+ if (!args[index + 1] || args[index + 1].startsWith("--"))
13
+ throw Error(name + " needs a value");
14
+ return args[index + 1];
15
+ };
16
+ const root = resolve(option("--root") || process.cwd());
17
+ const graph = option("--definition")
18
+ ? JSON.parse(readFileSync(join(root, option("--definition")), "utf8"))
19
+ : readRepositoryMap(root);
20
+ if (!graph)
21
+ throw Error("No Fractory map in this repository. Run fractory setup.");
22
+ const report = await mappingCoverage(root, graph), summary = coverageSummary(report);
23
+ const items = args.includes("--missing") ||
24
+ args.includes("--excluded") ||
25
+ args.includes("--discarded")
26
+ ? report.items.filter((item) => item.excluded ===
27
+ (args.includes("--excluded") || args.includes("--discarded")))
28
+ : undefined;
29
+ if (args.includes("--json"))
30
+ return JSON.stringify({ ...summary, ...(items ? { items } : {}) }, null, 2);
31
+ return [
32
+ `Map coverage · ${report.percent === null ? "no in-scope source" : report.percent.toFixed(1) + "%"}`,
33
+ `${report.mapped.toLocaleString()} mapped / ${(report.mapped + report.missing).toLocaleString()} in-scope TS/JS source lines · ${report.excluded.toLocaleString()} discarded`,
34
+ `${report.mappedDeclarations.toLocaleString()} in declarations · ${report.mappedBlockSource.toLocaleString()} in block implementation files`,
35
+ `${summary.missingRegions} missing regions · ${report.sourceWarnings.length} stale source references · ${report.warnings.length} unmeasured files`,
36
+ ...(items
37
+ ? items.map((item) => `${item.file}:${item.start}-${item.end} · ${item.lines} lines\n ${item.label}${item.exclusionReason ? "\n " + item.exclusionReason : ""}`)
38
+ : [
39
+ "Use --missing to inspect uncovered declarations, or --excluded for dismissed regions.",
40
+ ]),
41
+ ].join("\n");
42
+ }
@@ -0,0 +1,3 @@
1
+ import type { DefinitionGraph } from "./model.js";
2
+ /** Associate decorator sites by their declared identities, never by filesystem nesting. */
3
+ export declare function declarationSources(graph: DefinitionGraph, file: string, text: string): DefinitionGraph;
@@ -0,0 +1,51 @@
1
+ import ts from "typescript";
2
+ import { sourceDigest } from "./source-index.js";
3
+ /** Associate decorator sites by their declared identities, never by filesystem nesting. */
4
+ export function declarationSources(graph, file, text) {
5
+ const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
6
+ const sources = new Map();
7
+ const digest = sourceDigest(text);
8
+ for (const node of sf.statements) {
9
+ if (!ts.isClassDeclaration(node))
10
+ continue;
11
+ const decorator = ts
12
+ .getDecorators(node)
13
+ ?.find((d) => ts.isCallExpression(d.expression) &&
14
+ d.expression.expression.getText(sf) === "block");
15
+ if (!decorator || !ts.isCallExpression(decorator.expression))
16
+ continue;
17
+ const config = decorator.expression.arguments[0];
18
+ if (!config || !ts.isObjectLiteralExpression(config))
19
+ continue;
20
+ const prop = config.properties.find((p) => ts.isPropertyAssignment(p) && p.name.getText(sf) === "id");
21
+ if (!prop ||
22
+ !ts.isPropertyAssignment(prop) ||
23
+ !ts.isStringLiteral(prop.initializer))
24
+ continue;
25
+ const local = prop.initializer.text;
26
+ const blocks = graph.elements.filter((e) => e.id === local || e.id.endsWith(`/${local}`));
27
+ if (blocks.length !== 1)
28
+ continue;
29
+ const block = blocks[0];
30
+ const ref = (item) => ({
31
+ file,
32
+ line: sf.getLineAndCharacterOfPosition(item.getStart(sf)).line + 1,
33
+ digest,
34
+ });
35
+ sources.set(block.id, ref(node));
36
+ for (const member of node.members)
37
+ if (ts.isMethodDeclaration(member) &&
38
+ ts
39
+ .getDecorators(member)
40
+ ?.some((d) => ts.isCallExpression(d.expression) &&
41
+ d.expression.expression.getText(sf) === "operation")) {
42
+ const id = `${block.id}#${member.name.getText(sf)}`;
43
+ if (graph.elements.some((e) => e.id === id))
44
+ sources.set(id, ref(member));
45
+ }
46
+ }
47
+ return {
48
+ ...graph,
49
+ elements: graph.elements.map((e) => sources.has(e.id) ? { ...e, source: sources.get(e.id) } : e),
50
+ };
51
+ }
@@ -0,0 +1,3 @@
1
+ import type { DefinitionGraph } from "./model.js";
2
+ /** This fingerprints the declared structure and schemas, not a deployment's source revision. */
3
+ export declare function declaredGraph(root: object): DefinitionGraph;
@@ -0,0 +1,67 @@
1
+ import { declarations } from "./core.js";
2
+ /** This fingerprints the declared structure and schemas, not a deployment's source revision. */
3
+ export function declaredGraph(root) {
4
+ const blocks = declarations(root);
5
+ const elements = blocks.flatMap((b) => [
6
+ {
7
+ id: b.id,
8
+ parent: b.parent,
9
+ label: b.definition.title || b.definition.id,
10
+ kind: b.definition.kind || "block",
11
+ provenance: "declared",
12
+ description: b.definition.docs,
13
+ },
14
+ ...b.operations.map((op) => ({
15
+ id: `${b.id}#${op.name}`,
16
+ parent: b.id,
17
+ label: op.name,
18
+ // An externally bound operation is itself a public contract, not an internal method.
19
+ kind: "interface",
20
+ provenance: "declared",
21
+ ...(b.operations.length === 1 ? { description: b.definition.docs } : {}),
22
+ contract: {
23
+ id: op.contract.id,
24
+ input: op.contract.input.jsonSchema,
25
+ output: op.contract.output.jsonSchema,
26
+ },
27
+ })),
28
+ ]);
29
+ const providers = new Map();
30
+ for (const b of blocks)
31
+ for (const op of b.operations)
32
+ providers.set(op.contract.id, [
33
+ ...(providers.get(op.contract.id) || []),
34
+ `${b.id}#${op.name}`,
35
+ ]);
36
+ const connections = [];
37
+ for (const b of blocks)
38
+ for (const requirement of b.requires) {
39
+ const candidates = providers.get(requirement) || [];
40
+ if (candidates.length !== 1)
41
+ throw new Error(`Declared capability ${requirement} needs one provider, found ${candidates.length}`);
42
+ connections.push({
43
+ id: `${b.id}->${candidates[0]}:${requirement}`,
44
+ source: b.operations.length === 1 ? `${b.id}#${b.operations[0].name}` : b.id,
45
+ target: candidates[0],
46
+ relation: "requires",
47
+ label: requirement,
48
+ provenance: "declared",
49
+ });
50
+ }
51
+ const content = JSON.stringify({ elements, connections });
52
+ let fingerprint = 14695981039346656037n;
53
+ for (const byte of new TextEncoder().encode(content))
54
+ fingerprint = BigInt.asUintN(64, (fingerprint ^ BigInt(byte)) * 1099511628211n);
55
+ return {
56
+ schema: "fractal.definition.v1",
57
+ id: blocks[0].id,
58
+ revision: fingerprint.toString(16).padStart(16, "0"),
59
+ generatedAt: "declaration",
60
+ scope: blocks[0].definition.title || blocks[0].definition.id,
61
+ elements,
62
+ connections,
63
+ tests: [],
64
+ failures: [],
65
+ gaps: [],
66
+ };
67
+ }
@@ -0,0 +1,2 @@
1
+ /** A readable fallback for code symbols. Explicit product labels and identities stay intact. */
2
+ export declare function displayName(symbol: string): string;
@@ -0,0 +1,8 @@
1
+ /** A readable fallback for code symbols. Explicit product labels and identities stay intact. */
2
+ export function displayName(symbol) {
3
+ return symbol
4
+ .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
5
+ .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
6
+ .replace(/[_-]+/g, " ")
7
+ .replace(/^./, (letter) => letter.toUpperCase());
8
+ }
@@ -0,0 +1,58 @@
1
+ import type { DefinitionGraph } from "./model.js";
2
+ export interface ErrorObservation {
3
+ eventId: string;
4
+ project: string;
5
+ issueId?: string;
6
+ title: string;
7
+ issueUrl?: string;
8
+ commit?: string;
9
+ matchReason?: string;
10
+ at?: string;
11
+ elementId?: string;
12
+ basis: "source" | "component" | "unassigned";
13
+ }
14
+ export interface ErrorHeat {
15
+ counts?: ErrorCount[];
16
+ accounting?: {
17
+ total: number;
18
+ source: number;
19
+ related: number;
20
+ projects: {
21
+ project: string;
22
+ total: number | null;
23
+ }[];
24
+ samplePartial: boolean;
25
+ classificationPartial: boolean;
26
+ };
27
+ warnings?: import("./sentry.js").SentryProjectWarning[];
28
+ fetchedAt: string;
29
+ period: string;
30
+ window?: import("./time-window.js").TimeWindow;
31
+ partial: boolean;
32
+ events: ErrorObservation[];
33
+ cells: Record<string, {
34
+ source: number;
35
+ related: number;
36
+ intensity: number;
37
+ }>;
38
+ unassigned: number;
39
+ }
40
+ /** Aggregate occurrences are not synthetic event IDs or extrapolated event samples. */
41
+ export interface ErrorCount {
42
+ project: string;
43
+ count: number;
44
+ elementId?: string;
45
+ basis: "source" | "component" | "unassigned";
46
+ reason?: string;
47
+ }
48
+ /** Each event contributes once to its owner and once to each ancestor, never to siblings. */
49
+ export declare function errorHeat(graph: DefinitionGraph, observations: ErrorObservation[], partial?: boolean, counts?: ErrorCount[]): ErrorHeat;
50
+ /** Group only provider issue identities; unrelated ungrouped events remain separate. */
51
+ export declare function groupErrors(events: ErrorObservation[]): {
52
+ events: ErrorObservation[];
53
+ key: string;
54
+ title: string;
55
+ project: string;
56
+ issueId?: string;
57
+ issueUrl?: string;
58
+ }[];