@granular-software/fractory 0.1.24 → 0.1.25

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/dist/annotations.d.ts +4 -0
  2. package/dist/compiler.js +161 -4
  3. package/dist/core.d.ts +1 -0
  4. package/dist/core.js +1 -0
  5. package/dist/declared-graph.js +2 -1
  6. package/dist/factory-graph.d.ts +4 -1
  7. package/dist/factory-graph.js +77 -6
  8. package/dist/factory-model.d.ts +14 -0
  9. package/dist/git-code.js +1 -1
  10. package/dist/interface-map.d.ts +15 -0
  11. package/dist/interface-map.js +125 -0
  12. package/dist/map-quality.d.ts +6 -0
  13. package/dist/map-quality.js +5 -0
  14. package/dist/model.d.ts +6 -2
  15. package/dist/product-map.d.ts +2 -0
  16. package/dist/product-map.js +33 -4
  17. package/dist/public-boundaries.d.ts +13 -0
  18. package/dist/public-boundaries.js +115 -0
  19. package/dist/repository-map.js +3 -1
  20. package/dist/scope.d.ts +2 -0
  21. package/dist/scope.js +77 -3
  22. package/dist/source-index.js +4 -0
  23. package/dist/source-review-git.js +3 -1
  24. package/dist/source-review.d.ts +3 -1
  25. package/dist/source-review.js +94 -14
  26. package/dist/work-check.d.ts +1 -0
  27. package/dist/work-check.js +6 -1
  28. package/dist/work-cli.js +29 -1
  29. package/dist/work-context.d.ts +2 -0
  30. package/dist/work-context.js +30 -4
  31. package/dist/work-lock-check.d.ts +12 -0
  32. package/dist/work-lock-check.js +339 -0
  33. package/dist/work-locks.d.ts +10 -0
  34. package/dist/work-locks.js +98 -0
  35. package/dist/work-model.d.ts +9 -0
  36. package/dist/work-model.js +50 -1
  37. package/package.json +1 -1
  38. package/src/annotations.ts +4 -0
  39. package/src/compiler.ts +190 -4
  40. package/src/core.ts +4 -0
  41. package/src/declared-graph.ts +2 -1
  42. package/src/factory-graph.ts +89 -5
  43. package/src/factory-model.ts +9 -0
  44. package/src/git-code.ts +1 -1
  45. package/src/interface-map.ts +166 -0
  46. package/src/map-quality.ts +5 -0
  47. package/src/model.ts +10 -3
  48. package/src/product-map.ts +51 -16
  49. package/src/public-boundaries.ts +143 -0
  50. package/src/repository-map.ts +3 -1
  51. package/src/scope.ts +92 -3
  52. package/src/source-index.ts +3 -0
  53. package/src/source-review-git.ts +3 -1
  54. package/src/source-review.ts +112 -13
  55. package/src/work-check.ts +7 -1
  56. package/src/work-cli.ts +35 -1
  57. package/src/work-context.ts +43 -3
  58. package/src/work-lock-check.ts +549 -0
  59. package/src/work-locks.ts +108 -0
  60. package/src/work-model.ts +67 -1
  61. package/toolkit/GUIDE.md +72 -23
  62. package/toolkit/SKILL.md +16 -5
  63. package/toolkit/build.json +1 -1
package/src/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
- const interfaceId = apiNode && apis.get(apiNode);
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
- owners.set(member, block.id);
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
@@ -1,4 +1,8 @@
1
1
  /** Browser/Worker-safe decorators. Discovery never imports an application to execute it. */
2
+ export {
3
+ assertPublicConnections,
4
+ publicConnectionError,
5
+ } from "./public-boundaries";
2
6
  export {
3
7
  Block,
4
8
  Interface,
@@ -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
- kind: "operation" as const,
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: {
@@ -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.id,
289
- target: method.blockId,
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
- return graph;
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
  }
@@ -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
+ }
@@ -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 = "declared" | "source" | "inferred" | "observed" | "proposed";
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
- /** Explicit implementation-module ownership; does not claim a method boundary. */
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;