ExcerptBuilder.ts

// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
// See LICENSE in the project root for license information.

import * as ts from 'typescript';

import type { DeclarationReference } from '@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference';
import {
  ExcerptTokenKind,
  type IExcerptToken,
  type IExcerptTokenRange
} from '@microsoft/api-extractor-model';

import { Span } from '../analyzer/Span';
import type { DeclarationReferenceGenerator } from './DeclarationReferenceGenerator';
import type { AstDeclaration } from '../analyzer/AstDeclaration';
import { condenseTokens } from './condenseTokens';

/**
 * Used to provide ExcerptBuilder with a list of nodes whose token range we want to capture.
 */
export interface IExcerptBuilderNodeTransform {
  /**
   * The node to process
   */
  node: ts.Node;

  /**
   * A token range whose startIndex/endIndex will be overwritten with the indexes for the
   * tokens corresponding to IExcerptBuilderNodeTransform.node
   */
  captureTokenRange?: IExcerptTokenRange;

  /**
   * Text that will replace the text of the given node during emit.
   */
  replacementText?: string;
}

/**
 * Internal state for ExcerptBuilder
 */
interface IBuildSpanState {
  referenceGenerator: DeclarationReferenceGenerator;

  /**
   * The AST node that we will traverse to extract tokens
   */
  startingNode: ts.Node;

  /**
   * Normally, the excerpt will include all child nodes for `startingNode`; whereas if `childKindToStopBefore`
   * is specified, then the node traversal will stop before (i.e. excluding) the first immediate child
   * of `startingNode` with the specified syntax kind.
   *
   * @remarks
   * For example, suppose the signature is `interface X: Y { z: string }`.  The token `{` has syntax kind
   * `ts.SyntaxKind.FirstPunctuation`, so we can specify that to truncate the excerpt to `interface X: Y`.
   */
  stopBeforeChildKind: ts.SyntaxKind | undefined;

  transformsByNode: Map<ts.Node, IExcerptBuilderNodeTransform>;

  /**
   * Tracks whether the last appended token was a separator. If so, and we're in the middle of
   * capturing a token range, then omit the separator from the range.
   */
  lastAppendedTokenIsSeparator: boolean;
}

export class ExcerptBuilder {
  /**
   * Appends a blank line to the `excerptTokens` list.
   * @param excerptTokens - The target token list to append to
   */
  public static addBlankLine(excerptTokens: IExcerptToken[]): void {
    let newlines: string = '\n\n';
    // If the existing text already ended with a newline, then only append one newline
    if (excerptTokens.length > 0) {
      const previousText: string = excerptTokens[excerptTokens.length - 1].text;
      if (/\n$/.test(previousText)) {
        newlines = '\n';
      }
    }
    excerptTokens.push({ kind: ExcerptTokenKind.Content, text: newlines });
  }

  /**
   * Appends the signature for the specified `AstDeclaration` to the `excerptTokens` list.
   * @param excerptTokens - The target token list to append to
   * @param nodeTransforms - A list of child nodes whose token ranges we want to capture
   */
  public static addDeclaration(
    excerptTokens: IExcerptToken[],
    astDeclaration: AstDeclaration,
    nodeTransforms: IExcerptBuilderNodeTransform[],
    referenceGenerator: DeclarationReferenceGenerator
  ): void {
    let stopBeforeChildKind: ts.SyntaxKind | undefined = undefined;

    switch (astDeclaration.declaration.kind) {
      case ts.SyntaxKind.ClassDeclaration:
      case ts.SyntaxKind.EnumDeclaration:
      case ts.SyntaxKind.InterfaceDeclaration:
        // FirstPunctuation = "{"
        stopBeforeChildKind = ts.SyntaxKind.FirstPunctuation;
        break;
      case ts.SyntaxKind.ModuleDeclaration:
        // ModuleBlock = the "{ ... }" block
        stopBeforeChildKind = ts.SyntaxKind.ModuleBlock;
        break;
    }

    const span: Span = new Span(astDeclaration.declaration);

    const transformsByNode: Map<ts.Node, IExcerptBuilderNodeTransform> = new Map();
    const captureTokenRanges: IExcerptTokenRange[] = [];
    for (const nodeTransform of nodeTransforms || []) {
      transformsByNode.set(nodeTransform.node, nodeTransform);
      if (nodeTransform.captureTokenRange) {
        captureTokenRanges.push(nodeTransform.captureTokenRange);
      }
    }

    _buildSpan(excerptTokens, span, {
      referenceGenerator: referenceGenerator,
      startingNode: span.node,
      stopBeforeChildKind,
      transformsByNode: transformsByNode,
      lastAppendedTokenIsSeparator: false
    });

    condenseTokens(excerptTokens, captureTokenRanges);
  }

  public static createEmptyTokenRange(): IExcerptTokenRange {
    return { startIndex: 0, endIndex: 0 };
  }
}

