// 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; /** * 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 = 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; } }