@granular-software/fractory 0.0.0-stage → 0.1.24

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (273) 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 +118 -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 +1083 -0
  37. package/dist/compose.d.ts +9 -0
  38. package/dist/compose.js +72 -0
  39. package/dist/core.d.ts +86 -0
  40. package/dist/core.js +206 -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 +66 -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 +4 -0
  54. package/dist/factory-graph.js +318 -0
  55. package/dist/factory-model.d.ts +97 -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/issue-cache.d.ts +9 -0
  76. package/dist/issue-cache.js +68 -0
  77. package/dist/issue-cli.d.ts +1 -0
  78. package/dist/issue-cli.js +89 -0
  79. package/dist/issue-links.d.ts +15 -0
  80. package/dist/issue-links.js +125 -0
  81. package/dist/linear-issues.d.ts +19 -0
  82. package/dist/linear-issues.js +124 -0
  83. package/dist/local-runtime.d.ts +8 -0
  84. package/dist/local-runtime.js +59 -0
  85. package/dist/map-activity.d.ts +73 -0
  86. package/dist/map-activity.js +234 -0
  87. package/dist/map-model.d.ts +5 -0
  88. package/dist/map-model.js +166 -0
  89. package/dist/map-quality.d.ts +14 -0
  90. package/dist/map-quality.js +56 -0
  91. package/dist/mapping-coverage.d.ts +87 -0
  92. package/dist/mapping-coverage.js +404 -0
  93. package/dist/model.d.ts +182 -0
  94. package/dist/model.js +66 -0
  95. package/dist/operation-benchmark-worker.d.ts +2 -0
  96. package/dist/operation-benchmark-worker.js +60 -0
  97. package/dist/operation-benchmark.d.ts +29 -0
  98. package/dist/operation-benchmark.js +1 -0
  99. package/dist/otel-metrics.d.ts +21 -0
  100. package/dist/otel-metrics.js +146 -0
  101. package/dist/performance-model.d.ts +185 -0
  102. package/dist/performance-model.js +396 -0
  103. package/dist/product-map.d.ts +69 -0
  104. package/dist/product-map.js +168 -0
  105. package/dist/provider-access.cjs +207 -0
  106. package/dist/provider-access.d.cts +14 -0
  107. package/dist/reports-cli.d.ts +1 -0
  108. package/dist/reports-cli.js +111 -0
  109. package/dist/reports-model.d.ts +27 -0
  110. package/dist/reports-model.js +39 -0
  111. package/dist/reports.d.ts +23 -0
  112. package/dist/reports.js +223 -0
  113. package/dist/repository-map.d.ts +22 -0
  114. package/dist/repository-map.js +151 -0
  115. package/dist/resource-cache.d.ts +17 -0
  116. package/dist/resource-cache.js +65 -0
  117. package/dist/review-cli.d.ts +19 -0
  118. package/dist/review-cli.js +224 -0
  119. package/dist/review.d.ts +48 -0
  120. package/dist/review.js +289 -0
  121. package/dist/runtime-metrics.d.ts +26 -0
  122. package/dist/runtime-metrics.js +290 -0
  123. package/dist/scope.d.ts +12 -0
  124. package/dist/scope.js +94 -0
  125. package/dist/sentry-activity.d.ts +39 -0
  126. package/dist/sentry-activity.js +174 -0
  127. package/dist/sentry.d.ts +130 -0
  128. package/dist/sentry.js +369 -0
  129. package/dist/service-release.d.ts +16 -0
  130. package/dist/service-release.js +14 -0
  131. package/dist/setup-cli.d.ts +2 -0
  132. package/dist/setup-cli.js +52 -0
  133. package/dist/setup-kit.cjs +163 -0
  134. package/dist/setup-kit.d.cts +32 -0
  135. package/dist/source-index.d.ts +37 -0
  136. package/dist/source-index.js +166 -0
  137. package/dist/source-review-git.d.ts +7 -0
  138. package/dist/source-review-git.js +103 -0
  139. package/dist/source-review.d.ts +16 -0
  140. package/dist/source-review.js +493 -0
  141. package/dist/telemetry.d.ts +17 -0
  142. package/dist/telemetry.js +51 -0
  143. package/dist/time-window.d.ts +9 -0
  144. package/dist/time-window.js +35 -0
  145. package/dist/trace-evidence.d.ts +23 -0
  146. package/dist/trace-evidence.js +55 -0
  147. package/dist/trace-model.d.ts +26 -0
  148. package/dist/trace-model.js +1 -0
  149. package/dist/tracing.d.ts +44 -0
  150. package/dist/tracing.js +123 -0
  151. package/dist/work-check.d.ts +17 -0
  152. package/dist/work-check.js +110 -0
  153. package/dist/work-cli.d.ts +1 -0
  154. package/dist/work-cli.js +148 -0
  155. package/dist/work-context.d.ts +57 -0
  156. package/dist/work-context.js +568 -0
  157. package/dist/work-intents.d.ts +6 -0
  158. package/dist/work-intents.js +140 -0
  159. package/dist/work-items.d.ts +58 -0
  160. package/dist/work-items.js +86 -0
  161. package/dist/work-model.d.ts +110 -0
  162. package/dist/work-model.js +261 -0
  163. package/dist/work-review-git.d.ts +8 -0
  164. package/dist/work-review-git.js +111 -0
  165. package/dist/work-review.d.ts +26 -0
  166. package/dist/work-review.js +426 -0
  167. package/dist/work-switcher-model.d.ts +43 -0
  168. package/dist/work-switcher-model.js +79 -0
  169. package/dist/work-switcher.d.ts +6 -0
  170. package/dist/work-switcher.js +171 -0
  171. package/dist/working-cli.d.ts +1 -0
  172. package/dist/working-cli.js +33 -0
  173. package/dist/working-code.d.ts +74 -0
  174. package/dist/working-code.js +421 -0
  175. package/dist/workspace-notes.d.ts +71 -0
  176. package/dist/workspace-notes.js +177 -0
  177. package/dist/workspace-tests.d.ts +21 -0
  178. package/dist/workspace-tests.js +573 -0
  179. package/package.json +547 -4
  180. package/src/activity-volume.ts +149 -0
  181. package/src/annotations.ts +481 -0
  182. package/src/benchmark-cli.ts +118 -0
  183. package/src/benchmark-worker.ts +22 -0
  184. package/src/benchmarks.ts +493 -0
  185. package/src/bin.ts +54 -0
  186. package/src/block-cli.ts +106 -0
  187. package/src/block-documents.ts +117 -0
  188. package/src/change-impact.ts +280 -0
  189. package/src/check-source.ts +82 -0
  190. package/src/checks-model.ts +108 -0
  191. package/src/cli.ts +440 -0
  192. package/src/code-model.ts +159 -0
  193. package/src/code-store.ts +98 -0
  194. package/src/compare-artifact.ts +314 -0
  195. package/src/compare.ts +440 -0
  196. package/src/compiler.ts +1326 -0
  197. package/src/compose.ts +94 -0
  198. package/src/core.ts +357 -0
  199. package/src/coverage-cli.ts +52 -0
  200. package/src/declaration-sources.ts +69 -0
  201. package/src/declared-graph.ts +74 -0
  202. package/src/display-name.ts +8 -0
  203. package/src/error-heat.ts +161 -0
  204. package/src/evidence.ts +94 -0
  205. package/src/factory-graph.ts +378 -0
  206. package/src/factory-model.ts +73 -0
  207. package/src/git-code.ts +461 -0
  208. package/src/git-refs.ts +43 -0
  209. package/src/history-activity.ts +146 -0
  210. package/src/history-churn.ts +416 -0
  211. package/src/history-git.ts +163 -0
  212. package/src/history-ledger.ts +636 -0
  213. package/src/history-ownership.ts +116 -0
  214. package/src/history-source.ts +117 -0
  215. package/src/integrations-cli.ts +187 -0
  216. package/src/issue-cache.ts +96 -0
  217. package/src/issue-cli.ts +137 -0
  218. package/src/issue-links.ts +153 -0
  219. package/src/linear-issues.ts +154 -0
  220. package/src/local-runtime.ts +70 -0
  221. package/src/map-activity.ts +309 -0
  222. package/src/map-model.ts +213 -0
  223. package/src/map-quality.ts +61 -0
  224. package/src/mapping-coverage.ts +570 -0
  225. package/src/model.ts +221 -0
  226. package/src/operation-benchmark-worker.ts +60 -0
  227. package/src/operation-benchmark.ts +28 -0
  228. package/src/otel-metrics.ts +176 -0
  229. package/src/performance-model.ts +575 -0
  230. package/src/product-map.ts +236 -0
  231. package/src/provider-access.cjs +207 -0
  232. package/src/provider-access.d.cts +14 -0
  233. package/src/reports-cli.ts +125 -0
  234. package/src/reports-model.ts +73 -0
  235. package/src/reports.ts +276 -0
  236. package/src/repository-map.ts +189 -0
  237. package/src/resource-cache.ts +76 -0
  238. package/src/review-cli.ts +256 -0
  239. package/src/review.ts +376 -0
  240. package/src/runtime-metrics.ts +386 -0
  241. package/src/scope.ts +103 -0
  242. package/src/sentry-activity.ts +234 -0
  243. package/src/sentry.ts +545 -0
  244. package/src/service-release.ts +18 -0
  245. package/src/setup-cli.ts +58 -0
  246. package/src/setup-kit.cjs +163 -0
  247. package/src/setup-kit.d.cts +32 -0
  248. package/src/source-index.ts +205 -0
  249. package/src/source-review-git.ts +129 -0
  250. package/src/source-review.ts +637 -0
  251. package/src/telemetry.ts +68 -0
  252. package/src/time-window.ts +51 -0
  253. package/src/trace-evidence.ts +80 -0
  254. package/src/trace-model.ts +26 -0
  255. package/src/tracing.ts +165 -0
  256. package/src/work-check.ts +143 -0
  257. package/src/work-cli.ts +195 -0
  258. package/src/work-context.ts +713 -0
  259. package/src/work-intents.ts +196 -0
  260. package/src/work-items.ts +151 -0
  261. package/src/work-model.ts +400 -0
  262. package/src/work-review-git.ts +130 -0
  263. package/src/work-review.ts +573 -0
  264. package/src/work-switcher-model.ts +121 -0
  265. package/src/work-switcher.ts +191 -0
  266. package/src/working-cli.ts +38 -0
  267. package/src/working-code.ts +582 -0
  268. package/src/workspace-notes.ts +203 -0
  269. package/src/workspace-tests.ts +654 -0
  270. package/toolkit/GUIDE.md +305 -0
  271. package/toolkit/SKILL.md +131 -0
  272. package/toolkit/bin/fractory +2 -0
  273. package/toolkit/build.json +1 -0
