@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,39 @@
1
+ export function resolvedReportBlock(graph, id) {
2
+ const seen = new Set();
3
+ while (graph.aliases && Object.hasOwn(graph.aliases, id) && typeof graph.aliases[id] === "string" && !seen.has(id)) {
4
+ seen.add(id);
5
+ id = graph.aliases[id];
6
+ }
7
+ return id;
8
+ }
9
+ /** A multi-target report contributes once to each ancestor, including the root. */
10
+ export function reportBlocks(graph, report) {
11
+ const byId = new Map(graph.elements.map((node) => [node.id, node]));
12
+ const owners = new Set();
13
+ // The repository inbox must also retain reports whose target was removed.
14
+ // Their tree placement stays explicitly Unassigned, never a guessed leaf.
15
+ if (byId.has(graph.id))
16
+ owners.add(graph.id);
17
+ for (const target of report.blocks) {
18
+ let id = resolvedReportBlock(graph, target);
19
+ const seen = new Set();
20
+ while (id && byId.has(id) && !seen.has(id)) {
21
+ seen.add(id);
22
+ owners.add(id);
23
+ id = byId.get(id).parent;
24
+ }
25
+ }
26
+ return owners;
27
+ }
28
+ export function unreadReportCounts(graph, reports) {
29
+ const counts = Object.create(null);
30
+ for (const report of reports)
31
+ if (report.unread)
32
+ for (const id of reportBlocks(graph, report))
33
+ counts[id] = (counts[id] || 0) + 1;
34
+ return counts;
35
+ }
36
+ export function reportsForBlock(graph, reports, block) {
37
+ const id = resolvedReportBlock(graph, block);
38
+ return reports.filter((report) => reportBlocks(graph, report).has(id));
39
+ }
@@ -0,0 +1,23 @@
1
+ import type { DefinitionGraph } from "./model.js";
2
+ import { type ReportDocument, type ReportsView } from "./reports-model.js";
3
+ export declare function listReports(root: string, ref?: string): ReportsView;
4
+ export declare function readReport(root: string, id: string, ref?: string): ReportDocument;
5
+ export declare function createReport(root: string, graph: DefinitionGraph, input: {
6
+ title: string;
7
+ blocks: string[];
8
+ body: string;
9
+ author?: string;
10
+ }): ReportDocument;
11
+ export declare function markReport(root: string, id: string, revision: string, read: boolean, ref?: string): {
12
+ unread: boolean;
13
+ body: string;
14
+ file: string;
15
+ revision: string;
16
+ schema: "fractory.report.v1";
17
+ id: string;
18
+ title: string;
19
+ blocks: string[];
20
+ createdAt: string;
21
+ author?: string;
22
+ codeRevision?: string;
23
+ };
@@ -0,0 +1,223 @@
1
+ import { readGit } from "./git-refs.js";
2
+ import { randomUUID } from "node:crypto";
3
+ import { execFileSync } from "node:child_process";
4
+ import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
5
+ import { dirname, join } from "node:path";
6
+ import { checkedPath, noteRevision, WorkspaceConflict, } from "./workspace-notes.js";
7
+ import { resolvedReportBlock, } from "./reports-model.js";
8
+ const directory = "docs/fractory/reports";
9
+ const limit = 128_000;
10
+ const validId = /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/;
11
+ const cache = new Map();
12
+ function reportFile(id) {
13
+ if (!validId.test(id))
14
+ throw Error("Choose a valid report ID.");
15
+ return `${directory}/${id}.md`;
16
+ }
17
+ function receiptFile(id) {
18
+ reportFile(id);
19
+ return `.fractal/reports/read/${id}.json`;
20
+ }
21
+ function atomic(root, file, body) {
22
+ const path = checkedPath(root, file, true);
23
+ mkdirSync(dirname(path), { recursive: true });
24
+ checkedPath(root, file, true);
25
+ const temp = join(dirname(path), `.fractory-${randomUUID()}.tmp`);
26
+ try {
27
+ writeFileSync(temp, body, { flag: "wx", mode: 0o600 });
28
+ renameSync(temp, path);
29
+ }
30
+ finally {
31
+ if (existsSync(temp))
32
+ unlinkSync(temp);
33
+ }
34
+ }
35
+ function parse(text, id) {
36
+ // Standard Markdown front matter with a JSON/YAML flow mapping. Reports do
37
+ // not need a new parser dependency or an additional registry of bindings.
38
+ const match = /^---\r?\nfractory: ([^\r\n]+)\r?\n---\r?\n/.exec(text);
39
+ if (!match)
40
+ throw Error("Missing Fractory report front matter.");
41
+ const metadata = JSON.parse(match[1]);
42
+ if (metadata.schema !== "fractory.report.v1" ||
43
+ metadata.id !== id ||
44
+ !validId.test(metadata.id) ||
45
+ typeof metadata.title !== "string" ||
46
+ !metadata.title.trim() ||
47
+ metadata.title.length > 160 ||
48
+ !Array.isArray(metadata.blocks) ||
49
+ !metadata.blocks.length ||
50
+ metadata.blocks.some((block) => typeof block !== "string" || !block || block.length > 4096) ||
51
+ typeof metadata.createdAt !== "string" ||
52
+ !Number.isFinite(Date.parse(metadata.createdAt)) ||
53
+ (metadata.author !== undefined &&
54
+ (typeof metadata.author !== "string" || metadata.author.length > 100)) ||
55
+ (metadata.codeRevision !== undefined &&
56
+ !/^[a-f0-9]{40,64}$/.test(metadata.codeRevision)))
57
+ throw Error("Invalid Fractory report metadata.");
58
+ return { metadata, body: text.slice(match[0].length) };
59
+ }
60
+ function readRevision(root, id) {
61
+ const path = checkedPath(root, receiptFile(id), true);
62
+ if (!existsSync(path))
63
+ return undefined;
64
+ try {
65
+ const value = JSON.parse(readFileSync(path, "utf8"));
66
+ return typeof value.revision === "string" ? value.revision : undefined;
67
+ }
68
+ catch {
69
+ return undefined;
70
+ }
71
+ }
72
+ function summary(root, id) {
73
+ const file = reportFile(id), path = checkedPath(root, file);
74
+ const stat = lstatSync(path);
75
+ if (!stat.isFile() || stat.size > limit)
76
+ throw Error("Report must be a Markdown file below 128 KB.");
77
+ const stamp = `${stat.ino}:${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}`;
78
+ let entry = cache.get(path);
79
+ if (!entry || entry.stamp !== stamp) {
80
+ const text = readFileSync(path, "utf8");
81
+ entry = {
82
+ stamp,
83
+ metadata: parse(text, id).metadata,
84
+ revision: noteRevision(text),
85
+ };
86
+ cache.set(path, entry);
87
+ if (cache.size > 2048)
88
+ cache.delete(cache.keys().next().value);
89
+ }
90
+ return {
91
+ ...entry.metadata,
92
+ file,
93
+ revision: entry.revision,
94
+ unread: readRevision(root, id) !== entry.revision,
95
+ };
96
+ }
97
+ export function listReports(root, ref) {
98
+ if (ref) {
99
+ const reports = [], warnings = [];
100
+ for (const file of readGit(root, [
101
+ "ls-tree",
102
+ "-r",
103
+ "--name-only",
104
+ ref,
105
+ "--",
106
+ directory,
107
+ ])
108
+ .trim()
109
+ .split("\n")
110
+ .filter(Boolean)) {
111
+ try {
112
+ const id = file.split("/").at(-1).replace(/\.md$/, ""), { body, ...report } = readReport(root, id, ref);
113
+ reports.push(report);
114
+ }
115
+ catch (e) {
116
+ warnings.push(`${file}: unreadable report`);
117
+ }
118
+ }
119
+ return {
120
+ reports: reports.sort((a, b) => b.createdAt.localeCompare(a.createdAt)),
121
+ warnings,
122
+ };
123
+ }
124
+ const path = checkedPath(root, directory, true);
125
+ if (!existsSync(path))
126
+ return { reports: [], warnings: [] };
127
+ const reports = [], warnings = [];
128
+ for (const file of readdirSync(path).sort()) {
129
+ if (!file.endsWith(".md"))
130
+ continue;
131
+ const id = file.slice(0, -3);
132
+ try {
133
+ reports.push(summary(root, id));
134
+ }
135
+ catch (error) {
136
+ warnings.push(`${file}: ${error instanceof Error ? error.message : "Unreadable report"}`);
137
+ }
138
+ }
139
+ reports.sort((a, b) => b.createdAt.localeCompare(a.createdAt) || a.id.localeCompare(b.id));
140
+ return { reports, warnings };
141
+ }
142
+ export function readReport(root, id, ref) {
143
+ if (ref) {
144
+ const file = reportFile(id), text = readGit(root, ["show", `${ref}:${file}`]);
145
+ if (Buffer.byteLength(text) > limit)
146
+ throw Error("Report exceeds read budget.");
147
+ const { metadata, body } = parse(text, id), revision = noteRevision(text);
148
+ return {
149
+ ...metadata,
150
+ file,
151
+ revision,
152
+ body,
153
+ unread: readRevision(root, id) !== revision,
154
+ };
155
+ }
156
+ const file = reportFile(id), path = checkedPath(root, file);
157
+ const stat = lstatSync(path);
158
+ if (!stat.isFile() || stat.size > limit)
159
+ throw Error("Report must be a Markdown file below 128 KB.");
160
+ const text = readFileSync(path, "utf8");
161
+ if (Buffer.byteLength(text) > limit)
162
+ throw Error("Keep this report below 128 KB.");
163
+ const { metadata, body } = parse(text, id), revision = noteRevision(text);
164
+ return {
165
+ ...metadata,
166
+ file,
167
+ revision,
168
+ unread: readRevision(root, id) !== revision,
169
+ body,
170
+ };
171
+ }
172
+ export function createReport(root, graph, input) {
173
+ if (!input.title.trim() ||
174
+ input.title.length > 160 ||
175
+ /[\r\n\0]/.test(input.title))
176
+ throw Error("Use a report title of 1–160 characters.");
177
+ if (!input.body.trim())
178
+ throw Error("Write the report’s Markdown content.");
179
+ if (input.author !== undefined &&
180
+ (input.author.length > 100 || /[\r\n\0]/.test(input.author)))
181
+ throw Error("Use a short author label.");
182
+ const blocks = [
183
+ ...new Set(input.blocks.map((id) => resolvedReportBlock(graph, id))),
184
+ ];
185
+ if (!blocks.length ||
186
+ blocks.some((id) => !graph.elements.some((node) => node.id === id)))
187
+ throw Error("Attach this report to at least one existing block ID.");
188
+ let codeRevision;
189
+ try {
190
+ codeRevision = execFileSync("git", ["rev-parse", "HEAD"], {
191
+ cwd: root,
192
+ encoding: "utf8",
193
+ stdio: ["ignore", "pipe", "ignore"],
194
+ timeout: 2000,
195
+ }).trim();
196
+ }
197
+ catch { }
198
+ const metadata = {
199
+ schema: "fractory.report.v1",
200
+ id: randomUUID(),
201
+ title: input.title.trim(),
202
+ blocks,
203
+ createdAt: new Date().toISOString(),
204
+ ...(input.author ? { author: input.author } : {}),
205
+ ...(codeRevision ? { codeRevision } : {}),
206
+ };
207
+ const body = `---\nfractory: ${JSON.stringify(metadata)}\n---\n\n${input.body.trim()}\n`;
208
+ if (Buffer.byteLength(body) > limit)
209
+ throw Error("Keep this report below 128 KB.");
210
+ atomic(root, reportFile(metadata.id), body);
211
+ return readReport(root, metadata.id);
212
+ }
213
+ export function markReport(root, id, revision, read, ref) {
214
+ const report = readReport(root, id, ref);
215
+ if (report.revision !== revision)
216
+ throw new WorkspaceConflict("This report changed. Read its latest version before marking it read.");
217
+ const file = receiptFile(id), path = checkedPath(root, file, true);
218
+ if (read)
219
+ atomic(root, file, JSON.stringify({ revision }));
220
+ else if (existsSync(path))
221
+ unlinkSync(path);
222
+ return { ...report, unread: !read };
223
+ }
@@ -0,0 +1,22 @@
1
+ import type { DefinitionGraph } from "./model.js";
2
+ import type { SentryAreaRule } from "./sentry.js";
3
+ export interface RepositoryMapConfiguration {
4
+ /** Optional compatibility with repositories which generate several map artifacts. */
5
+ map?: {
6
+ base: string;
7
+ mounts?: Array<{
8
+ file: string;
9
+ at: string;
10
+ root: string;
11
+ }>;
12
+ annotations?: string;
13
+ };
14
+ sentryAreas?: SentryAreaRule[];
15
+ }
16
+ export declare function repositoryMapConfiguration(root: string): RepositoryMapConfiguration;
17
+ export declare function parseMapConfiguration(text: string): RepositoryMapConfiguration;
18
+ export declare function repositoryMapPaths(root: string, configuration?: RepositoryMapConfiguration): string[];
19
+ export declare function mapFromArtifacts(config: RepositoryMapConfiguration, read: (file: string) => string | undefined): DefinitionGraph | null;
20
+ export declare function readRepositoryMap(root: string): DefinitionGraph | null;
21
+ /** Uses maps and source blobs from the exact revision; never today's ownership. */
22
+ export declare function captureRepositoryCommit(root: string, ref: string, definition?: string): import("./code-model.js").CodeSnapshot;
@@ -0,0 +1,153 @@
1
+ /** Repository-owned mapping configuration. Fractory ships no product map or provider rules. */
2
+ import { existsSync, readFileSync, realpathSync } from "node:fs";
3
+ import { join } from "node:path";
4
+ import { composeDefinitions } from "./compose.js";
5
+ import { factoryGraph } from "./factory-graph.js";
6
+ import { captureCommit, resolveCommit } from "./git-code.js";
7
+ import { execFileSync } from "node:child_process";
8
+ function repositoryFile(file) {
9
+ if (!file ||
10
+ file.startsWith("/") ||
11
+ /[\\\r\n\0]/.test(file) ||
12
+ file.split("/").some((p) => p === ".."))
13
+ throw Error("Map configuration must use repository-relative paths.");
14
+ return file;
15
+ }
16
+ export function repositoryMapConfiguration(root) {
17
+ let path = join(root, "fractory.config.json");
18
+ if (!existsSync(path)) {
19
+ // A linked worktree can predate an uncommitted repository configuration.
20
+ // Share only its primary checkout's rules, proven by Git's own inventory.
21
+ // The map/source blobs themselves are still read from the selected checkout.
22
+ try {
23
+ const primary = execFileSync("git", ["worktree", "list", "--porcelain", "-z"], {
24
+ cwd: root,
25
+ encoding: "utf8",
26
+ stdio: ["ignore", "pipe", "ignore"],
27
+ timeout: 5000,
28
+ maxBuffer: 1024 * 1024,
29
+ })
30
+ .split("\0")
31
+ .find((line) => line.startsWith("worktree "))
32
+ ?.slice(9);
33
+ if (!primary || realpathSync(primary) === realpathSync(root))
34
+ return {};
35
+ path = join(primary, "fractory.config.json");
36
+ }
37
+ catch {
38
+ return {};
39
+ }
40
+ }
41
+ if (!existsSync(path))
42
+ return {};
43
+ return parseMapConfiguration(readFileSync(path, "utf8"));
44
+ }
45
+ export function parseMapConfiguration(text) {
46
+ const config = JSON.parse(text);
47
+ if (config.map) {
48
+ repositoryFile(config.map.base);
49
+ for (const mount of config.map.mounts || [])
50
+ repositoryFile(mount.file);
51
+ if (config.map.annotations)
52
+ repositoryFile(config.map.annotations);
53
+ }
54
+ return config;
55
+ }
56
+ export function repositoryMapPaths(root, configuration = repositoryMapConfiguration(root)) {
57
+ const map = configuration.map;
58
+ return [
59
+ ...new Set([
60
+ "fractory.json",
61
+ ...(map
62
+ ? [
63
+ map.base,
64
+ ...(map.mounts || []).map((m) => m.file),
65
+ ...(map.annotations ? [map.annotations] : []),
66
+ ]
67
+ : []),
68
+ ]),
69
+ ];
70
+ }
71
+ export function mapFromArtifacts(config, read) {
72
+ const canonical = read("fractory.json");
73
+ if (canonical)
74
+ return JSON.parse(canonical);
75
+ const map = config.map;
76
+ if (!map)
77
+ return null;
78
+ const base = read(map.base);
79
+ if (!base)
80
+ return null;
81
+ const mounts = [];
82
+ for (const mount of map.mounts || []) {
83
+ const value = read(mount.file);
84
+ if (!value)
85
+ return null;
86
+ mounts.push({
87
+ at: mount.at,
88
+ root: mount.root,
89
+ definition: JSON.parse(value),
90
+ });
91
+ }
92
+ const graph = composeDefinitions(JSON.parse(base), mounts);
93
+ const annotations = map.annotations && read(map.annotations);
94
+ return annotations
95
+ ? factoryGraph(JSON.parse(annotations), graph, {
96
+ legacySnapshot: true,
97
+ })
98
+ : graph;
99
+ }
100
+ export function readRepositoryMap(root) {
101
+ return mapFromArtifacts(repositoryMapConfiguration(root), (file) => {
102
+ try {
103
+ return readFileSync(join(root, repositoryFile(file)), "utf8");
104
+ }
105
+ catch (error) {
106
+ if (error.code === "ENOENT")
107
+ return undefined;
108
+ throw error;
109
+ }
110
+ });
111
+ }
112
+ /** Uses maps and source blobs from the exact revision; never today's ownership. */
113
+ export function captureRepositoryCommit(root, ref, definition) {
114
+ const commit = resolveCommit(root, ref);
115
+ let canonical = !!definition;
116
+ if (!canonical) {
117
+ try {
118
+ execFileSync("git", ["cat-file", "-e", `${commit}:fractory.json`], {
119
+ cwd: root,
120
+ stdio: "ignore",
121
+ });
122
+ canonical = true;
123
+ }
124
+ catch {
125
+ /* Older multi-artifact map. */
126
+ }
127
+ }
128
+ if (canonical)
129
+ return captureCommit(root, commit, [repositoryFile(definition || "fractory.json")], ([graph]) => graph);
130
+ let historicalConfiguration;
131
+ try {
132
+ historicalConfiguration = execFileSync("git", ["show", `${commit}:fractory.config.json`], {
133
+ cwd: root,
134
+ encoding: "utf8",
135
+ stdio: ["ignore", "pipe", "ignore"],
136
+ maxBuffer: 1024 * 1024,
137
+ });
138
+ }
139
+ catch {
140
+ /* Repositories predating this configuration use the current legacy artifact locations. */
141
+ }
142
+ const config = historicalConfiguration
143
+ ? parseMapConfiguration(historicalConfiguration)
144
+ : repositoryMapConfiguration(root);
145
+ const map = config.map;
146
+ if (!map)
147
+ throw Error("No factory map captured at this revision.");
148
+ return captureCommit(root, commit, [map.base, ...(map.mounts || []).map((m) => m.file)], (graphs) => composeDefinitions(graphs[0], (map.mounts || []).map((m, i) => ({
149
+ at: m.at,
150
+ root: m.root,
151
+ definition: graphs[i + 1],
152
+ }))), map.annotations);
153
+ }
@@ -0,0 +1,17 @@
1
+ /** Bounded stale-while-revalidate cache. Store sanitized views, never provider payloads or credentials. */
2
+ export declare class ResourceCache<T> {
3
+ private ttl;
4
+ private staleFor;
5
+ private now;
6
+ private entries;
7
+ constructor(ttl?: number, staleFor?: number, now?: () => number);
8
+ read(key: string, load: () => Promise<T>, force?: boolean): Promise<{
9
+ data: T & ({} | null);
10
+ cache: {
11
+ at: string;
12
+ stale: boolean;
13
+ refreshing: boolean;
14
+ failed: boolean;
15
+ };
16
+ }>;
17
+ }
@@ -0,0 +1,65 @@
1
+ /** Bounded stale-while-revalidate cache. Store sanitized views, never provider payloads or credentials. */
2
+ export class ResourceCache {
3
+ ttl;
4
+ staleFor;
5
+ now;
6
+ entries = new Map();
7
+ constructor(ttl = 300_000, staleFor = 3_600_000, now = Date.now) {
8
+ this.ttl = ttl;
9
+ this.staleFor = staleFor;
10
+ this.now = now;
11
+ }
12
+ async read(key, load, force = false) {
13
+ let entry = this.entries.get(key);
14
+ if (!entry) {
15
+ entry = { at: 0, retryAt: 0, failed: false };
16
+ this.entries.set(key, entry);
17
+ if (this.entries.size > 16) {
18
+ const victim = [...this.entries].find(([k, v]) => k !== key && !v.pending);
19
+ if (victim)
20
+ this.entries.delete(victim[0]);
21
+ }
22
+ }
23
+ const age = this.now() - entry.at, usable = entry.value !== undefined && age < this.staleFor;
24
+ if (!entry.pending &&
25
+ (force || !usable || age >= this.ttl) &&
26
+ this.now() >= entry.retryAt) {
27
+ const target = entry;
28
+ target.pending = Promise.resolve()
29
+ .then(load)
30
+ .then((value) => {
31
+ target.value = value;
32
+ target.at = this.now();
33
+ target.failed = false;
34
+ target.lastError = undefined;
35
+ target.retryAt = 0;
36
+ })
37
+ .catch((error) => {
38
+ target.failed = true;
39
+ target.lastError = error;
40
+ target.retryAt = this.now() + 60_000;
41
+ if (!usable)
42
+ throw error;
43
+ })
44
+ .finally(() => {
45
+ target.pending = undefined;
46
+ });
47
+ // Background refreshes must never become unhandled rejections.
48
+ void target.pending.catch(() => { });
49
+ }
50
+ if ((!usable || force) && entry.pending)
51
+ await entry.pending;
52
+ if (entry.value === undefined || this.now() - entry.at >= this.staleFor)
53
+ throw (entry.lastError ||
54
+ Error("Activity unavailable; retry after the provider recovers."));
55
+ return {
56
+ data: entry.value,
57
+ cache: {
58
+ at: new Date(entry.at).toISOString(),
59
+ stale: this.now() - entry.at >= this.ttl,
60
+ refreshing: !!entry.pending,
61
+ failed: entry.failed,
62
+ },
63
+ };
64
+ }
65
+ }
@@ -0,0 +1,19 @@
1
+ export interface ReviewTargetOptions {
2
+ base?: string;
3
+ head?: string;
4
+ viewer?: string;
5
+ definition?: string;
6
+ title?: string;
7
+ url?: string;
8
+ }
9
+ export declare function reviewTarget(root: string, options?: ReviewTargetOptions): {
10
+ url: string;
11
+ branch: string | null;
12
+ base: string;
13
+ mergeBase: string;
14
+ head: string;
15
+ basis: "snapshots" | "current-map";
16
+ dirtyEntries: number;
17
+ warnings: string[];
18
+ };
19
+ export declare function runReview(args: string[], cwd?: string, open?: (url: string) => void): string;