Skip to content

chore: restore the pre-commit hook with lefthook - #5222

Draft
Frank3K wants to merge 17 commits into
google:masterfrom
Frank3K:chore/lefthook-pre-commit
Draft

Frank3K wants to merge 17 commits into
google:masterfrom
Frank3K:chore/lefthook-pre-commit

Conversation

@Frank3K

@Frank3K Frank3K commented Nov 13, 2026

Copy link
Copy Markdown
Contributor

⚠️ Depends on #5220 (ESLint 10 flat config), because the hook runs eslint --fix. Until #5220 is merged, this PR also shows its commits. The changes for this PR are the last two commits. ⚠️

Description

Summary

The repo's pre-commit hook hasn't run since mid-2021. package.json still has a husky v4 "husky": {"hooks": …} block. husky 7 and later ignore that block, and there was no .husky/ directory or prepare script. The script it pointed to (scripts/pre-commit.sh) also had a bug: it ran git stash -k for unstaged changes but never popped the stash.

This PR restores the hook with lefthook instead of husky, which hasn't had a release since 9.1.7. It also fixes clang-format on Apple Silicon.

Changes

Pre-commit hook (lefthook.yml)

  • Runs on staged files only, in order:
    1. clang-format -i on packages/*/src/**/*.ts, excluding *.d.ts. This is the same scope as npm run format.
    2. eslint --fix on staged files. eslint.config.mjs decides which files are actually linted.
  • Fixed files are re-staged. In a partially staged file, unstaged changes are left as they were.
  • Hooks are installed by lefthook's postinstall script on npm install, so no prepare script is needed. On CI (CI=true) they are not installed.
  • Run LEFTHOOK=0 git commit … to skip the hook once.

clang-format

  • Replaces the clang-format npm package with clang-format-node, pinned to 4.0.4, which ships clang-format 23.1.4. The old package is at 1.8.0, last released in 2023. It bundles clang-format 15 and has only an x86_64 macOS binary, so it fails with spawn Unknown system error -86 on Apple Silicon Macs without Rosetta. clang-format-node is built from the official LLVM sources and ships native binaries for each platform.
  • The version is pinned exactly, because a different clang-format version formats code differently.
  • Adds npm run format:check (clang-format --dry-run --Werror) and runs it in the unit-tests workflow after lint.

Reformat

  • A separate style: commit reformats 13 files with clang-format 23.1.4. It only changes whitespace and line breaks (git diff -w shows only re-wrapped lines). Most of it is a re-indent of decorators.ts.

Removed

  • scripts/pre-commit.sh, the husky v4 config block, and the husky dev dependency.

Testing

Tested on macOS (Apple Silicon), Node 24:

  • npm install installs .git/hooks/pre-commit.
  • Staged a badly formatted change and left another edit unstaged in the same file, then committed. Only the staged change was formatted and committed. The unstaged edit stayed in the working tree, and no stash was left behind.
  • A file in a nested folder (src/features/…) is formatted, and .d.ts files are skipped.
  • npm run format:check, npm run lint (0 errors) and npm run build pass.

Notes for contributors

  • After pulling this, run npm install once to install the hook.
  • If you previously set up husky locally and git config core.hooksPath is set, lefthook won't install its hooks. Run git config --unset core.hooksPath, then run npm install again.

Keep line endings, final newlines, trailing whitespace and indentation
consistent across editors for files clang-format does not cover.
Strip trailing whitespace and convert two CRLF files to LF. Markdown is
left untouched since trailing spaces can be significant there.
Whitespace-only change: git diff -w shows nothing.
Replace the legacy .eslintrc.yaml/.eslintignore, which ESLint 9+ no
longer reads and which ignored every package, with eslint.config.mjs.

- eslint 10, @eslint/js and typescript-eslint recommended presets,
  eslint-plugin-wc best-practice, eslint-plugin-mocha recommended for
  tests
- drop the deprecated eslint-config-google; clang-format owns formatting
- no-explicit-any is a warning for now
- mocha/no-mocha-arrows and no-unused-expressions are off in tests to
  match the arrow-function style and chai assertions