@@ -0,0 +1,151 @@
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
+ : graph;
97
+ }
98
+ export function readRepositoryMap(root) {
99
+ return mapFromArtifacts(repositoryMapConfiguration(root), (file) => {
100
+ try {
101
+ return readFileSync(join(root, repositoryFile(file)), "utf8");
102
+ }
103
+ catch (error) {
104
+ if (error.code === "ENOENT")
105
+ return undefined;
106
+ throw error;
107
+ }
108
+ });
109
+ }
110
+ /** Uses maps and source blobs from the exact revision; never today's ownership. */
111
+ export function captureRepositoryCommit(root, ref, definition) {
112
+ const commit = resolveCommit(root, ref);
113
+ let canonical = !!definition;
114
+ if (!canonical) {
115
+ try {
116
+ execFileSync("git", ["cat-file", "-e", `${commit}:fractory.json`], {
117
+ cwd: root,
118
+ stdio: "ignore",
119
+ });
120
+ canonical = true;
121
+ }
122
+ catch {
123
+ /* Older multi-artifact map. */
124
+ }
125
+ }
126
+ if (canonical)
127
+ return captureCommit(root, commit, [repositoryFile(definition || "fractory.json")], ([graph]) => graph);
128
+ let historicalConfiguration;
129
+ try {
130
+ historicalConfiguration = execFileSync("git", ["show", `${commit}:fractory.config.json`], {
131
+ cwd: root,
132
+ encoding: "utf8",
133
+ stdio: ["ignore", "pipe", "ignore"],
134
+ maxBuffer: 1024 * 1024,
135
+ });
136
+ }
137
+ catch {
138
+ /* Repositories predating this configuration use the current legacy artifact locations. */
139
+ }
140
+ const config = historicalConfiguration
141
+ ? parseMapConfiguration(historicalConfiguration)
142
+ : repositoryMapConfiguration(root);
143
+ const map = config.map;
144
+ if (!map)
145
+ throw Error("No factory map captured at this revision.");
146
+ return captureCommit(root, commit, [map.base, ...(map.mounts || []).map((m) => m.file)], (graphs) => composeDefinitions(graphs[0], (map.mounts || []).map((m, i) => ({
147
+ at: m.at,
148
+ root: m.root,
149
+ definition: graphs[i + 1],
150
+ }))), map.annotations);
151
+ }
@@ -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;
@@ -0,0 +1,224 @@
1
+ import { repositoryMapPaths } from "./repository-map.js";
2
+ /** Resolve a review link using Git identities, without compiling or checking out code. */
3
+ import { execFileSync } from "node:child_process";
4
+ import { existsSync, readFileSync } from "node:fs";
5
+ import { join, resolve } from "node:path";
6
+ import { comparisonMergeBase, resolveComparisonRef } from "./git-refs.js";
7
+ const native = (command, args, cwd, input) => execFileSync(command, args, {
8
+ cwd,
9
+ input,
10
+ encoding: "utf8",
11
+ timeout: 15000,
12
+ maxBuffer: 16 * 1024 * 1024,
13
+ stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"],
14
+ env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" },
15
+ });
16
+ export function reviewTarget(root, options = {}) {
17
+ const git = (args, input) => native("git", ["--no-pager", ...args], root, input).trim();
18
+ let branch = null;
19
+ try {
20
+ branch = git(["symbolic-ref", "--quiet", "--short", "HEAD"]);
21
+ }
22
+ catch {
23
+ /* detached HEAD remains a valid explicit review */
24
+ }
25
+ let base = options.base;
26
+ if (!base) {
27
+ try {
28
+ base = git([
29
+ "symbolic-ref",
30
+ "--quiet",
31
+ "--short",
32
+ "refs/remotes/origin/HEAD",
33
+ ]);
34
+ }
35
+ catch {
36
+ /* repositories may not record a default remote branch */
37
+ }
38
+ if (!base)
39
+ for (const ref of ["origin/main", "origin/master", "main", "master"]) {
40
+ try {
41
+ resolveComparisonRef(root, ref);
42
+ base = ref;
43
+ break;
44
+ }
45
+ catch {
46
+ /* next local candidate */
47
+ }
48
+ }
49
+ }
50
+ if (!base)
51
+ throw Error("Choose --base REF; no default branch is available locally.");
52
+ let baseCommit, head;
53
+ try {
54
+ baseCommit = resolveComparisonRef(root, base);
55
+ head = resolveComparisonRef(root, options.head || "HEAD");
56
+ }
57
+ catch {
58
+ throw Error("These review refs are not available locally. Fetch the selected PR base/head, then retry; no checkout is needed.");
59
+ }
60
+ const from = comparisonMergeBase(root, baseCommit, head);
61
+ const definitions = options.definition
62
+ ? [options.definition]
63
+ : repositoryMapPaths(root);
64
+ if (definitions.some((file) => !file || /[\r\n\0]/.test(file)))
65
+ throw Error("Choose a repository-relative definition path.");
66
+ const captured = (commit) => {
67
+ const ref = join(root, ".fractal/commits", commit);
68
+ if (!existsSync(ref))
69
+ return false;
70
+ const id = readFileSync(ref, "utf8").trim();
71
+ return (/^[a-f0-9]{64}$/.test(id) &&
72
+ existsSync(join(root, ".fractal/objects", id + ".json")));
73
+ };
74
+ const available = (commit) => {
75
+ if (captured(commit))
76
+ return true;
77
+ const present = git(["cat-file", "--batch-check"], definitions.map((file) => `${commit}:${file}`).join("\n") + "\n")
78
+ .split("\n")
79
+ .map((line) => /^[a-f0-9]{40,64} blob \d+$/.test(line));
80
+ return options.definition
81
+ ? present.every(Boolean)
82
+ : present[0] || (present.length > 1 && present.slice(1).every(Boolean));
83
+ };
84
+ const historicalMaps = available(from) && available(head);
85
+ const status = git([
86
+ "status",
87
+ "--porcelain=v1",
88
+ "-z",
89
+ "--untracked-files=normal",
90
+ ]).split("\0");
91
+ let dirtyEntries = 0;
92
+ for (let i = 0; i < status.length; i++) {
93
+ if (!status[i])
94
+ continue;
95
+ dirtyEntries++;
96
+ if (/[RC]/.test(status[i].slice(0, 2)))
97
+ i++;
98
+ }
99
+ const viewer = new URL(options.viewer ||
100
+ process.env.FRACTORY_VIEWER_URL ||
101
+ "http://127.0.0.1:4318/fractal");
102
+ if (!["http:", "https:", "fractory:"].includes(viewer.protocol) ||
103
+ (viewer.protocol === "fractory:" && viewer.hostname !== "open") ||
104
+ viewer.username ||
105
+ viewer.password)
106
+ throw Error("Use an HTTP(S) factory viewer URL or fractory://open without credentials.");
107
+ if (viewer.pathname === "/")
108
+ viewer.pathname = "/fractal";
109
+ viewer.search = new URLSearchParams({
110
+ ...(viewer.protocol === "fractory:" ? { repo: root } : {}),
111
+ base: baseCommit,
112
+ head,
113
+ compare: "pr",
114
+ ...(!historicalMaps ? { footprint: "1" } : {}),
115
+ ...(options.title ? { reviewTitle: options.title.slice(0, 500) } : {}),
116
+ ...(options.url?.startsWith("https://") ? { reviewUrl: options.url } : {}),
117
+ }).toString();
118
+ return {
119
+ url: viewer.href,
120
+ branch,
121
+ base: baseCommit,
122
+ mergeBase: from,
123
+ head,
124
+ basis: historicalMaps ? "snapshots" : "current-map",
125
+ dirtyEntries,
126
+ warnings: [
127
+ ...(!historicalMaps
128
+ ? [
129
+ "Historical factory maps are missing. This opens source associations on a reviewed map; historical contracts and connection changes remain unknown.",
130
+ ]
131
+ : []),
132
+ ...(dirtyEntries
133
+ ? [
134
+ `${dirtyEntries} working-tree entries are uncommitted and are not included in this committed comparison. Use the map's working-change Impact view to inspect them.`,
135
+ ]
136
+ : []),
137
+ ...(from === head && baseCommit !== head
138
+ ? [
139
+ "The selected head is behind the base; it has no committed branch-only changes.",
140
+ ]
141
+ : []),
142
+ ],
143
+ };
144
+ }
145
+ export function runReview(args, cwd = process.cwd(), open = (url) => {
146
+ const command = process.platform === "darwin"
147
+ ? "open"
148
+ : process.platform === "win32"
149
+ ? "explorer.exe"
150
+ : "xdg-open";
151
+ native(command, [url], cwd);
152
+ }) {
153
+ if (args.includes("--help"))
154
+ return "Fractory review\n\n bun run fractal review [--base main] [--head HEAD] [--open]\n bun run fractal review --pr [466] [--open]\n bun run fractal review --base BASE_SHA --head HEAD_SHA --title 'PR #466' --url https://github.com/owner/repo/pull/466\n\nPrints a map URL for merge-base → head. A missing historical map opens an explicitly labeled file footprint. --pr uses the installed GitHub CLI for one metadata read; agents can instead use their GitHub connector and pass the resolved refs. --viewer URL selects the repository viewer. Uncommitted changes are reported separately.\n";
155
+ const allowed = new Set([
156
+ "--base",
157
+ "--head",
158
+ "--viewer",
159
+ "--definition",
160
+ "--title",
161
+ "--url",
162
+ "--root",
163
+ "--pr",
164
+ "--open",
165
+ "--help",
166
+ ]);
167
+ for (const argument of args)
168
+ if (argument.startsWith("--") && !allowed.has(argument))
169
+ throw Error(`Unknown review option: ${argument}`);
170
+ const value = (flag) => {
171
+ const index = args.indexOf(flag);
172
+ if (index < 0)
173
+ return;
174
+ const next = args[index + 1];
175
+ if (!next || next.startsWith("--"))
176
+ throw Error(`${flag} needs a value`);
177
+ return next;
178
+ };
179
+ const root = resolve(value("--root") ||
180
+ native("git", ["rev-parse", "--show-toplevel"], cwd).trim());
181
+ let options = {
182
+ base: value("--base"),
183
+ head: value("--head"),
184
+ viewer: value("--viewer"),
185
+ definition: value("--definition"),
186
+ title: value("--title"),
187
+ url: value("--url"),
188
+ };
189
+ const prIndex = args.indexOf("--pr");
190
+ const pr = prIndex >= 0 && args[prIndex + 1] && !args[prIndex + 1].startsWith("--")
191
+ ? args[prIndex + 1]
192
+ : undefined;
193
+ if (prIndex >= 0) {
194
+ if (pr &&
195
+ !/^(?:\d+|https:\/\/[^/\s]+\/[^/\s]+\/[^/\s]+\/pull\/\d+)$/.test(pr))
196
+ throw Error("Use a PR number or HTTPS pull-request URL.");
197
+ try {
198
+ const info = JSON.parse(native("gh", [
199
+ "pr",
200
+ "view",
201
+ ...(pr ? [pr] : []),
202
+ "--json",
203
+ "number,title,url,baseRefOid,headRefOid",
204
+ ], root));
205
+ if (!/^[a-f0-9]{40}$/.test(info.baseRefOid) ||
206
+ !/^[a-f0-9]{40}$/.test(info.headRefOid))
207
+ throw Error("Missing PR identities");
208
+ options = {
209
+ ...options,
210
+ base: info.baseRefOid,
211
+ head: info.headRefOid,
212
+ title: `PR #${info.number} · ${info.title}`,
213
+ url: info.url,
214
+ };
215
+ }
216
+ catch {
217
+ throw Error("Could not read this PR through gh. Use the GitHub connector, then pass --base SHA --head SHA --title TITLE --url URL.");
218
+ }
219
+ }
220
+ const target = reviewTarget(root, options);
221
+ if (args.includes("--open"))
222
+ open(target.url);
223
+ return JSON.stringify(target, null, 2);
224
+ }
@@ -0,0 +1,48 @@
1
+ import type { FactoryComparison } from "./compare.js";
2
+ import type { DefinitionGraph } from "./model.js";
3
+ import { connectionEvidence } from "./change-impact.js";
4
+ /** A footprint is explicitly today's map associated with changed paths, not two historical factories. */
5
+ export interface FactoryFootprint {
6
+ schema: "fractal.footprint.v1";
7
+ /** Added capability memberships and interactions were read from this commit. Not a historical contract diff. */
8
+ mappingRevision?: string;
9
+ concepts?: import("./work-review.js").WorkReview;
10
+ graph: DefinitionGraph;
11
+ base: string;
12
+ head: string;
13
+ title?: string;
14
+ url?: string;
15
+ files: {
16
+ path: string;
17
+ status: "added" | "removed" | "modified";
18
+ digest?: string;
19
+ }[];
20
+ }
21
+ export type ReviewFacet = "internal" | "interfaces" | "structure" | "metadata" | "source";
22
+ export declare const reviewFacets: ReviewFacet[];
23
+ export type ReviewMark = Record<ReviewFacet, number> & {
24
+ consumers: number;
25
+ };
26
+ export type ConsumerReason = {
27
+ id: string;
28
+ provider: string;
29
+ via: string;
30
+ distance: number;
31
+ evidence: ReturnType<typeof connectionEvidence>;
32
+ };
33
+ export interface FactoryReview {
34
+ graph: DefinitionGraph;
35
+ key: string;
36
+ basis: "snapshots" | "current-map" | "head-source" | "working-code";
37
+ direct: Record<string, ReviewFacet[]>;
38
+ marks: Record<string, ReviewMark>;
39
+ consumers: ConsumerReason[];
40
+ connectionIds: string[];
41
+ fingerprints: Record<string, string>;
42
+ files: Record<string, string[]>;
43
+ unmapped: string[];
44
+ }
45
+ export declare function factoryReview(input: FactoryComparison | FactoryFootprint, indirect?: boolean): FactoryReview;
46
+ /** A parent review is valid only while all of its scoped evidence is unchanged. */
47
+ export declare function reviewedScope(review: FactoryReview, saved: Record<string, string>, id: string): boolean;
48
+ export declare function reviewUnits(review: FactoryReview): string[];