@cparra/apexdocs 2.24.0 → 2.25.0-alpha.1

package/src/adapters/__tests__/references.spec.ts

@@ -0,0 +1,115 @@
+import { replaceInlineReferences } from '../references';
+import { Link } from '../../core/renderable/types';
+
+function getFileLink(typeName: string): Link {
+  return {
+    title: typeName,
+    url: `/api/${typeName}.html`,
+  };
+}
+
+function getEmailLink(typeName: string) {
+  return {
+    title: typeName,
+    url: `mailto:${typeName}`,
+  };
+}
+
+describe('reference utilities', () => {
+  it('returns a RenderableContent array with the full string when there are no links', () => {
+    const text = 'This is a test';
+    const result = replaceInlineReferences(text, getFileLink, getEmailLink);
+
+    const expected = ['This is a test'];
+
+    expect(result).toEqual(expected);
+  });
+
+  describe('replace inline links', () => {
+    it('replaces links in the format of <<ClassName>>', () => {
+      const text = 'This is a test <<ClassName>>.';
+      const result = replaceInlineReferences(text, getFileLink, getEmailLink);
+
+      const expected = [
+        'This is a test ',
+        {
+          title: 'ClassName',
+          url: '/api/ClassName.html',
+        },
+        '.',
+      ];
+
+      expect(result).toEqual(expected);
+    });
+    it('replaces links in the format of {@link ClassName}', () => {
+      function getFileLinkByTypeName(typeName: string): Link {
+        return {
+          title: typeName,
+          url: `/api/${typeName}.html`,
+        };
+      }
+
+      const text = 'This is a test {@link ClassName}';
+      const result = replaceInlineReferences(text, getFileLinkByTypeName, getEmailLink);
+
+      const expected = [
+        'This is a test ',
+        {
+          title: 'ClassName',
+          url: '/api/ClassName.html',
+        },
+      ];
+
+      expect(result).toEqual(expected);
+    });
+  });
+
+  describe('replace inline emails', () => {
+    it('replaces emails in the format of {@email email-address}', () => {
+      function getLinkByTypeName(typeName: string) {
+        return {
+          title: typeName,
+          url: `mailto:${typeName}`,
+        };
+      }
+
+      const text = 'This is an email {@email example@example.com}';
+      const result = replaceInlineReferences(text, getFileLink, getLinkByTypeName);
+
+      const expected = [
+        'This is an email ',
+        {
+          title: 'example@example.com',
+          url: 'mailto:example@example.com',
+        },
+      ];
+
+      expect(result).toEqual(expected);
+    });
+  });
+
+  it('replaces both links and emails in the same string', () => {
+    const text = 'This is a test <<ClassName>>, and {@link AnotherClass}, and an email {@email testerson}';
+    const result = replaceInlineReferences(text, getFileLink, getEmailLink);
+
+    const expected = [
+      'This is a test ',
+      {
+        title: 'ClassName',
+        url: '/api/ClassName.html',
+      },
+      ', and ',
+      {
+        title: 'AnotherClass',
+        url: '/api/AnotherClass.html',
+      },
+      ', and an email ',
+      {
+        title: 'testerson',
+        url: 'mailto:testerson',
+      },
+    ];
+
+    expect(result).toEqual(expected);
+  });
+});

package/src/adapters/apex-types.ts

