conductor.test.ts

import pathlib from 'path';
import type { ResolvedBundle } from '@sourceacademy/modules-repotools/types';
import * as td from 'typedoc';
import { describe, expect, it, vi } from 'vitest';
import { normalizeConductorDocs, normalizeConductorType } from '../conductor/index.js';
import { initTypedocForJson } from '../typedoc.js';

vi.setConfig({
  testTimeout: 10000
});

function createProject() {
  return new td.ProjectReflection('test', new td.FileRegistry());
}

function register<T extends td.Reflection>(project: td.ProjectReflection, reflection: T) {
  project.registerReflection(reflection, undefined, undefined);
  return reflection;
}

function conductorReference(project: td.ProjectReflection, name: string, qualifiedName = name) {
  const reference = td.ReferenceType.createBrokenReference(name, project, '@sourceacademy/conductor');
  reference.qualifiedName = qualifiedName;
  return reference;
}

function dataType(project: td.ProjectReflection, name: string) {
  return conductorReference(project, name, `DataType.${name}`);
}

function typedValue(project: td.ProjectReflection, typeName: string) {
  const reference = conductorReference(project, 'ITypedValue');
  reference.typeArguments = [dataType(project, typeName)];
  return reference;
}

function asyncGenerator(project: td.ProjectReflection, returnType: td.SomeType) {
  const reference = td.ReferenceType.createBrokenReference('AsyncGenerator', project, 'typescript');
  reference.typeArguments = [
    new td.IntrinsicType('void'),
    returnType,
    new td.UnknownType('unknown')
  ];
  return reference;
}

function createParameter(
  project: td.ProjectReflection,
  signature: td.SignatureReflection,
  name: string,
  type: td.SomeType
) {
  const parameter = register(
    project,
    new td.ParameterReflection(name, td.ReflectionKind.Parameter, signature)
  );
  parameter.type = type;
  return parameter;
}

describe(normalizeConductorType, () => {
  it('maps TypedValue numbers to native numbers', () => {
    const project = createProject();
    const normalized = normalizeConductorType(typedValue(project, 'NUMBER'), project);

    expect(normalized.stringify(td.TypeContext.none)).toEqual('number');
  });

  it('maps closures to Function', () => {
    const project = createProject();
    const normalized = normalizeConductorType(typedValue(project, 'CLOSURE'), project);

    expect(normalized.stringify(td.TypeContext.none)).toEqual('Function');
  });

  it('unwraps AsyncGenerator return values', () => {
    const project = createProject();
    const normalized = normalizeConductorType(
      asyncGenerator(project, typedValue(project, 'NUMBER')),
      project
    );

    expect(normalized.stringify(td.TypeContext.none)).toEqual('number');
  });

  it('leaves native types unchanged', () => {
    const project = createProject();
    const nativeType = new td.ArrayType(new td.IntrinsicType('string'));
    const normalized = normalizeConductorType(nativeType, project);

    expect(normalized.stringify(td.TypeContext.none)).toEqual('string[]');
  });
});

