@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.
- package/dist/annotations.d.ts +4 -0
- package/dist/compiler.js +161 -4
- package/dist/core.d.ts +1 -0
- package/dist/core.js +1 -0
- package/dist/declared-graph.js +2 -1
- package/dist/factory-graph.d.ts +4 -1
- package/dist/factory-graph.js +77 -6
- package/dist/factory-model.d.ts +14 -0
- package/dist/git-code.js +1 -1
- package/dist/interface-map.d.ts +15 -0
- package/dist/interface-map.js +125 -0
- package/dist/map-quality.d.ts +6 -0
- package/dist/map-quality.js +5 -0
- package/dist/model.d.ts +6 -2
- package/dist/product-map.d.ts +2 -0
- package/dist/product-map.js +33 -4
- package/dist/public-boundaries.d.ts +13 -0
- package/dist/public-boundaries.js +115 -0
- package/dist/repository-map.js +3 -1
- package/dist/scope.d.ts +2 -0
- package/dist/scope.js +77 -3
- package/dist/source-index.js +4 -0
- package/dist/source-review-git.js +3 -1
- package/dist/source-review.d.ts +3 -1
- package/dist/source-review.js +94 -14
- package/dist/work-check.d.ts +1 -0
- package/dist/work-check.js +6 -1
- package/dist/work-cli.js +29 -1
- package/dist/work-context.d.ts +2 -0
- package/dist/work-context.js +30 -4
- package/dist/work-lock-check.d.ts +12 -0
- package/dist/work-lock-check.js +339 -0
- package/dist/work-locks.d.ts +10 -0
- package/dist/work-locks.js +98 -0
- package/dist/work-model.d.ts +9 -0
- package/dist/work-model.js +50 -1
- package/package.json +1 -1
- package/src/annotations.ts +4 -0
- package/src/compiler.ts +190 -4
- package/src/core.ts +4 -0
- package/src/declared-graph.ts +2 -1
- package/src/factory-graph.ts +89 -5
- package/src/factory-model.ts +9 -0
- package/src/git-code.ts +1 -1
- package/src/interface-map.ts +166 -0
- package/src/map-quality.ts +5 -0
- package/src/model.ts +10 -3
- package/src/product-map.ts +51 -16
- package/src/public-boundaries.ts +143 -0
- package/src/repository-map.ts +3 -1
- package/src/scope.ts +92 -3
- package/src/source-index.ts +3 -0
- package/src/source-review-git.ts +3 -1
- package/src/source-review.ts +112 -13
- package/src/work-check.ts +7 -1
- package/src/work-cli.ts +35 -1
- package/src/work-context.ts +43 -3
- package/src/work-lock-check.ts +549 -0
- package/src/work-locks.ts +108 -0
- package/src/work-model.ts +67 -1
- package/toolkit/GUIDE.md +72 -23
- package/toolkit/SKILL.md +16 -5
- package/toolkit/build.json +1 -1
package/dist/work-context.js
CHANGED
|
@@ -1,14 +1,15 @@
|
|
|
1
|
-
import { mapFromArtifacts, repositoryMapConfiguration, parseMapConfiguration } from "./repository-map.js";
|
|
1
|
+
import { mapFromArtifacts, repositoryMapConfiguration, parseMapConfiguration, } from "./repository-map.js";
|
|
2
2
|
/** Local work contexts. Git refs are read without checkout; only explicit create adds a worktree. */
|
|
3
3
|
import { createHash, randomUUID } from "node:crypto";
|
|
4
4
|
import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, writeFileSync, rmSync, } from "node:fs";
|
|
5
5
|
import { join, resolve } from "node:path";
|
|
6
6
|
import { execFileSync } from "node:child_process";
|
|
7
7
|
import { readGit, resolveComparisonRef, comparisonMergeBase } from "./git-refs.js";
|
|
8
|
-
import { normalizeWorkScope, validateProposals, } from "./work-model.js";
|
|
8
|
+
import { normalizeWorkScope, validateProposals, proposalConnectionError, } from "./work-model.js";
|
|
9
9
|
import { checkedPath } from "./workspace-notes.js";
|
|
10
10
|
import { logicalMap } from "./map-model.js";
|
|
11
11
|
import { intentEvidence, workIntentStates } from "./work-intents.js";
|
|
12
|
+
import { validateLocks, lockBrief } from "./work-locks.js";
|
|
12
13
|
const uuid = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/;
|
|
13
14
|
const hash = (value) => createHash("sha256").update(value).digest("hex");
|
|
14
15
|
const identity = (path) => hash(path).slice(0, 20);
|
|
@@ -94,7 +95,16 @@ export function readWorkPlan(root, id, known) {
|
|
|
94
95
|
plan.scope.some((id) => typeof id !== "string") ||
|
|
95
96
|
(plan.excluded !== undefined &&
|
|
96
97
|
(!Array.isArray(plan.excluded) ||
|
|
97
|
-
plan.excluded.some((id) => typeof id !== "string")))
|
|
98
|
+
plan.excluded.some((id) => typeof id !== "string"))) ||
|
|
99
|
+
(plan.locks !== undefined &&
|
|
100
|
+
(!Array.isArray(plan.locks) ||
|
|
101
|
+
plan.locks.length > 500 ||
|
|
102
|
+
new Set(plan.locks.map((l) => l?.target)).size !== plan.locks.length ||
|
|
103
|
+
plan.locks.some((lock) => !lock ||
|
|
104
|
+
typeof lock.target !== "string" ||
|
|
105
|
+
!["subtree", "contract"].includes(lock.kind) ||
|
|
106
|
+
(lock.note !== undefined &&
|
|
107
|
+
(typeof lock.note !== "string" || lock.note.length > 4000))))))
|
|
98
108
|
throw Error("Invalid work plan.");
|
|
99
109
|
return { entry, plan, revision: hash(body) };
|
|
100
110
|
}
|
|
@@ -248,7 +258,9 @@ async function readFactoryMapUncached(root, ref) {
|
|
|
248
258
|
}
|
|
249
259
|
};
|
|
250
260
|
const configuration = text("fractory.config.json");
|
|
251
|
-
const graph = mapFromArtifacts(configuration
|
|
261
|
+
const graph = mapFromArtifacts(configuration
|
|
262
|
+
? parseMapConfiguration(configuration)
|
|
263
|
+
: repositoryMapConfiguration(root), text);
|
|
252
264
|
if (!graph)
|
|
253
265
|
return null;
|
|
254
266
|
if (graph.schema !== "fractal.definition.v1" ||
|
|
@@ -425,6 +437,9 @@ export function updateWorkPlan(root, id, graph, input, snapshot) {
|
|
|
425
437
|
throw Error("This plan changed. Reload it before saving.");
|
|
426
438
|
const plan = {
|
|
427
439
|
...current.plan,
|
|
440
|
+
...(input.locks !== undefined
|
|
441
|
+
? { locks: validateLocks(graph, input.locks, current.plan.locks) }
|
|
442
|
+
: {}),
|
|
428
443
|
proposals: input.proposals === undefined
|
|
429
444
|
? current.plan.proposals
|
|
430
445
|
: validateProposals(graph, input.proposals, current.plan.proposals),
|
|
@@ -555,9 +570,20 @@ export function workHandoff(context, graph) {
|
|
|
555
570
|
"",
|
|
556
571
|
]
|
|
557
572
|
: []),
|
|
573
|
+
...lockBrief(graph, plan?.locks || []),
|
|
558
574
|
"## Intended changes",
|
|
575
|
+
"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.",
|
|
559
576
|
...(plan?.proposals || []).map((p) => `- [${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}`),
|
|
560
577
|
"",
|
|
578
|
+
...(plan?.proposals.flatMap((proposal) => {
|
|
579
|
+
const issue = !proposal.implementation &&
|
|
580
|
+
proposalConnectionError(graph, plan, proposal);
|
|
581
|
+
return issue
|
|
582
|
+
? [
|
|
583
|
+
`Connection ${proposal.label || proposal.id} needs an interface target: ${issue}`,
|
|
584
|
+
]
|
|
585
|
+
: [];
|
|
586
|
+
}) || []),
|
|
561
587
|
"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.",
|
|
562
588
|
...(plan?.pullRequest ? [`Pull request: ${plan.pullRequest.url}`] : []),
|
|
563
589
|
`Check: fractory work check ${context.id} --root ${JSON.stringify(context.root)}`,
|
|
@@ -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[];
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
/** Public contracts can nest, but ordinary implementation children are not public
|
|
2
|
+
* merely because they sit inside an interface. Explicit exposure can bridge them. */
|
|
3
|
+
export function publicContractIds(graph, target) {
|
|
4
|
+
const publicKinds = new Set(["interface", "method", "operation"]);
|
|
5
|
+
const byId = new Map(graph.elements.map((n) => [n.id, n]));
|
|
6
|
+
const children = new Map();
|
|
7
|
+
const add = (parent, id) => {
|
|
8
|
+
if (!children.has(parent))
|
|
9
|
+
children.set(parent, []);
|
|
10
|
+
children.get(parent).push(id);
|
|
11
|
+
};
|
|
12
|
+
for (const n of graph.elements)
|
|
13
|
+
if (n.parent && publicKinds.has(n.kind))
|
|
14
|
+
add(n.parent, n.id);
|
|
15
|
+
for (const e of graph.connections)
|
|
16
|
+
if (e.relation === "exposes" &&
|
|
17
|
+
publicKinds.has(byId.get(e.target)?.kind || ""))
|
|
18
|
+
add(e.source, e.target);
|
|
19
|
+
const result = new Set();
|
|
20
|
+
const queue = [target];
|
|
21
|
+
while (queue.length) {
|
|
22
|
+
const id = queue.pop();
|
|
23
|
+
if (result.has(id))
|
|
24
|
+
continue;
|
|
25
|
+
result.add(id);
|
|
26
|
+
queue.push(...(children.get(id) || []));
|
|
27
|
+
}
|
|
28
|
+
return result;
|
|
29
|
+
}
|
|
30
|
+
/** A subtree lock wins over every nested contract lock; inclusion never unlocks code. */
|
|
31
|
+
export function lockIndex(graph, locks) {
|
|
32
|
+
const byId = new Map(graph.elements.map((n) => [n.id, n]));
|
|
33
|
+
const explicit = new Map(locks.map((l) => [l.target, l]));
|
|
34
|
+
const result = new Map();
|
|
35
|
+
for (const lock of locks)
|
|
36
|
+
if (lock.kind === "contract")
|
|
37
|
+
for (const id of publicContractIds(graph, lock.target))
|
|
38
|
+
result.set(id, lock);
|
|
39
|
+
for (const node of graph.elements) {
|
|
40
|
+
const seen = new Set();
|
|
41
|
+
let cursor = node.id;
|
|
42
|
+
let effective = explicit.get(node.id) || result.get(node.id);
|
|
43
|
+
while (cursor && !seen.has(cursor)) {
|
|
44
|
+
seen.add(cursor);
|
|
45
|
+
const lock = explicit.get(cursor);
|
|
46
|
+
if (lock?.kind === "subtree")
|
|
47
|
+
effective = lock;
|
|
48
|
+
cursor = byId.get(cursor)?.parent;
|
|
49
|
+
}
|
|
50
|
+
if (effective)
|
|
51
|
+
result.set(node.id, effective);
|
|
52
|
+
}
|
|
53
|
+
return result;
|
|
54
|
+
}
|
|
55
|
+
export function lockFor(graph, locks, id) {
|
|
56
|
+
return lockIndex(graph, locks).get(id);
|
|
57
|
+
}
|
|
58
|
+
export function validateLocks(graph, input, previous = []) {
|
|
59
|
+
if (!Array.isArray(input) || input.length > 500)
|
|
60
|
+
throw Error("Choose up to 500 block or interface locks.");
|
|
61
|
+
const targets = new Set();
|
|
62
|
+
return input.map((value) => {
|
|
63
|
+
if (!value || typeof value !== "object")
|
|
64
|
+
throw Error("Invalid lock.");
|
|
65
|
+
const { target, kind, note } = value;
|
|
66
|
+
if (typeof target !== "string" || !["subtree", "contract"].includes(kind))
|
|
67
|
+
throw Error("Choose a block subtree or interface contract to lock.");
|
|
68
|
+
if (targets.has(target))
|
|
69
|
+
throw Error("A target can only have one lock.");
|
|
70
|
+
targets.add(target);
|
|
71
|
+
const node = graph.elements.find((n) => n.id === target);
|
|
72
|
+
// Deleted targets remain locked and reviewable; adding an unknown target is rejected.
|
|
73
|
+
if (!node && !previous.some((l) => l.target === target && l.kind === kind))
|
|
74
|
+
throw Error(`Unknown lock target: ${target}`);
|
|
75
|
+
if (node &&
|
|
76
|
+
(node.provenance === "proposed" ||
|
|
77
|
+
(node.kind === "interface" ? kind !== "contract" : kind !== "subtree")))
|
|
78
|
+
throw Error("Lock an interface's public contract or a real block's whole subtree.");
|
|
79
|
+
if (note !== undefined && (typeof note !== "string" || note.length > 4000))
|
|
80
|
+
throw Error("Keep the lock reason below 4,000 characters.");
|
|
81
|
+
return { target, kind, ...(note?.trim() ? { note: note.trim() } : {}) };
|
|
82
|
+
});
|
|
83
|
+
}
|
|
84
|
+
export function lockBrief(graph, locks) {
|
|
85
|
+
if (!locks.length)
|
|
86
|
+
return [];
|
|
87
|
+
return [
|
|
88
|
+
"## Locked boundaries",
|
|
89
|
+
"Locks take precedence over the editable scope and proposed changes. Do not remove or weaken a lock to make a check pass.",
|
|
90
|
+
...locks.map((lock) => {
|
|
91
|
+
const node = graph.elements.find((n) => n.id === lock.target);
|
|
92
|
+
return `- ${node?.label || lock.target} (${lock.target}): ${lock.kind === "contract"
|
|
93
|
+
? "Freeze the public contract exactly: names, routes, signatures, inputs, outputs and explicitly exposed nested contracts. Internal implementation may change; this is not permission to change a signature even compatibly."
|
|
94
|
+
: "Freeze this block and its entire subtree, including code, interfaces and nested blocks."}${lock.note ? ` Reason: ${lock.note}` : ""}`;
|
|
95
|
+
}),
|
|
96
|
+
"",
|
|
97
|
+
];
|
|
98
|
+
}
|
package/dist/work-model.d.ts
CHANGED
|
@@ -29,6 +29,12 @@ export interface WorkIntentState {
|
|
|
29
29
|
implementation?: string;
|
|
30
30
|
reason?: string;
|
|
31
31
|
}
|
|
32
|
+
/** Constraints are independent of editable scope and temporary canvas selection. */
|
|
33
|
+
export interface WorkLock {
|
|
34
|
+
target: string;
|
|
35
|
+
kind: "subtree" | "contract";
|
|
36
|
+
note?: string;
|
|
37
|
+
}
|
|
32
38
|
export interface WorkPlan {
|
|
33
39
|
schema: "fractory.work.v1";
|
|
34
40
|
id: string;
|
|
@@ -40,6 +46,7 @@ export interface WorkPlan {
|
|
|
40
46
|
scope: string[];
|
|
41
47
|
/** Explicit subtree exceptions. The nearest include/exclude rule wins. */
|
|
42
48
|
excluded?: string[];
|
|
49
|
+
locks?: WorkLock[];
|
|
43
50
|
proposals: WorkProposal[];
|
|
44
51
|
bootstrapRevision?: string;
|
|
45
52
|
pullRequest?: {
|
|
@@ -108,3 +115,5 @@ export declare function compactScope(graph: DefinitionGraph, scope: string[]): s
|
|
|
108
115
|
export declare function validateProposals(graph: DefinitionGraph, proposals: unknown, previous?: WorkProposal[]): WorkProposal[];
|
|
109
116
|
/** Display composition only. Proposed elements never enter the compiler's output. */
|
|
110
117
|
export declare function workDisplayGraph(graph: DefinitionGraph, plan?: WorkPlan, states?: Record<string, WorkIntentState>): DefinitionGraph;
|
|
118
|
+
/** Legacy requests remain readable as intentions, not as invalid callable wires. */
|
|
119
|
+
export declare function proposalConnectionError(graph: DefinitionGraph, plan: WorkPlan | undefined, proposal: WorkProposal): string | undefined;
|
package/dist/work-model.js
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { publicConnectionError, boundaryViolations } from "./public-boundaries.js";
|
|
1
2
|
export function workTargetLabel(graph, proposals, id) {
|
|
2
3
|
const block = graph.elements.find((node) => node.id === id) ||
|
|
3
4
|
proposals.find((p) => p.kind === "block" && p.id === id);
|
|
@@ -200,6 +201,38 @@ export function validateProposals(graph, proposals, previous = []) {
|
|
|
200
201
|
cursor = parents.get(cursor);
|
|
201
202
|
}
|
|
202
203
|
}
|
|
204
|
+
const candidate = {
|
|
205
|
+
...graph,
|
|
206
|
+
elements: [
|
|
207
|
+
...graph.elements,
|
|
208
|
+
...result
|
|
209
|
+
.filter((item) => item.kind === "block")
|
|
210
|
+
.map((item) => ({
|
|
211
|
+
id: item.id,
|
|
212
|
+
parent: item.parent,
|
|
213
|
+
kind: item.blockKind || "block",
|
|
214
|
+
label: item.label,
|
|
215
|
+
provenance: "proposed",
|
|
216
|
+
})),
|
|
217
|
+
],
|
|
218
|
+
};
|
|
219
|
+
for (const item of result.filter((item) => item.kind === "connection")) {
|
|
220
|
+
// An unchanged historical request remains editable as a record. New links
|
|
221
|
+
// and endpoint edits must obey the same public contract as compiled maps.
|
|
222
|
+
const old = previous.find((entry) => entry.id === item.id && entry.kind === "connection");
|
|
223
|
+
if (old?.source === item.source && old?.target === item.target)
|
|
224
|
+
continue;
|
|
225
|
+
const error = publicConnectionError(candidate, {
|
|
226
|
+
id: item.id,
|
|
227
|
+
source: item.source,
|
|
228
|
+
target: item.target,
|
|
229
|
+
relation: "calls",
|
|
230
|
+
label: item.label,
|
|
231
|
+
provenance: "proposed",
|
|
232
|
+
});
|
|
233
|
+
if (error)
|
|
234
|
+
throw Error(error);
|
|
235
|
+
}
|
|
203
236
|
return result;
|
|
204
237
|
}
|
|
205
238
|
/** Display composition only. Proposed elements never enter the compiler's output. */
|
|
@@ -226,7 +259,7 @@ export function workDisplayGraph(graph, plan, states) {
|
|
|
226
259
|
const visual = proposals.filter((p) => p.kind !== "annotation" && needed.has(p.id));
|
|
227
260
|
if (!visual.length)
|
|
228
261
|
return graph;
|
|
229
|
-
|
|
262
|
+
const scene = {
|
|
230
263
|
...graph,
|
|
231
264
|
revision: `${graph.revision}:plan:${JSON.stringify(visual)}`,
|
|
232
265
|
elements: [
|
|
@@ -258,4 +291,20 @@ export function workDisplayGraph(graph, plan, states) {
|
|
|
258
291
|
visual.some((p) => p.kind === "block" && p.id === id))),
|
|
259
292
|
],
|
|
260
293
|
};
|
|
294
|
+
const invalid = new Set(boundaryViolations(scene).map((issue) => issue.connection));
|
|
295
|
+
scene.connections = scene.connections.filter((edge) => edge.provenance !== "proposed" || !invalid.has(edge.id));
|
|
296
|
+
return scene;
|
|
297
|
+
}
|
|
298
|
+
/** Legacy requests remain readable as intentions, not as invalid callable wires. */
|
|
299
|
+
export function proposalConnectionError(graph, plan, proposal) {
|
|
300
|
+
if (proposal.kind !== "connection")
|
|
301
|
+
return undefined;
|
|
302
|
+
return publicConnectionError(workDisplayGraph(graph, plan), {
|
|
303
|
+
id: proposal.id,
|
|
304
|
+
source: proposal.source,
|
|
305
|
+
target: proposal.target,
|
|
306
|
+
label: proposal.label,
|
|
307
|
+
relation: "calls",
|
|
308
|
+
provenance: "proposed",
|
|
309
|
+
});
|
|
261
310
|
}
|
package/package.json
CHANGED
package/src/annotations.ts
CHANGED
|
@@ -17,6 +17,8 @@ export interface RuntimeContract {
|
|
|
17
17
|
result?: { parse(value: unknown): unknown };
|
|
18
18
|
}
|
|
19
19
|
export interface InterfaceOptions extends Attachments {
|
|
20
|
+
/** Explicit publication through enclosing black boxes. Does not change runtime access. */
|
|
21
|
+
exposedBy?: readonly (() => object)[];
|
|
20
22
|
/** Optional stable identity when adopting an existing mapped interface. */
|
|
21
23
|
id?: string;
|
|
22
24
|
label?: string;
|
|
@@ -31,6 +33,8 @@ export interface InterfaceRef {
|
|
|
31
33
|
readonly options: InterfaceOptions;
|
|
32
34
|
}
|
|
33
35
|
export interface BlockOptions extends Attachments {
|
|
36
|
+
/** Publish this block's public interfaces through these enclosing blocks. */
|
|
37
|
+
exposedBy?: readonly (() => object)[];
|
|
34
38
|
/** Display names only; shapes still come from actual parameters and props. */
|
|
35
39
|
inputLabel?: string;
|
|
36
40
|
eventLabel?: string;
|