@principal-ai/subsystems-react 0.51.2 → 0.51.4

package/src/subsystem/c4.test.ts

@@ -1,573 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { buildC4Model, summarizeElements, labelFromPurl } from './c4';
-import type { C4Container, C4Element, C4Model } from './c4';
-import type { SubsystemModelDocument } from './model';
-
-const REPO = 'pkg:github/acme/repo';
-
-/**
- * The four element kinds as test factories.
- *
- * Separate helpers rather than one `element({ kind })`, because the point of
- * the union is that the shapes differ: a component has a `container`, a person
- * has no `technology`. A permissive factory would hide exactly what the types
- * are here to enforce.
- */
-function container(over: Partial<C4Container> & { id: string }): C4Container {
-  return {
-    kind: 'container',
-    containerKind: 'application',
-    technology: 'Bun',
-    members: [],
-    label: over.id,
-    state: 'proposed',
-    ...over,
-  };
-}
-
-function component(over: { id: string; container: string } & Partial<Omit<C4Element, 'kind'>>): C4Element {
-  return {
-    kind: 'component',
-    technology: 'React',
-    members: [],
-    label: over.id,
-    state: 'proposed',
-    ...over,
-  } as C4Element;
-}
-
-function external(over: { id: string } & Partial<C4Element>): C4Element {
-  return { kind: 'external-system', members: [], label: over.id, state: 'proposed', ...over } as C4Element;
-}
-
-function person(over: { id: string } & Partial<C4Element>): C4Element {
-  return { kind: 'person', members: [], label: over.id, state: 'proposed', ...over } as C4Element;
-}
-
-const doc: SubsystemModelDocument = {
-  components: [
-    { alias: 'a', name: 'Alpha', construct: 'function', file: 'src/a.ts', purl: `${REPO}#src/a.ts` },
-    { alias: 'b', name: 'Beta', construct: 'function', file: 'src/b.ts', purl: `${REPO}#src/b.ts` },
-    { alias: 'c', name: 'Gamma', construct: 'function', file: 'src/c.ts', purl: `${REPO}#src/c.ts` },
-    { alias: 'd', name: 'Delta', construct: 'function', file: 'src/d.ts', purl: `${REPO}#src/d.ts` },
-    { alias: 's', name: 'Cache', construct: 'store', file: 'src/s.ts', purl: `${REPO}#src/s.ts` },
-    { alias: 't', name: 'Iface', construct: 'interface', file: 'src/t.ts', purl: `${REPO}#src/t.ts` },
-  ],
-  trails: [
-    {
-      id: 'w1',
-      title: 'flow',
-      steps: [
-        { from: 'a', to: 'b', mechanism: 'calls', file: 'src/a.ts', line: 1, purl: `${REPO}#src/a.ts`, symbol: 'Alpha' },
-        { from: 'a', to: 'c', mechanism: 'calls', file: 'src/a.ts', line: 2, purl: `${REPO}#src/a.ts`, symbol: 'Alpha' },
-        { from: 'b', to: 'c', mechanism: 'reads', file: 'src/b.ts', line: 3, purl: `${REPO}#src/b.ts`, symbol: 'Beta' },
-      ],
-    },
-  ],
-};
-
-const ids = (m: C4Model, kind?: string) =>
-  m.nodes.filter((n) => !kind || n.kind === kind).map((n) => n.id);
-
-describe('buildC4Model — boxes come from the author, not a derivation', () => {
-  test('one box per element', () => {
-    const { model } = buildC4Model({
-      elements: [container({ id: 'container:x', members: ['a', 'b'] })],
-      document: doc,
-    });
-    expect(ids(model, 'container')).toEqual(['container:x']);
-  });
-
-  test('draws a box for an element the author named, with no process involved', () => {
-    // No `process` field anywhere — the membership is the author's claim.
-    const { model } = buildC4Model({
-      elements: [container({ id: 'container:invented', members: ['a'] })],
-      document: doc,
-    });
-    expect(model.nodes.find((n) => n.id === 'container:invented')).toBeDefined();
-  });
-
-  test('draws nothing nobody proposed', () => {
-    const { model, unmapped } = buildC4Model({
-      elements: [container({ id: 'container:x', members: ['a'] })],
-      document: doc,
-    });
-    expect(model.nodes).toHaveLength(1);
-    expect(unmapped.sort()).toEqual(['b', 'c', 'd', 's', 't']);
-  });
-
-  test('an empty element set yields an empty diagram, not a fallback', () => {
-    const { model, problems } = buildC4Model({ elements: [], document: doc });
-    expect(model.nodes).toHaveLength(0);
-    expect(model.edges).toHaveLength(0);
-    expect(problems).toHaveLength(0);
-  });
-
-  test('works with no document at all', () => {
-    const { model } = buildC4Model({
-      elements: [container({ id: 'container:x', members: ['a'] })],
-    });
-    expect(model.nodes).toHaveLength(1);
-    expect(model.nodes[0]!.members).toEqual(['a']);
-  });
-
-  test('resolves member constructs from the document', () => {
-    const { model } = buildC4Model({
-      elements: [container({ id: 'container:x', members: ['a', 's', 't'] })],
-      document: doc,
-    });
-    expect(model.nodes[0]!.constructs.sort()).toEqual(['function', 'interface', 'store']);
-  });
-
-  test('carries the container kind onto the drawn node', () => {
-    const { model } = buildC4Model({
-      elements: [
-        container({ id: 'container:store', containerKind: 'data-store', members: ['s'] }),
-        container({ id: 'container:app', members: ['a'] }),
-      ],
-      document: doc,
-    });
-    expect(model.nodes.find((n) => n.id === 'container:store')!.containerKind).toBe('data-store');
-    expect(model.nodes.find((n) => n.id === 'container:app')!.containerKind).toBe('application');
-  });
-});
-
-describe('the four kinds', () => {
-  test('a person carries no technology, and an external may', () => {
-    const { model } = buildC4Model({
-      elements: [
-        person({ id: 'person:op', members: ['a'] }),
-        external({ id: 'external:gh', members: ['b'], technology: 'REST' }),
-        external({ id: 'external:db', members: ['s'] }),
-      ],
-      document: doc,
-    });
-    expect(model.nodes.find((n) => n.id === 'person:op')!.technology).toBeUndefined();
-    expect(model.nodes.find((n) => n.id === 'external:gh')!.technology).toBe('REST');
-    expect(model.nodes.find((n) => n.id === 'external:db')!.technology).toBeUndefined();
-  });
-
-  test('an external system sits inside the boundary; a person does not', () => {
-    const { model } = buildC4Model({
-      elements: [
-        container({ id: 'container:x', members: ['a'] }),
-        external({ id: 'external:gh', members: ['b'] }),
-        person({ id: 'person:op', members: ['d'] }),
-        component({ id: 'component:z', container: 'container:x', members: ['c'] }),
-      ],
-      document: doc,
-    });
-    const parentOf = (id: string) => model.nodes.find((n) => n.id === id)!.parentId;
-    // C4 puts an external system inside the system boundary — it is something
-    // we depend on — and a person outside every system.
-    expect(parentOf('container:x')).toBe(model.system.id);
-    expect(parentOf('external:gh')).toBe(model.system.id);
-    expect(parentOf('person:op')).toBeUndefined();
-    expect(parentOf('component:z')).toBe('container:x');
-  });
-
-  test('the container view frames only containers', () => {
-    const { model } = buildC4Model({
-      elements: [
-        container({ id: 'container:x', members: ['a'] }),
-        external({ id: 'external:gh', members: ['b'] }),
-        person({ id: 'person:op', members: ['d'] }),
-        component({ id: 'component:z', container: 'container:x', members: ['c'] }),
-      ],
-      document: doc,
-      view: 'container',
-    });
-    expect(model.groups[0]!.memberIds).toEqual(['container:x']);
-  });
-});
-
-describe('rejection', () => {
-  test('a rejected element is not drawn', () => {
-    const { model } = buildC4Model({
-      elements: [container({ id: 'container:x', members: ['a'], state: 'rejected' })],
-      document: doc,
-    });
-    expect(model.nodes).toHaveLength(0);
-  });
-
-  test('lines into a rejected element are dropped, not left dangling', () => {
-    const { model } = buildC4Model({
-      elements: [
-        container({ id: 'container:x', members: ['a'] }),
-        container({ id: 'container:y', members: ['c'], state: 'rejected' }),
-      ],
-      document: doc,
-    });
-    for (const e of model.edges) {
-      expect(model.nodes.some((n) => n.id === e.source)).toBe(true);
-      expect(model.nodes.some((n) => n.id === e.target)).toBe(true);
-    }
-  });
-
-  test('its members become unclaimed rather than silently re-homed', () => {
-    const { unmapped } = buildC4Model({
-      elements: [
-        container({ id: 'container:x', members: ['a'] }),
-        container({ id: 'container:y', members: ['c'], state: 'rejected' }),
-      ],
-      document: doc,
-    });
-    expect(unmapped).toContain('c');
-  });
-
-  test('the system frame does not list a rejected element', () => {
-    const { model } = buildC4Model({
-      elements: [
-        container({ id: 'container:x', members: ['a'] }),
-        container({ id: 'container:y', members: ['c'], state: 'rejected' }),
-      ],
-      document: doc,
-    });
-    expect(model.groups[0]!.memberIds).toEqual(['container:x']);
-  });
-
-  test('rejecting a container orphans the components that named it', () => {
-    const { model, problems } = buildC4Model({
-      elements: [
-        container({ id: 'container:x', members: ['a'], state: 'rejected' }),
-        component({ id: 'component:z', container: 'container:x', members: ['c'] }),
-      ],
-      document: doc,
-    });
-    expect(problems.some((p) => p.kind === 'unknown_container')).toBe(true);
-    expect(model.nodes.find((n) => n.id === 'component:z')!.parentId).toBeUndefined();
-  });
-});
-
-describe('lines', () => {
-  test('trail steps become lines between the owning elements', () => {
-    const { model } = buildC4Model({
-      elements: [
-        container({ id: 'container:x', members: ['a'] }),
-        container({ id: 'container:y', members: ['b', 'c'] }),
-      ],
-      document: doc,
-    });
-    // a->b and a->c are both x->y, so they are one line, counted twice.
-    // b->c is inside y and draws nothing.
-    const e = model.edges.find((x) => x.source === 'container:x' && x.target === 'container:y');
-    expect(e?.count).toBe(2);
-    expect(e?.label).toBe('calls');
-  });
-
-  test('steps inside one element do not draw a self-loop', () => {
-    const { model } = buildC4Model({
-      elements: [container({ id: 'container:x', members: ['a', 'b', 'c'] })],
-      document: doc,
-    });
-    expect(model.edges.some((e) => e.source === e.target)).toBe(false);
-  });
-
-  test('a step between two members of one element draws no line', () => {
-    const { model } = buildC4Model({
-      elements: [
-        container({ id: 'container:x', members: ['a'] }),
-        container({ id: 'container:y', members: ['c'] }),
-      ],
-      document: doc,
-    });
-    // Only a->c is cross-element; b is claimed by nobody, and a->b dies with it.
-    expect(model.edges).toHaveLength(1);
-    expect(model.edges[0]).toMatchObject({ source: 'container:x', target: 'container:y', count: 1 });
-  });
-
-  test('several mechanisms on one line are labelled together', () => {
-    const twoTrails: SubsystemModelDocument = {
-      ...doc,
-      trails: [
-        doc.trails![0]!,
-        {
-          id: 'w2',
-          title: 'other',
-          steps: [{ from: 'a', to: 'c', mechanism: 'writes', file: 'src/a.ts', line: 9, purl: `${REPO}#src/a.ts`, symbol: 'Alpha' }],
-        },
-      ],
-    };
-    const { model } = buildC4Model({
-      elements: [
-        container({ id: 'container:x', members: ['a'] }),
-        container({ id: 'container:y', members: ['c'] }),
-      ],
-      document: twoTrails,
-    });
-    expect(model.edges[0]!.label).toBe('calls + writes');
-  });
-
-  test('a step whose endpoint nobody claims draws no line', () => {
-    const { model } = buildC4Model({
-      elements: [
-        container({ id: 'container:x', members: ['a'] }),
-        container({ id: 'container:y', members: ['b'] }),
-      ],
-      document: doc,
-    });
-    // c is claimed by nobody, so a->c and b->c cannot be drawn.
-    expect(model.edges).toHaveLength(1);
-    expect(model.edges[0]).toMatchObject({ source: 'container:x', target: 'container:y', count: 1 });
-  });
-
-  test('a line to a component beats the line to its container', () => {
-    // a->c resolves to the innermost owner of c, which is the component.
-    const { model } = buildC4Model({
-      elements: [
-        container({ id: 'container:x', members: ['a', 'b'] }),
-        container({ id: 'container:y', members: [] }),
-        component({ id: 'component:z', container: 'container:y', members: ['c'] }),
-      ],
-      document: doc,
-      view: 'component',
-    });
-    expect(model.edges.map((e) => `${e.source}->${e.target}`)).toContain('container:x->component:z');
-  });
-});
-
-describe('component level', () => {
-  test('a component nests under the container it names', () => {
-    const { model } = buildC4Model({
-      elements: [
-        container({ id: 'container:y', members: ['c'] }),
-        component({ id: 'component:z', container: 'container:y', members: ['t'] }),
-      ],
-      document: doc,
-      view: 'component',
-    });
-    expect(model.nodes.find((n) => n.id === 'component:z')!.parentId).toBe('container:y');
-  });
-
-  test('the named container wins over any shared member', () => {
-    // `c` is claimed by container:x too, but the component says it lives in y.
-    // Inferring from shared members would have put it in x.
-    const { model, problems } = buildC4Model({
-      elements: [
-        container({ id: 'container:x', members: ['a', 'b'] }),
-        container({ id: 'container:y', members: ['d'] }),
-        component({ id: 'component:z', container: 'container:y', members: ['c'] }),
-      ],
-      document: doc,
-      view: 'component',
-    });
-    expect(model.nodes.find((n) => n.id === 'component:z')!.parentId).toBe('container:y');
-    expect(problems).toHaveLength(0);
-  });
-
-  test('the container becomes a frame holding its components', () => {
-    const { model } = buildC4Model({
-      elements: [
-        container({ id: 'container:y', members: ['c'] }),
-        component({ id: 'component:z', container: 'container:y', members: ['t'] }),
-      ],
-      document: doc,
-      view: 'component',
-    });
-    expect(model.groups.some((g) => g.kind === 'container' && g.memberIds.includes('component:z'))).toBe(true);
-  });
-
-  test('a container holds its components\' members without being told twice', () => {
-    // Membership is authored once: the container must not repeat `t`. The
-    // rollup is what makes the container's count mean "everything inside me".
-    const { model, problems } = buildC4Model({
-      elements: [
-        container({ id: 'container:y', members: ['c'] }),
-        component({ id: 'component:z', container: 'container:y', members: ['t'] }),
-      ],
-      document: doc,
-    });
-    expect(problems.some((p) => p.kind === 'conflicting_member')).toBe(false);
-    expect(model.nodes.find((n) => n.id === 'container:y')!.members.sort()).toEqual(['c', 't']);
-    expect(model.nodes.find((n) => n.id === 'component:z')!.members).toEqual(['t']);
-  });
-
-  test('a component naming a container that is not in the set is reported', () => {
-    const { model, problems } = buildC4Model({
-      elements: [component({ id: 'component:z', container: 'container:absent', members: ['c'] })],
-      document: doc,
-      view: 'component',
-    });
-    expect(problems.some((p) => p.kind === 'unknown_container')).toBe(true);
-    expect(model.nodes.find((n) => n.id === 'component:z')!.parentId).toBeUndefined();
-  });
-
-  test('a component naming a non-container is reported', () => {
-    const { problems } = buildC4Model({
-      elements: [
-        external({ id: 'external:gh', members: ['d'] }),
-        component({ id: 'component:z', container: 'external:gh', members: ['c'] }),
-      ],
-      document: doc,
-      view: 'component',
-    });
-    expect(problems.some((p) => p.kind === 'unknown_container')).toBe(true);
-  });
-
-  test('a component is not drawn inside the system frame directly', () => {
-    const { model } = buildC4Model({
-      elements: [
-        container({ id: 'container:x', members: ['a', 'b'] }),
-        container({ id: 'container:y', members: [] }),
-        component({ id: 'component:z', container: 'container:x', members: ['c'] }),
-      ],
-      document: doc,
-      view: 'container',
-    });
-    expect(model.nodes.find((n) => n.id === 'component:z')!.parentId).toBe('container:x');
-    expect(model.groups[0]!.memberIds).toEqual(['container:x', 'container:y']);
-  });
-});
-
-describe('authoring problems', () => {
-  test('reports a member claimed by two elements, and keeps the first', () => {
-    const { model, problems } = buildC4Model({
-      elements: [
-        container({ id: 'container:x', members: ['a'] }),
-        container({ id: 'container:y', members: ['a'] }),
-      ],
-      document: doc,
-    });
-    expect(problems.some((p) => p.kind === 'conflicting_member')).toBe(true);
-    expect(model.nodes.find((n) => n.id === 'container:x')!.members).toEqual(['a']);
-    expect(model.nodes.find((n) => n.id === 'container:y')!.members).toEqual([]);
-  });
-
-  test('reports a member that is not in the document', () => {
-    const { problems } = buildC4Model({
-      elements: [container({ id: 'container:x', members: ['nope'] })],
-      document: doc,
-    });
-    expect(problems.some((p) => p.kind === 'unknown_member')).toBe(true);
-  });
-
-  test('reports a duplicate id and draws it once', () => {
-    const { model, problems } = buildC4Model({
-      elements: [
-        container({ id: 'container:x', members: ['a'] }),
-        container({ id: 'container:x', members: ['b'] }),
-      ],
-      document: doc,
-    });
-    expect(problems.some((p) => p.kind === 'duplicate_id')).toBe(true);
-    expect(model.nodes.filter((n) => n.id === 'container:x')).toHaveLength(1);
-  });
-
-  test('reports an element with nothing inside it', () => {
-    const { problems } = buildC4Model({
-      elements: [container({ id: 'container:x', members: [] })],
-      document: doc,
-    });
-    expect(problems.some((p) => p.kind === 'empty_element')).toBe(true);
-  });
-
-  test('a clean set reports nothing', () => {
-    const { problems } = buildC4Model({
-      elements: [container({ id: 'container:x', members: ['a', 'b'] })],
-      document: doc,
-    });
-    expect(problems).toHaveLength(0);
-  });
-});
-
-describe('system framing', () => {
-  test('derives the repo key from the members', () => {
-    const { model } = buildC4Model({
-      elements: [container({ id: 'container:x', members: ['a'] })],
-      document: doc,
-    });
-    expect(model.system.repoKey).toBe(REPO);
-    expect(model.system.label).toBe('acme/repo');
-  });
-
-  test('honours an explicit label and repo key', () => {
-    const { model } = buildC4Model({
-      elements: [container({ id: 'container:x', members: ['a'] })],
-      document: doc,
-      systemLabel: 'Acme',
-      repoKey: REPO,
-    });
-    expect(model.system.label).toBe('Acme');
-  });
-
-  test('a set with nothing repo-shaped is not attributed to a repo', () => {
-    // No document and no members, so there is no purl to attribute. Guessing a
-    // repo here would put a repo name on a boundary diagram.
-    const { model } = buildC4Model({
-      elements: [external({ id: 'external:gh', members: [] })],
-      document: { components: [], trails: [] },
-    });
-    expect(model.system.repoKey).toBeUndefined();
-    expect(model.system.label).toBe('Software System');
-  });
-
-  test('labelFromPurl trims scheme and keeps owner/name', () => {
-    expect(labelFromPurl(`${REPO}#src/a.ts`)).toBe('acme/repo');
-    expect(labelFromPurl('external:api.github.com/gists')).toBe('api.github.com/gists');
-  });
-});
-
-describe('consolidated provenance', () => {
-  test('a box that absorbed several keys says so', () => {
-    const { model } = buildC4Model({
-      elements: [container({ id: 'container:x', members: ['a'], derivedFrom: ['app/host', 'other/host'] })],
-      document: doc,
-    });
-    expect(model.nodes[0]!.derivedFrom).toEqual(['app/host', 'other/host']);
-  });
-
-  test('a single-key element carries no provenance list', () => {
-    const { model } = buildC4Model({
-      elements: [container({ id: 'container:x', members: ['a'], derivedFrom: ['app/host'] })],
-      document: doc,
-    });
-    expect(model.nodes[0]!.derivedFrom).toBeUndefined();
-  });
-});
-
-describe('summarizeElements', () => {
-  test('counts confirmed, proposed, and rejected separately', () => {
-    const s = summarizeElements([
-      container({ id: 'a', state: 'accepted' }),
-      container({ id: 'b', state: 'proposed' }),
-      container({ id: 'c', state: 'rejected' }),
-    ]);
-    expect(s).toMatchObject({ accepted: 1, proposed: 1, rejected: 1, needsDecision: 1 });
-  });
-
-  test('a rejected element still counts — the decision was made', () => {
-    const s = summarizeElements([container({ id: 'a', state: 'rejected' })]);
-    expect(s.rejected).toBe(1);
-  });
-
-  test('tallies the four kinds separately', () => {
-    const s = summarizeElements([
-      container({ id: 'c1' }),
-      container({ id: 'c2', containerKind: 'data-store' }),
-      component({ id: 'k1', container: 'c1' }),
-      external({ id: 'x1' }),
-      person({ id: 'p1' }),
-    ]);
-    expect(s).toMatchObject({ containers: 2, components: 1, externals: 1, people: 1 });
-  });
-
-  test('counts the notation gaps C4 requires on containers', () => {
-    const s = summarizeElements([
-      container({ id: 'a', state: 'accepted', technology: 'Bun' }),
-      container({ id: 'b', state: 'accepted', technology: '' }),
-    ]);
-    // `technology` is required by the type, so a gap can only be an empty
-    // string — which is what an agent that had no framework signal writes.
-    expect(s.missingTechnology).toBe(1);
-    expect(s.missingDescription).toBe(2);
-  });
-
-  test('the technology requirement does not apply to a person', () => {
-    const s = summarizeElements([
-      component({ id: 'a', container: 'container:x', state: 'accepted' }),
-      external({ id: 'b', state: 'accepted' }),
-      person({ id: 'c', state: 'accepted' }),
-    ]);
-    expect(s.missingTechnology).toBe(0);
-  });
-});