/** @returns false if we encountered a token that causes iteration to stop. */
function _buildSpan(excerptTokens: IExcerptToken[], span: Span, state: IBuildSpanState): boolean {
  if (span.kind === ts.SyntaxKind.JSDocComment) {
    // Discard any comments
    return true;
  }

  // Can this node start a excerpt?
  const transform: IExcerptBuilderNodeTransform | undefined = state.transformsByNode.get(span.node);

  let captureTokenRange: IExcerptTokenRange | undefined = undefined;

  if (transform) {
    captureTokenRange = transform.captureTokenRange;
    if (transform.replacementText !== undefined) {
      excerptTokens.push({
        kind: ExcerptTokenKind.Content,
        text: transform.replacementText
      });
      state.lastAppendedTokenIsSeparator = false;

      if (captureTokenRange) {
        captureTokenRange.startIndex = excerptTokens.length;
        captureTokenRange.endIndex = captureTokenRange.startIndex + 1;
      }
      return true;
    }
  }

  let excerptStartIndex: number = 0;

  if (captureTokenRange) {
    // We will assign capturedTokenRange.startIndex to be the index of the next token to be appended
    excerptStartIndex = excerptTokens.length;
  }

  if (span.prefix) {
    let canonicalReference: DeclarationReference | undefined = undefined;

    if (span.kind === ts.SyntaxKind.Identifier) {
      const name: ts.Identifier = span.node as ts.Identifier;
      if (!_isDeclarationName(name)) {
        canonicalReference = state.referenceGenerator.getDeclarationReferenceForIdentifier(name);
      }
    }

    if (canonicalReference) {
      _appendToken(excerptTokens, ExcerptTokenKind.Reference, span.prefix, canonicalReference);
    } else {
      _appendToken(excerptTokens, ExcerptTokenKind.Content, span.prefix);
    }
    state.lastAppendedTokenIsSeparator = false;
  }

  for (const child of span.children) {
    if (span.node === state.startingNode) {
      if (state.stopBeforeChildKind && child.kind === state.stopBeforeChildKind) {
        // We reached a child whose kind is stopBeforeChildKind, so stop traversing
        return false;
      }
    }

    if (!_buildSpan(excerptTokens, child, state)) {
      return false;
    }
  }

  if (span.suffix) {
    _appendToken(excerptTokens, ExcerptTokenKind.Content, span.suffix);
    state.lastAppendedTokenIsSeparator = false;
  }
  if (span.separator) {
    _appendToken(excerptTokens, ExcerptTokenKind.Content, span.separator);
    state.lastAppendedTokenIsSeparator = true;
  }

  // Are we building a excerpt?  If so, set its range
  if (captureTokenRange) {
    captureTokenRange.startIndex = excerptStartIndex;

    // We will assign capturedTokenRange.startIndex to be the index after the last token
    // that was appended so far. However, if the last appended token was a separator, omit
    // it from the range.
    let excerptEndIndex: number = excerptTokens.length;
    if (state.lastAppendedTokenIsSeparator) {
      excerptEndIndex--;
    }

    captureTokenRange.endIndex = excerptEndIndex;
  }

  return true;
}

function _appendToken(
  excerptTokens: IExcerptToken[],
  excerptTokenKind: ExcerptTokenKind,
  text: string,
  canonicalReference?: DeclarationReference
): void {
  if (text.length === 0) {
    return;
  }

  const excerptToken: IExcerptToken = { kind: excerptTokenKind, text: text };
  if (canonicalReference !== undefined) {
    excerptToken.canonicalReference = canonicalReference.toString();
  }
  excerptTokens.push(excerptToken);
}

function _isDeclarationName(name: ts.Identifier): boolean {
  return _isDeclaration(name.parent) && name.parent.name === name;
}

function _isDeclaration(node: ts.Node): node is ts.NamedDeclaration {
  switch (node.kind) {
    case ts.SyntaxKind.FunctionDeclaration:
    case ts.SyntaxKind.FunctionExpression:
    case ts.SyntaxKind.VariableDeclaration:
    case ts.SyntaxKind.Parameter:
    case ts.SyntaxKind.EnumDeclaration:
    case ts.SyntaxKind.ClassDeclaration:
    case ts.SyntaxKind.ClassExpression:
    case ts.SyntaxKind.ModuleDeclaration:
    case ts.SyntaxKind.MethodDeclaration:
    case ts.SyntaxKind.MethodSignature:
    case ts.SyntaxKind.PropertyDeclaration:
    case ts.SyntaxKind.PropertySignature:
    case ts.SyntaxKind.GetAccessor:
    case ts.SyntaxKind.SetAccessor:
    case ts.SyntaxKind.InterfaceDeclaration:
    case ts.SyntaxKind.TypeAliasDeclaration:
    case ts.SyntaxKind.TypeParameter:
    case ts.SyntaxKind.EnumMember:
    case ts.SyntaxKind.BindingElement:
      return true;
    default:
      return false;
  }
}