@@ -0,0 +1,224 @@
+import { ClassMirror, EnumMirror, InterfaceMirror, Type } from '@cparra/apex-reflection';
+import {
+  RenderableType,
+  RenderableClass,
+  RenderableEnum,
+  RenderableInterface,
+  Renderable,
+  RenderableSection,
+  GroupedMember,
+} from '../core/renderable/types';
+import { adaptDescribable, adaptDocumentable } from './documentables';
+import { GetRenderableContentByTypeName, linkFromTypeNameGenerator } from './references';
+import { FieldMirrorWithInheritance, PropertyMirrorWithInheritance } from '../model/inheritance';
+import { adaptConstructor, adaptMethod } from './methods-and-constructors';
+import { adaptFieldOrProperty } from './fields-and-properties';
+
+function baseTypeAdapter(
+  type: EnumMirror | InterfaceMirror | ClassMirror,
+  linkGenerator: GetRenderableContentByTypeName,
+  baseHeadingLevel: number,
+): RenderableType {
+  function getHeading(type: Type): string {
+    const suffixMap = {
+      class: 'Class',
+      interface: 'Interface',
+      enum: 'Enum',
+    };
+
+    return `${type.name} ${suffixMap[type.type_name]}`;
+  }
+
+  return {
+    headingLevel: baseHeadingLevel,
+    heading: getHeading(type),
+    doc: adaptDocumentable(type, linkGenerator, baseHeadingLevel + 1),
+    name: type.name,
+    meta: {
+      accessModifier: type.access_modifier,
+    },
+  };
+}
+
+export function typeToRenderableType(
+  type: Type,
+  linkGenerator: GetRenderableContentByTypeName,
+  namespace?: string,
+): Renderable {
+  function getRenderable() {
+    switch (type.type_name) {
+      case 'enum':
+        return enumTypeToEnumSource(type as EnumMirror, linkGenerator);
+      case 'interface':
+        return interfaceTypeToInterfaceSource(type as InterfaceMirror, linkGenerator);
+      case 'class':
+        return classTypeToClassSource(type as ClassMirror, linkGenerator);
+    }
+  }
+
+  return {
+    ...getRenderable(),
+    namespace,
+  };
+}
+
+export function enumTypeToEnumSource(
+  enumType: EnumMirror,
+  linkGenerator: GetRenderableContentByTypeName,
+  baseHeadingLevel: number = 1,
+): RenderableEnum {
+  return {
+    type: 'enum',
+    ...baseTypeAdapter(enumType, linkGenerator, baseHeadingLevel),
+    values: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Values',
+      value: enumType.values.map((value) => ({
+        ...adaptDescribable(value.docComment?.descriptionLines, linkGenerator),
+        value: value.name,
+      })),
+    },
+  };
+}
+
+export function interfaceTypeToInterfaceSource(
+  interfaceType: InterfaceMirror,
+  linkGenerator: GetRenderableContentByTypeName,
+  baseHeadingLevel: number = 1,
+): RenderableInterface {
+  return {
+    type: 'interface',
+    ...baseTypeAdapter(interfaceType, linkGenerator, baseHeadingLevel),
+    extends: interfaceType.extended_interfaces.map(linkFromTypeNameGenerator),
+    methods: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Methods',
+      value: interfaceType.methods.map((method) => adaptMethod(method, linkGenerator, baseHeadingLevel + 2)),
+    },
+  };
+}
+
+export function classTypeToClassSource(
+  classType: ClassMirror,
+  linkGenerator: GetRenderableContentByTypeName,
+  baseHeadingLevel: number = 1,
+): RenderableClass {
+  return {
+    type: 'class',
+    ...baseTypeAdapter(classType, linkGenerator, baseHeadingLevel),
+    classModifier: classType.classModifier,
+    sharingModifier: classType.sharingModifier,
+    implements: classType.implemented_interfaces.map(linkFromTypeNameGenerator),
+    extends: classType.extended_class ? linkFromTypeNameGenerator(classType.extended_class) : undefined,
+    methods: adaptMembers('Methods', classType.methods, adaptMethod, linkFromTypeNameGenerator, baseHeadingLevel + 1),
+    constructors: adaptMembers(
+      'Constructors',
+      classType.constructors,
+      (constructor, linkGenerator, baseHeadingLevel) =>
+        adaptConstructor(classType.name, constructor, linkGenerator, baseHeadingLevel),
+      linkFromTypeNameGenerator,
+      baseHeadingLevel + 1,
+    ),
+    fields: adaptMembers(
+      'Fields',
+      classType.fields as FieldMirrorWithInheritance[],
+      adaptFieldOrProperty,
+      linkFromTypeNameGenerator,
+      baseHeadingLevel + 1,
+    ),
+    properties: adaptMembers(
+      'Properties',
+      classType.properties as PropertyMirrorWithInheritance[],
+      adaptFieldOrProperty,
+      linkFromTypeNameGenerator,
+      baseHeadingLevel + 1,
+    ),
+    innerClasses: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Classes',
+      value: classType.classes.map((innerClass) =>
+        classTypeToClassSource(innerClass, linkGenerator, baseHeadingLevel + 2),
+      ),
+    },
+    innerEnums: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Enums',
+      value: classType.enums.map((innerEnum) => enumTypeToEnumSource(innerEnum, linkGenerator, baseHeadingLevel + 2)),
+    },
+    innerInterfaces: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Interfaces',
+      value: classType.interfaces.map((innerInterface) =>
+        interfaceTypeToInterfaceSource(innerInterface, linkGenerator, baseHeadingLevel + 2),
+      ),
+    },
+  };
+}
+
+type Groupable = { group?: string; groupDescription?: string };
+
+function adaptMembers<T extends Groupable, K>(
+  heading: string,
+  members: T[],
+  adapter: (member: T, linkGenerator: GetRenderableContentByTypeName, baseHeadingLevel: number) => K,
+  linkFromTypeNameGenerator: GetRenderableContentByTypeName,
+  headingLevel: number,
+): RenderableSection<K[] | GroupedMember<K>[]> & { isGrouped: boolean } {
+  return {
+    headingLevel,
+    heading,
+    isGrouped: hasGroup(members),
+    value: hasGroup(members)
+      ? toGroupedMembers(members, adapter, linkFromTypeNameGenerator, headingLevel + 1)
+      : toFlat(members, adapter, linkFromTypeNameGenerator, headingLevel + 1),
+  };
+}
+
+function hasGroup(members: Groupable[]): boolean {
+  return members.some((member) => member.group);
+}
+
+function toFlat<T extends Groupable, K>(
+  members: T[],
+  adapter: (member: T, linkGenerator: GetRenderableContentByTypeName, baseHeadingLevel: number) => K,
+  linkGenerator: GetRenderableContentByTypeName,
+  baseHeadingLevel: number,
+): K[] {
+  return members.map((member) => adapter(member, linkGenerator, baseHeadingLevel));
+}
+
+function toGroupedMembers<T extends Groupable, K>(
+  members: T[],
+  adapter: (member: T, linkGenerator: GetRenderableContentByTypeName, baseHeadingLevel: number) => K,
+  linkGenerator: GetRenderableContentByTypeName,
+  baseHeadingLevel: number,
+): GroupedMember<K>[] {
+  const groupedMembers = groupByGroupName(members);
+  return Object.entries(groupedMembers).map(([groupName, members]) =>
+    singleGroup(baseHeadingLevel, groupName, adapter, members, linkGenerator),
+  );
+}
+
+function groupByGroupName<T extends Groupable>(members: T[]): Record<string, T[]> {
+  return members.reduce((acc, member) => {
+    const groupName = member.group ?? 'Other';
+    acc[groupName] = acc[groupName] ?? [];
+    acc[groupName].push(member);
+    return acc;
+  }, {} as Record<string, T[]>);
+}
+
+function singleGroup<T extends Groupable, K>(
+  headingLevel: number,
+  groupName: string,
+  adapter: (member: T, linkGenerator: GetRenderableContentByTypeName, baseHeadingLevel: number) => K,
+  members: T[],
+  linkGenerator: GetRenderableContentByTypeName,
+): GroupedMember<K> {
+  return {
+    headingLevel: headingLevel,
+    heading: groupName,
+    groupDescription: members[0].groupDescription, // All fields in the group have the same description
+    value: toFlat(members, adapter, linkGenerator, headingLevel + 1),
+  };
+}

