@granular-software/fractory 0.1.24 → 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 (63) hide show
  1. package/dist/annotations.d.ts +4 -0
  2. package/dist/compiler.js +161 -4
  3. package/dist/core.d.ts +1 -0
  4. package/dist/core.js +1 -0
  5. package/dist/declared-graph.js +2 -1
  6. package/dist/factory-graph.d.ts +4 -1
  7. package/dist/factory-graph.js +77 -6
  8. package/dist/factory-model.d.ts +14 -0
  9. package/dist/git-code.js +1 -1
  10. package/dist/interface-map.d.ts +15 -0
  11. package/dist/interface-map.js +125 -0
  12. package/dist/map-quality.d.ts +6 -0
  13. package/dist/map-quality.js +5 -0
  14. package/dist/model.d.ts +6 -2
  15. package/dist/product-map.d.ts +2 -0
  16. package/dist/product-map.js +33 -4
  17. package/dist/public-boundaries.d.ts +13 -0
  18. package/dist/public-boundaries.js +115 -0
  19. package/dist/repository-map.js +3 -1
  20. package/dist/scope.d.ts +2 -0
  21. package/dist/scope.js +77 -3
  22. package/dist/source-index.js +4 -0
  23. package/dist/source-review-git.js +3 -1
  24. package/dist/source-review.d.ts +3 -1
  25. package/dist/source-review.js +94 -14
  26. package/dist/work-check.d.ts +1 -0
  27. package/dist/work-check.js +6 -1
  28. package/dist/work-cli.js +29 -1
  29. package/dist/work-context.d.ts +2 -0
  30. package/dist/work-context.js +30 -4
  31. package/dist/work-lock-check.d.ts +12 -0
  32. package/dist/work-lock-check.js +339 -0
  33. package/dist/work-locks.d.ts +10 -0
  34. package/dist/work-locks.js +98 -0
  35. package/dist/work-model.d.ts +9 -0
  36. package/dist/work-model.js +50 -1
  37. package/package.json +1 -1
  38. package/src/annotations.ts +4 -0
  39. package/src/compiler.ts +190 -4
  40. package/src/core.ts +4 -0
  41. package/src/declared-graph.ts +2 -1
  42. package/src/factory-graph.ts +89 -5
  43. package/src/factory-model.ts +9 -0
  44. package/src/git-code.ts +1 -1
  45. package/src/interface-map.ts +166 -0
  46. package/src/map-quality.ts +5 -0
  47. package/src/model.ts +10 -3
  48. package/src/product-map.ts +51 -16
  49. package/src/public-boundaries.ts +143 -0
  50. package/src/repository-map.ts +3 -1
  51. package/src/scope.ts +92 -3
  52. package/src/source-index.ts +3 -0
  53. package/src/source-review-git.ts +3 -1
  54. package/src/source-review.ts +112 -13
  55. package/src/work-check.ts +7 -1
  56. package/src/work-cli.ts +35 -1
  57. package/src/work-context.ts +43 -3
  58. package/src/work-lock-check.ts +549 -0
  59. package/src/work-locks.ts +108 -0
  60. package/src/work-model.ts +67 -1
  61. package/toolkit/GUIDE.md +72 -23
  62. package/toolkit/SKILL.md +16 -5
  63. package/toolkit/build.json +1 -1
package/src/work-cli.ts CHANGED
@@ -14,13 +14,14 @@ import {
14
14
  workHandoff,
15
15
  updateWorkIntent,
16
16
  } from "./work-context";
17
+ import { lockBrief } from "./work-locks";
17
18
  import { workIntentStates } from "./work-intents";
18
19
  import { readGit } from "./git-refs";
19
20
  import { checkWorkScope } from "./work-check";
20
21
 