describe(normalizeConductorDocs, () => {
  it('promotes plugin methods and removes Conductor implementation details', () => {
    const project = createProject();

    const implementation = register(
      project,
      new td.DeclarationReflection('repeat', td.ReflectionKind.Function, project)
    );
    project.addChild(implementation);

    const implementationSignature = register(
      project,
      new td.SignatureReflection('repeat', td.ReflectionKind.CallSignature, implementation)
    );
    implementation.signatures = [implementationSignature];
    implementationSignature.comment = new td.Comment([
      { kind: 'text', text: 'Returns a repeated function.' }
    ]);
    implementationSignature.parameters = [
      createParameter(project, implementationSignature, 'evaluator', conductorReference(project, 'IDataHandler')),
      createParameter(project, implementationSignature, 'func', typedValue(project, 'CLOSURE')),
      createParameter(project, implementationSignature, 'n', typedValue(project, 'NUMBER'))
    ];
    implementationSignature.type = asyncGenerator(project, typedValue(project, 'CLOSURE'));

    const plugin = register(
      project,
      new td.DeclarationReflection('default', td.ReflectionKind.Class, project)
    );
    project.addChild(plugin);
    plugin.extendedTypes = [
      conductorReference(project, 'RenamedModulePluginBase')
    ];

    const exportedNames = register(
      project,
      new td.DeclarationReflection('exportedNames', td.ReflectionKind.Property, plugin)
    );
    plugin.addChild(exportedNames);
    exportedNames.type = new td.TypeOperatorType(
      new td.TupleType([new td.LiteralType('repeat')]),
      'readonly'
    );

    const method = register(
      project,
      new td.DeclarationReflection('repeat', td.ReflectionKind.Method, plugin)
    );
    plugin.addChild(method);

    const methodSignature = register(
      project,
      new td.SignatureReflection('repeat', td.ReflectionKind.CallSignature, method)
    );
    method.signatures = [methodSignature];
    methodSignature.parameters = [
      createParameter(project, methodSignature, 'func', typedValue(project, 'CLOSURE')),
      createParameter(project, methodSignature, 'n', typedValue(project, 'NUMBER'))
    ];
    methodSignature.type = asyncGenerator(project, typedValue(project, 'CLOSURE'));

    const classesGroup = new td.ReflectionGroup('Classes', project);
    classesGroup.children = [plugin];
    const functionsGroup = new td.ReflectionGroup('Functions', project);
    functionsGroup.children = [implementation];
    project.groups = [classesGroup, functionsGroup];

    normalizeConductorDocs(project);

    expect(project.children?.map(child => child.name)).toEqual(['repeat']);
    expect(project.groups?.map(group => group.title)).toEqual(['Functions']);

    const publicFunction = project.children?.[0];
    expect(publicFunction?.kind).toEqual(td.ReflectionKind.Function);

    const [signature] = publicFunction?.signatures ?? [];
    expect(signature.comment?.summary.map(({ text }) => text).join('')).toEqual('Returns a repeated function.');
    expect(signature.parameters?.map(parameter => [
      parameter.name,
      parameter.type?.stringify(td.TypeContext.none)
    ])).toEqual([
      ['func', 'Function'],
      ['n', 'number']
    ]);
    expect(signature.type?.stringify(td.TypeContext.none)).toEqual('Function');
  });

  it('normalizes the migrated repeat bundle docs', async () => {
    const repeatBundle: ResolvedBundle = {
      type: 'bundle',
      name: 'repeat',
      manifest: {},
      directory: pathlib.resolve(import.meta.dirname, '../../../../../../src/bundles/repeat')
    };
    const app = await initTypedocForJson(repeatBundle, td.LogLevel.None);
    const project = await app.convert();
    expect(project).toBeDefined();

    normalizeConductorDocs(project!);

    const names = project!.children?.map(child => child.name);
    expect(names).toEqual(expect.arrayContaining(['repeat', 'twice', 'thrice']));
    expect(names).not.toContain('default');

    const publicFunctions = project!.children?.filter(child => {
      return child.kind === td.ReflectionKind.Function
        && ['repeat', 'twice', 'thrice'].includes(child.name);
    }) ?? [];
    const signatureText = publicFunctions
      .flatMap(func => func.signatures ?? [])
      .map(signature => [
        signature.parameters?.map(parameter => parameter.type?.stringify(td.TypeContext.none)).join(', '),
        signature.type?.stringify(td.TypeContext.none)
      ].join(' => '))
      .join('\n');

    expect(signatureText).not.toContain('AsyncGenerator');
    expect(signatureText).not.toContain('ITypedValue');
    expect(publicFunctions.find(func => func.name === 'repeat')?.signatures?.[0].parameters?.map(parameter => parameter.name))
      .toEqual(['func', 'n']);
  });
});