ci: skip redundant CJS api-extractor lint checks in ci:build

[frankmueller-msft]

Summary

The ci:build step runs 224 redundant api-extractor invocations validating CJS entry points that are byte-for-byte identical to their ESM counterparts. Removing them would save ~22 minutes of CPU time (~1 minute wall-clock on the 8-core CI agent).

Analysis

Current state

From build #381019 CI logs, npm run ci:build completes 1,510 leaf tasks in 8m 15s. The api-extractor and flub generate entrypoints invocations break down as:

Category	Count	CPU Time
api-extractor lint (ESM configs)	167	16m 26s
api-extractor lint (CJS configs)	159	15m 60s
api-extractor lint (bundle)	86	11m 20s
api-extractor run (doc model)	92	11m 11s
api-extractor run (reports)	94	9m 49s
flub generate entrypoints (ESM/lib)	68	6m 48s
flub generate entrypoints (CJS/dist)	65	6m 21s
Total CJS-related	224	22m 21s

At 22.7x effective concurrency, this is ~1 minute of the 8m 15s wall-clock time (12%).

Why the CJS checks are redundant

Both api-extractor:commonjs and api-extractor:esnext run flub generate entrypoints — one targeting --outDir ./dist (CJS), the other --outDir ./lib (ESM). The generated entry point files (public.d.ts, legacy.d.ts, index.d.ts) are byte-for-byte identical across all packages:

• public.d.ts: 41/41 identical
• legacy.d.ts: 35/35 identical
• index.d.ts: 50/50 identical (where both exist)

The check:exports:cjs:* lint scripts then run api-extractor against the CJS entry points (dist/public.d.ts) using -lint-public.cjs.json configs. These configs extend the same api-extractor-lint.entrypoint.json base and generate no output — they only validate the entry point is well-formed. Since the entry point files are identical to the ESM versions already validated by check:exports:esm:*, the CJS validation is tautological.

No reports, doc models, or documentation depend on CJS api-extractor output — all use ESM paths (api-extractor-model.esm.json, api-extractor-report-base.esm.json).

Dependency chain

ci:build
 └─ lint
     └─ check:exports              ← depends on "api"
         └─ api                    ← depends on BOTH api-extractor:commonjs AND api-extractor:esnext
             ├─ api-extractor:commonjs  ← "flub generate entrypoints --outDir ./dist" (REDUNDANT)
             └─ api-extractor:esnext    ← "flub generate entrypoints --outDir ./lib"

Each package's check:exports runs concurrently "npm:check:exports:*", picking up both check:exports:cjs:* and check:exports:esm:* scripts.

Proposed changes

Files to modify

1. fluidBuild.config.cjs — Remove api-extractor:commonjs from api task and build:test dependencies
2. 86 package.json files — Remove check:exports:cjs:* and api-extractor:commonjs scripts
3. ~160 api-extractor-lint-*.cjs.json files — Delete (no longer referenced)

Config changes

// fluidBuild.config.cjs — BEFORE
"api": {
    dependsOn: ["api-extractor:commonjs", "api-extractor:esnext"],
    script: false,
},
"build:test": ["typetests:gen", "tsc", "api-extractor:commonjs", "api-extractor:esnext"],
"build:test:cjs": ["typetests:gen", "tsc", "api-extractor:commonjs"],

// fluidBuild.config.cjs — AFTER
"api": {
    dependsOn: ["api-extractor:esnext"],
    script: false,
},
"build:test": ["typetests:gen", "tsc", "api-extractor:esnext"],
"build:test:cjs": ["typetests:gen", "tsc"],

Scripted cleanup

The package.json and config file changes could be scripted:

# Remove check:exports:cjs:* scripts from all package.json files
# Remove api-extractor:commonjs scripts from all package.json files
# Delete all api-extractor-lint-*.cjs.json config files

Expected impact

• 224 fewer task invocations per CI build (1,510 → 1,286)
• ~22 minutes less CPU time (187m → 165m)
• ~1 minute faster wall-clock (8m 15s → ~7m 15s for ci:build)
• ~250 fewer files in the repo (config files + script entries)

Risks

• If flub generate entrypoints ever produces different output for CJS vs ESM, the divergence would go undetected. This seems unlikely since both use the same TypeScript source and the tool has no CJS-specific logic.
• Local developer builds would no longer validate CJS entry points. Developers using npm run build would still get ESM validation.

Data source

All timing data from build #381019 (PR #26586 on ci/combined-pipeline-parallelization), extracted via ADO timeline API.

[tylerbutler]

I'm not sure this is safe. But I also don't fully understand what all the api extractor tests do. @jason-ha and @Josmithr should review.

[tylerbutler]

The time savings is really nice though... maybe we can move these tests to a different phase that runs out of band. Running them in pr and every main build may not be needed but we do need some coverage if we start getting different output from typescript for cjs and ESM.

[jason-ha]

@tylerbutler is correct. We need verification for those. While the file contents are the same the context is different. The files that are tested are referencing two different file sets. There are some cases where the deviations are more critical, but by far that is not the case.
I would agree that PRs going to the main branch don't need those checks. It would be sufficient to have them for CI on the main branch. I would still prefer them run for any release branch PR, but we can avoid that complexity and rely on CI post merge.

Here is a bolder savings plan. Create FF client 3.0 and drop CJS support. I am pretty sure we can't do that yet per jest use. But we would save a lot more in build time and would be able to stop using a custom tool config and more.
When presence package was first created, I tried to skip CommonJS support, but it didn't fly.

To get things split I would first go clean up the dependency graph. There are dependencies on the "api" task that should not exist. I cleaned up most some time ago, but I know there were some left. The "api" task set should really be renamed for clarity too. But I would prefer to proceed with another effort that might make that clean up moot.
15 months ago, we lost resources to complete the plan I had to generate .ts entrypoint files and have those be checked in as source (Sub Feature 14504: Node16 Debt: workaround VS Code auto import deficiencies). If that work is restored, then there would be at most "api-extractor" task. See the feature for other known goodness. Incidentally, I determined this morning that making that change will solve 95% of the issue we have with boards being able to split its schema into a separate package.

[frankmueller-msft]

Thanks @tylerbutler and @jason-ha for the detailed context.

Sounds like the consensus is:

1. The CJS checks are needed — while the output is identical today, the ESM and CJS contexts are semantically different and we need coverage for when they diverge.
2. They don't need to run on every PR — running them in CI post-merge on main (and release branches) provides sufficient coverage without blocking PR velocity.
3. Longer term, completing the .ts entrypoint generation work (ADO Feature 14504) would eliminate most api-extractor tasks entirely, which is a much bigger win.

Updated proposal for the near-term:

• Move CJS api-extractor checks off the PR critical path by splitting ci:build so that CJS validation runs post-merge only (or in a separate non-blocking pipeline stage)
• Keep the checks running on CI for main and release branches
• This gives the ~22 min CPU savings on PR builds without losing coverage

I'll also note that @jason-ha mentioned cleaning up the api task dependency graph — there are dependencies on the "api" task set that shouldn't exist. That cleanup would be a prerequisite for splitting cleanly.