Responded to PR feedback

Author: zelliott

apps/api-extractor/src/api/ExtractorConfig.ts

@@ -162,6 +162,7 @@ interface IExtractorConfigParameters {
   docModelEnabled: boolean;
   apiJsonFilePath: string;
   docModelIncludeForgottenExports: boolean;
+  projectFolderUrl: string | undefined;
   rollupEnabled: boolean;
   untrimmedFilePath: string;
   alphaTrimmedFilePath: string;
@@ -257,6 +258,8 @@ export class ExtractorConfig {
   public readonly apiJsonFilePath: string;
   /** {@inheritDoc IConfigDocModel.includeForgottenExports} */
   public readonly docModelIncludeForgottenExports: boolean;
+  /** {@inheritDoc IConfigDocModel.projectFolderUrl} */
+  public readonly projectFolderUrl: string | undefined;
 
   /** {@inheritDoc IConfigDtsRollup.enabled} */
   public readonly rollupEnabled: boolean;
@@ -317,6 +320,7 @@ export class ExtractorConfig {
     this.docModelEnabled = parameters.docModelEnabled;
     this.apiJsonFilePath = parameters.apiJsonFilePath;
     this.docModelIncludeForgottenExports = parameters.docModelIncludeForgottenExports;
+    this.projectFolderUrl = parameters.projectFolderUrl;
     this.rollupEnabled = parameters.rollupEnabled;
     this.untrimmedFilePath = parameters.untrimmedFilePath;
     this.alphaTrimmedFilePath = parameters.alphaTrimmedFilePath;
@@ -894,6 +898,7 @@ export class ExtractorConfig {
       let docModelEnabled: boolean = false;
       let apiJsonFilePath: string = '';
       let docModelIncludeForgottenExports: boolean = false;
+      let projectFolderUrl: string | undefined;
       if (configObject.docModel) {
         docModelEnabled = !!configObject.docModel.enabled;
         apiJsonFilePath = ExtractorConfig._resolvePathWithTokens(
@@ -902,6 +907,7 @@ export class ExtractorConfig {
           tokenContext
         );
         docModelIncludeForgottenExports = !!configObject.docModel.includeForgottenExports;
+        projectFolderUrl = configObject.docModel.projectFolderUrl;
       }
 
       let tsdocMetadataEnabled: boolean = false;
@@ -1009,6 +1015,7 @@ export class ExtractorConfig {
         docModelEnabled,
         apiJsonFilePath,
         docModelIncludeForgottenExports,
+        projectFolderUrl,
         rollupEnabled,
         untrimmedFilePath,
         alphaTrimmedFilePath,

apps/api-extractor/src/api/IConfigFile.ts

@@ -141,7 +141,21 @@ export interface IConfigDocModel {
    *
    * @defaultValue `false`
    */
-  includeForgottenExports?: boolean;
+   includeForgottenExports?: boolean;
+
+  /**
+   * The URL to the `<projectFolder>` token where the project's source code can be viewed on a website like GitHub or
+   * Azure DevOps.
+   *
+   * @remarks
+   * This URL is concatenated with the file paths serialized to the doc model to produce URL file paths to individual API items.
+   * For example, if the `projectFolderUrl` is "https://github.com/microsoft/rushstack/tree/main/apps/api-extractor" and an API
+   * item's file path is "api/ExtractorConfig.ts", the full URL file path would be
+   * "https://github.com/microsoft/rushstack/tree/main/apps/api-extractor/api/ExtractorConfig.js".
+   *
+   * Can be omitted if you don't care about including source code links in your API documentation reference.
+   */
+   projectFolderUrl?: string;
 }
 
 /**

apps/api-extractor/src/collector/MessageRouter.ts

@@ -204,11 +204,11 @@ export class MessageRouter {
       // NOTE: Since compiler errors pertain to issues specific to the .d.ts files,
       // we do not apply source mappings for them.
       const sourceFile: ts.SourceFile = diagnostic.file;
-      const sourceLocation: ISourceLocation = this._sourceMapper.getSourceLocationFromFileAndPos(
+      const sourceLocation: ISourceLocation = this._sourceMapper.getSourceLocation({
         sourceFile,
-        diagnostic.start || 0,
-        true /* useDtsLocation */
-      );
+        pos: diagnostic.start || 0,
+        useDtsLocation: true
+      });
       options.sourceFilePath = sourceLocation.sourceFilePath;
       options.sourceFileLine = sourceLocation.sourceFileLine;
       options.sourceFileColumn = sourceLocation.sourceFileColumn;
@@ -260,10 +260,10 @@ export class MessageRouter {
         text: message.unformattedText
       };
 
-      const sourceLocation: ISourceLocation = this._sourceMapper.getSourceLocationFromFileAndPos(
+      const sourceLocation: ISourceLocation = this._sourceMapper.getSourceLocation({
         sourceFile,
-        message.textRange.pos
-      );
+        pos: message.textRange.pos
+      });
       options.sourceFilePath = sourceLocation.sourceFilePath;
       options.sourceFileLine = sourceLocation.sourceFileLine;
       options.sourceFileColumn = sourceLocation.sourceFileColumn;
@@ -378,10 +378,10 @@ export class MessageRouter {
       properties
     };
 
-    const sourceLocation: ISourceLocation = this._sourceMapper.getSourceLocationFromFileAndPos(
+    const sourceLocation: ISourceLocation = this._sourceMapper.getSourceLocation({
       sourceFile,
       pos
-    );
+    });
     options.sourceFilePath = sourceLocation.sourceFilePath;
     options.sourceFileLine = sourceLocation.sourceFileLine;
     options.sourceFileColumn = sourceLocation.sourceFileColumn;

apps/api-extractor/src/collector/SourceMapper.ts

@@ -41,6 +41,28 @@ export interface ISourceLocation {
   sourceFileColumn: number;
 }
 
+export interface IGetSourceLocationOptions {
+  /**
+   * The source file to get the source location from.
+   */
+  sourceFile: ts.SourceFile;
+
+  /**
+   * The position within the source file to get the source location from.
+   */
+  pos: number;
+
+  /**
+   * If `false` or not provided, then we attempt to follow source maps in order to resolve the
+   * location to the original `.ts` file. If resolution isn't possible for some reason, we fall
+   * back to the `.d.ts` location.
+   *
+   * If `true`, then we don't bother following source maps, and the location refers to the `.d.ts`
+   * location.
+   */
+  useDtsLocation?: boolean;
+}
+
 export class SourceMapper {
   // Map from .d.ts file path --> ISourceMap if a source map was found, or null if not found
   private _sourceMapByFilePath: Map<string, ISourceMap | null> = new Map<string, ISourceMap | null>();
@@ -51,28 +73,18 @@ export class SourceMapper {
   /**
    * Given a `.d.ts` source file and a specific position within the file, return the corresponding
    * `ISourceLocation`.
-   *
-   * @remarks
-   * If `useDtsLocation` is `false` (default), then we attempt to follow source maps in order to resolve
-   * the location to the original `.ts` file. If resolution isn't possible for some reason, we fall back
-   * to the `.d.ts` location.
-   *
-   * If `useDtsLocation` is `true`, then we don't bother following source maps, and the location refers
-   * to the `.d.ts` location.
    */
-  public getSourceLocationFromFileAndPos(
-    sourceFile: ts.SourceFile,
-    pos: number,
-    useDtsLocation: boolean = false
-  ): ISourceLocation {
-    const lineAndCharacter: ts.LineAndCharacter = sourceFile.getLineAndCharacterOfPosition(pos);
+  public getSourceLocation(options: IGetSourceLocationOptions): ISourceLocation {
+    const lineAndCharacter: ts.LineAndCharacter = options.sourceFile.getLineAndCharacterOfPosition(
+      options.pos
+    );
     const sourceLocation: ISourceLocation = {
-      sourceFilePath: sourceFile.fileName,
+      sourceFilePath: options.sourceFile.fileName,
       sourceFileLine: lineAndCharacter.line + 1,
       sourceFileColumn: lineAndCharacter.character + 1
     };
 
-    if (useDtsLocation) {
+    if (options.useDtsLocation) {
       return sourceLocation;
     }