More test coverage improvements

Author: Gerrit0

src/lib/converter/comments/linkResolver.ts

@@ -1,9 +1,8 @@
 import ts from "typescript";
 import {
- type Comment,
  type CommentDisplayPart,
- DeclarationReflection,
  type InlineTagDisplayPart,
+ makeRecursiveVisitor,
  Reflection,
  ReflectionKind,
  ReflectionSymbolId,
@@ -35,27 +34,28 @@ export type LinkResolverOptions = {
 };
 
 export function resolveLinks(
- comment: Comment,
  reflection: Reflection,
  externalResolver: ExternalSymbolResolver,
  options: LinkResolverOptions,
 ) {
- comment.summary = resolvePartLinks(
- reflection,
- comment.summary,
- externalResolver,
- options,
- );
- for (const tag of comment.blockTags) {
- tag.content = resolvePartLinks(
+ if (reflection.comment) {
+ reflection.comment.summary = resolvePartLinks(
  reflection,
- tag.content,
+ reflection.comment.summary,
  externalResolver,
  options,
  );
+ for (const tag of reflection.comment.blockTags) {
+ tag.content = resolvePartLinks(
+ reflection,
+ tag.content,
+ externalResolver,
+ options,
+ );
+ }
  }
 
- if (reflection instanceof DeclarationReflection && reflection.readme) {
+ if ((reflection.isDeclaration() || reflection.isProject()) && reflection.readme) {
  reflection.readme = resolvePartLinks(
  reflection,
  reflection.readme,
@@ -64,6 +64,18 @@ export function resolveLinks(
  );
  }
 
+ if (reflection.isDeclaration()) {
+ reflection.type?.visit(
+ makeRecursiveVisitor({
+ union: (type) => {
+ type.elementSummaries = type.elementSummaries?.map(
+ (parts) => resolvePartLinks(reflection, parts, externalResolver, options),
+ );
+ },
+ }),
+ );
+ }
+
  if (reflection.isDocument()) {
  reflection.content = resolvePartLinks(
  reflection,
@@ -72,6 +84,57 @@ export function resolveLinks(
  options,
  );
  }
+
+ if (
+ reflection.isParameter() &&
+ reflection.type?.type === "reference" &&
+ reflection.type.highlightedProperties
+ ) {
+ const resolved = new Map(
+ Array.from(
+ reflection.type.highlightedProperties,
+ ([name, parts]) => {
+ return [
+ name,
+ resolvePartLinks(reflection, parts, externalResolver, options),
+ ];
+ },
+ ),
+ );
+
+ reflection.type.highlightedProperties = resolved;
+ }
+
+ if (reflection.isContainer()) {
+ if (reflection.groups) {
+ for (const group of reflection.groups) {
+ if (group.description) {
+ group.description = resolvePartLinks(
+ reflection,
+ group.description,
+ externalResolver,
+ options,
+ );
+ }
+
+ if (group.categories) {
+ for (const cat of group.categories) {
+ if (cat.description) {
+ cat.description = resolvePartLinks(reflection, cat.description, externalResolver, options);
+ }
+ }
+ }
+ }
+ }
+
+ if (reflection.categories) {
+ for (const cat of reflection.categories) {
+ if (cat.description) {
+ cat.description = resolvePartLinks(reflection, cat.description, externalResolver, options);
+ }
+ }
+ }
+ }
 }
 
 export function resolvePartLinks(
@@ -133,10 +196,10 @@ function resolveLinkTag(
 
  if (tsTargets.length) {
  // Find the target most likely to have a real url in the generated documentation
- // 1. A direct export (class, interface, variable)
- // 2. A property of a direct export (class/interface property)
- // 3. A property of a type of an export (property on type alias)
- // 4. Whatever the first symbol found was
+ // 4. A direct export (class, interface, variable)
+ // 3. A property of a direct export (class/interface property)
+ // 2. A property of a type of an export (property on type alias)
+ // 1. Whatever the first symbol found was
  target = maxElementByScore(tsTargets, (r) => {
  if (r.kindOf(ReflectionKind.SomeExport)) {
  return 4;

src/lib/converter/converter.ts

@@ -10,7 +10,7 @@ import {
  DocumentReflection,
  type ParameterReflection,
  ProjectReflection,
- type Reflection,
+ Reflection,
  ReflectionKind,
  type ReflectionSymbolId,
  type SignatureReflection,
@@ -436,25 +436,32 @@ export class Converter extends AbstractComponent<Application, ConverterEvents> {
  }
  }
 
+ resolveLinks(reflection: Reflection): void;
+ /** @deprecated just pass the reflection */
  resolveLinks(comment: Comment, owner: Reflection): void;
  resolveLinks(
  parts: readonly CommentDisplayPart[],
  owner: Reflection,
  ): CommentDisplayPart[];
  resolveLinks(
- comment: Comment | readonly CommentDisplayPart[],
- owner: Reflection,
+ comment: Reflection | Comment | readonly CommentDisplayPart[],
+ owner?: Reflection,
  ): CommentDisplayPart[] | undefined {
- if (comment instanceof Comment) {
+ if (comment instanceof Reflection) {
  resolveLinks(
  comment,
- owner,
+ (ref, part, refl, id) => this.resolveExternalLink(ref, part, refl, id),
+ { preserveLinkText: this.preserveLinkText },
+ );
+ } else if (comment instanceof Comment) {
+ resolveLinks(
+ owner!,
  (ref, part, refl, id) => this.resolveExternalLink(ref, part, refl, id),
  { preserveLinkText: this.preserveLinkText },
  );
  } else {
  return resolvePartLinks(
- owner,
+ owner!,
  comment,
  (ref, part, refl, id) => this.resolveExternalLink(ref, part, refl, id),
  { preserveLinkText: this.preserveLinkText },

src/lib/converter/plugins/LinkResolverPlugin.ts

@@ -2,13 +2,7 @@ import { ConverterComponent } from "../components.js";
 import type { Context, Converter } from "../../converter/index.js";
 import { ConverterEvents } from "../converter-events.js";
 import { Option, type ValidationOptions } from "../../utils/index.js";
-import {
- ContainerReflection,
- makeRecursiveVisitor,
- type ProjectReflection,
- type Reflection,
- type ReflectionCategory,
-} from "../../models/index.js";
+import type { ProjectReflection } from "../../models/index.js";
 import { discoverAllReferenceTypes } from "../../utils/reflections.js";
 import { ApplicationEvents } from "../../application-events.js";
 
@@ -40,84 +34,7 @@ export class LinkResolverPlugin extends ConverterComponent {
  resolveLinks(project: ProjectReflection) {
  for (const id in project.reflections) {
  const reflection = project.reflections[id];
- if (reflection.comment) {
- this.owner.resolveLinks(reflection.comment, reflection);
- }
-
- if (reflection.isDeclaration()) {
- reflection.type?.visit(
- makeRecursiveVisitor({
- union: (type) => {
- type.elementSummaries = type.elementSummaries?.map(
- (parts) => this.owner.resolveLinks(parts, reflection),
- );
- },
- }),
- );
-
- if (reflection.readme) {
- reflection.readme = this.owner.resolveLinks(
- reflection.readme,
- reflection,
- );
- }
- }
-
- if (reflection.isDocument()) {
- reflection.content = this.owner.resolveLinks(
- reflection.content,
- reflection,
- );
- }
-
- if (
- reflection.isParameter() &&
- reflection.type?.type === "reference" &&
- reflection.type.highlightedProperties
- ) {
- const resolved = new Map(
- Array.from(
- reflection.type.highlightedProperties,
- ([name, parts]) => {
- return [
- name,
- this.owner.resolveLinks(parts, reflection),
- ];
- },
- ),
- );
-
- reflection.type.highlightedProperties = resolved;
- }
-
- if (reflection instanceof ContainerReflection) {
- if (reflection.groups) {
- for (const group of reflection.groups) {
- if (group.description) {
- group.description = this.owner.resolveLinks(
- group.description,
- reflection,
- );
- }
-
- if (group.categories) {
- for (const cat of group.categories) {
- this.resolveCategoryLinks(cat, reflection);
- }
- }
- }
- }
-
- if (reflection.categories) {
- for (const cat of reflection.categories) {
- this.resolveCategoryLinks(cat, reflection);
- }
- }
- }
- }
-
- if (project.readme) {
- project.readme = this.owner.resolveLinks(project.readme, project);
+ this.owner.resolveLinks(reflection);
  }
 
  for (
@@ -144,16 +61,4 @@ export class LinkResolverPlugin extends ConverterComponent {
  }
  }
  }
-
- private resolveCategoryLinks(
- category: ReflectionCategory,
- owner: Reflection,
- ) {
- if (category.description) {
- category.description = this.owner.resolveLinks(
- category.description,
- owner,
- );
- }
- }
 }

src/lib/models/ContainerReflection.ts

@@ -113,6 +113,10 @@ export abstract class ContainerReflection extends Reflection {
  }
  }
 
+ override isContainer(): this is ContainerReflection {
+ return true;
+ }
+
  override traverse(callback: TraverseCallback) {
  for (const child of this.children?.slice() || []) {
  if (callback(child, TraverseProperty.Children) === false) {

src/lib/models/Reflection.ts

@@ -11,6 +11,7 @@ import type { ParameterReflection } from "./ParameterReflection.js";
 import type { ReferenceReflection } from "./ReferenceReflection.js";
 import type { SignatureReflection } from "./SignatureReflection.js";
 import type { TypeParameterReflection } from "./TypeParameterReflection.js";
+import type { ContainerReflection } from "./ContainerReflection.js";
 
 /**
  * Current reflection id.
@@ -455,6 +456,9 @@ export abstract class Reflection {
  isReference(): this is ReferenceReflection {
  return this.variant === "reference";
  }
+ isContainer(): this is ContainerReflection {
+ return false;
+ }
 
  /**
  * Check if this reflection or any of its parents have been marked with the `@deprecated` tag.

src/lib/output/themes/default/templates/hierarchy.tsx

@@ -37,7 +37,7 @@ function fullHierarchy(
  {context.reflectionIcon(root)}
  {root.name}
  </a>
- {children.length && <ul>{children}</ul>}
+ {children.length ? <ul>{children}</ul> : null}
  </li>
  );
 }

src/lib/utils-common/array.ts

@@ -149,13 +149,9 @@ export function filterMap<T, U>(
 }
 
 export function firstDefined<T, U>(
- array: readonly T[] | undefined,
+ array: readonly T[],
  callback: (element: T, index: number) => U | undefined,
 ): U | undefined {
- if (array === undefined) {
- return undefined;
- }
-
  for (let i = 0; i < array.length; i++) {
  const result = callback(array[i], i);
  if (result !== undefined) {
@@ -176,17 +172,6 @@ export function aggregate<T>(arr: T[], fn: (item: T) => number) {
  return arr.reduce((sum, it) => sum + fn(it), 0);
 }
 
-export function aggregateWithJoiner<T>(
- arr: T[],
- fn: (item: T) => number,
- joiner: string,
-) {
- return (
- arr.reduce((sum, it) => sum + fn(it), 0) +
- (arr.length - 1) * joiner.length
- );
-}
-
 export function joinArray<T>(
  arr: readonly T[] | undefined,
  joiner: string,

src/lib/utils-common/jsx.elements.ts

@@ -144,6 +144,8 @@ export type JsxChildren =
  | JsxElement
  | string
  | number
+ | boolean
+ | bigint
  | null
  | undefined
  | JsxChildren[];