[api-extractor] Optimize the analysis type-check pass by dmichon-msft · Pull Request #5891 · microsoft/rushstack

dmichon-msft · 2026-07-21T22:34:35Z

Summary

API Extractor analyzes the compiler's .d.ts outputs and, by default, does not enable skipLibCheck. Two code paths therefore forced a full-program semantic type-check over the entire transitively-reachable declaration closure — including deep dependencies that are not part of the analyzed API surface:

Collector.analyze called program.getSemanticDiagnostics() with no argument (whole program).
TypeScriptInternals.getGlobalVariableAnalyzer called typeChecker.getEmitResolver(), which forces a full-program diagnostic check before returning — even though only hasGlobalName is needed.

Changes

getEmitResolver(…, skipDiagnostics: true) — the globals table (ambient decls, jsGlobalAugmentations, declare global) is populated eagerly at checker creation, so hasGlobalName works without running diagnostics.
Scoped getSemanticDiagnostics(sourceFile) — diagnostics are now reported only for source files reachable from the entry point: analyzed declaration files (new AstSymbolTable.collectAnalyzedSourceFiles()) plus the intermediate re-export files already collected as nonExternalSourceFiles.

Binding, which the analysis relies on, still happens eagerly for all files when the checker is created, so the analysis itself is unaffected. The net behavior change is that compiler errors are now only reported for declarations that contribute to the analyzed API surface (errors in unreachable dependency files are no longer surfaced).

Performance

Verified through real heft build --clean runs on @rushstack/mcp-server (3 runs each):

	Baseline	Optimized
api-extractor step (subtree)	~4789ms	~942ms
`getEmitResolver`	~4035ms	~0ms
full build wall clock	~14.4s	~9.8s

In baseline, the expensive whole-program check actually fires inside getEmitResolver() during collector construction, which is why both changes are required. A sweep across all ~70 in-repo api-extractor packages showed a consistent ~1s saving on most packages, up to ~4.3s on the heaviest (mcp-server); packages with a cheap external type closure (e.g. rush-lib) are unaffected. An external production repo reported getDiagnosticsWorker dropping 14.1s → 11.3s.

Validation

All api-extractor acceptance-test projects rebuilt clean (api-extractor-scenarios self-validates snapshots; test-01..05, lib1..5-test, api-documenter-*, d-cts/d-mts). Byte-identical API reports / rollups / doc models.
Additionally cross-checked several library consumers (node-core-library, ts-command-line, terminal, rush-lib, mcp-server) — no .api.md/.api.json changes.
heft test: 89/89 pass.

A minor change file is included (the diagnostics-reporting behavior change).

Previously, `Collector.analyze` type-checked the entire program via `getSemanticDiagnostics()`, and `getGlobalVariableAnalyzer` forced a full-program check inside `getEmitResolver()`. Because API Extractor analyzes the compiler's .d.ts outputs with `skipLibCheck` disabled by default, this bind-and-checked every transitively reachable declaration file, including deep dependencies outside the API surface. This change: - Passes `skipDiagnostics: true` to `getEmitResolver()`, since only `hasGlobalName` is needed and the globals table is populated eagerly at checker creation. - Scopes `getSemanticDiagnostics()` to the source files reachable from the entry point (analyzed declarations plus intermediate re-export files) via the new `AstSymbolTable.collectAnalyzedSourceFiles()`. Binding, which the analysis relies on, still happens eagerly for all files, so the analysis itself is unchanged. Compiler errors are now only reported for declarations that contribute to the analyzed API. Verified on @rushstack/mcp-server: the api-extractor step dropped from ~4.8s to ~0.9s with byte-identical output. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Optimizes API Extractor’s analysis-time TypeScript type-checking by avoiding whole-program semantic diagnostics and avoiding an expensive internal getEmitResolver() diagnostic pass, while keeping analysis results (API reports/rollups/models) unchanged.

Changes:

Scope semantic diagnostics to source files reachable from the entry point (analyzed declarations + intermediate re-export files).
Avoid full-program diagnostics triggered by TypeChecker.getEmitResolver() by passing skipDiagnostics: true when only hasGlobalName is needed.
Add AstSymbolTable.collectAnalyzedSourceFiles() to identify the analyzed declaration source-file set used for diagnostics scoping.

Show a summary per file

File	Description
common/changes/@microsoft/api-extractor/optimize-typecheck_2026-07-21-22-06-48.json	Change file documenting the (minor) behavior change in diagnostics reporting scope.
apps/api-extractor/src/collector/Collector.ts	Replaces whole-program `getSemanticDiagnostics()` with diagnostics scoped to reachable/analyzed source files.
apps/api-extractor/src/analyzer/TypeScriptInternals.ts	Calls `getEmitResolver(..., skipDiagnostics: true)` to avoid triggering a full diagnostic pass when only `hasGlobalName` is needed.
apps/api-extractor/src/analyzer/AstSymbolTable.ts	Adds helper to collect source files containing declarations encountered/analyzed during symbol table construction.