21
22
  export async function runWork(args: string[]) {
22
23
  if (args.includes("--help"))
23
- 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.`;
24
+ 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 lock ID --block BLOCK_ID --revision REVISION [--note REASON]\nfractory work unlock ID --block BLOCK_ID --revision REVISION\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.`;
24
25
  const option = (name: string) => {
25
26
  const i = args.indexOf(name);
26
27
  if (i < 0) return undefined;
@@ -118,6 +119,29 @@ export async function runWork(args: string[]) {
118
119
  return JSON.stringify({ ...work, intents: intents() }, null, 2);
119
120
  }
120
121
  if (action === "handoff") return workHandoff(work, graph);
122
+ if (action === "lock" || action === "unlock") {
123
+ if (!work.plan || !option("--revision") || !option("--block"))
124
+ throw Error("Use --block ID and --revision from work show.");
125
+ const target = option("--block")!;
126
+ const node = graph.elements.find((n) => n.id === target);
127
+ if (action === "lock" && !node)
128
+ throw Error("Choose a mapped block or interface.");
129
+ const locks = (work.plan.locks || []).filter((l) => l.target !== target);
130
+ if (action === "lock")
131
+ locks.push({
132
+ target,
133
+ kind: node!.kind === "interface" ? "contract" : "subtree",
134
+ ...(option("--note") ? { note: option("--note") } : {}),
135
+ });
136
+ return JSON.stringify(
137
+ updateWorkPlan(root, id, graph, {
138
+ revision: option("--revision")!,
139
+ locks,
140
+ }),
141
+ null,
142
+ 2,
143
+ );
144
+ }
121
145
  if (action === "open") {
122
146
  const url = workDeepLink(root, id);
123
147
  execFileSync("open", [url], { stdio: "ignore", timeout: 5000 });
@@ -137,6 +161,15 @@ export async function runWork(args: string[]) {
137
161
  `Scope: ${(work.plan?.scope || []).map((id) => labels.get(id) || id).join(", ")}`,
138
162
  "",
139
163
  `Scope check: ${report.pass ? "passed" : `${report.outside} outside; ${report.uncertain} shared or unmapped`}`,
164
+ ...lockBrief(graph, work.plan?.locks || []),
165
+ ...report.locks.flatMap((l) =>
166
+ l.status === "unchanged"
167
+ ? []
168
+ : [
169
+ `Lock ${l.target}: ${l.status}`,
170
+ ...l.issues.map((i) => `- ${i.file || "Map"}: ${i.message}`),
171
+ ],
172
+ ),
140
173
  "",
141
174
  "| Change | Files |",
142
175
  "| --- | ---: |",
@@ -180,6 +213,7 @@ export async function runWork(args: string[]) {
180
213
  proposals: value.proposals || work.plan.proposals,
181
214
  scope: value.scope,
182
215
  excluded: value.excluded,
216
+ locks: value.locks,
183
217
  ...(action === "pr"
184
218
  ? {
185
219
  pullRequest: {
@@ -1,4 +1,8 @@
1
- import { mapFromArtifacts, repositoryMapConfiguration, parseMapConfiguration } from "./repository-map";
1
+ import {
2
+ mapFromArtifacts,
3
+ repositoryMapConfiguration,
4
+ parseMapConfiguration,
5
+ } from "./repository-map";
2
6
  /** Local work contexts. Git refs are read without checkout; only explicit create adds a worktree. */
3
7
  import { createHash, randomUUID } from "node:crypto";
4
8
  import {
@@ -17,6 +21,7 @@ import { readGit, resolveComparisonRef, comparisonMergeBase } from "./git-refs";
17
21
  import {
18
22
  normalizeWorkScope,
19
23
  validateProposals,
24
+ proposalConnectionError,
20
25
  type WorkContext,
21
26
  type WorkPlan,
22
27
  type WorkTarget,
@@ -25,6 +30,8 @@ import type { DefinitionGraph } from "./model";
25
30
  import { checkedPath } from "./workspace-notes";
26
31
  import { logicalMap } from "./map-model";
27
32
  import { intentEvidence, workIntentStates } from "./work-intents";
33
+ import { validateLocks, lockBrief } from "./work-locks";
34
+ import type { WorkLock } from "./work-model";
28
35
 
29
36
  const uuid = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/;
30
37
  const hash = (value: string) =>
@@ -142,7 +149,19 @@ export function readWorkPlan(
142
149
  plan.scope.some((id) => typeof id !== "string") ||
143
150
  (plan.excluded !== undefined &&
144
151
  (!Array.isArray(plan.excluded) ||
145
- plan.excluded.some((id) => typeof id !== "string")))
152
+ plan.excluded.some((id) => typeof id !== "string"))) ||
153
+ (plan.locks !== undefined &&
154
+ (!Array.isArray(plan.locks) ||
155
+ plan.locks.length > 500 ||
156
+ new Set(plan.locks.map((l) => l?.target)).size !== plan.locks.length ||
157
+ plan.locks.some(
158
+ (lock) =>
159
+ !lock ||
160
+ typeof lock.target !== "string" ||
161
+ !["subtree", "contract"].includes(lock.kind) ||
162
+ (lock.note !== undefined &&
163
+ (typeof lock.note !== "string" || lock.note.length > 4000)),
164
+ )))
146
165
  )
147
166
  throw Error("Invalid work plan.");
148
167
  return { entry, plan, revision: hash(body) };
@@ -303,7 +322,12 @@ async function readFactoryMapUncached(
303
322
  }
304
323
  };
305
324
  const configuration = text("fractory.config.json");
306
- const graph = mapFromArtifacts(configuration ? parseMapConfiguration(configuration) : repositoryMapConfiguration(root), text);
325
+ const graph = mapFromArtifacts(
326
+ configuration
327
+ ? parseMapConfiguration(configuration)
328
+ : repositoryMapConfiguration(root),
329
+ text,
330
+ );
307
331
  if (!graph) return null;
308
332
  if (
309
333
  graph.schema !== "fractal.definition.v1" ||
@@ -516,6 +540,7 @@ export function updateWorkPlan(
516
540
  proposals?: unknown;
517
541
  scope?: string[];
518
542
  excluded?: string[];
543
+ locks?: WorkLock[];
519
544
  pullRequest?: WorkPlan["pullRequest"];
520
545
  },
521
546
  snapshot?: WorkContext,
@@ -525,6 +550,9 @@ export function updateWorkPlan(
525
550
  throw Error("This plan changed. Reload it before saving.");
526
551
  const plan: WorkPlan = {
527
552
  ...current.plan,
553
+ ...(input.locks !== undefined
554
+ ? { locks: validateLocks(graph, input.locks, current.plan.locks) }
555
+ : {}),
528
556
  proposals:
529
557
  input.proposals === undefined
530
558
  ? current.plan.proposals
@@ -697,12 +725,24 @@ export function workHandoff(context: WorkContext, graph: DefinitionGraph) {
697
725
  "",
698
726
  ]
699
727
  : []),
728
+ ...lockBrief(graph, plan?.locks || []),
700
729
  "## Intended changes",
730
+ "Connections enter public interfaces. A plain box or internal method is not a valid external destination; preserve the request while choosing its real public contract.",
701
731
  ...(plan?.proposals || []).map(
702
732
  (p) =>
703
733
  `- [${states[p.id]?.status === "changed" ? "needs recheck" : states[p.id]?.status || "planned"}] ${p.kind === "annotation" ? "comment" : p.kind}: ${p.label || labels.get(p.target || "") || p.target} [${p.id}]${p.resolved ? " [resolved]" : ""}${p.kind === "annotation" && p.target ? `; attached to ${labels.get(p.target) || p.target} (${p.target})` : ""}${p.parent ? `; inside ${labels.get(p.parent) || p.parent}` : ""}${p.source ? `; ${labels.get(p.source) || p.source} → ${labels.get(p.target!) || p.target}` : ""}${p.change ? `; ${p.change}` : ""}${p.implementation ? `; implementation: ${labels.get(p.implementation) || p.implementation} (${p.implementation})` : ""}\n ${p.note}`,
704
734
  ),
705
735
  "",
736
+ ...(plan?.proposals.flatMap((proposal) => {
737
+ const issue =
738
+ !proposal.implementation &&
739
+ proposalConnectionError(graph, plan, proposal);
740
+ return issue
741
+ ? [
742
+ `Connection ${proposal.label || proposal.id} needs an interface target: ${issue}`,
743
+ ]
744
+ : [];
745
+ }) || []),
706
746
  "Continue planned items and items needing recheck. Done and dropped items remain recorded; do not implement them again without reopening them. Done is an explicit confirmation with a source fingerprint, not a test result.",
707
747
  ...(plan?.pullRequest ? [`Pull request: ${plan.pullRequest.url}`] : []),
708
748
  `Check: fractory work check ${context.id} --root ${JSON.stringify(context.root)}`,