Merge remote-tracking branch 'remotes/origin/main' into excerpt-tokens

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

@@ -95,7 +95,13 @@ export const enum ExtractorMessageId {
   /**
    * "The property ___ has a setter but no getter."
    */
-  MissingGetter = 'ae-missing-getter'
+  MissingGetter = 'ae-missing-getter',
+
+  /**
+   * "Incorrect file type; API Extractor expects to analyze compiler outputs with the .d.ts file extension.
+   * Troubleshooting tips: `https://api-extractor.com/link/dts-error`"
+   */
+  WrongInputFileType = 'ae-wrong-input-file-type'
 }
 
 export const allExtractorMessageIds: Set<string> = new Set<string>([
@@ -114,5 +120,6 @@ export const allExtractorMessageIds: Set<string> = new Set<string>([
   'ae-cyclic-inherit-doc',
   'ae-unresolved-link',
   'ae-setter-with-docs',
-  'ae-missing-getter'
+  'ae-missing-getter',
+  'ae-wrong-input-file-type'
 ]);

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

@@ -188,6 +188,8 @@ export class Collector {
       this.messageRouter.addCompilerDiagnostic(diagnostic);
     }
 
+    const sourceFiles: readonly ts.SourceFile[] = this.program.getSourceFiles();
+
     if (this.messageRouter.showDiagnostics) {
       this.messageRouter.logDiagnosticHeader('Root filenames');
       for (const fileName of this.program.getRootFileNames()) {
@@ -196,12 +198,28 @@ export class Collector {
       this.messageRouter.logDiagnosticFooter();
 
       this.messageRouter.logDiagnosticHeader('Files analyzed by compiler');
-      for (const sourceFile of this.program.getSourceFiles()) {
+      for (const sourceFile of sourceFiles) {
         this.messageRouter.logDiagnostic(sourceFile.fileName);
       }
       this.messageRouter.logDiagnosticFooter();
     }
 
+    // We can throw this error earlier in CompilerState.ts, but intentionally wait until after we've logged the
+    // associated diagnostic message above to make debugging easier for developers.
+    // Typically there will be many such files -- to avoid too much noise, only report the first one.
+    const badSourceFile: ts.SourceFile | undefined = sourceFiles.find(
+      ({ fileName }) => !ExtractorConfig.hasDtsFileExtension(fileName)
+    );
+    if (badSourceFile) {
+      this.messageRouter.addAnalyzerIssueForPosition(
+        ExtractorMessageId.WrongInputFileType,
+        'Incorrect file type; API Extractor expects to analyze compiler outputs with the .d.ts file extension. ' +
+          'Troubleshooting tips: https://api-extractor.com/link/dts-error',
+        badSourceFile,
+        0
+      );
+    }
+
     // Build the entry point
     const entryPointSourceFile: ts.SourceFile = this.workingPackage.entryPointSourceFile;
 

apps/api-extractor/src/generators/ApiModelGenerator.ts

@@ -202,6 +202,10 @@ export class ApiModelGenerator {
         this._processApiProperty(astDeclaration, exportedName, parentApiItem);
         break;
 
+      case ts.SyntaxKind.SetAccessor:
+        this._processApiProperty(astDeclaration, exportedName, parentApiItem);
+        break;
+
       case ts.SyntaxKind.IndexSignature:
         this._processApiIndexSignature(astDeclaration, exportedName, parentApiItem);
         break;
@@ -817,13 +821,17 @@ export class ApiModelGenerator {
     let apiProperty: ApiProperty | undefined = parentApiItem.tryGetMemberByKey(containerKey) as ApiProperty;
 
     if (apiProperty === undefined) {
-      const propertyDeclaration: ts.PropertyDeclaration =
-        astDeclaration.declaration as ts.PropertyDeclaration;
-
       const nodesToCapture: IExcerptBuilderNodeToCapture[] = [];
 
       const propertyTypeTokenRange: IExcerptTokenRange = ExcerptBuilder.createEmptyTokenRange();
-      nodesToCapture.push({ node: propertyDeclaration.type, tokenRange: propertyTypeTokenRange });
+
+      // If the property declaration's type is `undefined`, then we're processing a setter with no corresponding
+      // getter. Use the parameter type instead (note that TypeScript always reports an error if a setter
+      // does not have exactly one parameter).
+      const propertyTypeNode: ts.TypeNode | undefined =
+        (astDeclaration.declaration as ts.PropertyDeclaration | ts.GetAccessorDeclaration).type ||
+        (astDeclaration.declaration as ts.SetAccessorDeclaration).parameters[0].type;
+      nodesToCapture.push({ node: propertyTypeNode, tokenRange: propertyTypeTokenRange });
 
       const excerptTokens: IExcerptToken[] = this._buildExcerptTokens(astDeclaration, nodesToCapture);
       const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);

apps/api-extractor/src/schemas/api-extractor-defaults.json

@@ -72,6 +72,9 @@
       "ae-unresolved-inheritdoc-base": {
         "logLevel": "warning",
         "addToApiReportFile": true
+      },
+      "ae-wrong-input-file-type": {
+        "logLevel": "error"
       }
     },
     "tsdocMessageReporting": {

apps/rush/CHANGELOG.json

@@ -1,6 +1,18 @@
 {
   "name": "@microsoft/rush",
   "entries": [
+    {
+      "version": "5.70.0",
+      "tag": "@microsoft/rush_v5.70.0",
+      "date": "Wed, 11 May 2022 22:21:40 GMT",
+      "comments": {
+        "none": [
+          {
+            "comment": "Add a new `afterExecuteOperations` hook to phased command execution. This hook is used for the console timeline view and the standard result summary."
+          }
+        ]
+      }
+    },
     {
       "version": "5.69.0",
       "tag": "@microsoft/rush_v5.69.0",

apps/rush/CHANGELOG.md

@@ -1,6 +1,13 @@
 # Change Log - @microsoft/rush
 
-This log was last generated on Tue, 10 May 2022 01:20:58 GMT and should not be manually modified.
+This log was last generated on Wed, 11 May 2022 22:21:40 GMT and should not be manually modified.
+
+## 5.70.0
+Wed, 11 May 2022 22:21:40 GMT
+
+### Updates
+
+- Add a new `afterExecuteOperations` hook to phased command execution. This hook is used for the console timeline view and the standard result summary.
 
 ## 5.69.0
 Tue, 10 May 2022 01:20:58 GMT

apps/rush/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/rush",
-  "version": "5.69.0",
+  "version": "5.70.0",
   "description": "A professional solution for consolidating all your JavaScript projects in one Git repo",
   "keywords": [
     "install",

build-tests/api-documenter-test/config/api-extractor.json

@@ -18,5 +18,14 @@
     "enabled": false
   },
 
-  "testMode": true
+  "testMode": true,
+
+  "messages": {
+    "extractorMessageReporting": {
+      // Purposefully disabled for the `writeonlyProperty` test case.
+      "ae-missing-getter": {
+        "logLevel": "none"
+      }
+    }
+  }
 }

build-tests/api-documenter-test/etc/api-documenter-test.api.json

@@ -905,6 +905,33 @@
                 "endIndex": 2
               },
               "isStatic": false
+            },
+            {
+              "kind": "Property",
+              "canonicalReference": "api-documenter-test!DocClass1#writeonlyProperty:member",
+              "docComment": "/**\n * API Extractor will surface an `ae-missing-getter` finding for this property.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "set writeonlyProperty(value: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ");"
+                }
+              ],
+              "isOptional": false,
+              "releaseTag": "Public",
+              "name": "writeonlyProperty",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": false
             }
           ],
           "extendsTokenRange": {

build-tests/api-documenter-test/etc/api-documenter-test.api.md

@@ -49,6 +49,7 @@ export class DocClass1 extends DocBaseClass implements IDocInterface1, IDocInter
     // (undocumented)
     get writeableProperty(): string;
     set writeableProperty(value: string);
+    set writeonlyProperty(value: string);
 }
 
 // @public

build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.md

@@ -38,6 +38,7 @@ The constructor for this class is marked as internal. Third-party code should no
 |  [readonlyProperty](./api-documenter-test.docclass1.readonlyproperty.md) |  | string |  |
 |  [regularProperty](./api-documenter-test.docclass1.regularproperty.md) |  | [SystemEvent](./api-documenter-test.systemevent.md) | This is a regular property that happens to use the SystemEvent type. |
 |  [writeableProperty](./api-documenter-test.docclass1.writeableproperty.md) |  | string |  |
+|  [writeonlyProperty](./api-documenter-test.docclass1.writeonlyproperty.md) |  | string | API Extractor will surface an <code>ae-missing-getter</code> finding for this property. |
 
 ## Methods
 

build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.writeonlyproperty.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [api-documenter-test](./api-documenter-test.md) &gt; [DocClass1](./api-documenter-test.docclass1.md) &gt; [writeonlyProperty](./api-documenter-test.docclass1.writeonlyproperty.md)
+
+## DocClass1.writeonlyProperty property
+
+API Extractor will surface an `ae-missing-getter` finding for this property.
+
+<b>Signature:</b>
+
+```typescript
+set writeonlyProperty(value: string);
+```

build-tests/api-documenter-test/etc/yaml/api-documenter-test/docclass1.yml

@@ -61,6 +61,19 @@ properties:
         set writeableProperty(value: string);
       return:
         type: string
+  - name: writeonlyProperty
+    uid: 'api-documenter-test!DocClass1#writeonlyProperty:member'
+    package: api-documenter-test!
+    fullName: writeonlyProperty
+    summary: API Extractor will surface an `ae-missing-getter` finding for this property.
+    remarks: ''
+    example: []
+    isPreview: false
+    isDeprecated: false
+    syntax:
+      content: 'set writeonlyProperty(value: string);'
+      return:
+        type: string
 methods:
   - name: deprecatedExample()
     uid: 'api-documenter-test!DocClass1#deprecatedExample:member(1)'

build-tests/api-documenter-test/src/DocClass1.ts

@@ -206,6 +206,11 @@ export class DocClass1 extends DocBaseClass implements IDocInterface1, IDocInter
   }
   public set writeableProperty(value: string) {}
 
+  /**
+   * API Extractor will surface an `ae-missing-getter` finding for this property.
+   */
+  public set writeonlyProperty(value: string) {}
+
   /**
    * This event is fired whenever the object is modified.
    * @eventProperty

common/changes/@microsoft/api-extractor/better-ts-file-error_2022-04-10-00-42.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "comment": "Throw an error early if API Extractor will attempt to process non-.d.ts files",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@microsoft/api-extractor"
+}

common/changes/@microsoft/api-extractor/handle-setters_2022-05-05-17-41.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "comment": "Generate API doc model nodes for setters without getters",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@microsoft/api-extractor"
+}

common/changes/@microsoft/rush/phased-telemetry_2022-05-12-23-49.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/rush",
+      "comment": "Write local telemetry for all phased commands, including partial runs when running in watch mode.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@microsoft/rush"
+}

common/changes/@microsoft/rush/workspace-versions-pnpmfile_2022-05-12-19-50.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/rush",
+      "comment": "Export the list of workspace packages to the pnpmfile shim.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@microsoft/rush"
+}

common/config/rush/version-policies.json

@@ -102,7 +102,7 @@
   {
     "policyName": "rush",
     "definitionName": "lockStepVersion",
-    "version": "5.69.0",
+    "version": "5.70.0",
     "nextBump": "minor",
     "mainProject": "@microsoft/rush"
   }

common/reviews/api/api-extractor.api.md

@@ -141,7 +141,8 @@ export const enum ExtractorMessageId {
     SetterWithDocs = "ae-setter-with-docs",
     UnresolvedInheritDocBase = "ae-unresolved-inheritdoc-base",
     UnresolvedInheritDocReference = "ae-unresolved-inheritdoc-reference",
-    UnresolvedLink = "ae-unresolved-link"
+    UnresolvedLink = "ae-unresolved-link",
+    WrongInputFileType = "ae-wrong-input-file-type"
 }
 
 // @public

common/reviews/api/rush-lib.api.md

@@ -287,6 +287,12 @@ export interface IEnvironmentConfigurationInitializeOptions {
     doNotNormalizePaths?: boolean;
 }
 
+// @alpha
+export interface IExecutionResult {
+    readonly operationResults: ReadonlyMap<Operation, IOperationExecutionResult>;
+    readonly status: OperationStatus;
+}
+
 // @beta
 export interface IExperimentsJson {
     buildCacheWithAllowWarningsInSuccessfulBuild?: boolean;
@@ -360,6 +366,14 @@ export class IndividualVersionPolicy extends VersionPolicy {
 export interface _INpmOptionsJson extends IPackageManagerOptionsJsonBase {
 }
 
+// @alpha
+export interface IOperationExecutionResult {
+    readonly error: Error | undefined;
+    readonly status: OperationStatus;
+    readonly stdioSummarizer: StdioSummarizer;
+    readonly stopwatch: IStopwatchResult;
+}
+
 // @alpha
 export interface IOperationOptions {
     phase?: IPhase | undefined;
@@ -446,12 +460,20 @@ export interface IRushSessionOptions {
     terminalProvider: ITerminalProvider;
 }
 
+// @alpha
+export interface IStopwatchResult {
+    get duration(): number;
+    get endTime(): number | undefined;
+    get startTime(): number | undefined;
+    toString(): string;
+}
+
 // @beta (undocumented)
 export interface ITelemetryData {
     readonly durationInSeconds: number;
     // (undocumented)
     readonly extraData?: {
-        [key: string]: string;
+        [key: string]: string | number | boolean;
     };
     readonly name: string;
     readonly platform?: string;
@@ -605,6 +627,7 @@ export abstract class PackageManagerOptionsConfigurationBase implements IPackage
 
 // @alpha
 export class PhasedCommandHooks {
+    readonly afterExecuteOperations: AsyncSeriesHook<[IExecutionResult, ICreateOperationsContext]>;
     readonly createOperations: AsyncSeriesWaterfallHook<[Set<Operation>, ICreateOperationsContext]>;
     readonly waitingForChanges: SyncHook<void>;
 }

libraries/rush-lib/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/rush-lib",
-  "version": "5.69.0",
+  "version": "5.70.0",
   "description": "A library for writing scripts that interact with the Rush tool",
   "repository": {
     "type": "git",