package/src/adapters/documentables.ts

@@ -0,0 +1,93 @@
+import { CustomTag, RenderableDocumentation, RenderableContent } from '../core/renderable/types';
+import { Describable, Documentable } from './types';
+import { GetRenderableContentByTypeName, replaceInlineReferences } from './references';
+import { isEmptyLine } from './type-utils';
+
+export function adaptDescribable(
+  describable: Describable,
+  linkGenerator: GetRenderableContentByTypeName,
+): {
+  description?: RenderableContent[];
+} {
+  function describableToRenderableContent(describable: Describable): RenderableContent[] | undefined {
+    if (!describable) {
+      return;
+    }
+
+    return (
+      describable
+        .map<RenderableContent[]>((line) => [
+          ...replaceInlineReferences(line, linkGenerator),
+          {
+            type: 'empty-line',
+          },
+        ])
+        .flatMap((line) => line)
+        // If the last element is an empty line, remove it
+        .filter((line, index, lines) => !(isEmptyLine(line) && index === lines.length - 1))
+    );
+  }
+
+  return {
+    description: describableToRenderableContent(describable),
+  };
+}
+
+export function adaptDocumentable(
+  documentable: Documentable,
+  linkGenerator: GetRenderableContentByTypeName,
+  subHeadingLevel: number,
+): RenderableDocumentation {
+  function extractCustomTags(type: Documentable): CustomTag[] {
+    const baseTags = ['description', 'group', 'author', 'date', 'see', 'example', 'mermaid', 'throws', 'exception'];
+
+    return (
+      type.docComment?.annotations
+        .filter((currentAnnotation) => !baseTags.includes(currentAnnotation.name.toLowerCase()))
+        .map<CustomTag>((currentAnnotation) => ({
+          ...adaptDescribable(currentAnnotation.bodyLines, linkGenerator),
+          name: currentAnnotation.name,
+        })) ?? []
+    );
+  }
+
+  function extractAnnotationBodyLines(type: Documentable, annotationName: string): string[] | undefined {
+    return type.docComment?.annotations.find(
+      (currentAnnotation) => currentAnnotation.name.toLowerCase() === annotationName,
+    )?.bodyLines;
+  }
+
+  function extractAnnotationBody(type: Documentable, annotationName: string): string | undefined {
+    return type.docComment?.annotations.find(
+      (currentAnnotation) => currentAnnotation.name.toLowerCase() === annotationName,
+    )?.body;
+  }
+
+  function extractSeeAnnotations(type: Documentable): string[] {
+    return (
+      type.docComment?.annotations
+        .filter((currentAnnotation) => currentAnnotation.name.toLowerCase() === 'see')
+        .map((currentAnnotation) => currentAnnotation.body) ?? []
+    );
+  }
+
+  return {
+    ...adaptDescribable(documentable.docComment?.descriptionLines, linkGenerator),
+    annotations: documentable.annotations.map((annotation) => annotation.type.toUpperCase()),
+    customTags: extractCustomTags(documentable),
+    mermaid: {
+      headingLevel: subHeadingLevel,
+      heading: 'Diagram',
+      value: extractAnnotationBodyLines(documentable, 'mermaid'),
+    },
+    example: {
+      headingLevel: subHeadingLevel,
+      heading: 'Example',
+      value: documentable.docComment?.exampleAnnotation?.bodyLines,
+    },
+    group: extractAnnotationBody(documentable, 'group'),
+    author: extractAnnotationBody(documentable, 'author'),
+    date: extractAnnotationBody(documentable, 'date'),
+    sees: extractSeeAnnotations(documentable).map(linkGenerator),
+  };
+}

