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

[ChumpChief]

Description

Tracking: AB#73445.

@fluidframework/common-utils is deprecated but still lives in this repo as its own pnpm workspace. Leaving it on its old build/lint/test setup makes it expensive to respond to Component Governance alerts and to apply uniform changes to build tooling and pipelines — each one has to be handled twice (once for the modern packages, once for this one's bespoke world). Bringing it in line with client-utils and protocol-definitions makes future maintenance roughly free.

Updates

• Switched to the Node16 ESM-first tsconfig layout, .js-extension relative imports, and .cjs jest configs (matches client-utils).
• Restructured the package entrypoints so the full public API surface is reachable via the package self-import (was broken: Heap, assert, etc. were unreachable through the modern exports map).
• Bumped @fluid-tools/build-cli and @fluidframework/build-tools to ^0.65.0; refreshed devDependencies (mocha 11, rewire 9, cross-env 10, jest-junit 16, ts-node 10.9); added @arethetypeswrong/cli ^0.18.2 and chained check:are-the-types-wrong into lint.
• Adopted @fluid-internal/mocha-test-setup via a one-line .mocharc.cjs, dropping the bespoke :report script chain. ESM-built mocha tests now actually run (were being compiled but never executed).
• Replaced the standalone hand-rolled flat eslint config with @fluidframework/eslint-config-fluid@^10 recommended (resolves the AB#59243 TODO). Existing violations are silenced with package-wide disables — this package is in deprecation mode and is not getting source-level cleanups.
• Switched lodash → lodash.clonedeep (the named import was broken under ESM); dropped the deprecated @types/base64-js stub; removed the vestigial bump-version script and stale build:docs flags.

Reviewer Guidance

The review process is outlined on this wiki page.

Each commit is scoped to one logical change for easier bisecting. Verified locally: build, ci:build, test:mocha (53 ESM + 53 CJS), test:jest (19), lint (incl. attw across all four resolution modes).

[github-actions]

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

Based on the diff (4558 lines, 43 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: ⚠️ Approve with Suggestions

0 Spicy, 0 Pungent, 1 Smelly

Findings

Sev	#	Area	File	What	Fix
🧅 Smelly	M1	Testing	common/lib/common-utils/src/base64EncodingBrowser.ts:40	toUtf8 in the new browser-specific module has an untested default branch that converts arbitrary encodings to utf-8 using the browser IsoBuffer implementation. The three functions fromBase64ToUtf8, fromUtf8ToBase64, and toUtf8 are now new public exports from the browser entry point (indexBrowser.ts) that did not exist there before. No test verifies that the browser implementations produce results identical to the node implementations (base64EncodingNode.ts). If the browser IsoBuffer mishandles a specific encoding (e.g., base64url), toUtf8(input, 'base64url') would silently return wrong output with no test to catch the regression.	Add a Jest test (alongside the existing buffer.spec.ts) that imports both base64EncodingBrowser.js and base64EncodingNode.js and asserts parity: (1) fromBase64ToUtf8('YXNkZmFzZGY=') equals 'asdfasdf' from both modules; (2) fromUtf8ToBase64('asdfasdf') equals 'YXNkZmFzZGY=' from both modules; (3) toUtf8('asdfasdf', 'utf-8') returns the passthrough 'asdfasdf' unchanged; (4) toUtf8('YXNkZmFzZGY=', 'base64') returns 'asdfasdf' from the browser module, exercising the default branch.

---

View workflow run

[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

[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.