build(common-utils): modernize build, lint, and test setup

[ChumpChief]

Description

Tracking: AB#73445.

@fluidframework/common-utils is deprecated but lives in this repo as its own pnpm workspace. Its bespoke build/lint/test setup makes routine maintenance (CG alerts, pipeline rollouts) expensive — each change has to be done twice. This PR brings it in line with client-utils and protocol-definitions.

Updates

• Modern exports map. Replaced the legacy main/module/browser field setup with a conditional exports map providing per-environment entrypoints. indexBrowser.ts and indexNode.ts now carry the full public API surface (was: thin env-specific files used only by the bundler browser-field remap).
• Dropped the ESM dual-emit. Removed tsconfig.esnext.json and the lib/ output. Modern resolution already routed to CJS via main since there was no exports map; the ESM build was orphaned. attw 🟢 across all four modes. client-utils is the dual-emit replacement for downstream.
• Node16 tsconfig layout. Single root tsconfig extending tsconfig.node16.json, .js-extension relative imports, tsconfig.test.node16.json-based test configs (mirrors client-utils).
• API extraction. Replaced the single api-extractor.json + api-extractor-lint.json with a per-entrypoint api-extractor/ config dir (browser/node lint + model-browser docs). Added @arethetypeswrong/cli, chained into lint.
• Mocha setup. Adopted @fluid-internal/mocha-test-setup via .mocharc.cjs, replacing the bespoke test:report / test:mocha:multireport chain.
• Eslint config. Replaced the hand-rolled flat config with @fluidframework/eslint-config-fluid@^10 recommended (resolves AB#59243). Violations silenced package-wide — deprecation mode, no source cleanups.
• Tooling refresh. Bumped @fluid-tools/build-cli + @fluidframework/build-tools to ^0.65.0; refreshed mocha/rewire/cross-env/jest-junit/ts-node.
• Misc cleanup. lodash → lodash.clonedeep (named import broken under ESM); dropped @types/base64-js and the bump-version script; renamed jest.config.js / jest-puppeteer.config.js → .cjs.
• The Buffer re-export from indexNode is now type-only. import { Buffer } from "@fluidframework/common-utils"; new Buffer(...) will fail at runtime. Package is @internal/@deprecated with no in-repo consumers; Node global Buffer and IsoBuffer remain available.

Reviewer Guidance

The review process is outlined on this wiki page.

Commits are scoped to one logical change for bisecting. Verified locally: build, test:mocha (53), test:jest (19), check:exports (3/3), attw (🟢 all four modes), eslint.

[github-actions]

Hi! Thank you for opening this PR. Want me to review it?

Based on the diff (4722 lines, 47 files), I've queued these reviewers:

• Correctness — logic errors, race conditions, lifecycle issues
• Security — vulnerabilities, secret exposure, injection
• API Compatibility — breaking changes, release tags, type design
• Performance — algorithmic regressions, memory leaks
• Testing — coverage gaps, hollow tests

How this works

• Adjust the reviewer set by ticking/unticking boxes above. Reviewer toggles alone don't trigger anything.

• Tick Start review below to dispatch the review fleet.

• After review finishes, tick Start review again to request another run — it auto-resets after each dispatch.

• This comment updates as new commits land; your reviewer selections are preserved.

• Start review

[github-actions]

🔭 PR Review Fleet Report

Note

This report is generated by an experimental AI review fleet and is provided as a beta feature. Findings are a starting point for discussion, not a gate. Use your own judgement.

Verdict: ❌ Request Changes

0 Spicy, 1 Pungent, 1 Smelly

Findings

Sev	#	Area	File	What	Fix
🧄 Pungent	H1	Correctness	common/lib/common-utils/src/indexNode.ts:11	Buffer is re-exported as type-only (export { type Buffer }) from indexNode.ts, but the type-compatibility test in validateCommonUtilsPrevious.generated.ts:313 uses typeof current.Buffer in a type position — which requires Buffer to be a value export. Before this PR, index.ts did export * from './indexNode' which exported Buffer as a value (via export declare class Buffer in bufferNode.ts). Changing to export { type Buffer } removes the value declaration from the public API, making typeof current.Buffer a TypeScript error ('Buffer' only refers to a type, but is being used as a value here). Since ClassStatics_Buffer is not listed in typeValidation.broken in package.json, the test at line 313 is expected to pass — it will instead fail to compile, breaking the build:test:types CI step.	Either change export { type Buffer } to export { Buffer } in indexNode.ts to preserve the value export (matching the old export * from './indexNode' behaviour), or add "ClassStatics_Buffer": {"backCompat": false} to the typeValidation.broken section in package.json and add a corresponding // @ts-expect-error compatibility expected to be broken comment above line 313 in validateCommonUtilsPrevious.generated.ts.
🧅 Smelly	M1	Testing	common/lib/common-utils/src/rangeTracker.ts:77	cloneDeep (lodash) was replaced with structuredClone in both the snapshot constructor (line 77) and serialize() (line 90). The existing tests verify that snapshot values are copied correctly but never verify that the copy is independent from the source — no test mutates the deserialized RangeTracker (via .add() or .updateBase()) and then checks that the original snapshot object's ranges array is unchanged. If structuredClone were ever replaced with a shallow copy (e.g., [...primary.ranges]), mutations to the cloned tracker's IRange items would corrupt the original snapshot object, and the current tests would not detect it.	Add a test: (1) create a RangeTracker, add several ranges, call serialize() to get snapshot; (2) construct a new RangeTracker(snapshot) copy; (3) call copy.add(...) and copy.updateBase(...) on the copy; (4) assert snapshot.ranges is unchanged and the original tracker's values are unchanged. This verifies the deep-copy contract introduced by structuredClone.

---

View workflow run

[Copilot]

Pull request overview

This PR modernizes the deprecated @fluidframework/common-utils workspace to align with the repo’s current build/lint/test and ESM/exports patterns (similar to client-utils), so future maintenance (tooling updates, CG responses, pipeline alignment) is cheaper and more uniform.

Changes:

• Migrates to Node16 ESM-first TypeScript config and updates source/test imports to explicit .js extensions.
• Reworks package entrypoints/exports to support proper self-import usage across Node/browser and ESM/CJS, plus adds export-validation and arethetypeswrong checks.
• Updates build, lint, and test wiring (fluid-build tasks, eslint-config-fluid flat config, mocha/jest configs, refreshed devDependencies).

Reviewed changes

Copilot reviewed 40 out of 43 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
common/lib/common-utils/tsconfig.json	Switches to Node16 ESM tsconfig base and adjusts output to lib/, relaxing a couple of strictness flags for deprecated code.
common/lib/common-utils/tsconfig.esnext.json	Removes the old ESNext-specific tsconfig.
common/lib/common-utils/tsconfig.cjs.json	Adds a dedicated CJS build tsconfig (for fluid-tsc commonjs) outputting to dist/.
common/lib/common-utils/src/trace.ts	Updates import to .js extension (now ESM-style).
common/lib/common-utils/src/timer.ts	Updates internal imports to .js extensions.
common/lib/common-utils/src/test/types/validateCommonUtilsPrevious.generated.ts	Updates generated type-test import to package self-import and refreshes generator comment.
common/lib/common-utils/src/test/types/tsconfig.json	Moves type-test build output to lib/ and aligns test tsconfig with Node16 test base.
common/lib/common-utils/src/test/mocha/typedEventEmitter.spec.ts	Switches test imports to explicit entrypoint/module paths with .js.
common/lib/common-utils/src/test/mocha/tsconfig.json	Aligns mocha test TS config with Node16 test base and outputs to lib/.
common/lib/common-utils/src/test/mocha/tsconfig.cjs.json	Adds a CJS-specific mocha test build config emitting into dist/.
common/lib/common-utils/src/test/mocha/timer.spec.ts	Switches test import to explicit index.js entrypoint with .js.
common/lib/common-utils/src/test/mocha/rangeTracker.spec.ts	Switches test import to explicit index.js entrypoint with .js.
common/lib/common-utils/src/test/mocha/promiseCache.spec.ts	Switches test import to explicit index.js entrypoint with .js.
common/lib/common-utils/src/test/mocha/idleTaskScheduler.spec.ts	Switches test import to explicit module path with .js.
common/lib/common-utils/src/test/mocha/assert.spec.ts	Switches test import to explicit module path with .js.
common/lib/common-utils/src/test/jest/tsconfig.cjs.json	Aligns jest test compilation config with Node16 test base and references the package CJS build config.
common/lib/common-utils/src/test/jest/gitHash.spec.ts	Switches test import to explicit module path with .js.
common/lib/common-utils/src/test/jest/buffer.spec.ts	Switches test imports to explicit module paths with .js.
common/lib/common-utils/src/rangeTracker.ts	Replaces lodash cloneDeep usage with structuredClone.
common/lib/common-utils/src/indexNode.ts	Builds a complete Node entrypoint surface via explicit re-exports and adds @packageDocumentation.
common/lib/common-utils/src/indexBrowser.ts	Builds a complete browser entrypoint surface via explicit re-exports and adds @packageDocumentation.
common/lib/common-utils/src/index.ts	Converts index.ts into a stub re-export for tooling compatibility.
common/lib/common-utils/src/hashFileNode.ts	Updates sha.js import style and .js extension on internal type import.
common/lib/common-utils/src/hashFileBrowser.ts	Updates imports/paths for ESM .js extensions; adds @internal tags to deprecated APIs.
common/lib/common-utils/src/bufferBrowser.ts	Adds @internal tags to deprecated browser buffer utilities.
common/lib/common-utils/src/base64Encoding.ts	Updates import path to ESM .js extension.
common/lib/common-utils/pnpm-workspace.yaml	Adds trust-policy exclusions with rationale for specific transitive versions.
common/lib/common-utils/package.json	Converts package to ESM (type: module), adds conditional exports (node/default + import/require + types), updates scripts, and refreshes deps/devDeps.
common/lib/common-utils/jest.config.cjs	Adds a CJS jest config (puppeteer preset + junit reporter).
common/lib/common-utils/jest-puppeteer.config.cjs	Adds a CJS jest-puppeteer launch config for CI environments.
common/lib/common-utils/eslint.config.mts	Replaces bespoke flat config with @fluidframework/eslint-config-fluid and customizes TS parser project list + disables for existing deprecated violations.
common/lib/common-utils/api-report/common-utils.public.api.md	Updates generated API report content (now indicates missing package documentation for the configured entrypoint).
common/lib/common-utils/api-report/common-utils.beta.api.md	Updates generated API report content (now indicates missing package documentation for the configured entrypoint).
common/lib/common-utils/api-report/common-utils.alpha.api.md	Updates generated API report content (now indicates missing package documentation for the configured entrypoint).
common/lib/common-utils/api-extractor/api-extractor-lint-indexNode.esm.json	Adds API-extractor lint config for the Node ESM entrypoint.
common/lib/common-utils/api-extractor/api-extractor-lint-indexNode.cjs.json	Adds API-extractor lint config for the Node CJS entrypoint.
common/lib/common-utils/api-extractor/api-extractor-lint-indexBrowser.esm.json	Adds API-extractor lint config for the browser ESM entrypoint.
common/lib/common-utils/api-extractor/api-extractor-lint-indexBrowser.cjs.json	Adds API-extractor lint config for the browser CJS entrypoint.
common/lib/common-utils/api-extractor/api-extractor-lint-bundle.json	Adds API-extractor lint config for the “bundle” entrypoint.
common/lib/common-utils/api-extractor.json	Switches API Extractor base config to the ESM (no-legacy) base.
common/lib/common-utils/api-extractor-lint.json	Removes the old single-entrypoint API-extractor lint config.
common/lib/common-utils/.mocharc.cjs	Adds mocha config via @fluid-internal/mocha-test-setup.

[kian-thompson]

Reviewed via Copilot CLI (deep mode). Verdict: Approve with suggestions — 0 CRITICAL, 0 HIGH, 4 MEDIUM.

Findings

Sev	Area	File	What	Fix
🟡	API Quality / Correctness	src/indexNode.ts:17	Buffer re-export changed from value+type to export { type Buffer }. Any import { Buffer } from "@fluidframework/common-utils"; new Buffer(...) will fail at runtime. No in-repo consumers and the package is @internal+@deprecated, so likely acceptable, but it isn't called out in the PR description as a behavior change.	Re-export Buffer as a value from ./bufferNode.js, or explicitly note the symbol removal in the commit (common-utils: stop pulling Node graph into browser builds) and PR description.
🟡	API Quality	src/base64EncodingBrowser.ts:15,25,37 (also pre-existing in bufferBrowser.ts, hashFileBrowser.ts, bufferNode.ts, etc.)	New file's @deprecated tags point at @fluidframework-internal/client-utils, which is not a real package. The real one (correctly used in the new @packageDocumentation block in index*.ts) is @fluid-internal/client-utils. src/timer.ts:246,263 uses yet a third name (@fluid-private/client-utils). IntelliSense steers users to nonexistent packages.	At minimum fix the three new occurrences in base64EncodingBrowser.ts. Ideally do a sweep across the package: @fluidframework-internal/client-utils and @fluid-private/client-utils → @fluid-internal/client-utils.
🟡	Architecture	src/index.ts:15	Comment says "THIS FILE IS NOT ACTUALLY USED", but it remains the api-extractor mainEntryPointFilePath (inherited as <projectFolder>/lib/index.d.ts from api-extractor-base.esm.json, no override in api-extractor.json) and the type-test path validateCommonUtilsPrevious.generated.ts resolves @fluidframework/common-utils through the exports map. The comment will mislead future maintainers.	Update the comment to acknowledge the api-extractor + type-test role, or override mainEntryPointFilePath in api-extractor.json to point at a real shipped entrypoint (e.g. lib/indexNode.d.ts).
🟡	Correctness	package.json:39-40	Legacy fallback main: "lib/indexBrowser.js" / types: "lib/indexBrowser.d.ts" while "type": "module". Resolvers that don't honor exports (older bundlers / legacy tooling) will try to require() ESM → ERR_REQUIRE_ESM. Previously these pointed at the CJS dist/ build.	Either drop the legacy fields (exports-only) or point them at the CJS bundle (./dist/indexBrowser.js / ./dist/indexBrowser.d.ts).

Suggestions (non-blocking)

• The tsc script copies common/build/build-common/src/cjs/package.json into ./dist for CJS subpath resolution. Worth a quick parity check against client-utils to confirm both packages use the same mechanism.
• c8 config in package.json still only includes dist/**/*.*js / dist/test/**/*.*js. With the dual ESM/CJS layout, coverage now misses lib/**. Consider broadening if coverage parity matters.

[jason-ha]

Main question is switch to ESM and whether instead ESM support should just be removed. More detailed ramblings in sub-issues.

[jason-ha]

I would not switch this around now since it is deprecated but keep with the same to reduce any risk.
In fact, if the ESM build was invalid which I have commonly found recently for packages that weren't dealt with in the large client migration, then it feels safe to drop the ESM build.
Node16 cleanup is good but leave out ESM.
"Restore" "type": "commonjs" (that was implicit before).
If there is a need for valid ESM build, then make ESM secondary using fluid-tsc module.

[ChumpChief]

Switched to CJS primary in latest

[jason-ha]

Doesn't actually switch to CJS primary for consumers in case that is what you are hoping for.
Once exports are added, then these properties are ignored by modern things.
So, as it stands ESM consumers will get ESM where they would have gotten CJS before.
I don't think we should add ESM here. Can discuss more next week.

[ChumpChief]

Dropped ESM in latest - my main goal was to align with other packages as best we could (so by default, dual-building like most do) but the ESM build isn't crucial to most of the gains (aligning the dependencies, build tools, etc.).

[ChumpChief]

Also updated client-utils based on feedback that equally applied there.

[Copilot]

Pull request overview

Copilot reviewed 54 out of 57 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 48 out of 51 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 48 out of 51 changed files in this pull request and generated 1 comment.

[jason-ha]

partial (quick) re-review

[Copilot]

Pull request overview

Copilot reviewed 44 out of 47 changed files in this pull request and generated no new comments.

[github-actions]

🔗 No broken links found! ✅

Your attention to detail is admirable.

linkcheck output

> fluid-framework-docs-site@0.0.0 ci:check-links /home/runner/work/FluidFramework/FluidFramework/docs
> start-server-and-test "npm run serve -- --no-open" 3000 check-links

1: starting server using command "npm run serve -- --no-open"
and when url "[ 'http://127.0.0.1:3000' ]" is responding with HTTP status code 200
running tests using command "npm run check-links"


> fluid-framework-docs-site@0.0.0 serve
> docusaurus serve --no-open

[SUCCESS] Serving "build" directory at: http://localhost:3000/

> fluid-framework-docs-site@0.0.0 check-links
> linkcheck http://localhost:3000 --skip-file skipped-urls.txt

Crawling...

Stats:
  288859 links
    1925 destination URLs
    2175 URLs ignored
       0 warnings
       0 errors