@principal-ai/subsystems-react 0.51.0 → 0.51.2

package/src/subsystem/c4Evidence.test.ts

@@ -0,0 +1,386 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  deriveConcerns,
+  suggestMerges,
+  findUnassigned,
+  isRuntimeConstruct,
+  suggestContainerKind,
+  proposeElements,
+  mergeElements,
+} from './c4Evidence';
+import type { C4MemberView } from './c4Evidence';
+import type { C4Container, C4Element } from './c4';
+
+const REPO = 'pkg:github/acme/repo';
+
+function member(over: Partial<C4MemberView> & { alias: string }): C4MemberView {
+  return { construct: 'function', purl: `${REPO}#src/x.ts`, ...over };
+}
+
+describe('isRuntimeConstruct', () => {
+  test('only code that runs can be inside a deployable unit', () => {
+    expect(isRuntimeConstruct('function')).toBe(true);
+    expect(isRuntimeConstruct('class')).toBe(true);
+    expect(isRuntimeConstruct('custom_entity')).toBe(true);
+  });
+
+  test('types, stores, and externals do not run', () => {
+    for (const c of ['interface', 'type_alias', 'enum', 'store', 'external', 'method']) {
+      expect(isRuntimeConstruct(c)).toBe(false);
+    }
+  });
+});
+
+describe('deriveConcerns — questions, not answers', () => {
+  test('flags a lone member as a singleton', () => {
+    const out = deriveConcerns('graphify/extract', [member({ alias: 'x' })]);
+    expect(out.some((c) => c.kind === 'singleton')).toBe(true);
+  });
+
+  test('flags a group with no runtime member as library-shaped', () => {
+    const out = deriveConcerns(
+      'subsystems-core',
+      [
+        member({ alias: 'a', construct: 'interface' }),
+        member({ alias: 'b', construct: 'type_alias' }),
+      ],
+      { frameworks: [] },
+    );
+    expect(out.some((c) => c.kind === 'library_shaped')).toBe(true);
+  });
+
+  test('a single non-runtime member is also library-shaped', () => {
+    const out = deriveConcerns('shared', [member({ alias: 'a', construct: 'type_alias' })]);
+    expect(out.some((c) => c.kind === 'library_shaped')).toBe(true);
+  });
+
+  test('flags a runtime container with no technology signal', () => {
+    const out = deriveConcerns('p2', [member({ alias: 'c' })], { frameworks: [] });
+    expect(out.some((c) => c.kind === 'missing_technology')).toBe(true);
+  });
+
+  test('does not demand technology once a framework is present', () => {
+    const out = deriveConcerns(
+      'p1',
+      [member({ alias: 'a' }), member({ alias: 'b' })],
+      { frameworks: ['react'] },
+    );
+    expect(out.some((c) => c.kind === 'missing_technology')).toBe(false);
+  });
+
+  test('flags members spanning two repo keys', () => {
+    const out = deriveConcerns('p1', [
+      member({ alias: 'a' }),
+      member({ alias: 'z', purl: 'pkg:github/other/thing#z.ts' }),
+    ]);
+    expect(out.some((c) => c.kind === 'spans_repos')).toBe(true);
+  });
+
+  test('flags a store with no storage kind', () => {
+    const out = deriveConcerns('p1', [
+      member({ alias: 'a' }),
+      member({ alias: 's', construct: 'store', declaration: { kind: 'store', properties: [] } }),
+    ]);
+    expect(out.some((c) => c.kind === 'store_unclassified')).toBe(true);
+  });
+
+  test('does not flag a store that declared its storage', () => {
+    const out = deriveConcerns('p1', [
+      member({ alias: 'a' }),
+      member({ alias: 's', construct: 'store', declaration: { kind: 'store', storage: 'memory' } }),
+    ]);
+    expect(out.some((c) => c.kind === 'store_unclassified')).toBe(false);
+  });
+
+  test('flags an external with no resolvable identity', () => {
+    const out = deriveConcerns('p1', [
+      member({ alias: 'a' }),
+      member({ alias: 'x', construct: 'external', purl: 'external' }),
+    ]);
+    expect(out.some((c) => c.kind === 'external_unidentified')).toBe(true);
+  });
+
+  test('does not flag an external that has a real purl', () => {
+    const out = deriveConcerns('p1', [
+      member({ alias: 'a' }),
+      member({ alias: 'x', construct: 'external', purl: 'pkg:npm/some-pkg' }),
+    ]);
+    expect(out.some((c) => c.kind === 'external_unidentified')).toBe(false);
+  });
+
+  test('a healthy container raises nothing', () => {
+    const out = deriveConcerns(
+      'subsystems-studio/host',
+      [
+        member({ alias: 'a' }),
+        member({ alias: 'b' }),
+        member({ alias: 's', construct: 'store', declaration: { kind: 'store', storage: 'memory' } }),
+      ],
+      { frameworks: ['bun'] },
+    );
+    expect(out).toHaveLength(0);
+  });
+
+  test('never returns a decision — only concerns', () => {
+    const out = deriveConcerns('graphify/extract', [member({ alias: 'x' })]);
+    // Every field describes something to look at, never a verdict.
+    for (const c of out) {
+      expect(typeof c.kind).toBe('string');
+      expect(c.message.length).toBeGreaterThan(0);
+      expect(c.message).not.toMatch(/^\s*(is|use)\b/i);
+    }
+  });
+});
+
+describe('suggestMerges', () => {
+  test('groups keys that share a trailing role', () => {
+    const out = suggestMerges([
+      { key: 'subsystems-studio/host', memberCount: 9 },
+      { key: 'principal-studio/host', memberCount: 1 },
+      { key: 'subsystems-studio/renderer', memberCount: 5 },
+    ]);
+    expect(out).toHaveLength(1);
+    expect(out[0]!.role).toBe('host');
+    expect(out[0]!.keys).toEqual(['principal-studio/host', 'subsystems-studio/host']);
+  });
+
+  test('ignores a bare key with no app/role shape', () => {
+    const out = suggestMerges([
+      { key: 'subsystems-react', memberCount: 2 },
+      { key: 'subsystems-core', memberCount: 1 },
+    ]);
+    expect(out).toHaveLength(0);
+  });
+
+  test('frames the finding as a question', () => {
+    const out = suggestMerges([
+      { key: 'a/host', memberCount: 1 },
+      { key: 'b/host', memberCount: 1 },
+    ]);
+    expect(out[0]!.reason).toContain('or two units?');
+  });
+});
+
+describe('findUnassigned', () => {
+  test('returns runtime components that state no process', () => {
+    const out = findUnassigned([
+      member({ alias: 'a' }),
+      member({ alias: 'b', process: 'p1' }),
+      member({ alias: 'i', construct: 'interface' }),
+    ]);
+    expect(out.map((m) => m.alias)).toEqual(['a']);
+  });
+});
+
+describe('suggestContainerKind', () => {
+  test('disk- or externally-backed stores make a data store', () => {
+    for (const storage of ['disk', 'external']) {
+      const members = [
+        member({ alias: 'a' }),
+        member({ alias: 's', construct: 'store', declaration: { kind: 'store', storage } }),
+      ];
+      expect(suggestContainerKind(members)).toBe('data-store');
+    }
+  });
+
+  test('in-memory state stays an application, not a data store', () => {
+    const members = [
+      member({ alias: 'a' }),
+      member({ alias: 's', construct: 'store', declaration: { kind: 'store', storage: 'memory' } }),
+    ];
+    expect(suggestContainerKind(members)).toBe('application');
+  });
+
+  test('defaults to application when the evidence is thin', () => {
+    expect(suggestContainerKind([member({ alias: 'a' })])).toBe('application');
+  });
+
+  test('there is no library answer, even for a library-shaped group', () => {
+    // The kinds are application | data-store. A package of interfaces still
+    // comes back `application`, with the question left to a person in the
+    // `library_shaped` concern. Returning `library` here would put a non-C4
+    // concept into the vocabulary.
+    const members = [member({ alias: 'a', construct: 'interface' })];
+    expect(deriveConcerns('x', members).some((c) => c.kind === 'library_shaped')).toBe(true);
+    expect(suggestContainerKind(members)).toBe('application');
+  });
+});
+
+describe('proposeElements', () => {
+  const rollup = [
+    {
+      key: 'subsystems-studio/host',
+      frameworks: ['bun'],
+      members: [
+        member({ alias: 'a' }),
+        member({ alias: 's', construct: 'store', declaration: { kind: 'store', storage: 'disk' } }),
+      ],
+    },
+    {
+      key: 'subsystems-core',
+      frameworks: [],
+      members: [member({ alias: 'i', construct: 'interface' })],
+    },
+  ];
+
+  test('proposes one element per derived key, never accepted', () => {
+    const set = proposeElements({ repoKey: REPO, rollup });
+    expect(set.elements).toHaveLength(2);
+    expect(set.elements.every((e) => e.state === 'proposed')).toBe(true);
+  });
+
+  test('every proposal is a container, since a key names a process', () => {
+    const set = proposeElements({ repoKey: REPO, rollup });
+    expect(set.elements.every((e) => e.kind === 'container')).toBe(true);
+  });
+
+  test('every proposal carries the open questions as its rationale', () => {
+    const set = proposeElements({ repoKey: REPO, rollup });
+    const core = set.elements.find((e) => e.derivedFrom?.includes('subsystems-core'))!;
+    expect(core.rationale).toContain('library');
+  });
+
+  test('a healthy key gets no rationale, because there is nothing to ask', () => {
+    const set = proposeElements({
+      repoKey: REPO,
+      rollup: [
+        {
+          key: 'app/host',
+          frameworks: ['bun'],
+          members: [member({ alias: 'a' }), member({ alias: 'b' })],
+        },
+      ],
+    });
+    expect(set.elements[0]!.rationale).toBeUndefined();
+  });
+
+  test('members are named, not inferred from the key', () => {
+    const set = proposeElements({ repoKey: REPO, rollup });
+    const host = set.elements.find((e) => e.derivedFrom?.includes('subsystems-studio/host'))!;
+    expect(host.members).toEqual(['a', 's']);
+  });
+
+  test('a key with no framework signal gets an empty technology, not a guess', () => {
+    // `technology` is required by the type, and `summarizeElements` reports the
+    // gap. Writing "TypeScript" here would be the derivation this module does
+    // not do.
+    const set = proposeElements({ repoKey: REPO, rollup });
+    const core = set.elements.find((e) => e.derivedFrom?.includes('subsystems-core'))!;
+    expect((core as C4Container).technology).toBe('');
+  });
+
+  test('the set is sorted by id, so a review list is stable', () => {
+    const set = proposeElements({ repoKey: REPO, rollup });
+    expect(set.elements.map((e) => e.id)).toEqual([...set.elements.map((e) => e.id)].sort());
+  });
+});
+
+describe('mergeElements', () => {
+  function container(over: Partial<C4Container> & { id: string }): C4Container {
+    return {
+      kind: 'container',
+      containerKind: 'application',
+      technology: 'Bun',
+      members: [],
+      label: over.id,
+      state: 'proposed',
+      ...over,
+    };
+  }
+
+  const set: C4Element[] = [
+    container({ id: 'container:big', derivedFrom: ['subsystems-studio/host'], members: ['a', 'b', 'c'] }),
+    container({ id: 'container:small', derivedFrom: ['principal-studio/host'], members: ['z'] }),
+    container({ id: 'container:other', derivedFrom: ['site/web'], members: ['w'] }),
+  ];
+
+  test('folds the named keys into one element holding both member sets', () => {
+    const out = mergeElements(set, ['subsystems-studio/host', 'principal-studio/host']);
+    expect(out).toHaveLength(2);
+    const host = out.find((e) => e.id === 'container:big')!;
+    expect(host.members.sort()).toEqual(['a', 'b', 'c', 'z']);
+    expect(host.derivedFrom!.sort()).toEqual(['principal-studio/host', 'subsystems-studio/host']);
+  });
+
+  test('the evidence-heavy side survives by default', () => {
+    // container:big holds 3 members and container:small holds 1.
+    const out = mergeElements(set, ['subsystems-studio/host', 'principal-studio/host']);
+    expect(out.some((e) => e.id === 'container:big')).toBe(true);
+    expect(out.some((e) => e.id === 'container:small')).toBe(false);
+  });
+
+  test('a caller can override which side survives', () => {
+    const out = mergeElements(
+      set,
+      ['subsystems-studio/host', 'principal-studio/host'],
+      'container:small',
+    );
+    expect(out.some((e) => e.id === 'container:small')).toBe(true);
+  });
+
+  test('leaves unrelated elements alone', () => {
+    const out = mergeElements(set, ['subsystems-studio/host', 'principal-studio/host']);
+    expect(out.some((e) => e.id === 'container:other')).toBe(true);
+  });
+
+  test('a merge with nothing to absorb is a no-op', () => {
+    expect(mergeElements(set, ['subsystems-studio/host'])).toHaveLength(3);
+  });
+
+  test('is a no-op when only one side is present', () => {
+    expect(mergeElements(set, ['nope/nothing', 'site/web'])).toHaveLength(3);
+  });
+
+  test('refuses to fold a component into another element', () => {
+    // A component has a required `container`, so absorbing one would silently
+    // repoint it at a parent the caller never agreed to.
+    const withComponent: C4Element[] = [
+      container({ id: 'container:a', derivedFrom: ['x/host'], members: ['a'] }),
+      {
+        kind: 'component',
+        container: 'container:a',
+        technology: 'React',
+        members: ['b'],
+        label: 'component:b',
+        state: 'proposed',
+        derivedFrom: ['y/host'],
+      },
+    ];
+    expect(mergeElements(withComponent, ['x/host', 'y/host'])).toHaveLength(2);
+  });
+
+  test('does not touch the input set', () => {
+    mergeElements(set, ['subsystems-studio/host', 'principal-studio/host']);
+    expect(set).toHaveLength(3);
+  });
+
+  test('is idempotent', () => {
+    const once = mergeElements(set, ['subsystems-studio/host', 'principal-studio/host']);
+    expect(mergeElements(once, ['subsystems-studio/host', 'principal-studio/host'])).toEqual(once);
+  });
+
+  test('keeps the confirmed attributes of the survivor', () => {
+    const withTech = set.map((e) =>
+      e.id === 'container:big' ? { ...e, technology: 'Electrobun', state: 'accepted' as const } : e,
+    );
+    const out = mergeElements(withTech, ['subsystems-studio/host', 'principal-studio/host']);
+    expect(out.find((e) => e.id === 'container:big')).toMatchObject({
+      technology: 'Electrobun',
+      state: 'accepted',
+    });
+  });
+
+  test('both rationales survive, so the decision is still readable', () => {
+    const annotated = set.map((e) =>
+      e.id === 'container:big'
+        ? { ...e, rationale: 'two app names, one process' }
+        : e.id === 'container:small'
+          ? { ...e, rationale: 'one member' }
+          : e,
+    );
+    const out = mergeElements(annotated, ['subsystems-studio/host', 'principal-studio/host']);
+    const host = out.find((e) => e.id === 'container:big')!;
+    expect(host.rationale).toContain('two app names');
+    expect(host.rationale).toContain('one member');
+  });
+});