package/src/adapters/fields-and-properties.ts

@@ -0,0 +1,38 @@
+import { FieldMirrorWithInheritance, PropertyMirrorWithInheritance } from '../model/inheritance';
+import { RenderableField } from '../core/renderable/types';
+import { adaptDocumentable } from './documentables';
+import { GetRenderableContentByTypeName, linkFromTypeNameGenerator } from './references';
+
+export function adaptFieldOrProperty(
+  field: FieldMirrorWithInheritance | PropertyMirrorWithInheritance,
+  linkGenerator: GetRenderableContentByTypeName,
+  baseHeadingLevel: number,
+): RenderableField {
+  function buildSignature() {
+    const { access_modifier, name } = field;
+    const memberModifiers = field.memberModifiers.join(' ');
+    return (
+      `${access_modifier} ${memberModifiers} ${name}`
+        // remove double spaces
+        .replace(/ {2}/g, ' ')
+    );
+  }
+
+  return {
+    headingLevel: baseHeadingLevel,
+    doc: adaptDocumentable(field, linkGenerator, baseHeadingLevel + 1),
+    heading: field.name,
+    type: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Type',
+      value: linkFromTypeNameGenerator(field.typeReference.rawDeclaration),
+    },
+    inherited: field.inherited,
+    accessModifier: field.access_modifier,
+    signature: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Signature',
+      value: [buildSignature()],
+    },
+  };
+}

package/src/adapters/methods-and-constructors.ts