- npm run lint now lints every package, including JS/MJS files
Output of `eslint . --fix` (curly, prefer-const, no-var,
explicit-member-accessibility, no-wrapper-object-types, prefer-as-const,
no-extra-boolean-cast, ...). Changed lines were reformatted with
git-clang-format. Vendored third_party code is now ignored.
- drop unnecessary backslashes in regular expressions and strings
- use strict equality; comparisons against undefined become == null to
  keep matching both null and undefined
- dropdown compares Number(selected), since paper-listbox's selected
  may be a string
- super.x && super.x() becomes super.x?.()
- use optional catch bindings where the error is unused
- replace comma operators with statements in camera_settings
- drop type-only $CombinedState imports; declarations still emit
- use the Category interface instead of a placeholder constant
- comment out imports only used by commented-out test-runner config
- controls: keep the elapsed interaction-prompt time across visibility
  changes; it was reset on every call
- validation: compare severityTitle instead of assigning it, so the
  glTF URL is only revoked after a conversion
- exportScene: only wrap exporter.parse in the Promise, so errors from
  the awaited setup reject instead of leaving it pending; drop async
  from Promise executors that never await
- custom-select example: set up shadow-DOM listeners once in the
  constructor and remove the document listener on disconnect
- compare-results: read JSON with fs, as require() is unavailable in
  the ESM output
- scene-graph-spec: the variant-revert tests returned from inside the
  search loop and never asserted; use break. The 'Yellow Red' case
  fails once it runs, so it is skipped with a TODO
- wrap lexical declarations in case blocks
- Object.prototype.hasOwnProperty.call instead of obj.hasOwnProperty
- replace Function and {} types with specific types
- assert non-null instead of mixing ?. with ! in tests
- attach caught errors as cause (adds es2022.error lib to
  render-fidelity-tools)
- drop unneeded @ts-ignore comments, this aliases, dead initial
  assignments and a full-width space
- comment empty catch blocks
- turn off no-unexpected-multiline, which conflicts with clang-format's
  layout of calls and tagged templates
Lint runs right after npm ci so it fails fast. Warnings
(no-explicit-any) do not fail the build.
- Lit update/updated overrides take Map<string|number|symbol, unknown>,
  matching existing usage; one caller now casts the old value
- throttle/debounce are generic over the wrapped function's arguments
- type render-fidelity configs as ImageComparisonConfig and let
  puppeteer/child_process handler types be inferred
- catch bindings are unknown and cast to Error where .message is read
- allow `...args: any[]` (ignoreRestArgs), which TypeScript mixins
  require

no-explicit-any warnings: 269 -> 217.
User-Agent Client Hints are missing from TypeScript's DOM lib, so
declare the one method we use and move the XR form-factor check into a
helper. Behavior is unchanged.
lib/ is published and its .d.ts files are public. Restore the original
throttle/debounce (any) and getValueOfEnum (T extends Object)
signatures so callers that deep-import them are not broken by stricter
types.
The zizmor check fails on pull requests that change a workflow file
containing actions referenced by tag. Pin every action to the commit
its current tag points to, with the version in a comment, and give the
read-only workflows an explicit `contents: read` permission.
The hook config in package.json used the husky v4 format, which husky 7+
ignores, so the hook has not run since mid-2021. scripts/pre-commit.sh
also never popped the stash it created for unstaged changes.

- Replace husky with lefthook. Its postinstall script installs the hooks
  on `npm install`. lefthook.yml formats staged TypeScript sources with
  clang-format and then runs `eslint --fix`, re-staging the results.
  Unstaged changes in partially staged files are left untouched.
- Replace the clang-format npm package (clang-format 15, x86_64-only on
  macOS) with clang-format-node, pinned to 4.0.4 (clang-format 23.1.4),
  which ships native binaries for Apple Silicon.
- Add `npm run format:check` and run it in the unit-tests workflow.
- Remove scripts/pre-commit.sh and the husky v4 config block.
Whitespace-only changes from running `npm run format` with the
clang-format version now pinned via clang-format-node.
@Frank3K
Frank3K force-pushed the chore/lefthook-pre-commit branch from 60189a3 to 8798e1b Compare November 14, 2026 00:12
…lint-all-packages

# Conflicts:
#	.github/workflows/deploy-documentation.yml
#	.github/workflows/fidelity-tests.yml
#	.github/workflows/unit-tests.yml
#	package-lock.json
…-pre-commit

# Conflicts:
#	package-lock.json

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant