@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
@@ -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
- const interfaceId = apiNode && apis.get(apiNode);
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
- owners.set(member, block.id);
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())
@@ -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
- kind: "operation",
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: {
@@ -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): DefinitionGraph;
4
+ export declare function factoryGraph(model: FactoryModel, base?: DefinitionGraph, options?: {
5
+ legacySnapshot?: boolean;
6
+ exposeAncestors?: boolean;
7
+ }): DefinitionGraph;
@@ -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.id,
238
- target: method.blockId,
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
- return graph;
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
  }
@@ -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
+ }
@@ -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;
@@ -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
- /** Explicit implementation-module ownership; does not claim a method boundary. */
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;
@@ -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;