@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/annotations.d.ts
CHANGED
|
@@ -21,6 +21,8 @@ export interface RuntimeContract {
|
|
|
21
21
|
};
|
|
22
22
|
}
|
|
23
23
|
export interface InterfaceOptions extends Attachments {
|
|
24
|
+
/** Explicit publication through enclosing black boxes. Does not change runtime access. */
|
|
25
|
+
exposedBy?: readonly (() => object)[];
|
|
24
26
|
/** Optional stable identity when adopting an existing mapped interface. */
|
|
25
27
|
id?: string;
|
|
26
28
|
label?: string;
|
|
@@ -35,6 +37,8 @@ export interface InterfaceRef {
|
|
|
35
37
|
readonly options: InterfaceOptions;
|
|
36
38
|
}
|
|
37
39
|
export interface BlockOptions extends Attachments {
|
|
40
|
+
/** Publish this block's public interfaces through these enclosing blocks. */
|
|
41
|
+
exposedBy?: readonly (() => object)[];
|
|
38
42
|
/** Display names only; shapes still come from actual parameters and props. */
|
|
39
43
|
inputLabel?: string;
|
|
40
44
|
eventLabel?: string;
|
package/dist/compiler.js
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.js";
|
|
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";
|
|
@@ -410,6 +411,67 @@ export function compileFactory(options) {
|
|
|
410
411
|
if (parent)
|
|
411
412
|
block.parent = parent.id;
|
|
412
413
|
}
|
|
414
|
+
const exposures = (config, node) => {
|
|
415
|
+
const value = property(config, "exposedBy");
|
|
416
|
+
if (!value)
|
|
417
|
+
return undefined;
|
|
418
|
+
if (!ts.isArrayLiteralExpression(value)) {
|
|
419
|
+
problem(node, "exposedBy must reference enclosing annotated blocks");
|
|
420
|
+
return undefined;
|
|
421
|
+
}
|
|
422
|
+
return value.elements.flatMap((entry) => {
|
|
423
|
+
const declaration = resolvedNode(entry), block = declaration && blocks.get(declaration);
|
|
424
|
+
if (!block) {
|
|
425
|
+
problem(node, "exposedBy must reference an annotated block/process declaration");
|
|
426
|
+
return [];
|
|
427
|
+
}
|
|
428
|
+
return [block.id];
|
|
429
|
+
});
|
|
430
|
+
};
|
|
431
|
+
for (const item of pending.filter((entry) => entry.kind === "Block" || entry.kind === "Process")) {
|
|
432
|
+
const block = blocks.get(item.node);
|
|
433
|
+
if (block)
|
|
434
|
+
block.exposedBy = exposures(configOf(item.call), item.node);
|
|
435
|
+
if (!block || !ts.isClassDeclaration(item.node))
|
|
436
|
+
continue;
|
|
437
|
+
const ctor = item.node.members.find(ts.isConstructorDeclaration);
|
|
438
|
+
if (ctor &&
|
|
439
|
+
ts
|
|
440
|
+
.getModifiers(ctor)
|
|
441
|
+
?.some((modifier) => [
|
|
442
|
+
ts.SyntaxKind.PrivateKeyword,
|
|
443
|
+
ts.SyntaxKind.ProtectedKeyword,
|
|
444
|
+
].includes(modifier.kind)))
|
|
445
|
+
continue;
|
|
446
|
+
model.interfaces.push({
|
|
447
|
+
id: `${block.id}::construct`,
|
|
448
|
+
blockId: block.id,
|
|
449
|
+
name: "construct",
|
|
450
|
+
label: `Create ${block.label}`,
|
|
451
|
+
source: source(ctor || item.node),
|
|
452
|
+
attachments: {
|
|
453
|
+
docs: [],
|
|
454
|
+
tests: [],
|
|
455
|
+
description: `Public constructor of ${block.label}.`,
|
|
456
|
+
},
|
|
457
|
+
methods: [],
|
|
458
|
+
constructorContract: {
|
|
459
|
+
signature: ctor
|
|
460
|
+
? ctor
|
|
461
|
+
.getText()
|
|
462
|
+
.slice(0, ctor.body ? ctor.body.getStart() - ctor.getStart() : undefined)
|
|
463
|
+
.trim()
|
|
464
|
+
: `new ${item.node.name?.text || block.label}()`,
|
|
465
|
+
args: (ctor?.parameters || []).map((parameter) => ({
|
|
466
|
+
name: parameter.name.getText(),
|
|
467
|
+
type: parameter.type?.getText() || "unknown",
|
|
468
|
+
optional: !!parameter.questionToken || !!parameter.initializer,
|
|
469
|
+
rest: !!parameter.dotDotDotToken,
|
|
470
|
+
})),
|
|
471
|
+
result: item.node.name?.text || block.label,
|
|
472
|
+
},
|
|
473
|
+
});
|
|
474
|
+
}
|
|
413
475
|
for (const { node, call } of pending.filter((p) => p.kind === "Interface")) {
|
|
414
476
|
const config = call.arguments[0] && ts.isStringLiteral(call.arguments[0])
|
|
415
477
|
? call.arguments[1]
|
|
@@ -461,9 +523,11 @@ export function compileFactory(options) {
|
|
|
461
523
|
source: source(node),
|
|
462
524
|
attachments: attachments(config, node),
|
|
463
525
|
methods: [],
|
|
526
|
+
exposedBy: exposures(config, node),
|
|
464
527
|
});
|
|
465
528
|
}
|
|
466
529
|
for (const { node, call, kind } of pending.filter((p) => p.kind === "Method" ||
|
|
530
|
+
(p.kind === "Block" && !!callable(p.node)) ||
|
|
467
531
|
(p.kind === "Process" &&
|
|
468
532
|
!pending.some((other) => other.node === p.node && other.kind === "Method")))) {
|
|
469
533
|
const declaration = callable(node);
|
|
@@ -472,19 +536,32 @@ export function compileFactory(options) {
|
|
|
472
536
|
continue;
|
|
473
537
|
}
|
|
474
538
|
const apiNode = kind === "Method" ? resolvedNode(call.arguments[0]) : undefined;
|
|
475
|
-
|
|
539
|
+
let interfaceId = apiNode && apis.get(apiNode);
|
|
476
540
|
const api = model.interfaces.find((api) => api.id === interfaceId);
|
|
477
541
|
if (kind === "Method" && !api) {
|
|
478
542
|
problem(node, "@Method must reference a declared interface");
|
|
479
543
|
continue;
|
|
480
544
|
}
|
|
481
|
-
const block = kind === "Process"
|
|
545
|
+
const block = kind === "Process" || kind === "Block"
|
|
482
546
|
? blocks.get(node)
|
|
483
547
|
: blocks.get(node) ||
|
|
484
548
|
model.blocks.find((block) => block.id === api?.blockId) ||
|
|
485
549
|
(api ? { id: api.blockId } : undefined);
|
|
486
550
|
if (!block)
|
|
487
551
|
continue;
|
|
552
|
+
if (kind === "Block") {
|
|
553
|
+
interfaceId = `${block.id}::entry`;
|
|
554
|
+
model.interfaces.push({
|
|
555
|
+
id: interfaceId,
|
|
556
|
+
blockId: block.id,
|
|
557
|
+
name: "entry",
|
|
558
|
+
label: blocks.get(node)?.label || block.id,
|
|
559
|
+
source: source(node),
|
|
560
|
+
attachments: attachments(configOf(call), node),
|
|
561
|
+
methods: [],
|
|
562
|
+
entrypoint: true,
|
|
563
|
+
});
|
|
564
|
+
}
|
|
488
565
|
let parent = node.parent;
|
|
489
566
|
while (parent &&
|
|
490
567
|
(ts.isCallExpression(parent) ||
|
|
@@ -602,8 +679,52 @@ export function compileFactory(options) {
|
|
|
602
679
|
ts.SyntaxKind.StaticKeyword,
|
|
603
680
|
].includes(modifier.kind)) &&
|
|
604
681
|
!(member.name && ts.isPrivateIdentifier(member.name)) &&
|
|
605
|
-
!owners.has(member))
|
|
606
|
-
|
|
682
|
+
!owners.has(member)) {
|
|
683
|
+
// TypeScript public members are real callable contracts too. Preserve
|
|
684
|
+
// their exact signatures instead of representing them as calls to the
|
|
685
|
+
// owning box (or incorrectly treating them as constructor calls).
|
|
686
|
+
const name = `${ts.isGetAccessorDeclaration(member) ? "get:" : ts.isSetAccessorDeclaration(member) ? "set:" : ""}${member.name.getText()}`, id = `${block.id}::public`;
|
|
687
|
+
const signature = checker.getSignatureFromDeclaration(member);
|
|
688
|
+
const method = {
|
|
689
|
+
id: `${id}#${name}`,
|
|
690
|
+
blockId: block.id,
|
|
691
|
+
interfaceId: id,
|
|
692
|
+
name,
|
|
693
|
+
source: source(member),
|
|
694
|
+
signature: signature
|
|
695
|
+
? checker.signatureToString(signature, member, ts.TypeFormatFlags.NoTruncation)
|
|
696
|
+
: member.getText().split("{")[0],
|
|
697
|
+
contract: {
|
|
698
|
+
args: member.parameters.map((parameter) => ({
|
|
699
|
+
name: parameter.name.getText(),
|
|
700
|
+
type: checker.typeToString(checker.getTypeAtLocation(parameter), parameter, ts.TypeFormatFlags.NoTruncation),
|
|
701
|
+
optional: !!parameter.questionToken || !!parameter.initializer,
|
|
702
|
+
rest: !!parameter.dotDotDotToken,
|
|
703
|
+
})),
|
|
704
|
+
result: signature
|
|
705
|
+
? checker.typeToString(checker.getReturnTypeOfSignature(signature), member, ts.TypeFormatFlags.NoTruncation)
|
|
706
|
+
: "unknown",
|
|
707
|
+
typeSources: typeSources(member),
|
|
708
|
+
runtimeValidation: false,
|
|
709
|
+
},
|
|
710
|
+
attachments: attachments(undefined, member),
|
|
711
|
+
};
|
|
712
|
+
const existing = model.interfaces.find((api) => api.id === id);
|
|
713
|
+
if (existing)
|
|
714
|
+
existing.methods.push(method.id);
|
|
715
|
+
else
|
|
716
|
+
model.interfaces.push({
|
|
717
|
+
id,
|
|
718
|
+
blockId: block.id,
|
|
719
|
+
name: "public",
|
|
720
|
+
label: `${block.label} public API`,
|
|
721
|
+
source: source(member),
|
|
722
|
+
attachments: method.attachments,
|
|
723
|
+
methods: [method.id],
|
|
724
|
+
});
|
|
725
|
+
model.methods.push(method);
|
|
726
|
+
owners.set(member, method.id);
|
|
727
|
+
}
|
|
607
728
|
}
|
|
608
729
|
const bodyOf = (node) => {
|
|
609
730
|
if (!node)
|
|
@@ -890,6 +1011,30 @@ export function compileFactory(options) {
|
|
|
890
1011
|
const follow = (target, at, relation = "calls") => {
|
|
891
1012
|
if (!target)
|
|
892
1013
|
return;
|
|
1014
|
+
if (ts.isMethodDeclaration(target) &&
|
|
1015
|
+
target.modifiers?.some((modifier) => [
|
|
1016
|
+
ts.SyntaxKind.PrivateKeyword,
|
|
1017
|
+
ts.SyntaxKind.ProtectedKeyword,
|
|
1018
|
+
].includes(modifier.kind))) {
|
|
1019
|
+
const receiver = nearestBlock(target);
|
|
1020
|
+
// Access belongs to the lexical call site. A returned closure can
|
|
1021
|
+
// legally call its class's private helper even when an outside entry
|
|
1022
|
+
// caused us to traverse it; that caller does not own the closure body.
|
|
1023
|
+
let sender = nearestBlock(at)?.id ||
|
|
1024
|
+
model.methods.find((method) => method.id === owner)?.blockId ||
|
|
1025
|
+
model.interfaces.find((api) => api.id === owner)?.blockId ||
|
|
1026
|
+
owner;
|
|
1027
|
+
const seen = new Set();
|
|
1028
|
+
while (receiver && sender !== receiver.id && !seen.has(sender)) {
|
|
1029
|
+
seen.add(sender);
|
|
1030
|
+
sender =
|
|
1031
|
+
model.blocks.find((block) => block.id === sender)?.parent || "";
|
|
1032
|
+
}
|
|
1033
|
+
if (receiver && sender !== receiver.id) {
|
|
1034
|
+
problem(at, `Private member ${target.name.getText()} cannot receive calls from outside ${receiver.label}; use its public interface.`);
|
|
1035
|
+
return;
|
|
1036
|
+
}
|
|
1037
|
+
}
|
|
893
1038
|
const boundVia = [...via, ...(injectionEvidence.get(at) || [])];
|
|
894
1039
|
const boundary = owners.get(target);
|
|
895
1040
|
if (boundary) {
|
|
@@ -1078,6 +1223,18 @@ export function compileFactory(options) {
|
|
|
1078
1223
|
api.methods.sort();
|
|
1079
1224
|
model.dependencies.sort((a, b) => `${a.source}:${a.target}:${a.at.line}`.localeCompare(`${b.source}:${b.target}:${b.at.line}`));
|
|
1080
1225
|
model.revision = digest(JSON.stringify({ ...model, revision: "" })).slice(0, 16);
|
|
1226
|
+
if (!model.diagnostics.length) {
|
|
1227
|
+
try {
|
|
1228
|
+
checkedFactoryGraph(model);
|
|
1229
|
+
}
|
|
1230
|
+
catch (error) {
|
|
1231
|
+
model.diagnostics.push({
|
|
1232
|
+
file: "<public interfaces>",
|
|
1233
|
+
line: 1,
|
|
1234
|
+
message: error instanceof Error ? error.message : String(error),
|
|
1235
|
+
});
|
|
1236
|
+
}
|
|
1237
|
+
}
|
|
1081
1238
|
return model;
|
|
1082
1239
|
}
|
|
1083
1240
|
export { factoryGraph } from "./factory-graph.js";
|
package/dist/core.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
/** Browser/Worker-safe decorators. Discovery never imports an application to execute it. */
|
|
2
|
+
export { assertPublicConnections, publicConnectionError, } from "./public-boundaries.js";
|
|
2
3
|
export { Block, Interface, Method, Process, observeFactory, installFactoryHost, } from "./annotations.js";
|
|
3
4
|
export type { InterfaceRef, FactoryEvent, FactoryHost } from "./annotations.js";
|
|
4
5
|
export interface Schema<T> {
|
package/dist/core.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
/** Browser/Worker-safe decorators. Discovery never imports an application to execute it. */
|
|
2
|
+
export { assertPublicConnections, publicConnectionError, } from "./public-boundaries.js";
|
|
2
3
|
export { Block, Interface, Method, Process, observeFactory, installFactoryHost, } from "./annotations.js";
|
|
3
4
|
export function contract(id, schemas) {
|
|
4
5
|
if (!id.trim())
|
package/dist/declared-graph.js
CHANGED
|
@@ -15,7 +15,8 @@ export function declaredGraph(root) {
|
|
|
15
15
|
id: `${b.id}#${op.name}`,
|
|
16
16
|
parent: b.id,
|
|
17
17
|
label: op.name,
|
|
18
|
-
|
|
18
|
+
// An externally bound operation is itself a public contract, not an internal method.
|
|
19
|
+
kind: "interface",
|
|
19
20
|
provenance: "declared",
|
|
20
21
|
...(b.operations.length === 1 ? { description: b.definition.docs } : {}),
|
|
21
22
|
contract: {
|
package/dist/factory-graph.d.ts
CHANGED
|
@@ -1,4 +1,7 @@
|
|
|
1
1
|
import type { FactoryModel } from "./factory-model.js";
|
|
2
2
|
import type { DefinitionGraph } from "./model.js";
|
|
3
3
|
/** Compatibility projection only. The v2 model retains interface/member semantics. */
|
|
4
|
-
export declare function factoryGraph(model: FactoryModel, base?: DefinitionGraph
|
|
4
|
+
export declare function factoryGraph(model: FactoryModel, base?: DefinitionGraph, options?: {
|
|
5
|
+
legacySnapshot?: boolean;
|
|
6
|
+
exposeAncestors?: boolean;
|
|
7
|
+
}): DefinitionGraph;
|
package/dist/factory-graph.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { displayName } from "./display-name.js";
|
|
2
|
+
import { interfaceMap } from "./interface-map.js";
|
|
2
3
|
function digest(value) {
|
|
3
4
|
let hash = BigInt("14695981039346656037");
|
|
4
5
|
for (const byte of new TextEncoder().encode(value))
|
|
@@ -6,7 +7,7 @@ function digest(value) {
|
|
|
6
7
|
return hash.toString(16).padStart(16, "0");
|
|
7
8
|
}
|
|
8
9
|
/** Compatibility projection only. The v2 model retains interface/member semantics. */
|
|
9
|
-
export function factoryGraph(model, base) {
|
|
10
|
+
export function factoryGraph(model, base, options = {}) {
|
|
10
11
|
if (model.diagnostics.length)
|
|
11
12
|
throw new Error(model.diagnostics
|
|
12
13
|
.map((d) => `${d.file}:${d.line}: ${d.message}`)
|
|
@@ -35,6 +36,8 @@ export function factoryGraph(model, base) {
|
|
|
35
36
|
// Reviewed inventories describe product areas, not executable control flow.
|
|
36
37
|
// Retire their handwritten process internals when source declarations take over.
|
|
37
38
|
const declaredIds = new Set([...model.blocks, ...model.interfaces, ...model.methods].map((item) => item.id));
|
|
39
|
+
for (const process of model.processes)
|
|
40
|
+
declaredIds.add(`${process.blockId}::entry`);
|
|
38
41
|
const processIds = new Set(model.processes.map((item) => item.blockId));
|
|
39
42
|
const oldById = new Map(graph.elements.map((item) => [item.id, item]));
|
|
40
43
|
// Incremental adoption: an ID names a logical area, never a source folder.
|
|
@@ -210,14 +213,18 @@ export function factoryGraph(model, base) {
|
|
|
210
213
|
.replace(/([a-z])([A-Z])/g, "$1 $2")
|
|
211
214
|
.replace(/^./, (letter) => letter.toUpperCase()),
|
|
212
215
|
provenance: "declared",
|
|
213
|
-
source: api.source,
|
|
214
|
-
sources: [api.source],
|
|
216
|
+
source: { ...api.source, scope: "contract" },
|
|
217
|
+
sources: [{ ...api.source, scope: "contract" }],
|
|
215
218
|
attachments: api.attachments,
|
|
216
219
|
description: api.attachments.description,
|
|
220
|
+
signature: api.constructorContract?.signature,
|
|
217
221
|
contract: {
|
|
218
222
|
id: api.id,
|
|
219
223
|
input: {
|
|
220
224
|
language: "typescript",
|
|
225
|
+
...(api.constructorContract
|
|
226
|
+
? { args: api.constructorContract.args }
|
|
227
|
+
: {}),
|
|
221
228
|
members: model.methods
|
|
222
229
|
.filter((method) => method.interfaceId === api.id)
|
|
223
230
|
.map((method) => ({ name: method.name, ...method.contract })),
|
|
@@ -225,6 +232,20 @@ export function factoryGraph(model, base) {
|
|
|
225
232
|
},
|
|
226
233
|
});
|
|
227
234
|
attach(api.id, api.attachments, api.source);
|
|
235
|
+
for (const owner of [
|
|
236
|
+
...(api.exposedBy || []),
|
|
237
|
+
...(model.blocks.find((block) => block.id === api.blockId)?.exposedBy ||
|
|
238
|
+
[]),
|
|
239
|
+
])
|
|
240
|
+
graph.connections.push({
|
|
241
|
+
id: `public-exposure:${owner}:${api.id}`,
|
|
242
|
+
source: owner,
|
|
243
|
+
target: api.id,
|
|
244
|
+
relation: "exposes",
|
|
245
|
+
label: api.label || api.name,
|
|
246
|
+
provenance: "declared",
|
|
247
|
+
sourceRef: api.source,
|
|
248
|
+
});
|
|
228
249
|
}
|
|
229
250
|
for (const method of model.methods) {
|
|
230
251
|
// A process entry is the implementation of its process box, not an extra method box.
|
|
@@ -234,8 +255,8 @@ export function factoryGraph(model, base) {
|
|
|
234
255
|
if (processEntry && method.interfaceId)
|
|
235
256
|
graph.connections.push({
|
|
236
257
|
id: `interface-entry:${method.id}`,
|
|
237
|
-
source: method.
|
|
238
|
-
target: method.
|
|
258
|
+
source: method.blockId,
|
|
259
|
+
target: method.interfaceId,
|
|
239
260
|
relation: "exposes",
|
|
240
261
|
label: method.name,
|
|
241
262
|
provenance: "declared",
|
|
@@ -314,5 +335,55 @@ export function factoryGraph(model, base) {
|
|
|
314
335
|
failures: graph.failures,
|
|
315
336
|
gaps: graph.gaps,
|
|
316
337
|
})).slice(0, 16);
|
|
317
|
-
|
|
338
|
+
const entries = model.interfaces
|
|
339
|
+
.filter((api) => api.constructorContract || api.entrypoint)
|
|
340
|
+
.map((api) => ({
|
|
341
|
+
implementation: api.blockId,
|
|
342
|
+
interface: graph.elements.find((node) => node.id === api.id),
|
|
343
|
+
}));
|
|
344
|
+
entries.push(...model.processes.flatMap((process) => {
|
|
345
|
+
const method = model.methods.find((item) => item.id === process.entryMethodId);
|
|
346
|
+
if (!method ||
|
|
347
|
+
!graph.elements.some((item) => item.id === process.blockId))
|
|
348
|
+
return [];
|
|
349
|
+
const id = `${process.blockId}::entry`;
|
|
350
|
+
for (const owner of model.blocks.find((block) => block.id === process.blockId)?.exposedBy || [])
|
|
351
|
+
graph.connections.push({
|
|
352
|
+
id: `public-exposure:${owner}:${id}`,
|
|
353
|
+
source: owner,
|
|
354
|
+
target: id,
|
|
355
|
+
relation: "exposes",
|
|
356
|
+
label: method.name,
|
|
357
|
+
provenance: "declared",
|
|
358
|
+
sourceRef: method.source,
|
|
359
|
+
});
|
|
360
|
+
return [
|
|
361
|
+
{
|
|
362
|
+
implementation: process.blockId,
|
|
363
|
+
interface: {
|
|
364
|
+
id,
|
|
365
|
+
parent: process.blockId,
|
|
366
|
+
kind: "interface",
|
|
367
|
+
provenance: "declared",
|
|
368
|
+
label: method.label || displayName(method.name),
|
|
369
|
+
description: method.attachments.description ||
|
|
370
|
+
`Public entry to ${graph.elements.find((item) => item.id === process.blockId).label}.`,
|
|
371
|
+
source: { ...method.source, scope: "contract" },
|
|
372
|
+
sources: [{ ...method.source, scope: "contract" }],
|
|
373
|
+
signature: method.signature,
|
|
374
|
+
contract: {
|
|
375
|
+
id,
|
|
376
|
+
input: { language: "typescript", args: method.contract.args },
|
|
377
|
+
output: { language: "typescript", type: method.contract.result },
|
|
378
|
+
},
|
|
379
|
+
},
|
|
380
|
+
},
|
|
381
|
+
];
|
|
382
|
+
}));
|
|
383
|
+
const result = interfaceMap(graph, entries, {
|
|
384
|
+
exposeAncestors: options.exposeAncestors,
|
|
385
|
+
validate: !options.legacySnapshot,
|
|
386
|
+
});
|
|
387
|
+
result.revision = digest(JSON.stringify({ ...result, revision: "" })).slice(0, 16);
|
|
388
|
+
return result;
|
|
318
389
|
}
|
package/dist/factory-model.d.ts
CHANGED
|
@@ -11,6 +11,7 @@ export interface FactoryAttachments {
|
|
|
11
11
|
};
|
|
12
12
|
}
|
|
13
13
|
export interface FactoryBlock {
|
|
14
|
+
exposedBy?: string[];
|
|
14
15
|
inputLabel?: string;
|
|
15
16
|
eventLabel?: string;
|
|
16
17
|
id: string;
|
|
@@ -20,6 +21,19 @@ export interface FactoryBlock {
|
|
|
20
21
|
attachments: FactoryAttachments;
|
|
21
22
|
}
|
|
22
23
|
export interface FactoryInterface {
|
|
24
|
+
/** A callable block or class constructor is implemented by its owning box. */
|
|
25
|
+
entrypoint?: boolean;
|
|
26
|
+
exposedBy?: string[];
|
|
27
|
+
constructorContract?: {
|
|
28
|
+
signature: string;
|
|
29
|
+
args: {
|
|
30
|
+
name: string;
|
|
31
|
+
type: string;
|
|
32
|
+
optional: boolean;
|
|
33
|
+
rest: boolean;
|
|
34
|
+
}[];
|
|
35
|
+
result: string;
|
|
36
|
+
};
|
|
23
37
|
id: string;
|
|
24
38
|
blockId: string;
|
|
25
39
|
name: string;
|
package/dist/git-code.js
CHANGED
|
@@ -174,7 +174,7 @@ export function captureCommit(root, ref, definitionFiles, compose, annotationsFi
|
|
|
174
174
|
throw new Error("Unsupported historical annotation model");
|
|
175
175
|
const graph = {
|
|
176
176
|
...(annotations
|
|
177
|
-
? factoryGraph(annotations, compose(graphs))
|
|
177
|
+
? factoryGraph(annotations, compose(graphs), { legacySnapshot: true })
|
|
178
178
|
: compose(graphs)),
|
|
179
179
|
codeRevision: commit,
|
|
180
180
|
};
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
import type { DefinitionGraph, Element } from "./model.js";
|
|
2
|
+
export type PublicEntry = {
|
|
3
|
+
/** Existing implementation identity. The interface is an explicit declaration,
|
|
4
|
+
* backed by this entry's real signature/schema and source evidence. */
|
|
5
|
+
implementation: string;
|
|
6
|
+
interface: Element;
|
|
7
|
+
};
|
|
8
|
+
/** Repository adapters declare reviewed public surfaces here. This does not
|
|
9
|
+
* guess interfaces for unknown callees or change application runtime behavior.
|
|
10
|
+
* Exact callee identities remain on entrypoint and on the internal delegation.
|
|
11
|
+
*/
|
|
12
|
+
export declare function interfaceMap(definition: DefinitionGraph, entries: PublicEntry[], options?: {
|
|
13
|
+
exposeAncestors?: boolean;
|
|
14
|
+
validate?: boolean;
|
|
15
|
+
}): DefinitionGraph;
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
import { assertPublicConnections } from "./public-boundaries.js";
|
|
2
|
+
/** Repository adapters declare reviewed public surfaces here. This does not
|
|
3
|
+
* guess interfaces for unknown callees or change application runtime behavior.
|
|
4
|
+
* Exact callee identities remain on entrypoint and on the internal delegation.
|
|
5
|
+
*/
|
|
6
|
+
export function interfaceMap(definition, entries, options = {}) {
|
|
7
|
+
const graph = structuredClone(definition);
|
|
8
|
+
const byId = new Map(graph.elements.map((node) => [node.id, node]));
|
|
9
|
+
const publicEntries = new Map();
|
|
10
|
+
for (const entry of entries) {
|
|
11
|
+
if (entry.interface.kind !== "interface" || !byId.has(entry.implementation))
|
|
12
|
+
throw Error(`Declare an interface for an existing implementation: ${entry.implementation}`);
|
|
13
|
+
if (!entry.interface.contract ||
|
|
14
|
+
(!entry.interface.source &&
|
|
15
|
+
!entry.interface.sources?.length &&
|
|
16
|
+
entry.interface.provenance !== "declared"))
|
|
17
|
+
throw Error(`Public interface ${entry.interface.id} needs its source contract.`);
|
|
18
|
+
if (!byId.has(entry.interface.id)) {
|
|
19
|
+
graph.elements.push(entry.interface);
|
|
20
|
+
byId.set(entry.interface.id, entry.interface);
|
|
21
|
+
}
|
|
22
|
+
else {
|
|
23
|
+
const index = graph.elements.findIndex((node) => node.id === entry.interface.id);
|
|
24
|
+
graph.elements[index] = { ...graph.elements[index], ...entry.interface };
|
|
25
|
+
byId.set(entry.interface.id, graph.elements[index]);
|
|
26
|
+
}
|
|
27
|
+
publicEntries.set(entry.implementation, entry.interface.id);
|
|
28
|
+
}
|
|
29
|
+
// An annotated member is callable through its explicitly declared interface.
|
|
30
|
+
for (const node of graph.elements)
|
|
31
|
+
if (["method", "operation"].includes(node.kind) &&
|
|
32
|
+
byId.get(node.parent || "")?.kind === "interface")
|
|
33
|
+
publicEntries.set(node.id, node.parent);
|
|
34
|
+
const within = (id, ancestor) => {
|
|
35
|
+
const seen = new Set();
|
|
36
|
+
while (byId.has(id) && !seen.has(id)) {
|
|
37
|
+
if (id === ancestor)
|
|
38
|
+
return true;
|
|
39
|
+
seen.add(id);
|
|
40
|
+
id = byId.get(id).parent || "";
|
|
41
|
+
}
|
|
42
|
+
return false;
|
|
43
|
+
};
|
|
44
|
+
const owner = (id) => {
|
|
45
|
+
const seen = new Set();
|
|
46
|
+
while (byId.has(id) && !seen.has(id)) {
|
|
47
|
+
const node = byId.get(id);
|
|
48
|
+
if (!["interface", "method", "operation", "resource", "artifact"].includes(node.kind))
|
|
49
|
+
return id;
|
|
50
|
+
seen.add(id);
|
|
51
|
+
id = node.parent || "";
|
|
52
|
+
}
|
|
53
|
+
};
|
|
54
|
+
const delegations = new Map();
|
|
55
|
+
for (const entry of entries) {
|
|
56
|
+
if (entry.interface.id === entry.implementation)
|
|
57
|
+
continue;
|
|
58
|
+
const id = `interface-implementation:${entry.interface.id}:${entry.implementation}`;
|
|
59
|
+
delegations.set(id, {
|
|
60
|
+
id,
|
|
61
|
+
source: entry.interface.id,
|
|
62
|
+
target: entry.implementation,
|
|
63
|
+
relation: "delegates",
|
|
64
|
+
label: byId.get(entry.implementation).label,
|
|
65
|
+
provenance: entry.interface.provenance,
|
|
66
|
+
sourceRef: entry.interface.source,
|
|
67
|
+
});
|
|
68
|
+
}
|
|
69
|
+
graph.connections = graph.connections.map((edge) => {
|
|
70
|
+
const receiver = byId.get(edge.target), boundary = owner(edge.target);
|
|
71
|
+
const api = publicEntries.get(edge.target);
|
|
72
|
+
if (!api ||
|
|
73
|
+
receiver?.kind === "interface" ||
|
|
74
|
+
!boundary ||
|
|
75
|
+
(within(edge.source, boundary) && edge.relation !== "exposes"))
|
|
76
|
+
return edge;
|
|
77
|
+
const declaration = byId.get(api);
|
|
78
|
+
const id = `interface-implementation:${api}:${edge.target}`;
|
|
79
|
+
delegations.set(id, {
|
|
80
|
+
id,
|
|
81
|
+
source: api,
|
|
82
|
+
target: edge.target,
|
|
83
|
+
relation: "delegates",
|
|
84
|
+
label: receiver.label,
|
|
85
|
+
provenance: declaration.provenance,
|
|
86
|
+
sourceRef: receiver?.source || declaration.source,
|
|
87
|
+
});
|
|
88
|
+
return { ...edge, target: api, entrypoint: edge.entrypoint || edge.target };
|
|
89
|
+
});
|
|
90
|
+
graph.connections = graph.connections.filter((edge) => edge.relation !== "exposes" || edge.source !== edge.target);
|
|
91
|
+
graph.connections.push(...[...delegations.values()].filter((edge) => !graph.connections.some((current) => current.id === edge.id)));
|
|
92
|
+
if (options.exposeAncestors) {
|
|
93
|
+
// Source inventories group real exported entrypoints into logical boxes.
|
|
94
|
+
// The repository adapter explicitly exposes these same contracts through
|
|
95
|
+
// its enclosing responsibilities; no duplicate facade or fake API is made.
|
|
96
|
+
for (const api of graph.elements.filter((node) => node.kind === "interface")) {
|
|
97
|
+
let parent = byId.get(api.parent || "")?.parent;
|
|
98
|
+
const seen = new Set();
|
|
99
|
+
while (parent && byId.has(parent) && !seen.has(parent)) {
|
|
100
|
+
seen.add(parent);
|
|
101
|
+
const node = byId.get(parent);
|
|
102
|
+
if (!["interface", "method", "operation"].includes(node.kind) &&
|
|
103
|
+
parent !== graph.id) {
|
|
104
|
+
const id = `public-exposure:${parent}:${api.id}`;
|
|
105
|
+
if (!graph.connections.some((edge) => edge.source === parent &&
|
|
106
|
+
edge.target === api.id &&
|
|
107
|
+
edge.relation === "exposes"))
|
|
108
|
+
graph.connections.push({
|
|
109
|
+
id,
|
|
110
|
+
source: parent,
|
|
111
|
+
target: api.id,
|
|
112
|
+
relation: "exposes",
|
|
113
|
+
label: api.label,
|
|
114
|
+
provenance: api.provenance,
|
|
115
|
+
sourceRef: api.source,
|
|
116
|
+
});
|
|
117
|
+
}
|
|
118
|
+
parent = node.parent;
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
if (options.validate !== false)
|
|
123
|
+
assertPublicConnections(graph);
|
|
124
|
+
return graph;
|
|
125
|
+
}
|
package/dist/map-quality.d.ts
CHANGED
|
@@ -3,6 +3,12 @@ import type { DefinitionGraph } from "./model.js";
|
|
|
3
3
|
* parent identities, never string prefixes or physical file locations. */
|
|
4
4
|
export declare function mapQuality(graph: DefinitionGraph): {
|
|
5
5
|
problems: string[];
|
|
6
|
+
boundaryViolations: {
|
|
7
|
+
connection: string;
|
|
8
|
+
block: string;
|
|
9
|
+
target: string;
|
|
10
|
+
reason: string;
|
|
11
|
+
}[];
|
|
6
12
|
areas: {
|
|
7
13
|
id: string;
|
|
8
14
|
label: string;
|
package/dist/map-quality.js
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { boundaryViolations } from "./public-boundaries.js";
|
|
1
2
|
/** Evidence gaps, not claims that disconnected code is unused. Ownership follows
|
|
2
3
|
* parent identities, never string prefixes or physical file locations. */
|
|
3
4
|
export function mapQuality(graph) {
|
|
@@ -33,8 +34,12 @@ export function mapQuality(graph) {
|
|
|
33
34
|
}
|
|
34
35
|
if (byId.size !== graph.elements.length)
|
|
35
36
|
problems.push("Duplicate block identities");
|
|
37
|
+
const boundaries = boundaryViolations(graph);
|
|
38
|
+
for (const issue of boundaries)
|
|
39
|
+
problems.push(`${issue.connection}: ${issue.reason}`);
|
|
36
40
|
return {
|
|
37
41
|
problems,
|
|
42
|
+
boundaryViolations: boundaries,
|
|
38
43
|
areas: graph.elements
|
|
39
44
|
.filter((node) => node.parent === graph.id)
|
|
40
45
|
.map((node) => ({
|
package/dist/model.d.ts
CHANGED
|
@@ -4,8 +4,8 @@ export type Provenance = "declared" | "source" | "inferred" | "observed" | "prop
|
|
|
4
4
|
/** The four logical shapes. Older snapshots may still contain the legacy kinds above. */
|
|
5
5
|
export type LogicalKind = "block" | "interface" | "method" | "process";
|
|
6
6
|
export interface SourceRef {
|
|
7
|
-
/**
|
|
8
|
-
scope?: "file";
|
|
7
|
+
/** File owns a module; contract references describe an API without owning its implementation. */
|
|
8
|
+
scope?: "file" | "contract";
|
|
9
9
|
file: string;
|
|
10
10
|
line: number;
|
|
11
11
|
symbol?: string;
|
|
@@ -60,6 +60,8 @@ export interface Connection {
|
|
|
60
60
|
id: string;
|
|
61
61
|
source: string;
|
|
62
62
|
target: string;
|
|
63
|
+
/** Exact callable behind a public interface; preserved source evidence. */
|
|
64
|
+
entrypoint?: string;
|
|
63
65
|
relation: Relation;
|
|
64
66
|
label: string;
|
|
65
67
|
displayLabel?: string;
|
|
@@ -156,6 +158,8 @@ export declare function projectGraph(graph: DefinitionGraph, expanded: ReadonlyS
|
|
|
156
158
|
originalSource: string;
|
|
157
159
|
originalTarget: string;
|
|
158
160
|
id: string;
|
|
161
|
+
/** Exact callable behind a public interface; preserved source evidence. */
|
|
162
|
+
entrypoint?: string;
|
|
159
163
|
relation: Relation;
|
|
160
164
|
label: string;
|
|
161
165
|
displayLabel?: string;
|
package/dist/product-map.d.ts
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
import type { DefinitionGraph } from "./model.js";
|
|
2
2
|
export interface CatalogPart {
|
|
3
|
+
/** Explicit reviewed public surface for this existing implementation ID. */
|
|
4
|
+
entryFor?: string;
|
|
3
5
|
/** Stable identity: a local slug, or a qualified ID retained when a part moves. */
|
|
4
6
|
id?: string;
|
|
5
7
|
name: string;
|