@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,55 @@
1
+ /** Only compatible, recorded spans can color the graph. State alone never creates a span. */
2
+ export function executionPath(graph, snapshot) {
3
+ const byId = new Map(graph.elements.map((n) => [n.id, n]));
4
+ const spans = new Map();
5
+ let incompatibleEvents = 0;
6
+ for (const event of snapshot?.events || []) {
7
+ const node = byId.get(event.elementId);
8
+ if (event.definitionRevision !==
9
+ (node?.definitionRevision || graph.revision) ||
10
+ node?.contract?.id !== event.contract ||
11
+ (graph.codeRevision !== undefined &&
12
+ event.codeRevision !== graph.codeRevision)) {
13
+ incompatibleEvents++;
14
+ continue;
15
+ }
16
+ const previous = spans.get(event.spanId);
17
+ spans.set(event.spanId, {
18
+ spanId: event.spanId,
19
+ traceId: event.traceId,
20
+ elementId: event.elementId,
21
+ contract: event.contract,
22
+ parentSpanId: event.parentSpanId,
23
+ linkedSpanId: event.linkedSpanId,
24
+ linkedTraceId: event.linkedTraceId,
25
+ status: event.status,
26
+ durationMs: event.durationMs,
27
+ failureCode: event.failureCode,
28
+ jobStatus: event.jobStatus,
29
+ timestamp: previous?.timestamp ?? event.timestamp,
30
+ startObserved: previous?.startObserved || event.status === "started",
31
+ });
32
+ }
33
+ const connections = [];
34
+ for (const span of spans.values()) {
35
+ const parent = spans.get(span.parentSpanId || span.linkedSpanId || "");
36
+ if (!parent ||
37
+ (span.parentSpanId
38
+ ? parent.traceId !== span.traceId
39
+ : parent.traceId !== span.linkedTraceId))
40
+ continue;
41
+ connections.push({
42
+ id: `observed:${span.spanId}`,
43
+ source: parent.elementId,
44
+ target: span.elementId,
45
+ relation: span.parentSpanId ? "calls" : "resumes",
46
+ label: `${span.parentSpanId ? "" : "Continuation · "}${span.contract} · ${span.jobStatus === "failed" ? "job failed" : span.status}`,
47
+ provenance: "observed",
48
+ });
49
+ }
50
+ return {
51
+ spans: [...spans.values()].sort((a, b) => a.timestamp - b.timestamp),
52
+ connections,
53
+ incompatibleEvents,
54
+ };
55
+ }
@@ -0,0 +1,26 @@
1
+ /** Safe, payload-free records emitted only when a decorated boundary executes. */
2
+ export interface TraceEvent {
3
+ id: string;
4
+ traceId: string;
5
+ spanId: string;
6
+ parentSpanId?: string;
7
+ linkedSpanId?: string;
8
+ linkedTraceId?: string;
9
+ elementId: string;
10
+ contract: string;
11
+ definitionRevision: string;
12
+ codeRevision?: string;
13
+ timestamp: number;
14
+ durationMs?: number;
15
+ /** Persisted job state observed at the boundary; distinct from the method outcome. */
16
+ jobStatus?: string;
17
+ status: "started" | "completed" | "failed";
18
+ failureCode?: "InvalidInput" | "InvalidOutput" | "OperationFailed";
19
+ }
20
+ export interface TraceSnapshot {
21
+ schema: "fractal.trace.v1";
22
+ jobId: string;
23
+ events: TraceEvent[];
24
+ droppedEvents: number;
25
+ persistence: "available" | "degraded";
26
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,44 @@
1
+ import type { OperationRuntime } from "./core.js";
2
+ import type { TraceEvent } from "./trace-model.js";
3
+ export interface TraceLink {
4
+ traceId: string;
5
+ spanId: string;
6
+ definitionRevision: string;
7
+ }
8
+ export interface TraceFrame {
9
+ owner: object;
10
+ traceId: string;
11
+ spanId?: string;
12
+ linkedSpanId?: string;
13
+ linkedTraceId?: string;
14
+ correlation: {
15
+ jobId?: string;
16
+ pending: TraceEvent[];
17
+ };
18
+ }
19
+ export interface AsyncTraceScope {
20
+ getStore(): TraceFrame | undefined;
21
+ run<T>(frame: TraceFrame, callback: () => T): T;
22
+ }
23
+ /** Async context is supplied by the host; the core remains usable in a browser. */
24
+ export declare class TraceRuntime implements OperationRuntime {
25
+ private readonly options;
26
+ constructor(options: {
27
+ owner: object;
28
+ definitionRevision: string;
29
+ codeRevision?: string;
30
+ scope: AsyncTraceScope;
31
+ emit: (jobId: string, event: TraceEvent) => void;
32
+ observeJobStatus?: (jobId: string, contract: string) => string | undefined;
33
+ });
34
+ root<T>(jobId: string | undefined, predecessor: TraceLink | undefined, execute: () => Promise<T>, fresh?: boolean): Promise<T>;
35
+ private current;
36
+ associate(jobId: string): void;
37
+ reference(): TraceLink | undefined;
38
+ private emit;
39
+ invoke<T>(boundary: {
40
+ elementId: string;
41
+ operation: string;
42
+ contract: string;
43
+ }, execute: () => Promise<T>): Promise<T>;
44
+ }
@@ -0,0 +1,123 @@
1
+ import { ContractViolation } from "./core.js";
2
+ /** Async context is supplied by the host; the core remains usable in a browser. */
3
+ export class TraceRuntime {
4
+ options;
5
+ constructor(options) {
6
+ this.options = options;
7
+ }
8
+ root(jobId, predecessor, execute, fresh = false) {
9
+ const current = this.current();
10
+ if (current && !fresh) {
11
+ if (!jobId || current.correlation.jobId === jobId)
12
+ return execute();
13
+ if (!current.correlation.jobId) {
14
+ this.associate(jobId);
15
+ return execute();
16
+ }
17
+ }
18
+ const frame = {
19
+ owner: this.options.owner,
20
+ traceId: crypto.randomUUID(),
21
+ linkedSpanId: predecessor?.spanId,
22
+ linkedTraceId: predecessor?.traceId,
23
+ correlation: { jobId, pending: [] },
24
+ };
25
+ return this.options.scope.run(frame, execute);
26
+ }
27
+ current() {
28
+ const frame = this.options.scope.getStore();
29
+ return frame?.owner === this.options.owner ? frame : undefined;
30
+ }
31
+ associate(jobId) {
32
+ const frame = this.current();
33
+ if (!frame)
34
+ throw new Error("Job correlation requires an active trace");
35
+ if (frame.correlation.jobId && frame.correlation.jobId !== jobId)
36
+ throw new Error("A trace cannot change job identity");
37
+ frame.correlation.jobId = jobId;
38
+ for (const event of frame.correlation.pending.splice(0))
39
+ this.emit(jobId, event);
40
+ }
41
+ reference() {
42
+ const frame = this.current();
43
+ return frame?.spanId
44
+ ? {
45
+ traceId: frame.traceId,
46
+ spanId: frame.spanId,
47
+ definitionRevision: this.options.definitionRevision,
48
+ }
49
+ : undefined;
50
+ }
51
+ emit(jobId, event) {
52
+ try {
53
+ this.options.emit(jobId, event);
54
+ }
55
+ catch {
56
+ /* Observation cannot change execution semantics. */
57
+ }
58
+ }
59
+ invoke(boundary, execute) {
60
+ const parent = this.current();
61
+ if (!parent)
62
+ return this.root(undefined, undefined, () => this.invoke(boundary, execute));
63
+ const spanId = crypto.randomUUID();
64
+ const frame = { ...parent, spanId };
65
+ const started = performance.now();
66
+ const publish = (status, failureCode) => {
67
+ let jobStatus;
68
+ if (status !== "started" && frame.correlation.jobId) {
69
+ try {
70
+ jobStatus = this.options.observeJobStatus?.(frame.correlation.jobId, boundary.contract);
71
+ }
72
+ catch {
73
+ /* observation only */
74
+ }
75
+ }
76
+ const event = {
77
+ id: crypto.randomUUID(),
78
+ traceId: frame.traceId,
79
+ spanId,
80
+ ...(parent.spanId ? { parentSpanId: parent.spanId } : {}),
81
+ ...(!parent.spanId && parent.linkedSpanId
82
+ ? {
83
+ linkedSpanId: parent.linkedSpanId,
84
+ linkedTraceId: parent.linkedTraceId,
85
+ }
86
+ : {}),
87
+ elementId: boundary.elementId,
88
+ contract: boundary.contract,
89
+ definitionRevision: this.options.definitionRevision,
90
+ ...(this.options.codeRevision
91
+ ? { codeRevision: this.options.codeRevision }
92
+ : {}),
93
+ timestamp: Date.now(),
94
+ status,
95
+ ...(status !== "started"
96
+ ? { durationMs: performance.now() - started }
97
+ : {}),
98
+ ...(failureCode ? { failureCode } : {}),
99
+ ...(jobStatus ? { jobStatus } : {}),
100
+ };
101
+ if (frame.correlation.jobId)
102
+ this.emit(frame.correlation.jobId, event);
103
+ else if (frame.correlation.pending.length < 64)
104
+ frame.correlation.pending.push(event);
105
+ };
106
+ return this.options.scope.run(frame, async () => {
107
+ publish("started");
108
+ try {
109
+ const value = await execute();
110
+ publish("completed");
111
+ return value;
112
+ }
113
+ catch (error) {
114
+ publish("failed", error instanceof ContractViolation
115
+ ? error.phase === "input"
116
+ ? "InvalidInput"
117
+ : "InvalidOutput"
118
+ : "OperationFailed");
119
+ throw error;
120
+ }
121
+ });
122
+ }
123
+ }
@@ -0,0 +1,17 @@
1
+ import type { DefinitionGraph } from "./model.js";
2
+ /** Conservative file ownership check. Shared and unknown ownership never produce a pass. */
3
+ export declare function checkWorkScope(root: string, id: string, currentGraph: DefinitionGraph): Promise<{
4
+ work: string;
5
+ base: string;
6
+ head: string;
7
+ pass: boolean;
8
+ files: {
9
+ path: string;
10
+ status: string;
11
+ blocks: string[];
12
+ }[];
13
+ outside: number;
14
+ uncertain: number;
15
+ basis: string;
16
+ notice: string;
17
+ }>;
@@ -0,0 +1,110 @@
1
+ import { blockNoteFile } from "./workspace-notes.js";
2
+ import { readReport } from "./reports.js";
3
+ import { changedPaths } from "./git-code.js";
4
+ import { readGit, resolveComparisonRef } from "./git-refs.js";
5
+ import { parseWorkingStatus } from "./working-code.js";
6
+ import { readWorkPlan, workBaseline } from "./work-context.js";
7
+ import { scopeBlocks } from "./work-model.js";
8
+ /** Conservative file ownership check. Shared and unknown ownership never produce a pass. */
9
+ export async function checkWorkScope(root, id, currentGraph) {
10
+ const { entry, plan } = readWorkPlan(root, id);
11
+ const baseline = workBaseline(root, id);
12
+ const head = resolveComparisonRef(entry.root, "HEAD");
13
+ const committed = changedPaths(entry.root, plan.baseCommit, head).map((file) => file.path);
14
+ const working = parseWorkingStatus(readGit(entry.root, [
15
+ "status",
16
+ "--porcelain=v2",
17
+ "-z",
18
+ "--untracked-files=all",
19
+ ]));
20
+ const paths = [
21
+ ...new Set([
22
+ ...committed,
23
+ ...working.flatMap((path) => [
24
+ path.path,
25
+ ...(path.originalPath ? [path.originalPath] : []),
26
+ ]),
27
+ ]),
28
+ ].sort();
29
+ if (paths.length > 20000)
30
+ throw Error("Scope check exceeds the path budget; no pass was issued.");
31
+ const allowed = scopeBlocks(currentGraph, plan.scope, plan.excluded);
32
+ const baseAllowed = scopeBlocks(baseline, plan.scope, plan.excluded);
33
+ function owners(graph, path) {
34
+ if (/^docs\/fractory\/reports\/[a-f0-9-]{36}\.md$/.test(path))
35
+ try {
36
+ const report = readReport(entry.root, path.split("/").at(-1).slice(0, -3), graph === baseline ? plan.baseCommit : undefined);
37
+ return report.blocks.filter((id) => graph.elements.some((n) => n.id === id));
38
+ }
39
+ catch { }
40
+ const candidates = graph.elements.filter((node) => (node.sources || (node.source ? [node.source] : [])).some((source) => source.file === path ||
41
+ (path.endsWith("/") && source.file.startsWith(path))) ||
42
+ (node.attachments?.tests || []).includes(path) ||
43
+ (node.attachments?.docs || []).includes(path) ||
44
+ blockNoteFile(node.id) === path ||
45
+ path.startsWith(blockNoteFile(node.id).replace(/\.md$/, "/")));
46
+ for (const test of graph.tests.filter((test) => test.source.file === path))
47
+ for (const target of test.targets) {
48
+ const node = graph.elements.find((node) => node.id === target);
49
+ if (node && !candidates.some((item) => item.id === node.id))
50
+ candidates.push(node);
51
+ }
52
+ // Parent sources often describe the same module; the most specific mapped owners decide.
53
+ return candidates
54
+ .filter((node) => !candidates.some((other) => other.id !== node.id && isAncestor(graph, node.id, other.id)))
55
+ .map((node) => node.id);
56
+ }
57
+ const files = paths.map((path) => {
58
+ if ([
59
+ ".agents/skills/fractory/SKILL.md",
60
+ ".agents/skills/fractory/references/fractory-guide.md",
61
+ ].includes(path))
62
+ return { path, status: "setup", blocks: [] };
63
+ if (path === entry.planFile)
64
+ return {
65
+ path,
66
+ status: "plan",
67
+ blocks: [graphRoot(currentGraph)],
68
+ };
69
+ const baseOwners = owners(baseline, path);
70
+ const selected = baseOwners.length ? baseAllowed : allowed;
71
+ const blocks = baseOwners.length ? baseOwners : owners(currentGraph, path);
72
+ const inside = blocks.filter((block) => selected.has(block));
73
+ const status = !blocks.length
74
+ ? "unassigned"
75
+ : !inside.length
76
+ ? "outside"
77
+ : inside.length !== blocks.length
78
+ ? "shared"
79
+ : "inside";
80
+ return { path, status, blocks };
81
+ });
82
+ const uncertain = files.filter((file) => ["unassigned", "shared"].includes(file.status));
83
+ const outside = files.filter((file) => file.status === "outside");
84
+ return {
85
+ work: id,
86
+ base: plan.baseCommit,
87
+ head,
88
+ pass: !outside.length && !uncertain.length,
89
+ files,
90
+ outside: outside.length,
91
+ uncertain: uncertain.length,
92
+ basis: "pinned-file-ownership",
93
+ notice: "File ownership is conservative: shared and unassigned files require review. This check is not a filesystem sandbox or a protected-branch rule.",
94
+ };
95
+ }
96
+ function graphRoot(graph) {
97
+ return graph.id;
98
+ }
99
+ function isAncestor(graph, parent, child) {
100
+ const byId = new Map(graph.elements.map((n) => [n.id, n]));
101
+ const seen = new Set();
102
+ let id = child;
103
+ while (id && !seen.has(id)) {
104
+ if (id === parent)
105
+ return true;
106
+ seen.add(id);
107
+ id = byId.get(id)?.parent;
108
+ }
109
+ return false;
110
+ }
@@ -0,0 +1 @@
1
+ export declare function runWork(args: string[]): Promise<string>;
@@ -0,0 +1,148 @@
1
+ import { readFileSync, statSync } from "node:fs";
2
+ import { resolve } from "node:path";
3
+ import { execFileSync } from "node:child_process";
4
+ import { createWorkContext, adoptWorkContext, listWorkContexts, mainReference, readFactoryMap, resolveWorkContext, updateWorkPlan, workBaseline, workDeepLink, workHandoff, updateWorkIntent, } from "./work-context.js";
5
+ import { workIntentStates } from "./work-intents.js";
6
+ import { readGit } from "./git-refs.js";
7
+ import { checkWorkScope } from "./work-check.js";
8
+ export async function runWork(args) {
9
+ if (args.includes("--help"))
10
+ return `fractory work list\nfractory work create --title TITLE --block ID [--block ID] [--from REF]\nfractory work adopt ID --block ID [--block ID] [--title TITLE]\nfractory work show ID\nfractory work handoff ID\nfractory work open ID\nfractory work plan ID --file PLAN.json --revision REVISION\nfractory work check ID\nfractory work review ID\nfractory work intent ID --proposal PROPOSAL_ID --status planned|done|dropped --revision REV [--implementation BLOCK_OR_CONNECTION_ID]\nfractory work pr ID --url URL --title TITLE\nUse --root PATH to select a repository. Creating a work adds a worktree; it never switches the current checkout. Plan JSON contains a proposals array and optional scope. Shared or unknown file ownership makes check fail.`;
11
+ const option = (name) => {
12
+ const i = args.indexOf(name);
13
+ if (i < 0)
14
+ return undefined;
15
+ if (!args[i + 1] || args[i + 1].startsWith("--"))
16
+ throw Error(`${name} needs a value.`);
17
+ return args[i + 1];
18
+ };
19
+ const root = readGit(resolve(option("--root") || process.cwd()), [
20
+ "rev-parse",
21
+ "--show-toplevel",
22
+ ]).trim();
23
+ const action = args[1] || "list";
24
+ if (action === "list")
25
+ return JSON.stringify({ main: mainReference(root), targets: listWorkContexts(root) }, null, 2);
26
+ if (action === "create") {
27
+ const graph = await readFactoryMap(root);
28
+ if (!graph)
29
+ throw Error("Map this repository before starting block-scoped work.");
30
+ const scope = args.flatMap((value, index) => value === "--block" ? [args[index + 1]] : []);
31
+ const work = await createWorkContext(root, graph, {
32
+ title: option("--title") || "",
33
+ scope,
34
+ from: option("--from"),
35
+ });
36
+ return JSON.stringify({
37
+ ...work,
38
+ url: workDeepLink(root, work.id),
39
+ handoff: workHandoff(work, graph),
40
+ }, null, 2);
41
+ }
42
+ const id = args[2];
43
+ if (!id || id.startsWith("--"))
44
+ throw Error("Choose a work context from fractory work list.");
45
+ let work = resolveWorkContext(root, id);
46
+ const graph = (await readFactoryMap(work.root)) ||
47
+ (work.plan ? workBaseline(root, id) : await readFactoryMap(root));
48
+ if (!graph)
49
+ throw Error("No factory map is available for this work context.");
50
+ if (action === "adopt") {
51
+ const scope = args.flatMap((value, index) => value === "--block" ? [args[index + 1]] : []);
52
+ const adopted = await adoptWorkContext(root, id, graph, {
53
+ scope,
54
+ title: option("--title"),
55
+ });
56
+ return JSON.stringify({
57
+ ...adopted,
58
+ url: workDeepLink(root, adopted.id),
59
+ handoff: workHandoff(adopted, graph),
60
+ }, null, 2);
61
+ }
62
+ const intents = () => workIntentStates(work.root, graph, work.plan, work.plan ? workBaseline(root, id) : undefined);
63
+ if (action === "show")
64
+ return JSON.stringify({ ...work, intents: intents(), url: workDeepLink(root, id) }, null, 2);
65
+ if (action === "intent") {
66
+ if (!option("--proposal") ||
67
+ !option("--revision") ||
68
+ !["planned", "done", "dropped"].includes(option("--status") || ""))
69
+ throw Error("Use --proposal ID --status planned|done|dropped --revision REVISION, with --implementation ID to link actual code.");
70
+ work = updateWorkIntent(root, id, graph, {
71
+ revision: option("--revision"),
72
+ proposal: option("--proposal"),
73
+ status: option("--status"),
74
+ implementation: option("--implementation"),
75
+ });
76
+ return JSON.stringify({ ...work, intents: intents() }, null, 2);
77
+ }
78
+ if (action === "handoff")
79
+ return workHandoff(work, graph);
80
+ if (action === "open") {
81
+ const url = workDeepLink(root, id);
82
+ execFileSync("open", [url], { stdio: "ignore", timeout: 5000 });
83
+ return url;
84
+ }
85
+ if (action === "review") {
86
+ const report = await checkWorkScope(root, id, graph);
87
+ const states = intents();
88
+ const labels = new Map(graph.elements.map((n) => [n.id, n.label]));
89
+ return [
90
+ `## ${work.title}`,
91
+ "",
92
+ `[Open the factory work view](${workDeepLink(root, id)})`,
93
+ "",
94
+ `Base: ${work.baseCommit} · Head: ${work.head}`,
95
+ "",
96
+ `Scope: ${(work.plan?.scope || []).map((id) => labels.get(id) || id).join(", ")}`,
97
+ "",
98
+ `Scope check: ${report.pass ? "passed" : `${report.outside} outside; ${report.uncertain} shared or unmapped`}`,
99
+ "",
100
+ "| Change | Files |",
101
+ "| --- | ---: |",
102
+ ...["inside", "outside", "shared", "unassigned"].map((status) => `| ${status} | ${report.files.filter((f) => f.status === status).length} |`),
103
+ "",
104
+ ...(work.plan?.proposals.length
105
+ ? [
106
+ "### Intended changes",
107
+ ...work.plan.proposals.map((p) => `- [${states[p.id]?.status === "changed" ? "needs recheck" : states[p.id]?.status || "planned"}] ${p.kind}: ${p.label}${p.kind === "connection" ? ` (${labels.get(p.source) || p.source} → ${labels.get(p.target) || p.target})` : ""}${p.implementation ? ` → ${labels.get(p.implementation) || p.implementation}` : ""} — ${p.note.replace(/\n/g, " ")}`),
108
+ ]
109
+ : []),
110
+ "",
111
+ "The plan shows intent. File ownership is checked against the pinned map; this is not test evidence or merge protection.",
112
+ ].join("\n");
113
+ }
114
+ if (action === "check") {
115
+ const report = await checkWorkScope(root, id, graph);
116
+ if (!report.pass)
117
+ process.exitCode = 1;
118
+ return JSON.stringify(report, null, 2);
119
+ }
120
+ if (action === "plan" || action === "pr") {
121
+ if (!work.plan || !work.revision)
122
+ throw Error("Start a block-scoped work context first.");
123
+ const file = option("--file");
124
+ if (action === "plan" && (!file || !option("--revision")))
125
+ throw Error("Choose --file and --revision from work show.");
126
+ if (file && statSync(resolve(file)).size > 150000)
127
+ throw Error("Keep the plan below 150 KB.");
128
+ const value = action === "plan" && file
129
+ ? JSON.parse(readFileSync(resolve(file), "utf8"))
130
+ : {};
131
+ work = updateWorkPlan(root, id, graph, {
132
+ revision: option("--revision") || work.revision,
133
+ proposals: value.proposals || work.plan.proposals,
134
+ scope: value.scope,
135
+ excluded: value.excluded,
136
+ ...(action === "pr"
137
+ ? {
138
+ pullRequest: {
139
+ url: option("--url") || "",
140
+ title: option("--title") || "Pull request",
141
+ },
142
+ }
143
+ : {}),
144
+ });
145
+ return JSON.stringify(work, null, 2);
146
+ }
147
+ throw Error(`Unknown work command: ${action}`);
148
+ }
@@ -0,0 +1,57 @@
1
+ import { type WorkContext, type WorkPlan, type WorkTarget } from "./work-model.js";
2
+ import type { DefinitionGraph } from "./model.js";
3
+ export declare function workDirectory(root: string): string;
4
+ export declare function mainReference(root: string): {
5
+ ref: string;
6
+ commit: string;
7
+ };
8
+ export declare function gitWorkTargets(root: string): WorkTarget[];
9
+ interface RegistryEntry {
10
+ id: string;
11
+ root: string;
12
+ planFile: string;
13
+ baselineFile: string;
14
+ }
15
+ export declare function readWorkPlan(root: string, id: string, known?: {
16
+ directory: string;
17
+ targets: WorkTarget[];
18
+ }): {
19
+ entry: RegistryEntry;
20
+ plan: WorkPlan;
21
+ revision: string;
22
+ };
23
+ export declare function workBaseline(root: string, id: string): DefinitionGraph;
24
+ export declare function listWorkContexts(root: string): WorkTarget[];
25
+ export declare function resolveWorkContext(root: string, id?: string): WorkContext;
26
+ export declare function readFactoryMap(root: string, ref?: string): Promise<DefinitionGraph | null>;
27
+ export declare function createWorkContext(root: string, graph: DefinitionGraph, input: {
28
+ title: string;
29
+ scope: string[];
30
+ excluded?: string[];
31
+ branch?: string;
32
+ from?: string;
33
+ fromName?: string;
34
+ }): Promise<WorkContext>;
35
+ /** Attach a plan to an existing registered Git checkout. No checkout, branch creation or code copy. */
36
+ export declare function adoptWorkContext(root: string, targetId: string, graph: DefinitionGraph, input: {
37
+ scope: string[];
38
+ excluded?: string[];
39
+ title?: string;
40
+ }): Promise<WorkContext>;
41
+ export declare function updateWorkPlan(root: string, id: string, graph: DefinitionGraph, input: {
42
+ revision: string;
43
+ proposals?: unknown;
44
+ scope?: string[];
45
+ excluded?: string[];
46
+ pullRequest?: WorkPlan["pullRequest"];
47
+ }, snapshot?: WorkContext): WorkContext;
48
+ /** Explicit confirmation, with evidence read from this checkout and the pinned baseline. */
49
+ export declare function updateWorkIntent(root: string, id: string, graph: DefinitionGraph, input: {
50
+ revision: string;
51
+ proposal: string;
52
+ status: "planned" | "done" | "dropped";
53
+ implementation?: string;
54
+ }): WorkContext;
55
+ export declare function workDeepLink(root: string, id: string): string;
56
+ export declare function workHandoff(context: WorkContext, graph: DefinitionGraph): string;
57
+ export {};