@@ -0,0 +1,117 @@
+import { ConstructorMirror, MethodMirror, ParameterMirror, ThrowsAnnotation } from '@cparra/apex-reflection';
+import { RenderableConstructor, RenderableMethod } from '../core/renderable/types';
+import { MethodMirrorWithInheritance } from '../model/inheritance';
+import { adaptDescribable, adaptDocumentable } from './documentables';
+import { GetRenderableContentByTypeName, linkFromTypeNameGenerator } from './references';
+import { Documentable } from './types';
+
+export function adaptMethod(
+  method: MethodMirror,
+  linkGenerator: GetRenderableContentByTypeName,
+  baseHeadingLevel: number,
+): RenderableMethod {
+  function buildTitle(method: MethodMirrorWithInheritance): string {
+    const { name, parameters } = method;
+    const parametersString = parameters.map((param) => param.name).join(', ');
+    return `${name}(${parametersString})`;
+  }
+
+  function buildSignature(method: MethodMirrorWithInheritance): string {
+    const { access_modifier, typeReference, name, memberModifiers } = method;
+    const parameters = method.parameters
+      .map((param) => `${param.typeReference.rawDeclaration} ${param.name}`)
+      .join(', ');
+    const members = memberModifiers.length > 0 ? `${memberModifiers.join(' ')} ` : '';
+    return `${access_modifier} ${members}${typeReference.rawDeclaration} ${name}(${parameters})`;
+  }
+
+  return {
+    headingLevel: baseHeadingLevel,
+    doc: adaptDocumentable(method, linkGenerator, baseHeadingLevel + 1),
+    heading: buildTitle(method as MethodMirrorWithInheritance),
+    signature: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Signature',
+      value: [buildSignature(method as MethodMirrorWithInheritance)],
+    },
+    returnType: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Return Type',
+      value: {
+        ...adaptDescribable(method.docComment?.returnAnnotation?.bodyLines, linkGenerator),
+        type: linkFromTypeNameGenerator(method.typeReference.rawDeclaration),
+      },
+    },
+    throws: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Throws',
+      value: method.docComment?.throwsAnnotations.map((thrown) => mapThrows(thrown)),
+    },
+    parameters: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Parameters',
+      value: method.parameters.map((param) => mapParameters(method, param)),
+    },
+    inherited: (method as MethodMirrorWithInheritance).inherited,
+  };
+}
+
+export function adaptConstructor(
+  typeName: string,
+  constructor: ConstructorMirror,
+  linkGenerator: GetRenderableContentByTypeName,
+  baseHeadingLevel: number,
+): RenderableConstructor {
+  function buildTitle(name: string, constructor: ConstructorMirror): string {
+    const { parameters } = constructor;
+    const parametersString = parameters.map((param) => param.name).join(', ');
+    return `${name}(${parametersString})`;
+  }
+
+  function buildSignature(name: string, constructor: ConstructorMirror): string {
+    const { access_modifier } = constructor;
+    const parameters = constructor.parameters
+      .map((param) => `${param.typeReference.rawDeclaration} ${param.name}`)
+      .join(', ');
+    return `${access_modifier} ${name}(${parameters})`;
+  }
+
+  return {
+    doc: adaptDocumentable(constructor, linkGenerator, baseHeadingLevel + 1),
+    headingLevel: baseHeadingLevel,
+    heading: buildTitle(typeName, constructor),
+    signature: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Signature',
+      value: [buildSignature(typeName, constructor)],
+    },
+    parameters: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Parameters',
+      value: constructor.parameters.map((param) => mapParameters(constructor, param)),
+    },
+    throws: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Throws',
+      value: constructor.docComment?.throwsAnnotations.map((thrown) => mapThrows(thrown)),
+    },
+  };
+}
+
+function mapParameters(documentable: Documentable, param: ParameterMirror) {
+  const paramAnnotation = documentable.docComment?.paramAnnotations.find(
+    (pa) => pa.paramName.toLowerCase() === param.name.toLowerCase(),
+  );
+  return {
+    ...adaptDescribable(paramAnnotation?.bodyLines, linkFromTypeNameGenerator),
+    name: param.name,
+    type: linkFromTypeNameGenerator(param.typeReference.rawDeclaration),
+  };
+}
+
+function mapThrows(thrown: ThrowsAnnotation) {
+  return {
+    ...adaptDescribable(thrown.bodyLines, linkFromTypeNameGenerator),
+    type: linkFromTypeNameGenerator(thrown.exceptionName),
+  };
+}

package/src/adapters/references.ts

@@ -0,0 +1,113 @@
+import ClassFileGeneratorHelper from '../transpiler/markdown/class-file-generatorHelper';
+import { Link, RenderableContent, StringOrLink } from '../core/renderable/types';
+
+export type GetRenderableContentByTypeName = (typeName: string) => StringOrLink;
+
+export const linkFromTypeNameGenerator: GetRenderableContentByTypeName =
+  ClassFileGeneratorHelper.getRenderableLinkByTypeName;
+
+function defaultGetEmailByReference(email: string): Link {
+  return {
+    title: email,
+    url: `mailto:${email}`,
+  };
+}
+
+export function replaceInlineReferences(
+  text: string,
+  linkReplacer: GetRenderableContentByTypeName = linkFromTypeNameGenerator,
+  emailReplacer: GetRenderableContentByTypeName = defaultGetEmailByReference,
+): RenderableContent[] {
+  return replaceInlineEmails(replaceInlineLinks([text], linkReplacer), emailReplacer);
+}
+
+function replaceInlineLinks(
+  renderableContents: RenderableContent[],
+  getLinkByTypeName: GetRenderableContentByTypeName,
+): RenderableContent[] {
+  return renderableContents.flatMap((renderableContent) => inlineLinkContent(renderableContent, getLinkByTypeName));
+}
+
+function inlineLinkContent(
+  renderableContent: RenderableContent,
+  getLinkByTypeName: GetRenderableContentByTypeName,
+): RenderableContent[] {
+  if (typeof renderableContent !== 'string') {
+    return [renderableContent];
+  }
+
+  const text = renderableContent;
+
+  // Matches either `<<ClassName>>` or `{@link ClassName}`
+  const linkFormatRegEx = '{@link (.*?)}|<<([^>]+)>>';
+  const matches = match(linkFormatRegEx, text);
+  return createRenderableContents(matches, text, getLinkByTypeName);
+}
+
+export function replaceInlineEmails(
+  renderableContents: RenderableContent[],
+  getLinkByTypeName: GetRenderableContentByTypeName,
+): RenderableContent[] {
+  return renderableContents.flatMap((renderableContent) => inlineEmailContent(renderableContent, getLinkByTypeName));
+}
+
+function inlineEmailContent(
+  renderableContent: RenderableContent,
+  getLinkByTypeName: GetRenderableContentByTypeName,
+): RenderableContent[] {
+  if (typeof renderableContent !== 'string') {
+    return [renderableContent];
+  }
+
+  const text = renderableContent;
+
+  // Parsing references using the format '{@email email}'
+  const linkFormatRegEx = '{@email (.*?)}';
+  const matches = match(linkFormatRegEx, text);
+  return createRenderableContents(matches, text, getLinkByTypeName);
+}
+
+function match(regex: string, text: string) {
+  const expression = new RegExp(regex, 'gi');
+  let match;
+  const matches = [];
+
+  do {
+    match = expression.exec(text);
+    if (match) {
+      matches.push(match);
+    }
+  } while (match);
+
+  return matches;
+}
+
+function createRenderableContents(matches: RegExpExecArray[], text: string, linker: GetRenderableContentByTypeName) {
+  if (matches.length === 0) {
+    return [text];
+  }
+
+  const result: RenderableContent[] = [];
+  let lastIndex = 0;
+  for (const match of matches) {
+    const index = match.index;
+    const length = match[0].length;
+
+    // loop through the matches (skip the first one, which is the full match)
+    // until we find the first capturing group that has a value
+    const capturedGroup = match.slice(1).find((group) => group);
+    if (!capturedGroup) {
+      continue;
+    }
+    result.push(text.slice(lastIndex, index));
+    result.push(linker(capturedGroup));
+
+    lastIndex = index + length;
+  }
+
+  if (lastIndex < text.length) {
+    result.push(text.slice(lastIndex));
+  }
+
+  return result;
+}