@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/src/compiler.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
/** Build-time only: collect declarations and types without importing application code. */
|
|
2
2
|
import ts from "typescript";
|
|
3
|
+
import { factoryGraph as checkedFactoryGraph } from "./factory-graph";
|
|
3
4
|
import { createHash } from "node:crypto";
|
|
4
5
|
import { resolve, relative, dirname, isAbsolute, join } from "node:path";
|
|
5
6
|
import { readdirSync, readFileSync, existsSync } from "node:fs";
|
|
@@ -513,6 +514,77 @@ export function compileFactory(options: {
|
|
|
513
514
|
);
|
|
514
515
|
if (parent) block.parent = parent.id;
|
|
515
516
|
}
|
|
517
|
+
const exposures = (config: ts.Node | undefined, node: ts.Node) => {
|
|
518
|
+
const value = property(config, "exposedBy");
|
|
519
|
+
if (!value) return undefined;
|
|
520
|
+
if (!ts.isArrayLiteralExpression(value)) {
|
|
521
|
+
problem(node, "exposedBy must reference enclosing annotated blocks");
|
|
522
|
+
return undefined;
|
|
523
|
+
}
|
|
524
|
+
return value.elements.flatMap((entry) => {
|
|
525
|
+
const declaration = resolvedNode(entry),
|
|
526
|
+
block = declaration && blocks.get(declaration);
|
|
527
|
+
if (!block) {
|
|
528
|
+
problem(
|
|
529
|
+
node,
|
|
530
|
+
"exposedBy must reference an annotated block/process declaration",
|
|
531
|
+
);
|
|
532
|
+
return [];
|
|
533
|
+
}
|
|
534
|
+
return [block.id];
|
|
535
|
+
});
|
|
536
|
+
};
|
|
537
|
+
for (const item of pending.filter(
|
|
538
|
+
(entry) => entry.kind === "Block" || entry.kind === "Process",
|
|
539
|
+
)) {
|
|
540
|
+
const block = blocks.get(item.node);
|
|
541
|
+
if (block) block.exposedBy = exposures(configOf(item.call), item.node);
|
|
542
|
+
if (!block || !ts.isClassDeclaration(item.node)) continue;
|
|
543
|
+
const ctor = item.node.members.find(ts.isConstructorDeclaration);
|
|
544
|
+
if (
|
|
545
|
+
ctor &&
|
|
546
|
+
ts
|
|
547
|
+
.getModifiers(ctor)
|
|
548
|
+
?.some((modifier) =>
|
|
549
|
+
[
|
|
550
|
+
ts.SyntaxKind.PrivateKeyword,
|
|
551
|
+
ts.SyntaxKind.ProtectedKeyword,
|
|
552
|
+
].includes(modifier.kind),
|
|
553
|
+
)
|
|
554
|
+
)
|
|
555
|
+
continue;
|
|
556
|
+
model.interfaces.push({
|
|
557
|
+
id: `${block.id}::construct`,
|
|
558
|
+
blockId: block.id,
|
|
559
|
+
name: "construct",
|
|
560
|
+
label: `Create ${block.label}`,
|
|
561
|
+
source: source(ctor || item.node),
|
|
562
|
+
attachments: {
|
|
563
|
+
docs: [],
|
|
564
|
+
tests: [],
|
|
565
|
+
description: `Public constructor of ${block.label}.`,
|
|
566
|
+
},
|
|
567
|
+
methods: [],
|
|
568
|
+
constructorContract: {
|
|
569
|
+
signature: ctor
|
|
570
|
+
? ctor
|
|
571
|
+
.getText()
|
|
572
|
+
.slice(
|
|
573
|
+
0,
|
|
574
|
+
ctor.body ? ctor.body.getStart() - ctor.getStart() : undefined,
|
|
575
|
+
)
|
|
576
|
+
.trim()
|
|
577
|
+
: `new ${item.node.name?.text || block.label}()`,
|
|
578
|
+
args: (ctor?.parameters || []).map((parameter) => ({
|
|
579
|
+
name: parameter.name.getText(),
|
|
580
|
+
type: parameter.type?.getText() || "unknown",
|
|
581
|
+
optional: !!parameter.questionToken || !!parameter.initializer,
|
|
582
|
+
rest: !!parameter.dotDotDotToken,
|
|
583
|
+
})),
|
|
584
|
+
result: item.node.name?.text || block.label,
|
|
585
|
+
},
|
|
586
|
+
});
|
|
587
|
+
}
|
|
516
588
|
for (const { node, call } of pending.filter((p) => p.kind === "Interface")) {
|
|
517
589
|
const config =
|
|
518
590
|
call.arguments[0] && ts.isStringLiteral(call.arguments[0])
|
|
@@ -568,11 +640,13 @@ export function compileFactory(options: {
|
|
|
568
640
|
source: source(node),
|
|
569
641
|
attachments: attachments(config, node),
|
|
570
642
|
methods: [],
|
|
643
|
+
exposedBy: exposures(config, node),
|
|
571
644
|
});
|
|
572
645
|
}
|
|
573
646
|
for (const { node, call, kind } of pending.filter(
|
|
574
647
|
(p) =>
|
|
575
648
|
p.kind === "Method" ||
|
|
649
|
+
(p.kind === "Block" && !!callable(p.node)) ||
|
|
576
650
|
(p.kind === "Process" &&
|
|
577
651
|
!pending.some(
|
|
578
652
|
(other) => other.node === p.node && other.kind === "Method",
|
|
@@ -585,19 +659,32 @@ export function compileFactory(options: {
|
|
|
585
659
|
}
|
|
586
660
|
const apiNode =
|
|
587
661
|
kind === "Method" ? resolvedNode(call.arguments[0]) : undefined;
|
|
588
|
-
|
|
662
|
+
let interfaceId = apiNode && apis.get(apiNode);
|
|
589
663
|
const api = model.interfaces.find((api) => api.id === interfaceId);
|
|
590
664
|
if (kind === "Method" && !api) {
|
|
591
665
|
problem(node, "@Method must reference a declared interface");
|
|
592
666
|
continue;
|
|
593
667
|
}
|
|
594
668
|
const block =
|
|
595
|
-
kind === "Process"
|
|
669
|
+
kind === "Process" || kind === "Block"
|
|
596
670
|
? blocks.get(node)
|
|
597
671
|
: blocks.get(node) ||
|
|
598
672
|
model.blocks.find((block) => block.id === api?.blockId) ||
|
|
599
673
|
(api ? { id: api.blockId } : undefined);
|
|
600
674
|
if (!block) continue;
|
|
675
|
+
if (kind === "Block") {
|
|
676
|
+
interfaceId = `${block.id}::entry`;
|
|
677
|
+
model.interfaces.push({
|
|
678
|
+
id: interfaceId,
|
|
679
|
+
blockId: block.id,
|
|
680
|
+
name: "entry",
|
|
681
|
+
label: blocks.get(node)?.label || block.id,
|
|
682
|
+
source: source(node),
|
|
683
|
+
attachments: attachments(configOf(call), node),
|
|
684
|
+
methods: [],
|
|
685
|
+
entrypoint: true,
|
|
686
|
+
});
|
|
687
|
+
}
|
|
601
688
|
let parent = node.parent;
|
|
602
689
|
while (
|
|
603
690
|
parent &&
|
|
@@ -758,8 +845,64 @@ export function compileFactory(options: {
|
|
|
758
845
|
) &&
|
|
759
846
|
!(member.name && ts.isPrivateIdentifier(member.name)) &&
|
|
760
847
|
!owners.has(member)
|
|
761
|
-
)
|
|
762
|
-
|
|
848
|
+
) {
|
|
849
|
+
// TypeScript public members are real callable contracts too. Preserve
|
|
850
|
+
// their exact signatures instead of representing them as calls to the
|
|
851
|
+
// owning box (or incorrectly treating them as constructor calls).
|
|
852
|
+
const name = `${ts.isGetAccessorDeclaration(member) ? "get:" : ts.isSetAccessorDeclaration(member) ? "set:" : ""}${member.name.getText()}`,
|
|
853
|
+
id = `${block.id}::public`;
|
|
854
|
+
const signature = checker.getSignatureFromDeclaration(member);
|
|
855
|
+
const method: FactoryMethod = {
|
|
856
|
+
id: `${id}#${name}`,
|
|
857
|
+
blockId: block.id,
|
|
858
|
+
interfaceId: id,
|
|
859
|
+
name,
|
|
860
|
+
source: source(member),
|
|
861
|
+
signature: signature
|
|
862
|
+
? checker.signatureToString(
|
|
863
|
+
signature,
|
|
864
|
+
member,
|
|
865
|
+
ts.TypeFormatFlags.NoTruncation,
|
|
866
|
+
)
|
|
867
|
+
: member.getText().split("{")[0],
|
|
868
|
+
contract: {
|
|
869
|
+
args: member.parameters.map((parameter) => ({
|
|
870
|
+
name: parameter.name.getText(),
|
|
871
|
+
type: checker.typeToString(
|
|
872
|
+
checker.getTypeAtLocation(parameter),
|
|
873
|
+
parameter,
|
|
874
|
+
ts.TypeFormatFlags.NoTruncation,
|
|
875
|
+
),
|
|
876
|
+
optional: !!parameter.questionToken || !!parameter.initializer,
|
|
877
|
+
rest: !!parameter.dotDotDotToken,
|
|
878
|
+
})),
|
|
879
|
+
result: signature
|
|
880
|
+
? checker.typeToString(
|
|
881
|
+
checker.getReturnTypeOfSignature(signature),
|
|
882
|
+
member,
|
|
883
|
+
ts.TypeFormatFlags.NoTruncation,
|
|
884
|
+
)
|
|
885
|
+
: "unknown",
|
|
886
|
+
typeSources: typeSources(member),
|
|
887
|
+
runtimeValidation: false,
|
|
888
|
+
},
|
|
889
|
+
attachments: attachments(undefined, member),
|
|
890
|
+
};
|
|
891
|
+
const existing = model.interfaces.find((api) => api.id === id);
|
|
892
|
+
if (existing) existing.methods.push(method.id);
|
|
893
|
+
else
|
|
894
|
+
model.interfaces.push({
|
|
895
|
+
id,
|
|
896
|
+
blockId: block.id,
|
|
897
|
+
name: "public",
|
|
898
|
+
label: `${block.label} public API`,
|
|
899
|
+
source: source(member),
|
|
900
|
+
attachments: method.attachments,
|
|
901
|
+
methods: [method.id],
|
|
902
|
+
});
|
|
903
|
+
model.methods.push(method);
|
|
904
|
+
owners.set(member, method.id);
|
|
905
|
+
}
|
|
763
906
|
}
|
|
764
907
|
const bodyOf = (node: ts.Node | undefined): ts.Node | undefined => {
|
|
765
908
|
if (!node) return;
|
|
@@ -1087,6 +1230,38 @@ export function compileFactory(options: {
|
|
|
1087
1230
|
relation: "calls" | "delegates" = "calls",
|
|
1088
1231
|
) => {
|
|
1089
1232
|
if (!target) return;
|
|
1233
|
+
if (
|
|
1234
|
+
ts.isMethodDeclaration(target) &&
|
|
1235
|
+
target.modifiers?.some((modifier) =>
|
|
1236
|
+
[
|
|
1237
|
+
ts.SyntaxKind.PrivateKeyword,
|
|
1238
|
+
ts.SyntaxKind.ProtectedKeyword,
|
|
1239
|
+
].includes(modifier.kind),
|
|
1240
|
+
)
|
|
1241
|
+
) {
|
|
1242
|
+
const receiver = nearestBlock(target);
|
|
1243
|
+
// Access belongs to the lexical call site. A returned closure can
|
|
1244
|
+
// legally call its class's private helper even when an outside entry
|
|
1245
|
+
// caused us to traverse it; that caller does not own the closure body.
|
|
1246
|
+
let sender =
|
|
1247
|
+
nearestBlock(at)?.id ||
|
|
1248
|
+
model.methods.find((method) => method.id === owner)?.blockId ||
|
|
1249
|
+
model.interfaces.find((api) => api.id === owner)?.blockId ||
|
|
1250
|
+
owner;
|
|
1251
|
+
const seen = new Set<string>();
|
|
1252
|
+
while (receiver && sender !== receiver.id && !seen.has(sender)) {
|
|
1253
|
+
seen.add(sender);
|
|
1254
|
+
sender =
|
|
1255
|
+
model.blocks.find((block) => block.id === sender)?.parent || "";
|
|
1256
|
+
}
|
|
1257
|
+
if (receiver && sender !== receiver.id) {
|
|
1258
|
+
problem(
|
|
1259
|
+
at,
|
|
1260
|
+
`Private member ${target.name.getText()} cannot receive calls from outside ${receiver.label}; use its public interface.`,
|
|
1261
|
+
);
|
|
1262
|
+
return;
|
|
1263
|
+
}
|
|
1264
|
+
}
|
|
1090
1265
|
const boundVia = [...via, ...(injectionEvidence.get(at) || [])];
|
|
1091
1266
|
const boundary = owners.get(target);
|
|
1092
1267
|
if (boundary) {
|
|
@@ -1320,6 +1495,17 @@ export function compileFactory(options: {
|
|
|
1320
1495
|
0,
|
|
1321
1496
|
16,
|
|
1322
1497
|
);
|
|
1498
|
+
if (!model.diagnostics.length) {
|
|
1499
|
+
try {
|
|
1500
|
+
checkedFactoryGraph(model);
|
|
1501
|
+
} catch (error) {
|
|
1502
|
+
model.diagnostics.push({
|
|
1503
|
+
file: "<public interfaces>",
|
|
1504
|
+
line: 1,
|
|
1505
|
+
message: error instanceof Error ? error.message : String(error),
|
|
1506
|
+
});
|
|
1507
|
+
}
|
|
1508
|
+
}
|
|
1323
1509
|
return model;
|
|
1324
1510
|
}
|
|
1325
1511
|
|
package/src/core.ts
CHANGED
package/src/declared-graph.ts
CHANGED
|
@@ -17,7 +17,8 @@ export function declaredGraph(root: object): DefinitionGraph {
|
|
|
17
17
|
id: `${b.id}#${op.name}`,
|
|
18
18
|
parent: b.id,
|
|
19
19
|
label: op.name,
|
|
20
|
-
|
|
20
|
+
// An externally bound operation is itself a public contract, not an internal method.
|
|
21
|
+
kind: "interface" as const,
|
|
21
22
|
provenance: "declared" as const,
|
|
22
23
|
...(b.operations.length === 1 ? { description: b.definition.docs } : {}),
|
|
23
24
|
contract: {
|
package/src/factory-graph.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { displayName } from "./display-name";
|
|
2
2
|
import type { FactoryModel, FactoryAttachments } from "./factory-model";
|
|
3
3
|
import type { DefinitionGraph, SourceRef } from "./model";
|
|
4
|
+
import { interfaceMap, type PublicEntry } from "./interface-map";
|
|
4
5
|
function digest(value: string) {
|
|
5
6
|
let hash = BigInt("14695981039346656037");
|
|
6
7
|
for (const byte of new TextEncoder().encode(value))
|
|
@@ -12,6 +13,7 @@ function digest(value: string) {
|
|
|
12
13
|
export function factoryGraph(
|
|
13
14
|
model: FactoryModel,
|
|
14
15
|
base?: DefinitionGraph,
|
|
16
|
+
options: { legacySnapshot?: boolean; exposeAncestors?: boolean } = {},
|
|
15
17
|
): DefinitionGraph {
|
|
16
18
|
if (model.diagnostics.length)
|
|
17
19
|
throw new Error(
|
|
@@ -47,6 +49,8 @@ export function factoryGraph(
|
|
|
47
49
|
(item) => item.id,
|
|
48
50
|
),
|
|
49
51
|
);
|
|
52
|
+
for (const process of model.processes)
|
|
53
|
+
declaredIds.add(`${process.blockId}::entry`);
|
|
50
54
|
const processIds = new Set(model.processes.map((item) => item.blockId));
|
|
51
55
|
const oldById = new Map(graph.elements.map((item) => [item.id, item]));
|
|
52
56
|
// Incremental adoption: an ID names a logical area, never a source folder.
|
|
@@ -260,14 +264,18 @@ export function factoryGraph(
|
|
|
260
264
|
.replace(/([a-z])([A-Z])/g, "$1 $2")
|
|
261
265
|
.replace(/^./, (letter) => letter.toUpperCase()),
|
|
262
266
|
provenance: "declared",
|
|
263
|
-
source: api.source,
|
|
264
|
-
sources: [api.source],
|
|
267
|
+
source: { ...api.source, scope: "contract" },
|
|
268
|
+
sources: [{ ...api.source, scope: "contract" }],
|
|
265
269
|
attachments: api.attachments,
|
|
266
270
|
description: api.attachments.description,
|
|
271
|
+
signature: api.constructorContract?.signature,
|
|
267
272
|
contract: {
|
|
268
273
|
id: api.id,
|
|
269
274
|
input: {
|
|
270
275
|
language: "typescript",
|
|
276
|
+
...(api.constructorContract
|
|
277
|
+
? { args: api.constructorContract.args }
|
|
278
|
+
: {}),
|
|
271
279
|
members: model.methods
|
|
272
280
|
.filter((method) => method.interfaceId === api.id)
|
|
273
281
|
.map((method) => ({ name: method.name, ...method.contract })),
|
|
@@ -275,6 +283,20 @@ export function factoryGraph(
|
|
|
275
283
|
},
|
|
276
284
|
});
|
|
277
285
|
attach(api.id, api.attachments, api.source);
|
|
286
|
+
for (const owner of [
|
|
287
|
+
...(api.exposedBy || []),
|
|
288
|
+
...(model.blocks.find((block) => block.id === api.blockId)?.exposedBy ||
|
|
289
|
+
[]),
|
|
290
|
+
])
|
|
291
|
+
graph.connections.push({
|
|
292
|
+
id: `public-exposure:${owner}:${api.id}`,
|
|
293
|
+
source: owner,
|
|
294
|
+
target: api.id,
|
|
295
|
+
relation: "exposes",
|
|
296
|
+
label: api.label || api.name,
|
|
297
|
+
provenance: "declared",
|
|
298
|
+
sourceRef: api.source,
|
|
299
|
+
});
|
|
278
300
|
}
|
|
279
301
|
for (const method of model.methods) {
|
|
280
302
|
// A process entry is the implementation of its process box, not an extra method box.
|
|
@@ -285,8 +307,8 @@ export function factoryGraph(
|
|
|
285
307
|
if (processEntry && method.interfaceId)
|
|
286
308
|
graph.connections.push({
|
|
287
309
|
id: `interface-entry:${method.id}`,
|
|
288
|
-
source: method.
|
|
289
|
-
target: method.
|
|
310
|
+
source: method.blockId,
|
|
311
|
+
target: method.interfaceId!,
|
|
290
312
|
relation: "exposes",
|
|
291
313
|
label: method.name,
|
|
292
314
|
provenance: "declared",
|
|
@@ -374,5 +396,67 @@ export function factoryGraph(
|
|
|
374
396
|
gaps: graph.gaps,
|
|
375
397
|
}),
|
|
376
398
|
).slice(0, 16);
|
|
377
|
-
|
|
399
|
+
const entries: PublicEntry[] = model.interfaces
|
|
400
|
+
.filter((api) => api.constructorContract || api.entrypoint)
|
|
401
|
+
.map((api) => ({
|
|
402
|
+
implementation: api.blockId,
|
|
403
|
+
interface: graph.elements.find((node) => node.id === api.id)!,
|
|
404
|
+
}));
|
|
405
|
+
entries.push(
|
|
406
|
+
...model.processes.flatMap<PublicEntry>((process) => {
|
|
407
|
+
const method = model.methods.find(
|
|
408
|
+
(item) => item.id === process.entryMethodId,
|
|
409
|
+
);
|
|
410
|
+
if (
|
|
411
|
+
!method ||
|
|
412
|
+
!graph.elements.some((item) => item.id === process.blockId)
|
|
413
|
+
)
|
|
414
|
+
return [];
|
|
415
|
+
const id = `${process.blockId}::entry`;
|
|
416
|
+
for (const owner of model.blocks.find(
|
|
417
|
+
(block) => block.id === process.blockId,
|
|
418
|
+
)?.exposedBy || [])
|
|
419
|
+
graph.connections.push({
|
|
420
|
+
id: `public-exposure:${owner}:${id}`,
|
|
421
|
+
source: owner,
|
|
422
|
+
target: id,
|
|
423
|
+
relation: "exposes",
|
|
424
|
+
label: method.name,
|
|
425
|
+
provenance: "declared",
|
|
426
|
+
sourceRef: method.source,
|
|
427
|
+
});
|
|
428
|
+
return [
|
|
429
|
+
{
|
|
430
|
+
implementation: process.blockId,
|
|
431
|
+
interface: {
|
|
432
|
+
id,
|
|
433
|
+
parent: process.blockId,
|
|
434
|
+
kind: "interface",
|
|
435
|
+
provenance: "declared",
|
|
436
|
+
label: method.label || displayName(method.name),
|
|
437
|
+
description:
|
|
438
|
+
method.attachments.description ||
|
|
439
|
+
`Public entry to ${graph.elements.find((item) => item.id === process.blockId)!.label}.`,
|
|
440
|
+
source: { ...method.source, scope: "contract" },
|
|
441
|
+
sources: [{ ...method.source, scope: "contract" }],
|
|
442
|
+
signature: method.signature,
|
|
443
|
+
contract: {
|
|
444
|
+
id,
|
|
445
|
+
input: { language: "typescript", args: method.contract.args },
|
|
446
|
+
output: { language: "typescript", type: method.contract.result },
|
|
447
|
+
},
|
|
448
|
+
},
|
|
449
|
+
},
|
|
450
|
+
];
|
|
451
|
+
}),
|
|
452
|
+
);
|
|
453
|
+
const result = interfaceMap(graph, entries, {
|
|
454
|
+
exposeAncestors: options.exposeAncestors,
|
|
455
|
+
validate: !options.legacySnapshot,
|
|
456
|
+
});
|
|
457
|
+
result.revision = digest(JSON.stringify({ ...result, revision: "" })).slice(
|
|
458
|
+
0,
|
|
459
|
+
16,
|
|
460
|
+
);
|
|
461
|
+
return result;
|
|
378
462
|
}
|
package/src/factory-model.ts
CHANGED
|
@@ -9,6 +9,7 @@ export interface FactoryAttachments {
|
|
|
9
9
|
auth?: { symbol: string; source: SourceRef };
|
|
10
10
|
}
|
|
11
11
|
export interface FactoryBlock {
|
|
12
|
+
exposedBy?: string[];
|
|
12
13
|
inputLabel?: string;
|
|
13
14
|
eventLabel?: string;
|
|
14
15
|
id: string;
|
|
@@ -18,6 +19,14 @@ export interface FactoryBlock {
|
|
|
18
19
|
attachments: FactoryAttachments;
|
|
19
20
|
}
|
|
20
21
|
export interface FactoryInterface {
|
|
22
|
+
/** A callable block or class constructor is implemented by its owning box. */
|
|
23
|
+
entrypoint?: boolean;
|
|
24
|
+
exposedBy?: string[];
|
|
25
|
+
constructorContract?: {
|
|
26
|
+
signature: string;
|
|
27
|
+
args: { name: string; type: string; optional: boolean; rest: boolean }[];
|
|
28
|
+
result: string;
|
|
29
|
+
};
|
|
21
30
|
id: string;
|
|
22
31
|
blockId: string;
|
|
23
32
|
name: string;
|
package/src/git-code.ts
CHANGED
|
@@ -222,7 +222,7 @@ export function captureCommit(
|
|
|
222
222
|
throw new Error("Unsupported historical annotation model");
|
|
223
223
|
const graph = {
|
|
224
224
|
...(annotations
|
|
225
|
-
? factoryGraph(annotations, compose(graphs))
|
|
225
|
+
? factoryGraph(annotations, compose(graphs), { legacySnapshot: true })
|
|
226
226
|
: compose(graphs)),
|
|
227
227
|
codeRevision: commit,
|
|
228
228
|
};
|
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
import type { DefinitionGraph, Element, Connection } from "./model";
|
|
2
|
+
import { assertPublicConnections } from "./public-boundaries";
|
|
3
|
+
|
|
4
|
+
export type PublicEntry = {
|
|
5
|
+
/** Existing implementation identity. The interface is an explicit declaration,
|
|
6
|
+
* backed by this entry's real signature/schema and source evidence. */
|
|
7
|
+
implementation: string;
|
|
8
|
+
interface: Element;
|
|
9
|
+
};
|
|
10
|
+
|
|
11
|
+
/** Repository adapters declare reviewed public surfaces here. This does not
|
|
12
|
+
* guess interfaces for unknown callees or change application runtime behavior.
|
|
13
|
+
* Exact callee identities remain on entrypoint and on the internal delegation.
|
|
14
|
+
*/
|
|
15
|
+
export function interfaceMap(
|
|
16
|
+
definition: DefinitionGraph,
|
|
17
|
+
entries: PublicEntry[],
|
|
18
|
+
options: { exposeAncestors?: boolean; validate?: boolean } = {},
|
|
19
|
+
) {
|
|
20
|
+
const graph = structuredClone(definition);
|
|
21
|
+
const byId = new Map(graph.elements.map((node) => [node.id, node]));
|
|
22
|
+
const publicEntries = new Map<string, string>();
|
|
23
|
+
for (const entry of entries) {
|
|
24
|
+
if (entry.interface.kind !== "interface" || !byId.has(entry.implementation))
|
|
25
|
+
throw Error(
|
|
26
|
+
`Declare an interface for an existing implementation: ${entry.implementation}`,
|
|
27
|
+
);
|
|
28
|
+
if (
|
|
29
|
+
!entry.interface.contract ||
|
|
30
|
+
(!entry.interface.source &&
|
|
31
|
+
!entry.interface.sources?.length &&
|
|
32
|
+
entry.interface.provenance !== "declared")
|
|
33
|
+
)
|
|
34
|
+
throw Error(
|
|
35
|
+
`Public interface ${entry.interface.id} needs its source contract.`,
|
|
36
|
+
);
|
|
37
|
+
if (!byId.has(entry.interface.id)) {
|
|
38
|
+
graph.elements.push(entry.interface);
|
|
39
|
+
byId.set(entry.interface.id, entry.interface);
|
|
40
|
+
} else {
|
|
41
|
+
const index = graph.elements.findIndex(
|
|
42
|
+
(node) => node.id === entry.interface.id,
|
|
43
|
+
);
|
|
44
|
+
graph.elements[index] = { ...graph.elements[index], ...entry.interface };
|
|
45
|
+
byId.set(entry.interface.id, graph.elements[index]);
|
|
46
|
+
}
|
|
47
|
+
publicEntries.set(entry.implementation, entry.interface.id);
|
|
48
|
+
}
|
|
49
|
+
// An annotated member is callable through its explicitly declared interface.
|
|
50
|
+
for (const node of graph.elements)
|
|
51
|
+
if (
|
|
52
|
+
["method", "operation"].includes(node.kind) &&
|
|
53
|
+
byId.get(node.parent || "")?.kind === "interface"
|
|
54
|
+
)
|
|
55
|
+
publicEntries.set(node.id, node.parent!);
|
|
56
|
+
const within = (id: string, ancestor: string) => {
|
|
57
|
+
const seen = new Set<string>();
|
|
58
|
+
while (byId.has(id) && !seen.has(id)) {
|
|
59
|
+
if (id === ancestor) return true;
|
|
60
|
+
seen.add(id);
|
|
61
|
+
id = byId.get(id)!.parent || "";
|
|
62
|
+
}
|
|
63
|
+
return false;
|
|
64
|
+
};
|
|
65
|
+
const owner = (id: string) => {
|
|
66
|
+
const seen = new Set<string>();
|
|
67
|
+
while (byId.has(id) && !seen.has(id)) {
|
|
68
|
+
const node = byId.get(id)!;
|
|
69
|
+
if (
|
|
70
|
+
!["interface", "method", "operation", "resource", "artifact"].includes(
|
|
71
|
+
node.kind,
|
|
72
|
+
)
|
|
73
|
+
)
|
|
74
|
+
return id;
|
|
75
|
+
seen.add(id);
|
|
76
|
+
id = node.parent || "";
|
|
77
|
+
}
|
|
78
|
+
};
|
|
79
|
+
const delegations = new Map<string, Connection>();
|
|
80
|
+
for (const entry of entries) {
|
|
81
|
+
if (entry.interface.id === entry.implementation) continue;
|
|
82
|
+
const id = `interface-implementation:${entry.interface.id}:${entry.implementation}`;
|
|
83
|
+
delegations.set(id, {
|
|
84
|
+
id,
|
|
85
|
+
source: entry.interface.id,
|
|
86
|
+
target: entry.implementation,
|
|
87
|
+
relation: "delegates",
|
|
88
|
+
label: byId.get(entry.implementation)!.label,
|
|
89
|
+
provenance: entry.interface.provenance,
|
|
90
|
+
sourceRef: entry.interface.source,
|
|
91
|
+
});
|
|
92
|
+
}
|
|
93
|
+
graph.connections = graph.connections.map((edge) => {
|
|
94
|
+
const receiver = byId.get(edge.target),
|
|
95
|
+
boundary = owner(edge.target);
|
|
96
|
+
const api = publicEntries.get(edge.target);
|
|
97
|
+
if (
|
|
98
|
+
!api ||
|
|
99
|
+
receiver?.kind === "interface" ||
|
|
100
|
+
!boundary ||
|
|
101
|
+
(within(edge.source, boundary) && edge.relation !== "exposes")
|
|
102
|
+
)
|
|
103
|
+
return edge;
|
|
104
|
+
const declaration = byId.get(api)!;
|
|
105
|
+
const id = `interface-implementation:${api}:${edge.target}`;
|
|
106
|
+
delegations.set(id, {
|
|
107
|
+
id,
|
|
108
|
+
source: api,
|
|
109
|
+
target: edge.target,
|
|
110
|
+
relation: "delegates",
|
|
111
|
+
label: receiver!.label,
|
|
112
|
+
provenance: declaration.provenance,
|
|
113
|
+
sourceRef: receiver?.source || declaration.source,
|
|
114
|
+
});
|
|
115
|
+
return { ...edge, target: api, entrypoint: edge.entrypoint || edge.target };
|
|
116
|
+
});
|
|
117
|
+
graph.connections = graph.connections.filter(
|
|
118
|
+
(edge) => edge.relation !== "exposes" || edge.source !== edge.target,
|
|
119
|
+
);
|
|
120
|
+
graph.connections.push(
|
|
121
|
+
...[...delegations.values()].filter(
|
|
122
|
+
(edge) => !graph.connections.some((current) => current.id === edge.id),
|
|
123
|
+
),
|
|
124
|
+
);
|
|
125
|
+
if (options.exposeAncestors) {
|
|
126
|
+
// Source inventories group real exported entrypoints into logical boxes.
|
|
127
|
+
// The repository adapter explicitly exposes these same contracts through
|
|
128
|
+
// its enclosing responsibilities; no duplicate facade or fake API is made.
|
|
129
|
+
for (const api of graph.elements.filter(
|
|
130
|
+
(node) => node.kind === "interface",
|
|
131
|
+
)) {
|
|
132
|
+
let parent = byId.get(api.parent || "")?.parent;
|
|
133
|
+
const seen = new Set<string>();
|
|
134
|
+
while (parent && byId.has(parent) && !seen.has(parent)) {
|
|
135
|
+
seen.add(parent);
|
|
136
|
+
const node = byId.get(parent)!;
|
|
137
|
+
if (
|
|
138
|
+
!["interface", "method", "operation"].includes(node.kind) &&
|
|
139
|
+
parent !== graph.id
|
|
140
|
+
) {
|
|
141
|
+
const id = `public-exposure:${parent}:${api.id}`;
|
|
142
|
+
if (
|
|
143
|
+
!graph.connections.some(
|
|
144
|
+
(edge) =>
|
|
145
|
+
edge.source === parent &&
|
|
146
|
+
edge.target === api.id &&
|
|
147
|
+
edge.relation === "exposes",
|
|
148
|
+
)
|
|
149
|
+
)
|
|
150
|
+
graph.connections.push({
|
|
151
|
+
id,
|
|
152
|
+
source: parent,
|
|
153
|
+
target: api.id,
|
|
154
|
+
relation: "exposes",
|
|
155
|
+
label: api.label,
|
|
156
|
+
provenance: api.provenance,
|
|
157
|
+
sourceRef: api.source,
|
|
158
|
+
});
|
|
159
|
+
}
|
|
160
|
+
parent = node.parent;
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
if (options.validate !== false) assertPublicConnections(graph);
|
|
165
|
+
return graph;
|
|
166
|
+
}
|
package/src/map-quality.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { boundaryViolations } from "./public-boundaries";
|
|
1
2
|
import type { DefinitionGraph } from "./model";
|
|
2
3
|
|
|
3
4
|
/** Evidence gaps, not claims that disconnected code is unused. Ownership follows
|
|
@@ -35,8 +36,12 @@ export function mapQuality(graph: DefinitionGraph) {
|
|
|
35
36
|
}
|
|
36
37
|
if (byId.size !== graph.elements.length)
|
|
37
38
|
problems.push("Duplicate block identities");
|
|
39
|
+
const boundaries = boundaryViolations(graph);
|
|
40
|
+
for (const issue of boundaries)
|
|
41
|
+
problems.push(`${issue.connection}: ${issue.reason}`);
|
|
38
42
|
return {
|
|
39
43
|
problems,
|
|
44
|
+
boundaryViolations: boundaries,
|
|
40
45
|
areas: graph.elements
|
|
41
46
|
.filter((node) => node.parent === graph.id)
|
|
42
47
|
.map((node) => ({
|
package/src/model.ts
CHANGED
|
@@ -10,12 +10,17 @@ export type ElementKind =
|
|
|
10
10
|
| "operation"
|
|
11
11
|
| "resource"
|
|
12
12
|
| "artifact";
|
|
13
|
-
export type Provenance =
|
|
13
|
+
export type Provenance =
|
|
14
|
+
| "declared"
|
|
15
|
+
| "source"
|
|
16
|
+
| "inferred"
|
|
17
|
+
| "observed"
|
|
18
|
+
| "proposed";
|
|
14
19
|
/** The four logical shapes. Older snapshots may still contain the legacy kinds above. */
|
|
15
20
|
export type LogicalKind = "block" | "interface" | "method" | "process";
|
|
16
21
|
export interface SourceRef {
|
|
17
|
-
/**
|
|
18
|
-
scope?: "file";
|
|
22
|
+
/** File owns a module; contract references describe an API without owning its implementation. */
|
|
23
|
+
scope?: "file" | "contract";
|
|
19
24
|
file: string;
|
|
20
25
|
line: number;
|
|
21
26
|
symbol?: string;
|
|
@@ -78,6 +83,8 @@ export interface Connection {
|
|
|
78
83
|
id: string;
|
|
79
84
|
source: string;
|
|
80
85
|
target: string;
|
|
86
|
+
/** Exact callable behind a public interface; preserved source evidence. */
|
|
87
|
+
entrypoint?: string;
|
|
81
88
|
relation: Relation;
|
|
82
89
|
label: string;
|
|
83
90
|
displayLabel?: string;
|