@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,96 @@
1
+ /** Each event contributes once to its owner and once to each ancestor, never to siblings. */
2
+ export function errorHeat(graph, observations, partial = false, counts) {
3
+ const byId = new Map(graph.elements.map((node) => [node.id, node]));
4
+ const seen = new Set(), events = [], cells = {};
5
+ for (const event of observations) {
6
+ const key = `${event.project}:${event.eventId}`;
7
+ if (seen.has(key))
8
+ continue;
9
+ seen.add(key);
10
+ const owner = event.elementId &&
11
+ byId.get(graph.aliases?.[event.elementId] || event.elementId);
12
+ const record = owner
13
+ ? { ...event, elementId: owner.id }
14
+ : { ...event, elementId: undefined, basis: "unassigned" };
15
+ events.push(record);
16
+ }
17
+ let unassigned = 0, source = 0, related = 0;
18
+ for (const row of counts || events.map((event) => ({ ...event, count: 1 }))) {
19
+ if (!Number.isSafeInteger(row.count) || row.count < 0)
20
+ throw Error("Invalid Sentry occurrence count");
21
+ const owner = row.elementId &&
22
+ byId.get(graph.aliases?.[row.elementId] || row.elementId);
23
+ if (!owner || row.basis === "unassigned") {
24
+ unassigned += row.count;
25
+ continue;
26
+ }
27
+ if (row.basis === "source")
28
+ source += row.count;
29
+ else
30
+ related += row.count;
31
+ let current = owner;
32
+ const ancestors = new Set();
33
+ while (current && !ancestors.has(current.id)) {
34
+ ancestors.add(current.id);
35
+ const cell = (cells[current.id] ||= {
36
+ source: 0,
37
+ related: 0,
38
+ intensity: 0,
39
+ });
40
+ if (row.basis === "source")
41
+ cell.source += row.count;
42
+ else if (row.basis === "component")
43
+ cell.related += row.count;
44
+ current = current.parent ? byId.get(current.parent) : undefined;
45
+ }
46
+ }
47
+ const maximum = Math.max(1, ...Object.entries(cells)
48
+ .filter(([id]) => id !== graph.id)
49
+ .map(([, cell]) => cell.source + cell.related));
50
+ for (const cell of Object.values(cells))
51
+ cell.intensity = Math.min(1, (cell.source + cell.related) / maximum);
52
+ return {
53
+ fetchedAt: new Date().toISOString(),
54
+ period: "14d",
55
+ partial,
56
+ events,
57
+ cells,
58
+ unassigned,
59
+ ...(counts
60
+ ? {
61
+ counts,
62
+ accounting: {
63
+ total: source + related + unassigned,
64
+ source,
65
+ related,
66
+ projects: [],
67
+ samplePartial: false,
68
+ classificationPartial: false,
69
+ },
70
+ }
71
+ : {}),
72
+ };
73
+ }
74
+ /** Group only provider issue identities; unrelated ungrouped events remain separate. */
75
+ export function groupErrors(events) {
76
+ const groups = new Map();
77
+ for (const event of events) {
78
+ const key = `${event.project}:${event.issueId || "event:" + event.eventId}`;
79
+ const group = groups.get(key) || {
80
+ key,
81
+ title: event.title,
82
+ project: event.project,
83
+ issueId: event.issueId,
84
+ issueUrl: event.issueUrl,
85
+ events: [],
86
+ };
87
+ group.events.push(event);
88
+ groups.set(key, group);
89
+ }
90
+ return [...groups.values()]
91
+ .map((group) => ({
92
+ ...group,
93
+ events: group.events.sort((a, b) => (Date.parse(b.at || "") || 0) - (Date.parse(a.at || "") || 0)),
94
+ }))
95
+ .sort((a, b) => b.events.length - a.events.length || a.key.localeCompare(b.key));
96
+ }
@@ -0,0 +1,3 @@
1
+ import type { DefinitionGraph, ExecutionEvidence } from "./model.js";
2
+ /** Project a real materialized session document. Never infer a call path from a terminal status. */
3
+ export declare function inspectJob(document: unknown, jobId: string, graph: DefinitionGraph): ExecutionEvidence;
@@ -0,0 +1,68 @@
1
+ const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
2
+ ? value
3
+ : {};
4
+ /** Project a real materialized session document. Never infer a call path from a terminal status. */
5
+ export function inspectJob(document, jobId, graph) {
6
+ const doc = record(document), jobs = record(record(doc.jobs).byId), job = record(jobs[jobId]);
7
+ if (!Object.keys(job).length)
8
+ throw new Error(`Job not found in session document: ${jobId}`);
9
+ const metadata = record(job.metadata), diagnostics = record(metadata.diagnostics), intent = record(job.startIntent);
10
+ const failures = (Array.isArray(diagnostics.failures) ? diagnostics.failures : []).map((value) => {
11
+ const f = record(value);
12
+ return {
13
+ code: String(f.code || "Unknown"),
14
+ origin: String(f.origin || "unknown"),
15
+ commit: String(f.commit || "unknown"),
16
+ };
17
+ });
18
+ const pending = record(metadata.pendingInvocations);
19
+ const unresolved = Object.entries(pending)
20
+ .filter(([, value]) => record(value).readOnly !== true)
21
+ .map(([id, value]) => ({
22
+ operationId: String(record(value).operationId || id),
23
+ commit: "unknown",
24
+ reason: "Outstanding mutation recorded in the session; its outcome is not established by job status.",
25
+ }));
26
+ const resolutions = new Set((Array.isArray(diagnostics.resolutions) ? diagnostics.resolutions : []).map((value) => record(value).operationId));
27
+ for (const value of Array.isArray(diagnostics.failures)
28
+ ? diagnostics.failures
29
+ : []) {
30
+ const failure = record(value), id = failure.operationId;
31
+ if (failure.commit === "unknown" &&
32
+ typeof id === "string" &&
33
+ !resolutions.has(id) &&
34
+ !unresolved.some((item) => item.operationId === id))
35
+ unresolved.push({
36
+ operationId: id,
37
+ commit: "unknown",
38
+ reason: "Failure diagnostics record an unresolved commit outcome.",
39
+ });
40
+ }
41
+ const observations = [];
42
+ const jobNode = graph.elements.find((n) => n.source?.symbol === "handleJobSubmitRpc");
43
+ if (jobNode)
44
+ observations.push({
45
+ elementId: jobNode.id,
46
+ label: `Persisted job record: ${String(job.status || "unknown")}. Submission call itself was not traced.`,
47
+ confidence: "recorded",
48
+ });
49
+ // Evidence records state, not fabricated traversal of all the nodes that could have run.
50
+ return {
51
+ schema: "fractal.evidence.v1",
52
+ jobId,
53
+ status: String(job.status || "unknown"),
54
+ runtime: typeof metadata.jobRuntime === "string" ? metadata.jobRuntime : undefined,
55
+ startIntent: typeof intent.state === "string"
56
+ ? {
57
+ state: intent.state,
58
+ attempt: typeof intent.attempt === "number" ? intent.attempt : 0,
59
+ }
60
+ : undefined,
61
+ unresolved,
62
+ failures,
63
+ observations,
64
+ definitionRevision: typeof metadata.fractalDefinitionRevision === "string"
65
+ ? metadata.fractalDefinitionRevision
66
+ : undefined,
67
+ };
68
+ }
@@ -0,0 +1,7 @@
1
+ import type { FactoryModel } from "./factory-model.js";
2
+ import type { DefinitionGraph } from "./model.js";
3
+ /** Compatibility projection only. The v2 model retains interface/member semantics. */
4
+ export declare function factoryGraph(model: FactoryModel, base?: DefinitionGraph, options?: {
5
+ legacySnapshot?: boolean;
6
+ exposeAncestors?: boolean;
7
+ }): DefinitionGraph;
@@ -0,0 +1,389 @@
1
+ import { displayName } from "./display-name.js";
2
+ import { interfaceMap } from "./interface-map.js";
3
+ function digest(value) {
4
+ let hash = BigInt("14695981039346656037");
5
+ for (const byte of new TextEncoder().encode(value))
6
+ hash = BigInt.asUintN(64, (hash ^ BigInt(byte)) * BigInt("1099511628211"));
7
+ return hash.toString(16).padStart(16, "0");
8
+ }
9
+ /** Compatibility projection only. The v2 model retains interface/member semantics. */
10
+ export function factoryGraph(model, base, options = {}) {
11
+ if (model.diagnostics.length)
12
+ throw new Error(model.diagnostics
13
+ .map((d) => `${d.file}:${d.line}: ${d.message}`)
14
+ .join("\n"));
15
+ const graph = base
16
+ ? structuredClone(base)
17
+ : {
18
+ schema: "fractal.definition.v1",
19
+ id: "factory",
20
+ revision: "",
21
+ generatedAt: "compiled",
22
+ scope: "Annotated factory",
23
+ elements: [
24
+ {
25
+ id: "factory",
26
+ label: "Factory",
27
+ kind: "block",
28
+ provenance: "declared",
29
+ },
30
+ ],
31
+ connections: [],
32
+ tests: [],
33
+ failures: [],
34
+ gaps: [],
35
+ };
36
+ // Reviewed inventories describe product areas, not executable control flow.
37
+ // Retire their handwritten process internals when source declarations take over.
38
+ const declaredIds = new Set([...model.blocks, ...model.interfaces, ...model.methods].map((item) => item.id));
39
+ for (const process of model.processes)
40
+ declaredIds.add(`${process.blockId}::entry`);
41
+ const processIds = new Set(model.processes.map((item) => item.blockId));
42
+ const oldById = new Map(graph.elements.map((item) => [item.id, item]));
43
+ // Incremental adoption: an ID names a logical area, never a source folder.
44
+ // Keep unowned declarations inside the nearest existing inventory block.
45
+ // An explicit typed parent always wins; no parallel parent/child registry.
46
+ const inventoryParent = (id) => [...oldById.values()]
47
+ .filter((node) => kept.has(node.id) &&
48
+ id.startsWith(`${node.id}/`) &&
49
+ ![
50
+ "resource",
51
+ "artifact",
52
+ "method",
53
+ "operation",
54
+ "interface",
55
+ ].includes(node.kind))
56
+ .sort((a, b) => b.id.length - a.id.length)[0]?.id;
57
+ const inProcess = (id) => {
58
+ const seen = new Set();
59
+ while (id && !seen.has(id)) {
60
+ if (processIds.has(id))
61
+ return true;
62
+ seen.add(id);
63
+ id = oldById.get(id)?.parent || "";
64
+ }
65
+ return false;
66
+ };
67
+ // A reviewed leaf may describe the exact method now supplied by an annotation.
68
+ // Collapse only unambiguous matches inside the same logical owner; never infer
69
+ // ownership from a file alone or replace a capability group with its helper.
70
+ const ownedBy = (id, owner) => {
71
+ const seen = new Set();
72
+ while (id && !seen.has(id)) {
73
+ if (id === owner)
74
+ return true;
75
+ seen.add(id);
76
+ id = oldById.get(id)?.parent || "";
77
+ }
78
+ return false;
79
+ };
80
+ const adopted = new Map();
81
+ for (const node of graph.elements) {
82
+ if (node.kind !== "method" ||
83
+ node.provenance === "declared" ||
84
+ declaredIds.has(node.id) ||
85
+ graph.elements.some((child) => child.parent === node.id))
86
+ continue;
87
+ const candidates = model.methods.filter((method) => method.source.file === node.source?.file &&
88
+ ownedBy(node.parent || "", method.blockId) &&
89
+ (node.source?.symbol === method.name ||
90
+ new RegExp("\\b" +
91
+ method.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") +
92
+ "\\s*\\(").test(node.source?.symbol || "")));
93
+ if (candidates.length === 1) {
94
+ const method = candidates[0], process = model.processes.find((p) => p.entryMethodId === method.id);
95
+ adopted.set(node.id, process?.blockId || method.id);
96
+ }
97
+ }
98
+ graph.aliases = { ...graph.aliases, ...Object.fromEntries(adopted) };
99
+ graph.elements = graph.elements.filter((item) => (!inProcess(item.id) || declaredIds.has(item.id)) &&
100
+ !adopted.has(item.id));
101
+ graph.connections = graph.connections.map((edge) => ({
102
+ ...edge,
103
+ source: adopted.get(edge.source) || edge.source,
104
+ target: adopted.get(edge.target) || edge.target,
105
+ }));
106
+ graph.tests = graph.tests.map((test) => ({
107
+ ...test,
108
+ targets: [...new Set(test.targets.map((id) => adopted.get(id) || id))],
109
+ }));
110
+ const kept = new Set([
111
+ ...graph.elements.map((item) => item.id),
112
+ ...declaredIds,
113
+ ]);
114
+ graph.connections = graph.connections.filter((edge) => !edge.path &&
115
+ kept.has(edge.source) &&
116
+ kept.has(edge.target) &&
117
+ !(edge.id.startsWith("flow:") &&
118
+ (inProcess(edge.source) || inProcess(edge.target))));
119
+ graph.tests = graph.tests
120
+ .map((test) => ({
121
+ ...test,
122
+ targets: test.targets.filter((id) => kept.has(id)),
123
+ }))
124
+ .filter((test) => test.targets.length);
125
+ const put = (element) => {
126
+ element.definitionRevision = model.revision;
127
+ const index = graph.elements.findIndex((node) => node.id === element.id);
128
+ if (index < 0)
129
+ graph.elements.push(element);
130
+ else
131
+ graph.elements[index] = {
132
+ ...graph.elements[index],
133
+ ...element,
134
+ sources: [
135
+ ...(element.sources || (element.source ? [element.source] : [])),
136
+ ...(graph.elements[index].sources || []).filter((source) => source.scope === "file"),
137
+ ].filter((source, at, all) => all.findIndex((other) => JSON.stringify(other) === JSON.stringify(source)) === at),
138
+ description: element.description ?? graph.elements[index].description,
139
+ parent: element.parent || graph.elements[index].parent,
140
+ };
141
+ };
142
+ const attach = (id, attachments, source) => {
143
+ for (const file of attachments.tests) {
144
+ const testId = `attachment:${id}:${file}`;
145
+ if (!graph.tests.some((test) => test.id === testId))
146
+ graph.tests.push({
147
+ id: testId,
148
+ name: file,
149
+ source: { ...source, file, line: 1 },
150
+ targets: [id],
151
+ association: "attachment",
152
+ status: "not_run",
153
+ });
154
+ }
155
+ };
156
+ for (const block of model.blocks) {
157
+ const existing = graph.elements.find((node) => node.id === block.id);
158
+ const label = block.label === block.id.split("/").at(-1)
159
+ ? existing?.label || block.label
160
+ : block.label;
161
+ const entry = model.methods.find((method) => model.processes.some((process) => process.blockId === block.id && process.entryMethodId === method.id));
162
+ put({
163
+ id: block.id,
164
+ label,
165
+ parent: block.parent ||
166
+ existing?.parent ||
167
+ inventoryParent(block.id) ||
168
+ (block.id !== graph.id ? graph.id : undefined),
169
+ kind: model.processes.some((process) => process.blockId === block.id)
170
+ ? "process"
171
+ : "block",
172
+ provenance: "declared",
173
+ source: block.source,
174
+ sources: [block.source],
175
+ description: block.attachments.description,
176
+ attachments: block.attachments,
177
+ ...(entry
178
+ ? {
179
+ signature: entry.signature,
180
+ contract: {
181
+ id: block.id,
182
+ input: {
183
+ language: "typescript",
184
+ args: entry.contract.args,
185
+ typeSources: entry.contract.typeSources,
186
+ runtimeValidation: entry.contract.runtimeValidation,
187
+ },
188
+ output: { language: "typescript", type: entry.contract.result },
189
+ },
190
+ }
191
+ : {}),
192
+ });
193
+ attach(block.id, block.attachments, block.source);
194
+ }
195
+ for (const api of model.interfaces) {
196
+ const previous = `${api.blockId}::${api.name}`;
197
+ if (api.id !== previous) {
198
+ graph.aliases = { ...graph.aliases, [previous]: api.id };
199
+ for (const method of model.methods.filter((method) => method.interfaceId === api.id))
200
+ graph.aliases[`${previous}#${method.name}`] = method.id;
201
+ }
202
+ put({
203
+ id: api.id,
204
+ // A source inventory may supply the prefix owner during incremental
205
+ // adoption. With a smaller inventory, use its nearest known owner rather
206
+ // than emitting an orphan or manufacturing intermediate blocks.
207
+ parent: kept.has(api.blockId)
208
+ ? api.blockId
209
+ : inventoryParent(api.id) || graph.id,
210
+ kind: "interface",
211
+ label: api.label ||
212
+ api.name
213
+ .replace(/([a-z])([A-Z])/g, "$1 $2")
214
+ .replace(/^./, (letter) => letter.toUpperCase()),
215
+ provenance: "declared",
216
+ source: { ...api.source, scope: "contract" },
217
+ sources: [{ ...api.source, scope: "contract" }],
218
+ attachments: api.attachments,
219
+ description: api.attachments.description,
220
+ signature: api.constructorContract?.signature,
221
+ contract: {
222
+ id: api.id,
223
+ input: {
224
+ language: "typescript",
225
+ ...(api.constructorContract
226
+ ? { args: api.constructorContract.args }
227
+ : {}),
228
+ members: model.methods
229
+ .filter((method) => method.interfaceId === api.id)
230
+ .map((method) => ({ name: method.name, ...method.contract })),
231
+ },
232
+ },
233
+ });
234
+ attach(api.id, api.attachments, api.source);
235
+ for (const owner of [
236
+ ...(api.exposedBy || []),
237
+ ...(model.blocks.find((block) => block.id === api.blockId)?.exposedBy ||
238
+ []),
239
+ ])
240
+ graph.connections.push({
241
+ id: `public-exposure:${owner}:${api.id}`,
242
+ source: owner,
243
+ target: api.id,
244
+ relation: "exposes",
245
+ label: api.label || api.name,
246
+ provenance: "declared",
247
+ sourceRef: api.source,
248
+ });
249
+ }
250
+ for (const method of model.methods) {
251
+ // A process entry is the implementation of its process box, not an extra method box.
252
+ const processEntry = model.processes.some((process) => process.entryMethodId === method.id);
253
+ if (processEntry && !method.interfaceId)
254
+ continue;
255
+ if (processEntry && method.interfaceId)
256
+ graph.connections.push({
257
+ id: `interface-entry:${method.id}`,
258
+ source: method.blockId,
259
+ target: method.interfaceId,
260
+ relation: "exposes",
261
+ label: method.name,
262
+ provenance: "declared",
263
+ sourceRef: method.source,
264
+ });
265
+ put({
266
+ id: method.id,
267
+ parent: method.interfaceId || method.blockId,
268
+ kind: "method",
269
+ label: method.label || displayName(method.name),
270
+ provenance: "declared",
271
+ source: method.source,
272
+ sources: [method.source],
273
+ signature: method.endpoint
274
+ ? `${method.endpoint.method} ${method.endpoint.path}`
275
+ : method.signature,
276
+ ...(processEntry ? { implementationBlock: method.blockId } : {}),
277
+ contract: {
278
+ id: method.id,
279
+ input: {
280
+ language: "typescript",
281
+ ...(method.endpoint ? { endpoint: method.endpoint } : {}),
282
+ args: method.contract.args,
283
+ typeSources: method.contract.typeSources,
284
+ runtimeValidation: method.contract.runtimeValidation,
285
+ },
286
+ output: { language: "typescript", type: method.contract.result },
287
+ },
288
+ attachments: method.attachments,
289
+ });
290
+ attach(method.id, method.attachments, method.source);
291
+ }
292
+ for (const dependency of model.dependencies) {
293
+ const id = `call-site:${dependency.source}->${dependency.target}:${dependency.at.file}:${dependency.at.line}:${dependency.relation || "calls"}:${dependency.label || ""}`;
294
+ if (!graph.connections.some((edge) => edge.id === id))
295
+ graph.connections.push({
296
+ id,
297
+ source: dependency.source,
298
+ target: dependency.target,
299
+ relation: dependency.relation || "calls",
300
+ label: dependency.label ||
301
+ graph.elements.find((node) => node.id === dependency.target)?.label ||
302
+ dependency.target,
303
+ provenance: "source",
304
+ sourceRef: dependency.at,
305
+ ...(dependency.transport ? { transport: dependency.transport } : {}),
306
+ ...(dependency.via?.length
307
+ ? { sources: [...dependency.via, dependency.at] }
308
+ : {}),
309
+ ...(dependency.exchange ? { exchange: dependency.exchange } : {}),
310
+ ...(dependency.displayLabel
311
+ ? { displayLabel: dependency.displayLabel }
312
+ : {}),
313
+ });
314
+ }
315
+ // A bootstrap capability can be broader than the declared caller. Prefer the
316
+ // exact compiled owner for each identical call site, retaining uncovered sites.
317
+ const covered = new Set(model.dependencies.map((edge) => `${edge.target}:${edge.at.file}:${edge.at.line}:${edge.relation || "calls"}`));
318
+ graph.connections = graph.connections.flatMap((edge) => {
319
+ if (!edge.id.startsWith("source:"))
320
+ return [edge];
321
+ const refs = edge.sources || (edge.sourceRef ? [edge.sourceRef] : []);
322
+ const remaining = refs.filter((ref) => !covered.has(`${edge.target}:${ref.file}:${ref.line}:${edge.relation}`));
323
+ if (remaining.length === refs.length)
324
+ return [edge];
325
+ return remaining.length
326
+ ? [{ ...edge, sourceRef: remaining[0], sources: remaining }]
327
+ : [];
328
+ });
329
+ graph.gaps.push(...(model.interactionGaps || []));
330
+ // Call sites are explicitly source evidence; actual traversal comes only from traces.
331
+ graph.revision = digest(JSON.stringify({
332
+ elements: graph.elements,
333
+ connections: graph.connections,
334
+ tests: graph.tests,
335
+ failures: graph.failures,
336
+ gaps: graph.gaps,
337
+ })).slice(0, 16);
338
+ const entries = model.interfaces
339
+ .filter((api) => api.constructorContract || api.entrypoint)
340
+ .map((api) => ({
341
+ implementation: api.blockId,
342
+ interface: graph.elements.find((node) => node.id === api.id),
343
+ }));
344
+ entries.push(...model.processes.flatMap((process) => {
345
+ const method = model.methods.find((item) => item.id === process.entryMethodId);
346
+ if (!method ||
347
+ !graph.elements.some((item) => item.id === process.blockId))
348
+ return [];
349
+ const id = `${process.blockId}::entry`;
350
+ for (const owner of model.blocks.find((block) => block.id === process.blockId)?.exposedBy || [])
351
+ graph.connections.push({
352
+ id: `public-exposure:${owner}:${id}`,
353
+ source: owner,
354
+ target: id,
355
+ relation: "exposes",
356
+ label: method.name,
357
+ provenance: "declared",
358
+ sourceRef: method.source,
359
+ });
360
+ return [
361
+ {
362
+ implementation: process.blockId,
363
+ interface: {
364
+ id,
365
+ parent: process.blockId,
366
+ kind: "interface",
367
+ provenance: "declared",
368
+ label: method.label || displayName(method.name),
369
+ description: method.attachments.description ||
370
+ `Public entry to ${graph.elements.find((item) => item.id === process.blockId).label}.`,
371
+ source: { ...method.source, scope: "contract" },
372
+ sources: [{ ...method.source, scope: "contract" }],
373
+ signature: method.signature,
374
+ contract: {
375
+ id,
376
+ input: { language: "typescript", args: method.contract.args },
377
+ output: { language: "typescript", type: method.contract.result },
378
+ },
379
+ },
380
+ },
381
+ ];
382
+ }));
383
+ const result = interfaceMap(graph, entries, {
384
+ exposeAncestors: options.exposeAncestors,
385
+ validate: !options.legacySnapshot,
386
+ });
387
+ result.revision = digest(JSON.stringify({ ...result, revision: "" })).slice(0, 16);
388
+ return result;
389
+ }
@@ -0,0 +1,111 @@
1
+ import type { SourceRef } from "./model.js";
2
+ export interface FactoryAttachments {
3
+ benchmarks?: string[];
4
+ docs: string[];
5
+ tests: string[];
6
+ description?: string;
7
+ /** A policy is enforced by its runtime function, not by a descriptive label. */
8
+ auth?: {
9
+ symbol: string;
10
+ source: SourceRef;
11
+ };
12
+ }
13
+ export interface FactoryBlock {
14
+ exposedBy?: string[];
15
+ inputLabel?: string;
16
+ eventLabel?: string;
17
+ id: string;
18
+ label: string;
19
+ parent?: string;
20
+ source: SourceRef;
21
+ attachments: FactoryAttachments;
22
+ }
23
+ export interface FactoryInterface {
24
+ /** A callable block or class constructor is implemented by its owning box. */
25
+ entrypoint?: boolean;
26
+ exposedBy?: string[];
27
+ constructorContract?: {
28
+ signature: string;
29
+ args: {
30
+ name: string;
31
+ type: string;
32
+ optional: boolean;
33
+ rest: boolean;
34
+ }[];
35
+ result: string;
36
+ };
37
+ id: string;
38
+ blockId: string;
39
+ name: string;
40
+ label?: string;
41
+ source: SourceRef;
42
+ attachments: FactoryAttachments;
43
+ methods: string[];
44
+ }
45
+ export interface FactoryMethod {
46
+ label?: string;
47
+ endpoint?: {
48
+ method: string;
49
+ path: string;
50
+ };
51
+ id: string;
52
+ blockId: string;
53
+ interfaceId?: string;
54
+ name: string;
55
+ source: SourceRef;
56
+ signature: string;
57
+ contract: {
58
+ args: {
59
+ name: string;
60
+ type: string;
61
+ optional: boolean;
62
+ rest: boolean;
63
+ }[];
64
+ result: string;
65
+ /** Fingerprinted type dependencies; these files are not owned executable code. */
66
+ typeSources?: SourceRef[];
67
+ /** Type information is not a claim that a runtime validator exists. */
68
+ runtimeValidation: boolean;
69
+ };
70
+ attachments: FactoryAttachments;
71
+ }
72
+ export interface FactoryProcess {
73
+ blockId: string;
74
+ entryMethodId: string;
75
+ }
76
+ export interface FactoryModel {
77
+ schema: "fractal.factory.v2";
78
+ revision: string;
79
+ blocks: FactoryBlock[];
80
+ interfaces: FactoryInterface[];
81
+ methods: FactoryMethod[];
82
+ processes: FactoryProcess[];
83
+ /** Source-backed interactions. Helpers retain their evidence without becoming boxes. */
84
+ dependencies: {
85
+ source: string;
86
+ target: string;
87
+ at: SourceRef;
88
+ relation?: "calls" | "renders" | "callbacks" | "delegates" | "exposes";
89
+ label?: string;
90
+ displayLabel?: string;
91
+ transport?: string;
92
+ via?: SourceRef[];
93
+ exchange?: {
94
+ inputs: {
95
+ name: string;
96
+ type: string;
97
+ }[];
98
+ output?: string;
99
+ };
100
+ }[];
101
+ interactionGaps?: {
102
+ source: SourceRef;
103
+ expression: string;
104
+ reason: string;
105
+ }[];
106
+ diagnostics: {
107
+ file: string;
108
+ line: number;
109
+ message: string;
110
+ }[];
111
+ }
@@ -0,0 +1 @@
1
+ export {};