Review details

Files reviewed: 4/4 changed files
Comments generated: 1
Review effort level: Low

dmichon-msft · 2026-07-28T18:16:28Z

+    // Report compiler diagnostics, but only for the source files that are reachable from the entry
+    // point: the files that contribute an analyzed declaration, plus the intermediate re-export
+    // files that were visited while resolving exports.  API Extractor analyzes the compiler's `.d.ts`
+    // outputs and (by default) does not enable `skipLibCheck`, so running `getSemanticDiagnostics()`
+    // across the entire program would bind-and-check every transitively reachable declaration file,
+    // including deep dependencies that are not part of the API surface.  Scoping the diagnostics to
+    // the analyzed files avoids that cost while still surfacing every error that pertains to the
+    // exported API.  (Binding, which the analysis relies on, happens eagerly for all files when the
+    // type checker is created, so this does not affect the analysis itself.)
+    const diagnosticSourceFiles: Set<ts.SourceFile> = this.astSymbolTable.collectAnalyzedSourceFiles();
+    for (const sourceFile of nonExternalSourceFiles) {
+      diagnosticSourceFiles.add(sourceFile);
+    }
+    for (const sourceFile of diagnosticSourceFiles) {
+      for (const diagnostic of this._program.getSemanticDiagnostics(sourceFile)) {


API extractor only owns diagnostics relevant to files in the API report; files unrelated should be handled by the normal type checking pass.

octogonz · 2026-07-26T03:55:42Z

+    // including deep dependencies that are not part of the API surface.  Scoping the diagnostics to
+    // the analyzed files avoids that cost while still surfacing every error that pertains to the
+    // exported API.  (Binding, which the analysis relies on, happens eagerly for all files when the
+    // type checker is created, so this does not affect the analysis itself.)


Can we tighten this a bit? It is repeating the exact same sentence from your other check above, reads like slop (trying to explain every exact nuance, no mental model of what the audience would reasonably already know or what questions they would care about)

octogonz · 2026-07-26T03:58:24Z

@@ -129,6 +129,25 @@ export class AstSymbolTable {
    return this._exportAnalyzer.fetchAstModuleExportInfo(astModule);


Validation

All api-extractor acceptance-test projects rebuilt clean (api-extractor-scenarios self-validates snapshots; test-01..05, lib1..5-test, api-documenter-*, d-cts/d-mts). Byte-identical API reports / rollups / doc models.

Additionally cross-checked several library consumers (node-core-library, ts-command-line, terminal, rush-lib, mcp-server) — no .api.md/.api.json changes.

heft test: 89/89 pass.

Was there any validation that this optimization actually improved anything (e.g. runtime against a real repo)?

I've vetted about 3 seconds of saving on an internal project, and the @rushstack/mcp-server project in the rushstack repo was an immediate beneficiary, as it pulls in a lot of unrelated .d.ts files.

dmichon-msft requested review from apostolisms, bmiddha, iclanton, jxanthony and octogonz as code owners July 21, 2026 22:34

github-project-automation Bot moved this to Needs triage in Bug Triage Jul 21, 2026

github-project-automation Bot added this to Bug Triage Jul 21, 2026

dmichon-msft mentioned this pull request Jul 21, 2026

[api-extractor] Reuse TypeScript's module-resolution results to avoid realpath/lstat storm when resolving external package names #5892

Open

bmiddha requested a review from Copilot July 22, 2026 04:08

Copilot started reviewing on behalf of bmiddha July 22, 2026 04:09 View session

Copilot AI reviewed Jul 22, 2026

View reviewed changes

bmiddha approved these changes Jul 22, 2026

View reviewed changes

octogonz reviewed Jul 26, 2026

View reviewed changes

octogonz approved these changes Jul 26, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[api-extractor] Optimize the analysis type-check pass - #5891

[api-extractor] Optimize the analysis type-check pass#5891
dmichon-msft wants to merge 1 commit into
microsoft:mainfrom
dmichon-msft:api-extractor-optimize-typecheck

dmichon-msft commented Jul 21, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

dmichon-msft Jul 28, 2026

Uh oh!

octogonz Jul 26, 2026

Uh oh!

octogonz Jul 26, 2026

Uh oh!

dmichon-msft Jul 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

		@@ -129,6 +129,25 @@ export class AstSymbolTable {
		return this._exportAnalyzer.fetchAstModuleExportInfo(astModule);

Uh oh!

Conversation

dmichon-msft commented Jul 21, 2026

Summary

Changes

Performance

Validation

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Review details

Uh oh!

dmichon-msft Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

octogonz Jul 26, 2026

Choose a reason for hiding this comment

Uh oh!

octogonz Jul 26, 2026

Choose a reason for hiding this comment

Validation

Uh oh!

dmichon-msft Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants