Skip to content

Latest commit

 

History

History
210 lines (141 loc) · 12 KB

DEV.md

File metadata and controls

210 lines (141 loc) · 12 KB

Guidance for FluidFramework maintainers and contributors

Running tests and benchmarks

For packages using the shared Mocha configuration, see Running tests for commands, test selection, and performance measurements.

Git Hooks (hk)

This repo uses hk to manage git hooks. Hooks are configured in hk.pkl at the repo root. Currently, a pre-commit hook runs biome format on staged files and auto-stages the formatted results.

Git hooks are opt-in. To install them locally:

hk install

This sets up the hooks defined in hk.pkl to run automatically on commit. You can also run checks manually:

hk check  # verify formatting without modifying files
hk fix    # auto-format files in place

hk requires the pkl CLI. Both hk and pkl can be installed via mise.

Dependencies

This document tracks dependencies that cannot be upgraded to their latest major versions due to technical limitations.

Pinned

The following dependencies are pinned to older major versions because newer versions are incompatible with the current codebase.

ESM-only dependencies (Cannot upgrade while shipping CJS)

  1. uuid - Pinned to ^11.x
    • Latest: ^13.x
    • Issue: Version 12+ removed CommonJS support entirely
    • Impact: FluidFramework packages ship dual ESM/CJS builds. When consumers require() our packages, the CJS output would fail to require('uuid') since uuid v12+ is ESM-only.
    • Used in: Many packages across the repo (telemetry-utils, container-loader, odsp-driver, etc.)

ESLint and typescript-eslint

projectService vs explicit project arrays

The shared ESLint config uses parserOptions.projectService: true by default for TypeScript files. This is the recommended approach as of typescript-eslint v8. However, some packages require explicit parserOptions.project arrays due to non-standard tsconfig structures.

Why projectService is preferred

projectService: true uses TypeScript's Language Service API (the same API VS Code uses), which correctly handles advanced type features like asserts this is type narrowing. The explicit project array approach creates separate TypeScript Program instances that don't handle type narrowing across statements as well.

CLI vs VS Code discrepancies

If you see ESLint errors in the CLI that don't appear in VS Code (or vice versa), the cause is likely a mismatch in projectService settings:

  • VS Code's ESLint extension may default to projectService: true
  • CLI uses whatever is configured in eslint.config.mts

When these differ, the same code can produce different type information, causing false positives or missed errors. For example, asserts this is type narrowing may work correctly with projectService but fail with explicit project arrays.

To diagnose:

  1. Check if the package's eslint.config.mts has projectService: false with an explicit project array
  2. If so, VS Code may be using projectService while CLI uses the explicit array
  3. Ensure VS Code's ESLint settings match the CLI configuration, or update the package to use projectService if possible

When projectService works

projectService works when all TypeScript files are covered by tsconfigs that are discoverable. A tsconfig is discoverable if:

  1. It is named tsconfig.json and exists in the directory ancestry of the source file, OR
  2. It is referenced (directly or transitively) via project references from a discoverable tsconfig.json

For example:

  • ./tsconfig.json references ./tsconfig.main.json → both are discoverable
  • ./tsconfig.json references ./src/test/tsconfig.json → test config is discoverable
  • ./tsconfig.jest.json with no reference from any tsconfig.json → NOT discoverable

When explicit project arrays are required

Explicit parserOptions.project arrays are needed when files exist that are not covered by any discoverable tsconfig.

Common scenarios requiring explicit arrays:

  • Standalone non-standard tsconfig naming - e.g., tsconfig.jest.json or tsconfig.cjs.lint.json that is NOT referenced by any tsconfig.json
  • Files intentionally excluded from the main tsconfig graph - e.g., test files compiled separately to test different compiler options like exactOptionalPropertyTypes, where referencing them from the main tsconfig would cause double-compilation
  • Test-only packages without root tsconfig.json - no entry point for projectService to discover

These packages have comments in their eslint.config.mts explaining why explicit project arrays are needed.

Key limitation: projectService only recognizes tsconfig.json

The projectService only looks for files named tsconfig.json. It does not recognize tsconfig.eslint.json, tsconfig.jest.json, tsconfig.test.json, or any other naming convention. This is intentional - the typescript-eslint team made this choice to ensure consistency between editor type information and linting.

This means:

  • Non-standard tsconfig naming requires falling back to explicit project arrays
  • Files excluded from one tsconfig.json but needing a different tsconfig cannot use projectService

Why allowDefaultProject doesn't help

allowDefaultProject is designed for a small number of out-of-project files (like eslint.config.js or vitest.config.ts):

  • Default limit of 8 files
  • Cannot use ** glob patterns
  • Significant performance overhead per file
  • Not suitable for test directories or large numbers of files

Potential restructuring to enable projectService

To maximize projectService usage, packages could be restructured to follow typescript-eslint's recommendations:

  1. Use tsconfig.json as the "lint" config (what editors see)
  2. Use tsconfig.build.json for build-specific settings (inverts the common pattern of tsconfig.eslint.json)
  3. Ensure every directory with TypeScript files has a tsconfig.json that includes those files
  4. Use project references to connect all tsconfigs

For example, a test-only package without a root tsconfig could add one:

// root tsconfig.json
{
  "files": [],
  "references": [
    { "path": "./src/test" }
  ]
}

However, some scenarios are fundamentally incompatible with projectService:

  • Files that cannot be referenced from the main tsconfig graph - For example, test files that need different compiler options (like exactOptionalPropertyTypes: false) and would cause double-compilation if referenced. These files are intentionally excluded from the main tsconfig and use a separate tsconfig that cannot be added as a project reference.
  • Files needing different compiler settings than projectService would provide - projectService uses the nearest discoverable tsconfig.json. If files need settings from a different tsconfig that isn't in their directory ancestry and can't be referenced, explicit arrays are required.

For these cases, use flat config overrides targeting specific file patterns:

{
  files: ['**/*.cjs.ts'],
  languageOptions: {
    parserOptions: {
      projectService: false,
      project: ['./tsconfig.cjs.lint.json'],
    },
  },
}

References

pnpm Supply Chain Security Settings

All workspace pnpm-workspace.yaml files include security-hardening settings to protect against supply chain attacks. This section documents these settings and their rationale.

Settings Overview

Setting Value Purpose
minimumReleaseAge 0 See "Why minimumReleaseAge 0"
resolutionMode highest Use highest matching version (see explanation below)
blockExoticSubdeps true Block transitive deps from using git/tarball sources
trustPolicy off The publicPackages mirror does not preserve the metadata required for no-downgrade checks
trustPolicyExclude [] Retained exclusions for when trust metadata is available again (see note below)
strictDepBuilds true Require explicit approval for dependency build scripts

Why minimumReleaseAge 0

The default value for this setting is 1440 (1 day). The azure artifact feeds that are used by internal developers and our PR/CI pipelines already have similar built-in protections against recently released packages. Specifically, these feeds quarantine recently released packages based on risk profile (on the order of 1 to 7 days, where packages with install-time scripts are quarantined for longer).

Unfortunately, artifact feeds do not preserve package publish time when ingesting a package from npmjs upstream. Rather, they record when the package was first added to the downstream artifact feed. Therefore using a nonzero value here may arbitrarily block internal developers from installing a package until an additional delay period after they first try to install it.

Updating dependencies while respecting minimum release age

Use pnpm install-no-frozen in the affected workspace root when updating dependencies. The script checks pnpm's effective registry and sets a minimum release age of 10080 minutes (7 days) for registry.npmjs.org, or 0 for publicPackages, which applies its own package-age protections. It respects environment configuration and forwarded --registry arguments. For other registries, it leaves the configured minimum release age unchanged.

Why resolutionMode: highest instead of time-based

We would prefer to use resolutionMode: time-based to avoid pulling in the newest packages from npm. This delays ingestion of newly published packages, which helps avoid supply chain attacks.

However, with resolutionMode: time-based, the "anchor" time for a transitive dependency is the time at which the depending package was released. For example:

  1. We depend on PackageA, which depends on PackageB@^1.0.0
  2. At the time PackageA was published (t0), PackageB was at 1.0.0
  3. PackageB releases 1.1.0 two weeks later
  4. Version 1.1.0 matches PackageA's dependency range, but it was released outside the t0 + 24 hours window established by PackageA's release, so pnpm blocks it

This behavior is desired. However, pnpm does NOT attempt downward resolution to find a version that works (e.g., 1.0.0). Instead, it throws an error with no automatic fallback.

With resolutionMode: highest, Microsoft devs and infrastructure still get protection from installing packages via internal artifacts feeds.

Trust Policy Exclusions (trustPolicyExclude)

trustPolicyExclude lists packages that are exempt from trustPolicy: no-downgrade enforcement. This is needed for packages that are known to be safe but were published at a date after another version of the same package (including later major versions) that had better provenance information — causing pnpm to incorrectly treat the newer version as a trust downgrade.

This list must be reviewed carefully before adding any entry. Only add a package here after confirming it is safe and understanding why its publication order triggers the policy.

Build Script Approval (strictDepBuilds)

When strictDepBuilds: true, pnpm requires explicit approval before running build scripts from dependencies. Approved packages are listed in:

  • Root workspace: pnpm.onlyBuiltDependencies in /package.json
  • Sub-workspaces with own lockfiles: Both pnpm.onlyBuiltDependencies in the workspace's package.json AND onlyBuiltDependencies in the workspace's pnpm-workspace.yaml (due to pnpm bug #9082)

To approve a new package's build scripts, add it to the appropriate onlyBuiltDependencies list(s).