@microsoft/api-extractor 7.56.3 → 7.57.0

package/lib-esm/generators/ExcerptBuilder.js

@@ -0,0 +1,259 @@
+// 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 { ExcerptTokenKind } from '@microsoft/api-extractor-model';
+import { Span } from '../analyzer/Span';
+export class ExcerptBuilder {
+    /**
+     * Appends a blank line to the `excerptTokens` list.
+     * @param excerptTokens - The target token list to append to
+     */
+    static addBlankLine(excerptTokens) {
+        let newlines = '\n\n';
+        // If the existing text already ended with a newline, then only append one newline
+        if (excerptTokens.length > 0) {
+            const previousText = 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
+     */
+    static addDeclaration(excerptTokens, astDeclaration, nodeTransforms, referenceGenerator) {
+        let stopBeforeChildKind = 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 = new Span(astDeclaration.declaration);
+        const transformsByNode = new Map();
+        const captureTokenRanges = [];
+        for (const nodeTransform of nodeTransforms || []) {
+            transformsByNode.set(nodeTransform.node, nodeTransform);
+            if (nodeTransform.captureTokenRange) {
+                captureTokenRanges.push(nodeTransform.captureTokenRange);
+            }
+        }
+        ExcerptBuilder._buildSpan(excerptTokens, span, {
+            referenceGenerator: referenceGenerator,
+            startingNode: span.node,
+            stopBeforeChildKind,
+            transformsByNode: transformsByNode,
+            lastAppendedTokenIsSeparator: false
+        });
+        ExcerptBuilder._condenseTokens(excerptTokens, captureTokenRanges);
+    }
+    static createEmptyTokenRange() {
+        return { startIndex: 0, endIndex: 0 };
+    }
+    /** @returns false if we encountered a token that causes iteration to stop. */
+    static _buildSpan(excerptTokens, span, state) {
+        if (span.kind === ts.SyntaxKind.JSDocComment) {
+            // Discard any comments
+            return true;
+        }
+        // Can this node start a excerpt?
+        const transform = state.transformsByNode.get(span.node);
+        let captureTokenRange = 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 = 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 = undefined;
+            if (span.kind === ts.SyntaxKind.Identifier) {
+                const name = span.node;
+                if (!ExcerptBuilder._isDeclarationName(name)) {
+                    canonicalReference = state.referenceGenerator.getDeclarationReferenceForIdentifier(name);
+                }
+            }
+            if (canonicalReference) {
+                ExcerptBuilder._appendToken(excerptTokens, ExcerptTokenKind.Reference, span.prefix, canonicalReference);
+            }
+            else {
+                ExcerptBuilder._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 (!this._buildSpan(excerptTokens, child, state)) {
+                return false;
+            }
+        }
+        if (span.suffix) {
+            ExcerptBuilder._appendToken(excerptTokens, ExcerptTokenKind.Content, span.suffix);
+            state.lastAppendedTokenIsSeparator = false;
+        }
+        if (span.separator) {
+            ExcerptBuilder._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 = excerptTokens.length;
+            if (state.lastAppendedTokenIsSeparator) {
+                excerptEndIndex--;
+            }
+            captureTokenRange.endIndex = excerptEndIndex;
+        }
+        return true;
+    }
+    static _appendToken(excerptTokens, excerptTokenKind, text, canonicalReference) {
+        if (text.length === 0) {
+            return;
+        }
+        const excerptToken = { kind: excerptTokenKind, text: text };
+        if (canonicalReference !== undefined) {
+            excerptToken.canonicalReference = canonicalReference.toString();
+        }
+        excerptTokens.push(excerptToken);
+    }
+    /**
+     * Condenses the provided excerpt tokens by merging tokens where possible. Updates the provided token ranges to
+     * remain accurate after token merging.
+     *
+     * @remarks
+     * For example, suppose we have excerpt tokens ["A", "B", "C"] and a token range [0, 2]. If the excerpt tokens
+     * are condensed to ["AB", "C"], then the token range would be updated to [0, 1]. Note that merges are only
+     * performed if they are compatible with the provided token ranges. In the example above, if our token range was
+     * originally [0, 1], we would not be able to merge tokens "A" and "B".
+     */
+    static _condenseTokens(excerptTokens, tokenRanges) {
+        // This set is used to quickly lookup a start or end index.
+        const startOrEndIndices = new Set();
+        for (const tokenRange of tokenRanges) {
+            startOrEndIndices.add(tokenRange.startIndex);
+            startOrEndIndices.add(tokenRange.endIndex);
+        }
+        for (let currentIndex = 1; currentIndex < excerptTokens.length; ++currentIndex) {
+            while (currentIndex < excerptTokens.length) {
+                const prevPrevToken = excerptTokens[currentIndex - 2]; // May be undefined
+                const prevToken = excerptTokens[currentIndex - 1];
+                const currentToken = excerptTokens[currentIndex];
+                // The number of excerpt tokens that are merged in this iteration. We need this to determine
+                // how to update the start and end indices of our token ranges.
+                let mergeCount;
+                // There are two types of merges that can occur. We only perform these merges if they are
+                // compatible with all of our token ranges.
+                if (prevPrevToken &&
+                    prevPrevToken.kind === ExcerptTokenKind.Reference &&
+                    prevToken.kind === ExcerptTokenKind.Content &&
+                    prevToken.text.trim() === '.' &&
+                    currentToken.kind === ExcerptTokenKind.Reference &&
+                    !startOrEndIndices.has(currentIndex) &&
+                    !startOrEndIndices.has(currentIndex - 1)) {
+                    // If the current token is a reference token, the previous token is a ".", and the previous-
+                    // previous token is a reference token, then merge all three tokens into a reference token.
+                    //
+                    // For example: Given ["MyNamespace" (R), ".", "MyClass" (R)], tokens "." and "MyClass" might
+                    // be merged into "MyNamespace". The condensed token would be ["MyNamespace.MyClass" (R)].
+                    prevPrevToken.text += prevToken.text + currentToken.text;
+                    prevPrevToken.canonicalReference = currentToken.canonicalReference;
+                    mergeCount = 2;
+                    currentIndex--;
+                }
+                else if (
+                // If the current and previous tokens are both content tokens, then merge the tokens into a
+                // single content token. For example: Given ["export ", "declare class"], these tokens
+                // might be merged into "export declare class".
+                prevToken.kind === ExcerptTokenKind.Content &&
+                    prevToken.kind === currentToken.kind &&
+                    !startOrEndIndices.has(currentIndex)) {
+                    prevToken.text += currentToken.text;
+                    mergeCount = 1;
+                }
+                else {
+                    // Otherwise, no merging can occur here. Continue to the next index.
+                    break;
+                }
+                // Remove the now redundant excerpt token(s), as they were merged into a previous token.
+                excerptTokens.splice(currentIndex, mergeCount);
+                // Update the start and end indices for all token ranges based upon how many excerpt
+                // tokens were merged and in what positions.
+                for (const tokenRange of tokenRanges) {
+                    if (tokenRange.startIndex > currentIndex) {
+                        tokenRange.startIndex -= mergeCount;
+                    }
+                    if (tokenRange.endIndex > currentIndex) {
+                        tokenRange.endIndex -= mergeCount;
+                    }
+                }
+                // Clear and repopulate our set with the updated indices.
+                startOrEndIndices.clear();
+                for (const tokenRange of tokenRanges) {
+                    startOrEndIndices.add(tokenRange.startIndex);
+                    startOrEndIndices.add(tokenRange.endIndex);
+                }
+            }
+        }
+    }
+    static _isDeclarationName(name) {
+        return ExcerptBuilder._isDeclaration(name.parent) && name.parent.name === name;
+    }
+    static _isDeclaration(node) {
+        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;
+        }
+    }
+}
+//# sourceMappingURL=ExcerptBuilder.js.map

package/lib-esm/generators/ExcerptBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExcerptBuilder.js","sourceRoot":"","sources":["../../src/generators/ExcerptBuilder.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAE3D,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AAGjC,OAAO,EACL,gBAAgB,EAGjB,MAAM,gCAAgC,CAAC;AAExC,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAwDxC,MAAM,OAAO,cAAc;IACzB;;;OAGG;IACI,MAAM,CAAC,YAAY,CAAC,aAA8B;QACvD,IAAI,QAAQ,GAAW,MAAM,CAAC;QAC9B,kFAAkF;QAClF,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC7B,MAAM,YAAY,GAAW,aAAa,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;YAC1E,IAAI,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC;gBAC7B,QAAQ,GAAG,IAAI,CAAC;YAClB,CAAC;QACH,CAAC;QACD,aAAa,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,gBAAgB,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;IACzE,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAC,cAAc,CAC1B,aAA8B,EAC9B,cAA8B,EAC9B,cAA8C,EAC9C,kBAAiD;QAEjD,IAAI,mBAAmB,GAA8B,SAAS,CAAC;QAE/D,QAAQ,cAAc,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC;YACxC,KAAK,EAAE,CAAC,UAAU,CAAC,gBAAgB,CAAC;YACpC,KAAK,EAAE,CAAC,UAAU,CAAC,eAAe,CAAC;YACnC,KAAK,EAAE,CAAC,UAAU,CAAC,oBAAoB;gBACrC,yBAAyB;gBACzB,mBAAmB,GAAG,EAAE,CAAC,UAAU,CAAC,gBAAgB,CAAC;gBACrD,MAAM;YACR,KAAK,EAAE,CAAC,UAAU,CAAC,iBAAiB;gBAClC,oCAAoC;gBACpC,mBAAmB,GAAG,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC;gBAChD,MAAM;QACV,CAAC;QAED,MAAM,IAAI,GAAS,IAAI,IAAI,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;QAExD,MAAM,gBAAgB,GAA+C,IAAI,GAAG,EAAE,CAAC;QAC/E,MAAM,kBAAkB,GAAyB,EAAE,CAAC;QACpD,KAAK,MAAM,aAAa,IAAI,cAAc,IAAI,EAAE,EAAE,CAAC;YACjD,gBAAgB,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;YACxD,IAAI,aAAa,CAAC,iBAAiB,EAAE,CAAC;gBACpC,kBAAkB,CAAC,IAAI,CAAC,aAAa,CAAC,iBAAiB,CAAC,CAAC;YAC3D,CAAC;QACH,CAAC;QAED,cAAc,CAAC,UAAU,CAAC,aAAa,EAAE,IAAI,EAAE;YAC7C,kBAAkB,EAAE,kBAAkB;YACtC,YAAY,EAAE,IAAI,CAAC,IAAI;YACvB,mBAAmB;YACnB,gBAAgB,EAAE,gBAAgB;YAClC,4BAA4B,EAAE,KAAK;SACpC,CAAC,CAAC;QAEH,cAAc,CAAC,eAAe,CAAC,aAAa,EAAE,kBAAkB,CAAC,CAAC;IACpE,CAAC;IAEM,MAAM,CAAC,qBAAqB;QACjC,OAAO,EAAE,UAAU,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;IACxC,CAAC;IAED,8EAA8E;IACtE,MAAM,CAAC,UAAU,CAAC,aAA8B,EAAE,IAAU,EAAE,KAAsB;QAC1F,IAAI,IAAI,CAAC,IAAI,KAAK,EAAE,CAAC,UAAU,CAAC,YAAY,EAAE,CAAC;YAC7C,uBAAuB;YACvB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,iCAAiC;QACjC,MAAM,SAAS,GAA6C,KAAK,CAAC,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAElG,IAAI,iBAAiB,GAAmC,SAAS,CAAC;QAElE,IAAI,SAAS,EAAE,CAAC;YACd,iBAAiB,GAAG,SAAS,CAAC,iBAAiB,CAAC;YAChD,IAAI,SAAS,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;gBAC5C,aAAa,CAAC,IAAI,CAAC;oBACjB,IAAI,EAAE,gBAAgB,CAAC,OAAO;oBAC9B,IAAI,EAAE,SAAS,CAAC,eAAe;iBAChC,CAAC,CAAC;gBACH,KAAK,CAAC,4BAA4B,GAAG,KAAK,CAAC;gBAE3C,IAAI,iBAAiB,EAAE,CAAC;oBACtB,iBAAiB,CAAC,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC;oBACpD,iBAAiB,CAAC,QAAQ,GAAG,iBAAiB,CAAC,UAAU,GAAG,CAAC,CAAC;gBAChE,CAAC;gBACD,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;QAED,IAAI,iBAAiB,GAAW,CAAC,CAAC;QAElC,IAAI,iBAAiB,EAAE,CAAC;YACtB,gGAAgG;YAChG,iBAAiB,GAAG,aAAa,CAAC,MAAM,CAAC;QAC3C,CAAC;QAED,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,IAAI,kBAAkB,GAAqC,SAAS,CAAC;YAErE,IAAI,IAAI,CAAC,IAAI,KAAK,EAAE,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC;gBAC3C,MAAM,IAAI,GAAkB,IAAI,CAAC,IAAqB,CAAC;gBACvD,IAAI,CAAC,cAAc,CAAC,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC;oBAC7C,kBAAkB,GAAG,KAAK,CAAC,kBAAkB,CAAC,oCAAoC,CAAC,IAAI,CAAC,CAAC;gBAC3F,CAAC;YACH,CAAC;YAED,IAAI,kBAAkB,EAAE,CAAC;gBACvB,cAAc,CAAC,YAAY,CACzB,aAAa,EACb,gBAAgB,CAAC,SAAS,EAC1B,IAAI,CAAC,MAAM,EACX,kBAAkB,CACnB,CAAC;YACJ,CAAC;iBAAM,CAAC;gBACN,cAAc,CAAC,YAAY,CAAC,aAAa,EAAE,gBAAgB,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;YACpF,CAAC;YACD,KAAK,CAAC,4BAA4B,GAAG,KAAK,CAAC;QAC7C,CAAC;QAED,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClC,IAAI,IAAI,CAAC,IAAI,KAAK,KAAK,CAAC,YAAY,EAAE,CAAC;gBACrC,IAAI,KAAK,CAAC,mBAAmB,IAAI,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,mBAAmB,EAAE,CAAC;oBAC1E,2EAA2E;oBAC3E,OAAO,KAAK,CAAC;gBACf,CAAC;YACH,CAAC;YAED,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,aAAa,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC;gBAClD,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QAED,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,cAAc,CAAC,YAAY,CAAC,aAAa,EAAE,gBAAgB,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;YAClF,KAAK,CAAC,4BAA4B,GAAG,KAAK,CAAC;QAC7C,CAAC;QACD,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,cAAc,CAAC,YAAY,CAAC,aAAa,EAAE,gBAAgB,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;YACrF,KAAK,CAAC,4BAA4B,GAAG,IAAI,CAAC;QAC5C,CAAC;QAED,mDAAmD;QACnD,IAAI,iBAAiB,EAAE,CAAC;YACtB,iBAAiB,CAAC,UAAU,GAAG,iBAAiB,CAAC;YAEjD,oFAAoF;YACpF,sFAAsF;YACtF,qBAAqB;YACrB,IAAI,eAAe,GAAW,aAAa,CAAC,MAAM,CAAC;YACnD,IAAI,KAAK,CAAC,4BAA4B,EAAE,CAAC;gBACvC,eAAe,EAAE,CAAC;YACpB,CAAC;YAED,iBAAiB,CAAC,QAAQ,GAAG,eAAe,CAAC;QAC/C,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,MAAM,CAAC,YAAY,CACzB,aAA8B,EAC9B,gBAAkC,EAClC,IAAY,EACZ,kBAAyC;QAEzC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtB,OAAO;QACT,CAAC;QAED,MAAM,YAAY,GAAkB,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QAC3E,IAAI,kBAAkB,KAAK,SAAS,EAAE,CAAC;YACrC,YAAY,CAAC,kBAAkB,GAAG,kBAAkB,CAAC,QAAQ,EAAE,CAAC;QAClE,CAAC;QACD,aAAa,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACnC,CAAC;IAED;;;;;;;;;OASG;IACK,MAAM,CAAC,eAAe,CAAC,aAA8B,EAAE,WAAiC;QAC9F,2DAA2D;QAC3D,MAAM,iBAAiB,GAAgB,IAAI,GAAG,EAAE,CAAC;QACjD,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;YACrC,iBAAiB,CAAC,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;YAC7C,iBAAiB,CAAC,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;QAC7C,CAAC;QAED,KAAK,IAAI,YAAY,GAAW,CAAC,EAAE,YAAY,GAAG,aAAa,CAAC,MAAM,EAAE,EAAE,YAAY,EAAE,CAAC;YACvF,OAAO,YAAY,GAAG,aAAa,CAAC,MAAM,EAAE,CAAC;gBAC3C,MAAM,aAAa,GAAkB,aAAa,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC,CAAC,mBAAmB;gBACzF,MAAM,SAAS,GAAkB,aAAa,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC;gBACjE,MAAM,YAAY,GAAkB,aAAa,CAAC,YAAY,CAAC,CAAC;gBAEhE,4FAA4F;gBAC5F,+DAA+D;gBAC/D,IAAI,UAAkB,CAAC;gBAEvB,yFAAyF;gBACzF,2CAA2C;gBAC3C,IACE,aAAa;oBACb,aAAa,CAAC,IAAI,KAAK,gBAAgB,CAAC,SAAS;oBACjD,SAAS,CAAC,IAAI,KAAK,gBAAgB,CAAC,OAAO;oBAC3C,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,GAAG;oBAC7B,YAAY,CAAC,IAAI,KAAK,gBAAgB,CAAC,SAAS;oBAChD,CAAC,iBAAiB,CAAC,GAAG,CAAC,YAAY,CAAC;oBACpC,CAAC,iBAAiB,CAAC,GAAG,CAAC,YAAY,GAAG,CAAC,CAAC,EACxC,CAAC;oBACD,4FAA4F;oBAC5F,2FAA2F;oBAC3F,EAAE;oBACF,6FAA6F;oBAC7F,0FAA0F;oBAC1F,aAAa,CAAC,IAAI,IAAI,SAAS,CAAC,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC;oBACzD,aAAa,CAAC,kBAAkB,GAAG,YAAY,CAAC,kBAAkB,CAAC;oBACnE,UAAU,GAAG,CAAC,CAAC;oBACf,YAAY,EAAE,CAAC;gBACjB,CAAC;qBAAM;gBACL,2FAA2F;gBAC3F,sFAAsF;gBACtF,+CAA+C;gBAC/C,SAAS,CAAC,IAAI,KAAK,gBAAgB,CAAC,OAAO;oBAC3C,SAAS,CAAC,IAAI,KAAK,YAAY,CAAC,IAAI;oBACpC,CAAC,iBAAiB,CAAC,GAAG,CAAC,YAAY,CAAC,EACpC,CAAC;oBACD,SAAS,CAAC,IAAI,IAAI,YAAY,CAAC,IAAI,CAAC;oBACpC,UAAU,GAAG,CAAC,CAAC;gBACjB,CAAC;qBAAM,CAAC;oBACN,oEAAoE;oBACpE,MAAM;gBACR,CAAC;gBAED,wFAAwF;gBACxF,aAAa,CAAC,MAAM,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;gBAE/C,oFAAoF;gBACpF,4CAA4C;gBAC5C,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;oBACrC,IAAI,UAAU,CAAC,UAAU,GAAG,YAAY,EAAE,CAAC;wBACzC,UAAU,CAAC,UAAU,IAAI,UAAU,CAAC;oBACtC,CAAC;oBAED,IAAI,UAAU,CAAC,QAAQ,GAAG,YAAY,EAAE,CAAC;wBACvC,UAAU,CAAC,QAAQ,IAAI,UAAU,CAAC;oBACpC,CAAC;gBACH,CAAC;gBAED,yDAAyD;gBACzD,iBAAiB,CAAC,KAAK,EAAE,CAAC;gBAC1B,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;oBACrC,iBAAiB,CAAC,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;oBAC7C,iBAAiB,CAAC,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;gBAC7C,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAEO,MAAM,CAAC,kBAAkB,CAAC,IAAmB;QACnD,OAAO,cAAc,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,IAAI,CAAC;IACjF,CAAC;IAEO,MAAM,CAAC,cAAc,CAAC,IAAa;QACzC,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;YAClB,KAAK,EAAE,CAAC,UAAU,CAAC,mBAAmB,CAAC;YACvC,KAAK,EAAE,CAAC,UAAU,CAAC,kBAAkB,CAAC;YACtC,KAAK,EAAE,CAAC,UAAU,CAAC,mBAAmB,CAAC;YACvC,KAAK,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC;YAC7B,KAAK,EAAE,CAAC,UAAU,CAAC,eAAe,CAAC;YACnC,KAAK,EAAE,CAAC,UAAU,CAAC,gBAAgB,CAAC;YACpC,KAAK,EAAE,CAAC,UAAU,CAAC,eAAe,CAAC;YACnC,KAAK,EAAE,CAAC,UAAU,CAAC,iBAAiB,CAAC;YACrC,KAAK,EAAE,CAAC,UAAU,CAAC,iBAAiB,CAAC;YACrC,KAAK,EAAE,CAAC,UAAU,CAAC,eAAe,CAAC;YACnC,KAAK,EAAE,CAAC,UAAU,CAAC,mBAAmB,CAAC;YACvC,KAAK,EAAE,CAAC,UAAU,CAAC,iBAAiB,CAAC;YACrC,KAAK,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC;YAC/B,KAAK,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC;YAC/B,KAAK,EAAE,CAAC,UAAU,CAAC,oBAAoB,CAAC;YACxC,KAAK,EAAE,CAAC,UAAU,CAAC,oBAAoB,CAAC;YACxC,KAAK,EAAE,CAAC,UAAU,CAAC,aAAa,CAAC;YACjC,KAAK,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC;YAC9B,KAAK,EAAE,CAAC,UAAU,CAAC,cAAc;gBAC/B,OAAO,IAAI,CAAC;YACd;gBACE,OAAO,KAAK,CAAC;QACjB,CAAC;IACH,CAAC;CACF","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport * as ts from 'typescript';\n\nimport type { DeclarationReference } from '@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference';\nimport {\n  ExcerptTokenKind,\n  type IExcerptToken,\n  type IExcerptTokenRange\n} from '@microsoft/api-extractor-model';\n\nimport { Span } from '../analyzer/Span';\nimport type { DeclarationReferenceGenerator } from './DeclarationReferenceGenerator';\nimport type { AstDeclaration } from '../analyzer/AstDeclaration';\n\n/**\n * Used to provide ExcerptBuilder with a list of nodes whose token range we want to capture.\n */\nexport interface IExcerptBuilderNodeTransform {\n  /**\n   * The node to process\n   */\n  node: ts.Node;\n\n  /**\n   * A token range whose startIndex/endIndex will be overwritten with the indexes for the\n   * tokens corresponding to IExcerptBuilderNodeTransform.node\n   */\n  captureTokenRange?: IExcerptTokenRange;\n\n  /**\n   * Text that will replace the text of the given node during emit.\n   */\n  replacementText?: string;\n}\n\n/**\n * Internal state for ExcerptBuilder\n */\ninterface IBuildSpanState {\n  referenceGenerator: DeclarationReferenceGenerator;\n\n  /**\n   * The AST node that we will traverse to extract tokens\n   */\n  startingNode: ts.Node;\n\n  /**\n   * Normally, the excerpt will include all child nodes for `startingNode`; whereas if `childKindToStopBefore`\n   * is specified, then the node traversal will stop before (i.e. excluding) the first immediate child\n   * of `startingNode` with the specified syntax kind.\n   *\n   * @remarks\n   * For example, suppose the signature is `interface X: Y { z: string }`.  The token `{` has syntax kind\n   * `ts.SyntaxKind.FirstPunctuation`, so we can specify that to truncate the excerpt to `interface X: Y`.\n   */\n  stopBeforeChildKind: ts.SyntaxKind | undefined;\n\n  transformsByNode: Map<ts.Node, IExcerptBuilderNodeTransform>;\n\n  /**\n   * Tracks whether the last appended token was a separator. If so, and we're in the middle of\n   * capturing a token range, then omit the separator from the range.\n   */\n  lastAppendedTokenIsSeparator: boolean;\n}\n\nexport class ExcerptBuilder {\n  /**\n   * Appends a blank line to the `excerptTokens` list.\n   * @param excerptTokens - The target token list to append to\n   */\n  public static addBlankLine(excerptTokens: IExcerptToken[]): void {\n    let newlines: string = '\\n\\n';\n    // If the existing text already ended with a newline, then only append one newline\n    if (excerptTokens.length > 0) {\n      const previousText: string = excerptTokens[excerptTokens.length - 1].text;\n      if (/\\n$/.test(previousText)) {\n        newlines = '\\n';\n      }\n    }\n    excerptTokens.push({ kind: ExcerptTokenKind.Content, text: newlines });\n  }\n\n  /**\n   * Appends the signature for the specified `AstDeclaration` to the `excerptTokens` list.\n   * @param excerptTokens - The target token list to append to\n   * @param nodeTransforms - A list of child nodes whose token ranges we want to capture\n   */\n  public static addDeclaration(\n    excerptTokens: IExcerptToken[],\n    astDeclaration: AstDeclaration,\n    nodeTransforms: IExcerptBuilderNodeTransform[],\n    referenceGenerator: DeclarationReferenceGenerator\n  ): void {\n    let stopBeforeChildKind: ts.SyntaxKind | undefined = undefined;\n\n    switch (astDeclaration.declaration.kind) {\n      case ts.SyntaxKind.ClassDeclaration:\n      case ts.SyntaxKind.EnumDeclaration:\n      case ts.SyntaxKind.InterfaceDeclaration:\n        // FirstPunctuation = \"{\"\n        stopBeforeChildKind = ts.SyntaxKind.FirstPunctuation;\n        break;\n      case ts.SyntaxKind.ModuleDeclaration:\n        // ModuleBlock = the \"{ ... }\" block\n        stopBeforeChildKind = ts.SyntaxKind.ModuleBlock;\n        break;\n    }\n\n    const span: Span = new Span(astDeclaration.declaration);\n\n    const transformsByNode: Map<ts.Node, IExcerptBuilderNodeTransform> = new Map();\n    const captureTokenRanges: IExcerptTokenRange[] = [];\n    for (const nodeTransform of nodeTransforms || []) {\n      transformsByNode.set(nodeTransform.node, nodeTransform);\n      if (nodeTransform.captureTokenRange) {\n        captureTokenRanges.push(nodeTransform.captureTokenRange);\n      }\n    }\n\n    ExcerptBuilder._buildSpan(excerptTokens, span, {\n      referenceGenerator: referenceGenerator,\n      startingNode: span.node,\n      stopBeforeChildKind,\n      transformsByNode: transformsByNode,\n      lastAppendedTokenIsSeparator: false\n    });\n\n    ExcerptBuilder._condenseTokens(excerptTokens, captureTokenRanges);\n  }\n\n  public static createEmptyTokenRange(): IExcerptTokenRange {\n    return { startIndex: 0, endIndex: 0 };\n  }\n\n  /** @returns false if we encountered a token that causes iteration to stop. */\n  private static _buildSpan(excerptTokens: IExcerptToken[], span: Span, state: IBuildSpanState): boolean {\n    if (span.kind === ts.SyntaxKind.JSDocComment) {\n      // Discard any comments\n      return true;\n    }\n\n    // Can this node start a excerpt?\n    const transform: IExcerptBuilderNodeTransform | undefined = state.transformsByNode.get(span.node);\n\n    let captureTokenRange: IExcerptTokenRange | undefined = undefined;\n\n    if (transform) {\n      captureTokenRange = transform.captureTokenRange;\n      if (transform.replacementText !== undefined) {\n        excerptTokens.push({\n          kind: ExcerptTokenKind.Content,\n          text: transform.replacementText\n        });\n        state.lastAppendedTokenIsSeparator = false;\n\n        if (captureTokenRange) {\n          captureTokenRange.startIndex = excerptTokens.length;\n          captureTokenRange.endIndex = captureTokenRange.startIndex + 1;\n        }\n        return true;\n      }\n    }\n\n    let excerptStartIndex: number = 0;\n\n    if (captureTokenRange) {\n      // We will assign capturedTokenRange.startIndex to be the index of the next token to be appended\n      excerptStartIndex = excerptTokens.length;\n    }\n\n    if (span.prefix) {\n      let canonicalReference: DeclarationReference | undefined = undefined;\n\n      if (span.kind === ts.SyntaxKind.Identifier) {\n        const name: ts.Identifier = span.node as ts.Identifier;\n        if (!ExcerptBuilder._isDeclarationName(name)) {\n          canonicalReference = state.referenceGenerator.getDeclarationReferenceForIdentifier(name);\n        }\n      }\n\n      if (canonicalReference) {\n        ExcerptBuilder._appendToken(\n          excerptTokens,\n          ExcerptTokenKind.Reference,\n          span.prefix,\n          canonicalReference\n        );\n      } else {\n        ExcerptBuilder._appendToken(excerptTokens, ExcerptTokenKind.Content, span.prefix);\n      }\n      state.lastAppendedTokenIsSeparator = false;\n    }\n\n    for (const child of span.children) {\n      if (span.node === state.startingNode) {\n        if (state.stopBeforeChildKind && child.kind === state.stopBeforeChildKind) {\n          // We reached a child whose kind is stopBeforeChildKind, so stop traversing\n          return false;\n        }\n      }\n\n      if (!this._buildSpan(excerptTokens, child, state)) {\n        return false;\n      }\n    }\n\n    if (span.suffix) {\n      ExcerptBuilder._appendToken(excerptTokens, ExcerptTokenKind.Content, span.suffix);\n      state.lastAppendedTokenIsSeparator = false;\n    }\n    if (span.separator) {\n      ExcerptBuilder._appendToken(excerptTokens, ExcerptTokenKind.Content, span.separator);\n      state.lastAppendedTokenIsSeparator = true;\n    }\n\n    // Are we building a excerpt?  If so, set its range\n    if (captureTokenRange) {\n      captureTokenRange.startIndex = excerptStartIndex;\n\n      // We will assign capturedTokenRange.startIndex to be the index after the last token\n      // that was appended so far. However, if the last appended token was a separator, omit\n      // it from the range.\n      let excerptEndIndex: number = excerptTokens.length;\n      if (state.lastAppendedTokenIsSeparator) {\n        excerptEndIndex--;\n      }\n\n      captureTokenRange.endIndex = excerptEndIndex;\n    }\n\n    return true;\n  }\n\n  private static _appendToken(\n    excerptTokens: IExcerptToken[],\n    excerptTokenKind: ExcerptTokenKind,\n    text: string,\n    canonicalReference?: DeclarationReference\n  ): void {\n    if (text.length === 0) {\n      return;\n    }\n\n    const excerptToken: IExcerptToken = { kind: excerptTokenKind, text: text };\n    if (canonicalReference !== undefined) {\n      excerptToken.canonicalReference = canonicalReference.toString();\n    }\n    excerptTokens.push(excerptToken);\n  }\n\n  /**\n   * Condenses the provided excerpt tokens by merging tokens where possible. Updates the provided token ranges to\n   * remain accurate after token merging.\n   *\n   * @remarks\n   * For example, suppose we have excerpt tokens [\"A\", \"B\", \"C\"] and a token range [0, 2]. If the excerpt tokens\n   * are condensed to [\"AB\", \"C\"], then the token range would be updated to [0, 1]. Note that merges are only\n   * performed if they are compatible with the provided token ranges. In the example above, if our token range was\n   * originally [0, 1], we would not be able to merge tokens \"A\" and \"B\".\n   */\n  private static _condenseTokens(excerptTokens: IExcerptToken[], tokenRanges: IExcerptTokenRange[]): void {\n    // This set is used to quickly lookup a start or end index.\n    const startOrEndIndices: Set<number> = new Set();\n    for (const tokenRange of tokenRanges) {\n      startOrEndIndices.add(tokenRange.startIndex);\n      startOrEndIndices.add(tokenRange.endIndex);\n    }\n\n    for (let currentIndex: number = 1; currentIndex < excerptTokens.length; ++currentIndex) {\n      while (currentIndex < excerptTokens.length) {\n        const prevPrevToken: IExcerptToken = excerptTokens[currentIndex - 2]; // May be undefined\n        const prevToken: IExcerptToken = excerptTokens[currentIndex - 1];\n        const currentToken: IExcerptToken = excerptTokens[currentIndex];\n\n        // The number of excerpt tokens that are merged in this iteration. We need this to determine\n        // how to update the start and end indices of our token ranges.\n        let mergeCount: number;\n\n        // There are two types of merges that can occur. We only perform these merges if they are\n        // compatible with all of our token ranges.\n        if (\n          prevPrevToken &&\n          prevPrevToken.kind === ExcerptTokenKind.Reference &&\n          prevToken.kind === ExcerptTokenKind.Content &&\n          prevToken.text.trim() === '.' &&\n          currentToken.kind === ExcerptTokenKind.Reference &&\n          !startOrEndIndices.has(currentIndex) &&\n          !startOrEndIndices.has(currentIndex - 1)\n        ) {\n          // If the current token is a reference token, the previous token is a \".\", and the previous-\n          // previous token is a reference token, then merge all three tokens into a reference token.\n          //\n          // For example: Given [\"MyNamespace\" (R), \".\", \"MyClass\" (R)], tokens \".\" and \"MyClass\" might\n          // be merged into \"MyNamespace\". The condensed token would be [\"MyNamespace.MyClass\" (R)].\n          prevPrevToken.text += prevToken.text + currentToken.text;\n          prevPrevToken.canonicalReference = currentToken.canonicalReference;\n          mergeCount = 2;\n          currentIndex--;\n        } else if (\n          // If the current and previous tokens are both content tokens, then merge the tokens into a\n          // single content token. For example: Given [\"export \", \"declare class\"], these tokens\n          // might be merged into \"export declare class\".\n          prevToken.kind === ExcerptTokenKind.Content &&\n          prevToken.kind === currentToken.kind &&\n          !startOrEndIndices.has(currentIndex)\n        ) {\n          prevToken.text += currentToken.text;\n          mergeCount = 1;\n        } else {\n          // Otherwise, no merging can occur here. Continue to the next index.\n          break;\n        }\n\n        // Remove the now redundant excerpt token(s), as they were merged into a previous token.\n        excerptTokens.splice(currentIndex, mergeCount);\n\n        // Update the start and end indices for all token ranges based upon how many excerpt\n        // tokens were merged and in what positions.\n        for (const tokenRange of tokenRanges) {\n          if (tokenRange.startIndex > currentIndex) {\n            tokenRange.startIndex -= mergeCount;\n          }\n\n          if (tokenRange.endIndex > currentIndex) {\n            tokenRange.endIndex -= mergeCount;\n          }\n        }\n\n        // Clear and repopulate our set with the updated indices.\n        startOrEndIndices.clear();\n        for (const tokenRange of tokenRanges) {\n          startOrEndIndices.add(tokenRange.startIndex);\n          startOrEndIndices.add(tokenRange.endIndex);\n        }\n      }\n    }\n  }\n\n  private static _isDeclarationName(name: ts.Identifier): boolean {\n    return ExcerptBuilder._isDeclaration(name.parent) && name.parent.name === name;\n  }\n\n  private static _isDeclaration(node: ts.Node): node is ts.NamedDeclaration {\n    switch (node.kind) {\n      case ts.SyntaxKind.FunctionDeclaration:\n      case ts.SyntaxKind.FunctionExpression:\n      case ts.SyntaxKind.VariableDeclaration:\n      case ts.SyntaxKind.Parameter:\n      case ts.SyntaxKind.EnumDeclaration:\n      case ts.SyntaxKind.ClassDeclaration:\n      case ts.SyntaxKind.ClassExpression:\n      case ts.SyntaxKind.ModuleDeclaration:\n      case ts.SyntaxKind.MethodDeclaration:\n      case ts.SyntaxKind.MethodSignature:\n      case ts.SyntaxKind.PropertyDeclaration:\n      case ts.SyntaxKind.PropertySignature:\n      case ts.SyntaxKind.GetAccessor:\n      case ts.SyntaxKind.SetAccessor:\n      case ts.SyntaxKind.InterfaceDeclaration:\n      case ts.SyntaxKind.TypeAliasDeclaration:\n      case ts.SyntaxKind.TypeParameter:\n      case ts.SyntaxKind.EnumMember:\n      case ts.SyntaxKind.BindingElement:\n        return true;\n      default:\n        return false;\n    }\n  }\n}\n"]}

package/lib-esm/generators/IndentedWriter.js

@@ -0,0 +1,238 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import { StringBuilder } from '@rushstack/node-core-library';
+/**
+ * A utility for writing indented text.
+ *
+ * @remarks
+ *
+ * Note that the indentation is inserted at the last possible opportunity.
+ * For example, this code...
+ *
+ * ```ts
+ *   writer.write('begin\n');
+ *   writer.increaseIndent();
+ *   writer.write('one\ntwo\n');
+ *   writer.decreaseIndent();
+ *   writer.increaseIndent();
+ *   writer.decreaseIndent();
+ *   writer.write('end');
+ * ```
+ *
+ * ...would produce this output:
+ *
+ * ```
+ *   begin
+ *     one
+ *     two
+ *   end
+ * ```
+ */
+export class IndentedWriter {
+    constructor(builder) {
+        /**
+         * The text characters used to create one level of indentation.
+         * Two spaces by default.
+         */
+        this.defaultIndentPrefix = '    ';
+        /**
+         * Whether to indent blank lines
+         */
+        this.indentBlankLines = false;
+        /**
+         * Trims leading spaces from the input text before applying the indent.
+         *
+         * @remarks
+         * Consider the following example:
+         *
+         * ```ts
+         * indentedWriter.increaseIndent('    '); // four spaces
+         * indentedWriter.write('  a\n  b  c\n');
+         * indentedWriter.decreaseIndent();
+         * ```
+         *
+         * Normally the output would be indented by 6 spaces: 4 from `increaseIndent()`, plus the 2 spaces
+         * from `write()`:
+         * ```
+         *       a
+         *       b  c
+         * ```
+         *
+         * Setting `trimLeadingSpaces=true` will trim the leading spaces, so that the lines are indented
+         * by 4 spaces only:
+         * ```
+         *     a
+         *     b  c
+         * ```
+         */
+        this.trimLeadingSpaces = false;
+        this._builder = builder === undefined ? new StringBuilder() : builder;
+        this._latestChunk = undefined;
+        this._previousChunk = undefined;
+        this._atStartOfLine = true;
+        this._previousLineIsBlank = true;
+        this._currentLineIsBlank = true;
+        this._indentStack = [];
+        this._indentText = '';
+    }
+    /**
+     * Retrieves the output that was built so far.
+     */
+    getText() {
+        return this._builder.toString();
+    }
+    toString() {
+        return this.getText();
+    }
+    /**
+     * Increases the indentation.  Normally the indentation is two spaces,
+     * however an arbitrary prefix can optional be specified.  (For example,
+     * the prefix could be "// " to indent and comment simultaneously.)
+     * Each call to IndentedWriter.increaseIndent() must be followed by a
+     * corresponding call to IndentedWriter.decreaseIndent().
+     */
+    increaseIndent(indentPrefix) {
+        this._indentStack.push(indentPrefix !== undefined ? indentPrefix : this.defaultIndentPrefix);
+        this._updateIndentText();
+    }
+    /**
+     * Decreases the indentation, reverting the effect of the corresponding call
+     * to IndentedWriter.increaseIndent().
+     */
+    decreaseIndent() {
+        this._indentStack.pop();
+        this._updateIndentText();
+    }
+    /**
+     * A shorthand for ensuring that increaseIndent()/decreaseIndent() occur
+     * in pairs.
+     */
+    indentScope(scope, indentPrefix) {
+        this.increaseIndent(indentPrefix);
+        scope();
+        this.decreaseIndent();
+    }
+    /**
+     * Adds a newline if the file pointer is not already at the start of the line (or start of the stream).
+     */
+    ensureNewLine() {
+        const lastCharacter = this.peekLastCharacter();
+        if (lastCharacter !== '\n' && lastCharacter !== '') {
+            this._writeNewLine();
+        }
+    }
+    /**
+     * Adds up to two newlines to ensure that there is a blank line above the current position.
+     * The start of the stream is considered to be a blank line, so `ensureSkippedLine()` has no effect
+     * unless some text has been written.
+     */
+    ensureSkippedLine() {
+        this.ensureNewLine();
+        if (!this._previousLineIsBlank) {
+            this._writeNewLine();
+        }
+    }
+    /**
+     * Returns the last character that was written, or an empty string if no characters have been written yet.
+     */
+    peekLastCharacter() {
+        if (this._latestChunk !== undefined) {
+            return this._latestChunk.substr(-1, 1);
+        }
+        return '';
+    }
+    /**
+     * Returns the second to last character that was written, or an empty string if less than one characters
+     * have been written yet.
+     */
+    peekSecondLastCharacter() {
+        if (this._latestChunk !== undefined) {
+            if (this._latestChunk.length > 1) {
+                return this._latestChunk.substr(-2, 1);
+            }
+            if (this._previousChunk !== undefined) {
+                return this._previousChunk.substr(-1, 1);
+            }
+        }
+        return '';
+    }
+    /**
+     * Writes some text to the internal string buffer, applying indentation according
+     * to the current indentation level.  If the string contains multiple newlines,
+     * each line will be indented separately.
+     */
+    write(message) {
+        if (message.length === 0) {
+            return;
+        }
+        // If there are no newline characters, then append the string verbatim
+        if (!/[\r\n]/.test(message)) {
+            this._writeLinePart(message);
+            return;
+        }
+        // Otherwise split the lines and write each one individually
+        let first = true;
+        for (const linePart of message.split('\n')) {
+            if (!first) {
+                this._writeNewLine();
+            }
+            else {
+                first = false;
+            }
+            if (linePart) {
+                this._writeLinePart(linePart.replace(/[\r]/g, ''));
+            }
+        }
+    }
+    /**
+     * A shorthand for writing an optional message, followed by a newline.
+     * Indentation is applied following the semantics of IndentedWriter.write().
+     */
+    writeLine(message = '') {
+        if (message.length > 0) {
+            this.write(message);
+        }
+        this._writeNewLine();
+    }
+    /**
+     * Writes a string that does not contain any newline characters.
+     */
+    _writeLinePart(message) {
+        let trimmedMessage = message;
+        if (this.trimLeadingSpaces && this._atStartOfLine) {
+            trimmedMessage = message.replace(/^ +/, '');
+        }
+        if (trimmedMessage.length > 0) {
+            if (this._atStartOfLine && this._indentText.length > 0) {
+                this._write(this._indentText);
+            }
+            this._write(trimmedMessage);
+            if (this._currentLineIsBlank) {
+                if (/\S/.test(trimmedMessage)) {
+                    this._currentLineIsBlank = false;
+                }
+            }
+            this._atStartOfLine = false;
+        }
+    }
+    _writeNewLine() {
+        if (this.indentBlankLines) {
+            if (this._atStartOfLine && this._indentText.length > 0) {
+                this._write(this._indentText);
+            }
+        }
+        this._previousLineIsBlank = this._currentLineIsBlank;
+        this._write('\n');
+        this._currentLineIsBlank = true;
+        this._atStartOfLine = true;
+    }
+    _write(s) {
+        this._previousChunk = this._latestChunk;
+        this._latestChunk = s;
+        this._builder.append(s);
+    }
+    _updateIndentText() {
+        this._indentText = this._indentStack.join('');
+    }
+}
+//# sourceMappingURL=IndentedWriter.js.map

package/lib-esm/generators/IndentedWriter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IndentedWriter.js","sourceRoot":"","sources":["../../src/generators/IndentedWriter.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport { StringBuilder, type IStringBuilder } from '@rushstack/node-core-library';\n\n/**\n * A utility for writing indented text.\n *\n * @remarks\n *\n * Note that the indentation is inserted at the last possible opportunity.\n * For example, this code...\n *\n * ```ts\n *   writer.write('begin\\n');\n *   writer.increaseIndent();\n *   writer.write('one\\ntwo\\n');\n *   writer.decreaseIndent();\n *   writer.increaseIndent();\n *   writer.decreaseIndent();\n *   writer.write('end');\n * ```\n *\n * ...would produce this output:\n *\n * ```\n *   begin\n *     one\n *     two\n *   end\n * ```\n */\nexport class IndentedWriter {\n  /**\n   * The text characters used to create one level of indentation.\n   * Two spaces by default.\n   */\n  public defaultIndentPrefix: string = '    ';\n\n  /**\n   * Whether to indent blank lines\n   */\n  public indentBlankLines: boolean = false;\n\n  /**\n   * Trims leading spaces from the input text before applying the indent.\n   *\n   * @remarks\n   * Consider the following example:\n   *\n   * ```ts\n   * indentedWriter.increaseIndent('    '); // four spaces\n   * indentedWriter.write('  a\\n  b  c\\n');\n   * indentedWriter.decreaseIndent();\n   * ```\n   *\n   * Normally the output would be indented by 6 spaces: 4 from `increaseIndent()`, plus the 2 spaces\n   * from `write()`:\n   * ```\n   *       a\n   *       b  c\n   * ```\n   *\n   * Setting `trimLeadingSpaces=true` will trim the leading spaces, so that the lines are indented\n   * by 4 spaces only:\n   * ```\n   *     a\n   *     b  c\n   * ```\n   */\n  public trimLeadingSpaces: boolean = false;\n\n  private readonly _builder: IStringBuilder;\n\n  private _latestChunk: string | undefined;\n  private _previousChunk: string | undefined;\n  private _atStartOfLine: boolean;\n\n  private readonly _indentStack: string[];\n  private _indentText: string;\n\n  private _previousLineIsBlank: boolean;\n  private _currentLineIsBlank: boolean;\n\n  public constructor(builder?: IStringBuilder) {\n    this._builder = builder === undefined ? new StringBuilder() : builder;\n    this._latestChunk = undefined;\n    this._previousChunk = undefined;\n    this._atStartOfLine = true;\n    this._previousLineIsBlank = true;\n    this._currentLineIsBlank = true;\n\n    this._indentStack = [];\n    this._indentText = '';\n  }\n\n  /**\n   * Retrieves the output that was built so far.\n   */\n  public getText(): string {\n    return this._builder.toString();\n  }\n\n  public toString(): string {\n    return this.getText();\n  }\n\n  /**\n   * Increases the indentation.  Normally the indentation is two spaces,\n   * however an arbitrary prefix can optional be specified.  (For example,\n   * the prefix could be \"// \" to indent and comment simultaneously.)\n   * Each call to IndentedWriter.increaseIndent() must be followed by a\n   * corresponding call to IndentedWriter.decreaseIndent().\n   */\n  public increaseIndent(indentPrefix?: string): void {\n    this._indentStack.push(indentPrefix !== undefined ? indentPrefix : this.defaultIndentPrefix);\n    this._updateIndentText();\n  }\n\n  /**\n   * Decreases the indentation, reverting the effect of the corresponding call\n   * to IndentedWriter.increaseIndent().\n   */\n  public decreaseIndent(): void {\n    this._indentStack.pop();\n    this._updateIndentText();\n  }\n\n  /**\n   * A shorthand for ensuring that increaseIndent()/decreaseIndent() occur\n   * in pairs.\n   */\n  public indentScope(scope: () => void, indentPrefix?: string): void {\n    this.increaseIndent(indentPrefix);\n    scope();\n    this.decreaseIndent();\n  }\n\n  /**\n   * Adds a newline if the file pointer is not already at the start of the line (or start of the stream).\n   */\n  public ensureNewLine(): void {\n    const lastCharacter: string = this.peekLastCharacter();\n    if (lastCharacter !== '\\n' && lastCharacter !== '') {\n      this._writeNewLine();\n    }\n  }\n\n  /**\n   * Adds up to two newlines to ensure that there is a blank line above the current position.\n   * The start of the stream is considered to be a blank line, so `ensureSkippedLine()` has no effect\n   * unless some text has been written.\n   */\n  public ensureSkippedLine(): void {\n    this.ensureNewLine();\n    if (!this._previousLineIsBlank) {\n      this._writeNewLine();\n    }\n  }\n\n  /**\n   * Returns the last character that was written, or an empty string if no characters have been written yet.\n   */\n  public peekLastCharacter(): string {\n    if (this._latestChunk !== undefined) {\n      return this._latestChunk.substr(-1, 1);\n    }\n    return '';\n  }\n\n  /**\n   * Returns the second to last character that was written, or an empty string if less than one characters\n   * have been written yet.\n   */\n  public peekSecondLastCharacter(): string {\n    if (this._latestChunk !== undefined) {\n      if (this._latestChunk.length > 1) {\n        return this._latestChunk.substr(-2, 1);\n      }\n      if (this._previousChunk !== undefined) {\n        return this._previousChunk.substr(-1, 1);\n      }\n    }\n    return '';\n  }\n\n  /**\n   * Writes some text to the internal string buffer, applying indentation according\n   * to the current indentation level.  If the string contains multiple newlines,\n   * each line will be indented separately.\n   */\n  public write(message: string): void {\n    if (message.length === 0) {\n      return;\n    }\n\n    // If there are no newline characters, then append the string verbatim\n    if (!/[\\r\\n]/.test(message)) {\n      this._writeLinePart(message);\n      return;\n    }\n\n    // Otherwise split the lines and write each one individually\n    let first: boolean = true;\n    for (const linePart of message.split('\\n')) {\n      if (!first) {\n        this._writeNewLine();\n      } else {\n        first = false;\n      }\n      if (linePart) {\n        this._writeLinePart(linePart.replace(/[\\r]/g, ''));\n      }\n    }\n  }\n\n  /**\n   * A shorthand for writing an optional message, followed by a newline.\n   * Indentation is applied following the semantics of IndentedWriter.write().\n   */\n  public writeLine(message: string = ''): void {\n    if (message.length > 0) {\n      this.write(message);\n    }\n    this._writeNewLine();\n  }\n\n  /**\n   * Writes a string that does not contain any newline characters.\n   */\n  private _writeLinePart(message: string): void {\n    let trimmedMessage: string = message;\n\n    if (this.trimLeadingSpaces && this._atStartOfLine) {\n      trimmedMessage = message.replace(/^ +/, '');\n    }\n\n    if (trimmedMessage.length > 0) {\n      if (this._atStartOfLine && this._indentText.length > 0) {\n        this._write(this._indentText);\n      }\n      this._write(trimmedMessage);\n      if (this._currentLineIsBlank) {\n        if (/\\S/.test(trimmedMessage)) {\n          this._currentLineIsBlank = false;\n        }\n      }\n      this._atStartOfLine = false;\n    }\n  }\n\n  private _writeNewLine(): void {\n    if (this.indentBlankLines) {\n      if (this._atStartOfLine && this._indentText.length > 0) {\n        this._write(this._indentText);\n      }\n    }\n\n    this._previousLineIsBlank = this._currentLineIsBlank;\n    this._write('\\n');\n    this._currentLineIsBlank = true;\n    this._atStartOfLine = true;\n  }\n\n  private _write(s: string): void {\n    this._previousChunk = this._latestChunk;\n    this._latestChunk = s;\n    this._builder.append(s);\n  }\n\n  private _updateIndentText(): void {\n    this._indentText = this._indentStack.join('');\n  }\n}\n"]}

package/lib-esm/index.js

@@ -0,0 +1,17 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+/**
+ * API Extractor helps with validation, documentation, and reviewing of the exported API for a TypeScript library.
+ * The `@microsoft/api-extractor` package provides the command-line tool.  It also exposes a developer API that you
+ * can use to invoke API Extractor programmatically.
+ *
+ * @packageDocumentation
+ */
+export { ConsoleMessageId } from './api/ConsoleMessageId';
+export { CompilerState } from './api/CompilerState';
+export { Extractor, ExtractorResult } from './api/Extractor';
+export { ExtractorConfig } from './api/ExtractorConfig';
+export { ExtractorLogLevel } from './api/ExtractorLogLevel';
+export { ExtractorMessage, ExtractorMessageCategory } from './api/ExtractorMessage';
+export { ExtractorMessageId } from './api/ExtractorMessageId';
+//# sourceMappingURL=index.js.map

package/lib-esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAE3D;;;;;;GAMG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,EAAE,aAAa,EAAoC,MAAM,qBAAqB,CAAC;AAEtF,OAAO,EAAE,SAAS,EAAgC,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAE3F,OAAO,EAIL,eAAe,EAChB,MAAM,uBAAuB,CAAC;AAI/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5D,OAAO,EACL,gBAAgB,EAEhB,wBAAwB,EACzB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\n/**\n * API Extractor helps with validation, documentation, and reviewing of the exported API for a TypeScript library.\n * The `@microsoft/api-extractor` package provides the command-line tool.  It also exposes a developer API that you\n * can use to invoke API Extractor programmatically.\n *\n * @packageDocumentation\n */\n\nexport { ConsoleMessageId } from './api/ConsoleMessageId';\n\nexport { CompilerState, type ICompilerStateCreateOptions } from './api/CompilerState';\n\nexport { Extractor, type IExtractorInvokeOptions, ExtractorResult } from './api/Extractor';\n\nexport {\n  type IExtractorConfigApiReport,\n  type IExtractorConfigPrepareOptions,\n  type IExtractorConfigLoadForFolderOptions,\n  ExtractorConfig\n} from './api/ExtractorConfig';\n\nexport type { IApiModelGenerationOptions } from './generators/ApiModelGenerator';\n\nexport { ExtractorLogLevel } from './api/ExtractorLogLevel';\n\nexport {\n  ExtractorMessage,\n  type IExtractorMessageProperties,\n  ExtractorMessageCategory\n} from './api/ExtractorMessage';\n\nexport { ExtractorMessageId } from './api/ExtractorMessageId';\n\nexport type {\n  ApiReportVariant,\n  IConfigCompiler,\n  IConfigApiReport,\n  IConfigDocModel,\n  IConfigDtsRollup,\n  IConfigTsdocMetadata,\n  IConfigMessageReportingRule,\n  IConfigMessageReportingTable,\n  IExtractorMessagesConfig,\n  IConfigFile,\n  ReleaseTagForTrim\n} from './api/IConfigFile';\n"]}