@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,140 @@
1
+ /** Local confirmation records: current source evidence, never inferred completion or test coverage. */
2
+ import { createHash } from "node:crypto";
3
+ import { readFileSync, statSync } from "node:fs";
4
+ import { checkedPath } from "./workspace-notes.js";
5
+ const hash = (value) => createHash("sha256").update(value).digest("hex");
6
+ const stable = (value) => JSON.stringify(value, (_key, item) => item && typeof item === "object" && !Array.isArray(item)
7
+ ? Object.fromEntries(Object.keys(item)
8
+ .sort()
9
+ .map((key) => [key, item[key]]))
10
+ : item);
11
+ const files = new Map();
12
+ function fingerprint(root, file) {
13
+ const path = checkedPath(root, file), stat = statSync(path);
14
+ if (!stat.isFile() || stat.size > 2 * 1024 * 1024)
15
+ throw Error("Choose a smaller implementation block to confirm.");
16
+ const stamp = `${stat.ino}:${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}`;
17
+ let saved = files.get(path);
18
+ if (saved?.stamp !== stamp) {
19
+ saved = { stamp, digest: hash(readFileSync(path)), bytes: stat.size };
20
+ files.set(path, saved);
21
+ if (files.size > 2048)
22
+ files.delete(files.keys().next().value);
23
+ }
24
+ return saved;
25
+ }
26
+ export function intentTarget(graph, proposal) {
27
+ const id = proposal.implementation ||
28
+ (proposal.kind === "annotation" ? proposal.target : undefined);
29
+ return (id &&
30
+ (proposal.kind === "connection"
31
+ ? graph.connections.find((e) => e.id === id && e.provenance !== "proposed")
32
+ : graph.elements.find((n) => n.id === id && n.provenance !== "proposed") ||
33
+ (proposal.kind === "annotation"
34
+ ? graph.connections.find((e) => e.id === id && e.provenance !== "proposed")
35
+ : undefined)));
36
+ }
37
+ /** No fuzzy match: an agent/developer chooses the implementation identity explicitly. */
38
+ export function intentEvidence(root, graph, proposal, baseline) {
39
+ const target = intentTarget(graph, proposal);
40
+ const removed = proposal.kind === "annotation" &&
41
+ proposal.change === "remove" &&
42
+ !target &&
43
+ proposal.target &&
44
+ [...(baseline?.elements || []), ...(baseline?.connections || [])].find((n) => n.id === proposal.target);
45
+ if (!target && !removed)
46
+ throw Error("Link the real implementation on the map first.");
47
+ if (proposal.change === "remove" && target)
48
+ throw Error("This block or connection is still on the map.");
49
+ const nodes = target
50
+ ? [target]
51
+ : [removed];
52
+ if (target && "kind" in target) {
53
+ const ids = new Set([target.id]);
54
+ for (let i = 0, changed = true; changed && i < graph.elements.length; i++) {
55
+ changed = false;
56
+ for (const n of graph.elements)
57
+ if (n.parent && ids.has(n.parent) && !ids.has(n.id)) {
58
+ ids.add(n.id);
59
+ nodes.push(n);
60
+ changed = true;
61
+ }
62
+ }
63
+ }
64
+ const refs = nodes.flatMap((n) => [
65
+ ...("kind" in n && n.source ? [n.source] : []),
66
+ ...("sourceRef" in n && n.sourceRef ? [n.sourceRef] : []),
67
+ ...(n.sources || []),
68
+ ]);
69
+ if (!refs.length)
70
+ throw Error("Map this implementation to real source code before marking it done.");
71
+ const paths = new Set(refs.map((r) => r.file));
72
+ for (const n of nodes)
73
+ if ("attachments" in n) {
74
+ for (const path of [
75
+ ...(n.attachments?.docs || []),
76
+ ...(n.attachments?.tests || []),
77
+ ])
78
+ paths.add(path);
79
+ }
80
+ if (paths.size > 256)
81
+ throw Error("Choose a smaller implementation block to confirm.");
82
+ let bytes = 0;
83
+ const evidence = [];
84
+ for (const path of [...paths].sort()) {
85
+ let source;
86
+ try {
87
+ source = fingerprint(root, path);
88
+ }
89
+ catch (error) {
90
+ if (refs.some((r) => r.file === path) && !removed)
91
+ throw Error("The implementation source is missing or unavailable. Refresh its map before confirming.");
92
+ evidence.push([path, "missing"]);
93
+ continue;
94
+ }
95
+ bytes += source.bytes;
96
+ if (bytes > 16 * 1024 * 1024)
97
+ throw Error("Choose a smaller implementation block to confirm.");
98
+ if (!removed &&
99
+ refs.some((r) => r.file === path &&
100
+ (!/^(?:[a-f0-9]{16}|[a-f0-9]{64})$/.test(r.digest) ||
101
+ !source.digest.startsWith(r.digest))))
102
+ throw Error("The map’s source references are stale. Regenerate the map before confirming.");
103
+ evidence.push([path, source.digest]);
104
+ }
105
+ const { outcome: _outcome, position: _position, resolved: _resolved, createdAt: _createdAt, ...request } = proposal;
106
+ return hash(stable({
107
+ request,
108
+ nodes: nodes.sort((a, b) => a.id.localeCompare(b.id)),
109
+ removed: !!removed,
110
+ files: evidence,
111
+ }));
112
+ }
113
+ export function workIntentStates(root, graph, plan, baseline) {
114
+ return Object.fromEntries((plan?.proposals || []).map((p) => {
115
+ const implementation = p.implementation || (p.kind === "annotation" ? p.target : undefined);
116
+ let state = {
117
+ status: p.outcome?.status || "planned",
118
+ implementation,
119
+ };
120
+ if (p.outcome?.status === "done")
121
+ try {
122
+ if (intentEvidence(root, graph, p, baseline) !== p.outcome.evidence)
123
+ state = {
124
+ status: "changed",
125
+ implementation,
126
+ reason: "The request or implementation changed after it was marked done.",
127
+ };
128
+ }
129
+ catch (e) {
130
+ state = {
131
+ status: "changed",
132
+ implementation,
133
+ reason: e instanceof Error
134
+ ? e.message
135
+ : "Implementation evidence is unavailable.",
136
+ };
137
+ }
138
+ return [p.id, state];
139
+ }));
140
+ }
@@ -0,0 +1,58 @@
1
+ import type { DefinitionGraph } from "./model.js";
2
+ export type WorkState = "todo" | "in_progress" | "done" | "archived" | "canceled" | "unknown";
3
+ export interface LinearWorkIssue {
4
+ id: string;
5
+ identifier: string;
6
+ title: string;
7
+ url: string;
8
+ state: {
9
+ name: string;
10
+ type: string;
11
+ };
12
+ updatedAt: string;
13
+ checkedAt: string;
14
+ archivedAt?: string | null;
15
+ }
16
+ export interface IssueLink {
17
+ issue: string;
18
+ identifier?: string;
19
+ blocks: string[];
20
+ }
21
+ export interface IssueLinks {
22
+ schema: "fractal.issues.v1";
23
+ workspace?: {
24
+ id?: string;
25
+ name?: string;
26
+ url: string;
27
+ };
28
+ links: IssueLink[];
29
+ }
30
+ export interface WorkItem extends IssueLink {
31
+ metadata?: LinearWorkIssue;
32
+ state: WorkState;
33
+ }
34
+ export interface WorkView {
35
+ _cache?: {
36
+ at: string;
37
+ stale: boolean;
38
+ refreshing: boolean;
39
+ failed: boolean;
40
+ };
41
+ revision: string;
42
+ registry: IssueLinks;
43
+ items: WorkItem[];
44
+ connection: {
45
+ configured: boolean;
46
+ notice?: string;
47
+ source: "linear" | "recorded" | "unavailable";
48
+ };
49
+ }
50
+ export declare function issueReference(value: string): {
51
+ key: string;
52
+ workspace?: string;
53
+ url?: string;
54
+ };
55
+ export declare function workState(issue?: LinearWorkIssue): WorkState;
56
+ /** Use the provider's typed state; do not guess progress from a title or an assignee. */
57
+ export declare function workItems(registry: IssueLinks, metadata: LinearWorkIssue[], includeUnlinked?: boolean): WorkItem[];
58
+ export declare function workForScope(graph: DefinitionGraph, items: WorkItem[], scope: string): WorkItem[];
@@ -0,0 +1,86 @@
1
+ export function issueReference(value) {
2
+ value = value.trim();
3
+ if (/^https:\/\//i.test(value)) {
4
+ const url = new URL(value), parts = url.pathname.split("/").filter(Boolean);
5
+ if (url.hostname !== "linear.app" ||
6
+ url.port ||
7
+ url.username ||
8
+ url.password ||
9
+ parts[1] !== "issue")
10
+ throw Error("Use a Linear issue URL or identifier");
11
+ const key = parts[2]?.toUpperCase();
12
+ if (!/^[A-Z][A-Z0-9]{0,15}-[1-9][0-9]{0,9}$/.test(key || ""))
13
+ throw Error("Invalid Linear issue identifier");
14
+ return {
15
+ key,
16
+ workspace: parts[0],
17
+ url: `https://linear.app/${parts[0]}/issue/${key}`,
18
+ };
19
+ }
20
+ if (/^[A-Z][A-Z0-9]{0,15}-[1-9][0-9]{0,9}$/i.test(value))
21
+ return { key: value.toUpperCase() };
22
+ if (/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(value))
23
+ return { key: value.toLowerCase() };
24
+ throw Error("Enter a Linear issue identifier, UUID or URL");
25
+ }
26
+ export function workState(issue) {
27
+ if (!issue)
28
+ return "unknown";
29
+ if (issue.archivedAt)
30
+ return "archived";
31
+ if (issue.state.type === "started")
32
+ return "in_progress";
33
+ if (issue.state.type === "completed")
34
+ return "done";
35
+ if (["canceled", "duplicate"].includes(issue.state.type))
36
+ return "canceled";
37
+ return ["triage", "backlog", "unstarted"].includes(issue.state.type)
38
+ ? "todo"
39
+ : "unknown";
40
+ }
41
+ /** Use the provider's typed state; do not guess progress from a title or an assignee. */
42
+ export function workItems(registry, metadata, includeUnlinked = false) {
43
+ const byId = new Map(metadata.flatMap((issue) => [
44
+ [issue.id, issue],
45
+ [issue.identifier, issue],
46
+ ]));
47
+ const items = new Map();
48
+ for (const link of registry.links) {
49
+ const issue = byId.get(link.issue) ||
50
+ (link.identifier ? byId.get(link.identifier) : undefined);
51
+ const key = issue?.id || link.issue, prior = items.get(key);
52
+ items.set(key, {
53
+ ...link,
54
+ blocks: [...new Set([...(prior?.blocks || []), ...link.blocks])],
55
+ metadata: issue,
56
+ state: workState(issue),
57
+ });
58
+ }
59
+ if (includeUnlinked)
60
+ for (const issue of metadata)
61
+ if (!items.has(issue.id))
62
+ items.set(issue.id, {
63
+ issue: issue.id,
64
+ identifier: issue.identifier,
65
+ blocks: [],
66
+ metadata: issue,
67
+ state: workState(issue),
68
+ });
69
+ return [...items.values()];
70
+ }
71
+ export function workForScope(graph, items, scope) {
72
+ if (scope === graph.id)
73
+ return items;
74
+ const descendants = new Set([scope]);
75
+ for (let changed = true; changed;) {
76
+ changed = false;
77
+ for (const node of graph.elements)
78
+ if (node.parent &&
79
+ descendants.has(node.parent) &&
80
+ !descendants.has(node.id)) {
81
+ descendants.add(node.id);
82
+ changed = true;
83
+ }
84
+ }
85
+ return items.filter((item) => item.blocks.some((block) => descendants.has(graph.aliases?.[block] || block)));
86
+ }
@@ -0,0 +1,12 @@
1
+ import type { DefinitionGraph } from "./model.js";
2
+ import type { WorkPlan, WorkLock } from "./work-model.js";
3
+ export interface LockResult {
4
+ target: string;
5
+ kind: WorkLock["kind"];
6
+ status: "unchanged" | "violated" | "uncertain";
7
+ issues: {
8
+ file?: string;
9
+ message: string;
10
+ }[];
11
+ }
12
+ export declare function checkWorkLocks(root: string, plan: WorkPlan, baseline: DefinitionGraph, graph: DefinitionGraph, changed: string[]): LockResult[];
@@ -0,0 +1,339 @@
1
+ /** Read-only checks against the work's pinned starting revision. Never execute application code. */
2
+ import ts from "typescript";
3
+ import { readFileSync, lstatSync } from "node:fs";
4
+ import { resolve } from "node:path";
5
+ import { checkedPath } from "./workspace-notes.js";
6
+ import { readGit } from "./git-refs.js";
7
+ import { scopeBlocks } from "./work-model.js";
8
+ import { publicContractIds } from "./work-locks.js";
9
+ const stable = (value) => JSON.stringify(value, (_key, v) => v && typeof v === "object" && !Array.isArray(v)
10
+ ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => a.localeCompare(b)))
11
+ : v);
12
+ const refs = (node) => node.sources?.length ? node.sources : node.source ? [node.source] : [];
13
+ const printer = ts.createPrinter({ removeComments: true });
14
+ const print = (n, sf) => printer.printNode(ts.EmitHint.Unspecified, n, sf);
15
+ function declaration(text, ref, contract) {
16
+ const ast = ts.createSourceFile(ref.file, text, ts.ScriptTarget.Latest, true, ref.file.endsWith("x") ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
17
+ if (ast.parseDiagnostics
18
+ .length)
19
+ throw Error("Source cannot be parsed");
20
+ const found = [];
21
+ const nameOf = (n) => {
22
+ const name = n.name;
23
+ if (!name)
24
+ return undefined;
25
+ const cls = (ts.isMethodDeclaration(n) || ts.isPropertyDeclaration(n)) &&
26
+ ts.isClassDeclaration(n.parent)
27
+ ? n.parent.name?.text
28
+ : undefined;
29
+ return cls ? `${cls}.${name.getText(ast)}` : name.getText(ast);
30
+ };
31
+ function visit(n) {
32
+ if ((ts.isFunctionDeclaration(n) ||
33
+ ts.isMethodDeclaration(n) ||
34
+ ts.isVariableDeclaration(n) ||
35
+ ts.isInterfaceDeclaration(n) ||
36
+ ts.isTypeAliasDeclaration(n) ||
37
+ ts.isClassDeclaration(n) ||
38
+ ts.isPropertyDeclaration(n)) &&
39
+ (nameOf(n) === ref.symbol ||
40
+ n.name?.getText(ast) === ref.symbol))
41
+ found.push(n);
42
+ ts.forEachChild(n, visit);
43
+ }
44
+ if (ref.symbol)
45
+ visit(ast);
46
+ else if (ref.scope === "file" && contract) {
47
+ // A file-level interface exposes its exported declarations, never every private helper.
48
+ found.push(...ast.statements.filter((n) => ts.canHaveModifiers(n) &&
49
+ ts
50
+ .getModifiers(n)
51
+ ?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)));
52
+ }
53
+ else
54
+ throw Error("No unique source symbol identifies the protected declaration");
55
+ if (!found.length)
56
+ return undefined;
57
+ if (found.length > 1 &&
58
+ !found.every(ts.isFunctionDeclaration) &&
59
+ !found.every((n) => ts.isMethodDeclaration(n) && n.parent === found[0].parent))
60
+ throw Error("Protected source symbol is ambiguous");
61
+ if (!contract)
62
+ return {
63
+ value: found.map((n) => print(n, ast)).join("\n"),
64
+ inferred: false,
65
+ };
66
+ let inferred = false;
67
+ const signatures = found.map((node) => {
68
+ const result = ts.transform(node, [
69
+ (context) => {
70
+ const strip = (n) => {
71
+ if (ts.isClassDeclaration(n)) {
72
+ const members = n.members.filter((m) => !(ts.getCombinedModifierFlags(m) &
73
+ (ts.ModifierFlags.Private | ts.ModifierFlags.Protected) ||
74
+ (m.name && ts.isPrivateIdentifier(m.name))));
75
+ return ts.factory.updateClassDeclaration(n, n.modifiers, n.name, n.typeParameters, n.heritageClauses, members.map((m) => ts.visitNode(m, strip)));
76
+ }
77
+ if (ts.isConstructorDeclaration(n))
78
+ return ts.factory.updateConstructorDeclaration(n, n.modifiers, n.parameters, undefined);
79
+ if (ts.isGetAccessorDeclaration(n)) {
80
+ inferred ||= !!n.body && !n.type;
81
+ return ts.factory.updateGetAccessorDeclaration(n, n.modifiers, n.name, n.parameters, n.type, undefined);
82
+ }
83
+ if (ts.isSetAccessorDeclaration(n))
84
+ return ts.factory.updateSetAccessorDeclaration(n, n.modifiers, n.name, n.parameters, undefined);
85
+ if (ts.isPropertyDeclaration(n)) {
86
+ inferred ||= !!n.initializer && !n.type;
87
+ return ts.factory.updatePropertyDeclaration(n, n.modifiers, n.name, n.questionToken || n.exclamationToken, n.type, undefined);
88
+ }
89
+ if (ts.isFunctionDeclaration(n)) {
90
+ inferred ||= !!n.body && !n.type;
91
+ return ts.factory.updateFunctionDeclaration(n, n.modifiers, n.asteriskToken, n.name, n.typeParameters, n.parameters, n.type, undefined);
92
+ }
93
+ if (ts.isMethodDeclaration(n)) {
94
+ inferred ||= !!n.body && !n.type;
95
+ return ts.factory.updateMethodDeclaration(n, n.modifiers, n.asteriskToken, n.name, n.questionToken, n.typeParameters, n.parameters, n.type, undefined);
96
+ }
97
+ if (ts.isArrowFunction(n)) {
98
+ inferred ||= !n.type;
99
+ return ts.factory.updateArrowFunction(n, n.modifiers, n.typeParameters, n.parameters, n.type, n.equalsGreaterThanToken, ts.factory.createBlock([]));
100
+ }
101
+ if (ts.isFunctionExpression(n)) {
102
+ inferred ||= !n.type;
103
+ return ts.factory.updateFunctionExpression(n, n.modifiers, n.asteriskToken, n.name, n.typeParameters, n.parameters, n.type, ts.factory.createBlock([]));
104
+ }
105
+ return ts.visitEachChild(n, strip, context);
106
+ };
107
+ return (root) => ts.visitNode(root, strip);
108
+ },
109
+ ]);
110
+ let statement = node;
111
+ while (statement.parent && statement.parent !== ast)
112
+ statement = statement.parent;
113
+ const exposure = ts.canHaveModifiers(statement)
114
+ ? ts
115
+ .getModifiers(statement)
116
+ ?.filter((m) => [
117
+ ts.SyntaxKind.ExportKeyword,
118
+ ts.SyntaxKind.DefaultKeyword,
119
+ ].includes(m.kind))
120
+ .map((m) => print(m, ast))
121
+ .join(" ") || ""
122
+ : "";
123
+ const value = exposure + " " + print(result.transformed[0], ast);
124
+ result.dispose();
125
+ return value;
126
+ });
127
+ // Referenced local types and import bindings are part of the syntactic contract.
128
+ // Imported type definitions require a type check when dependencies have changed.
129
+ const referenced = new Set();
130
+ const collect = (n) => {
131
+ if (ts.isTypeReferenceNode(n))
132
+ referenced.add(n.typeName.getText(n.getSourceFile()).split(".")[0]);
133
+ if (ts.isTypeQueryNode(n))
134
+ referenced.add(n.exprName.getText(n.getSourceFile()).split(".")[0]);
135
+ ts.forEachChild(n, collect);
136
+ };
137
+ // Parse the stripped declaration: implementation-only types are not part of its contract.
138
+ collect(ts.createSourceFile("contract.ts", signatures.join("\n"), ts.ScriptTarget.Latest, true));
139
+ const local = ast.statements.filter((n) => ts.isTypeAliasDeclaration(n) || ts.isInterfaceDeclaration(n));
140
+ const types = [];
141
+ let importedTypes = false;
142
+ const used = new Set();
143
+ for (let pending = true; pending;) {
144
+ pending = false;
145
+ for (const n of local)
146
+ if (referenced.has(n.name.text) && !used.has(n.name.text)) {
147
+ used.add(n.name.text);
148
+ types.push(print(n, ast));
149
+ collect(n);
150
+ pending = true;
151
+ }
152
+ }
153
+ for (const n of ast.statements)
154
+ if (ts.isImportDeclaration(n)) {
155
+ const bindings = n.importClause?.namedBindings;
156
+ if (n.importClause?.name && referenced.has(n.importClause.name.text)) {
157
+ importedTypes = true;
158
+ types.push(`default ${n.importClause.name.text} from ${n.moduleSpecifier.getText(ast)}`);
159
+ }
160
+ if (bindings && ts.isNamedImports(bindings))
161
+ for (const item of bindings.elements)
162
+ if (referenced.has(item.name.text))
163
+ types.push(`${item.getText(ast)} from ${n.moduleSpecifier.getText(ast)}`);
164
+ if (bindings &&
165
+ ts.isNamespaceImport(bindings) &&
166
+ referenced.has(bindings.name.text))
167
+ types.push(`${bindings.getText(ast)} from ${n.moduleSpecifier.getText(ast)}`);
168
+ }
169
+ return {
170
+ value: signatures.join("\n") + "\n" + types.sort().join("\n"),
171
+ inferred,
172
+ importedTypes: importedTypes || types.some((text) => text.includes(" from ")),
173
+ };
174
+ }
175
+ export function checkWorkLocks(root, plan, baseline, graph, changed) {
176
+ const changedSet = new Set(changed);
177
+ const cache = new Map();
178
+ function source(file, version) {
179
+ const key = `${version}:${file}`;
180
+ if (cache.has(key))
181
+ return cache.get(key);
182
+ let text;
183
+ try {
184
+ if (version !== "saved")
185
+ text = readGit(root, [
186
+ "show",
187
+ `${version === "base" ? plan.baseCommit : ""}:${file}`,
188
+ ]);
189
+ else {
190
+ const path = checkedPath(root, file), stat = lstatSync(path);
191
+ if (stat.isSymbolicLink() || stat.size > 1024 * 1024)
192
+ throw Error("Linked or oversized source");
193
+ text = readFileSync(resolve(path), "utf8");
194
+ }
195
+ if (text.length > 1024 * 1024 || text.includes("\0"))
196
+ text = undefined;
197
+ }
198
+ catch {
199
+ text = undefined;
200
+ }
201
+ cache.set(key, text);
202
+ return text;
203
+ }
204
+ return (plan.locks || []).map((lock) => {
205
+ const result = {
206
+ target: lock.target,
207
+ kind: lock.kind,
208
+ status: "unchanged",
209
+ issues: [],
210
+ };
211
+ const issue = (status, message, file) => {
212
+ if (result.status !== "violated")
213
+ result.status = status;
214
+ result.issues.push({ ...(file ? { file } : {}), message });
215
+ };
216
+ const old = baseline.elements.find((n) => n.id === lock.target), now = graph.elements.find((n) => n.id === lock.target);
217
+ if (!old) {
218
+ issue("uncertain", "The starting map has no verified boundary for this lock.");
219
+ return result;
220
+ }
221
+ if (!now) {
222
+ issue("violated", "Locked boundary was removed from the map.");
223
+ return result;
224
+ }
225
+ const beforeIds = lock.kind === "subtree"
226
+ ? scopeBlocks(baseline, [lock.target])
227
+ : publicContractIds(baseline, lock.target);
228
+ const afterIds = lock.kind === "subtree"
229
+ ? scopeBlocks(graph, [lock.target])
230
+ : publicContractIds(graph, lock.target);
231
+ const beforeNodes = baseline.elements.filter((n) => beforeIds.has(n.id));
232
+ const afterNodes = graph.elements.filter((n) => afterIds.has(n.id));
233
+ const shape = (nodes) => nodes
234
+ .map((n) => ({
235
+ id: n.id,
236
+ kind: n.kind,
237
+ parent: n.parent,
238
+ contract: n.contract,
239
+ signature: n.signature,
240
+ auth: n.attachments?.auth,
241
+ ...(lock.kind === "subtree"
242
+ ? { implementationBlock: n.implementationBlock }
243
+ : {}),
244
+ }))
245
+ .sort((a, b) => a.id.localeCompare(b.id));
246
+ if (stable(shape(beforeNodes)) !== stable(shape(afterNodes)))
247
+ issue("violated", lock.kind === "contract"
248
+ ? "Public boundary, signature or declared contract changed."
249
+ : "Locked subtree structure or contract changed.");
250
+ const sources = new Map(beforeNodes
251
+ .flatMap((n) => [
252
+ ...refs(n),
253
+ ...(lock.kind === "subtree"
254
+ ? [
255
+ ...(n.attachments?.docs || []),
256
+ ...(n.attachments?.tests || []),
257
+ ].map((file) => ({
258
+ file,
259
+ line: 1,
260
+ digest: "",
261
+ scope: "file",
262
+ }))
263
+ : []),
264
+ ])
265
+ .map((r) => [`${r.file}:${r.scope || r.symbol || r.line}`, r]));
266
+ for (const n of afterNodes)
267
+ for (const r of refs(n)) {
268
+ if (![...sources.values()].some((old) => old.file === r.file &&
269
+ old.symbol === r.symbol &&
270
+ old.scope === r.scope))
271
+ issue("uncertain", "New source ownership in a locked boundary needs review.", r.file);
272
+ }
273
+ for (const ref of sources.values()) {
274
+ const dependencyChange = lock.kind === "contract" &&
275
+ changed.some((f) => f !== ref.file && /\.[cm]?[jt]sx?$/.test(f));
276
+ if (!changedSet.has(ref.file) && !dependencyChange)
277
+ continue;
278
+ const before = source(ref.file, "base");
279
+ const saved = source(ref.file, "saved"), staged = source(ref.file, "index");
280
+ const versions = [["Saved code", saved]];
281
+ if (staged !== saved)
282
+ versions.push(["Staged code", staged]);
283
+ for (const [label, after] of versions) {
284
+ const sourceIssue = (status, message, file) => issue(status, `${label}: ${message}`, file);
285
+ if (before === after && before !== undefined) {
286
+ if (dependencyChange && /\.[cm]?[jt]sx?$/.test(ref.file))
287
+ try {
288
+ const contract = declaration(before, ref, true);
289
+ if (!contract || contract.inferred || contract.importedTypes)
290
+ sourceIssue("uncertain", "Changed type dependencies need a type/API check.", ref.file);
291
+ }
292
+ catch {
293
+ sourceIssue("uncertain", "Dependent contract source cannot be verified.", ref.file);
294
+ }
295
+ continue;
296
+ }
297
+ if (before === undefined) {
298
+ sourceIssue("uncertain", "Starting source is unavailable for this lock.", ref.file);
299
+ continue;
300
+ }
301
+ if (after === undefined) {
302
+ sourceIssue("violated", "Locked source was removed or is unavailable.", ref.file);
303
+ continue;
304
+ }
305
+ if (lock.kind === "subtree" && (ref.scope === "file" || !ref.symbol)) {
306
+ sourceIssue("violated", "Source owned by the locked subtree changed.", ref.file);
307
+ continue;
308
+ }
309
+ if (!/\.[cm]?[jt]sx?$/.test(ref.file)) {
310
+ sourceIssue("uncertain", "This contract needs its language-specific check.", ref.file);
311
+ continue;
312
+ }
313
+ try {
314
+ const b = declaration(before, ref, lock.kind === "contract"), a = declaration(after, ref, lock.kind === "contract");
315
+ if (!b)
316
+ sourceIssue("uncertain", "Starting source symbol cannot be verified.", ref.file);
317
+ else if (!a || a.value !== b.value)
318
+ sourceIssue("violated", lock.kind === "contract"
319
+ ? "Public declaration changed."
320
+ : "Locked implementation changed.", ref.file);
321
+ else if (lock.kind === "contract" && (b.inferred || a.inferred))
322
+ sourceIssue("uncertain", "Return types are inferred; run a type/API check before asserting the contract is unchanged.", ref.file);
323
+ else if (lock.kind === "contract" &&
324
+ dependencyChange &&
325
+ (a.importedTypes || b.importedTypes))
326
+ sourceIssue("uncertain", "Changed type dependencies need a type/API check.", ref.file);
327
+ }
328
+ catch (error) {
329
+ sourceIssue("uncertain", error instanceof Error
330
+ ? error.message
331
+ : "Contract source unavailable.", ref.file);
332
+ }
333
+ }
334
+ }
335
+ if (!sources.size && !old.contract && !old.signature)
336
+ issue("uncertain", "No source or declared contract proves this boundary is unchanged.");
337
+ return result;
338
+ });
339
+ }
@@ -0,0 +1,10 @@
1
+ import type { DefinitionGraph } from "./model.js";
2
+ import type { WorkLock } from "./work-model.js";
3
+ /** Public contracts can nest, but ordinary implementation children are not public
4
+ * merely because they sit inside an interface. Explicit exposure can bridge them. */
5
+ export declare function publicContractIds(graph: DefinitionGraph, target: string): Set<string>;
6
+ /** A subtree lock wins over every nested contract lock; inclusion never unlocks code. */
7
+ export declare function lockIndex(graph: DefinitionGraph, locks: WorkLock[]): Map<string, WorkLock>;
8
+ export declare function lockFor(graph: DefinitionGraph, locks: WorkLock[], id: string): WorkLock | undefined;
9
+ export declare function validateLocks(graph: DefinitionGraph, input: unknown, previous?: WorkLock[]): WorkLock[];
10
+ export declare function lockBrief(graph: DefinitionGraph, locks: WorkLock[]): string[];