mirror of https://github.com/danny-avila/LibreChat.git synced 2026-09-06 14:39:10 +00:00

🪥 chore: Run CI's Static Checks on Each Commit's Diff (#15303 )

* 🪝 chore: Run Static Checks on Every Commit

Adds `scripts/static-checks.mts`, a local port of the Static Checks CI job
(.github/workflows/static-checks.yml) scoped to the files in a diff. It
resolves the changed-file list, applies the same `dorny/paths-filter` groups
the job uses, and runs whichever checks those paths activate — ESLint,
Prettier, import order, ESLint config validation, package.json validation, and
(behind `--full`) config migration tests, unused i18n keys and depcheck. Like
the job, every selected check runs even after one fails and the failures are
summarized at the end.

The pre-commit hook keeps lint-staged for the per-file layer, which verifies
the exact staged content of partially staged files, then runs the script for
everything lint-staged cannot cover. lint-staged now uses the job's ESLint
invocation, so warnings fail locally the way they fail CI.

The slow gates stay opt-in (`npm run static-checks:full`, or
`STATIC_CHECKS_FULL=1`) to keep commit latency unchanged.

Hooks were never installed: `config/prepare.js` existed but no `prepare` script
called it, so the hook only ran where `core.hooksPath` had been set by hand.
Replaces it with an inline `prepare` — both Dockerfiles run `npm ci` after
copying only the manifests, so a `node config/prepare.js` step would fail the
image build, and husky is absent from `--omit=dev` installs.

The i18n scan is a single pass over the source identifiers rather than one grep
per key, verified to flag exactly the same keys as the CI loop (including the
substring and dynamic-key cases) in 0.5s instead of 14s.

* 🩹 fix: Address Codex Round 1 on the Static Checks Runner

Activate gates from the unfiltered changed-path list. `dorny/paths-filter`
matches deleted paths too, so gating on the `--diff-filter=ACMRTUXB` list the
per-file steps use let a delete-only commit — the last reference to a
translation key, say — slip past the i18n and depcheck gates. The two lists are
now derived separately, the way CI derives them.

Pass `-m` to `git diff-tree` in `--commit` mode. Without it a merge commit
emits no paths at all, so `--commit <merge-sha>` reported "Nothing to check";
a real merge in this repo's history goes from 0 to 97 files.

Build the workspaces the config suite imports instead of skipping when `dist`
is absent. The three `dist` directories are gitignored and `npm ci` does not
produce them, so a fresh checkout reported a pass for a gate that never ran —
and an existing `dist` could be stale. Each is a sub-second tsdown build.

Resolve a global depcheck through a shell on Windows, where npm exposes it as
`depcheck.cmd` and `spawnSync` cannot see the shim.

Skip dot directories when walking for imports. `.claude/worktrees/` can hold a
full checkout per branch — 117 on this machine — and the root-wide scan behind
the depcheck gate walked every one of them.

Records the remaining boundary in the header: the per-file checks see exact
staged content via lint-staged, while the tree-wide gates read the working
tree, as running them by hand would.

* 🩹 fix: Address Codex Round 2 on the Static Checks Runner

Treat an unresolvable checker as a failure. ESLint and Prettier missing meant
the runner printed "All affected static checks passed" without having linted
anything; only depcheck, which CI installs globally and this documents as
optional, may still skip.

Catch per-check exceptions. The runner promises that every selected check runs
even after a failure, but a throw — a malformed translation JSON, say —
escaped and cancelled the checks after it. Each is now recorded as that
check's failure; verified that depcheck still runs after i18n throws.

Restrict `--commit` to the checked-out commit. Paths came from the named
commit while contents came from the working tree, so an older revision was
scored against the wrong file contents: a file added then deleted vanished,
and one modified since was read at its newer contents. It now fails with a
pointer to `--against`.

Reject unknown options. `--ful` silently ran the fast tier and `--commmit HEAD`
treated `HEAD` as a file path, both exiting 0 and implying gates had run.

Cover the runner in CI. `scripts/**` was absent from the workflow's trigger
paths, so a PR touching only the script the pre-commit hook now depends on got
no Static Checks run — and ESLint has no flat-config match for
`scripts/**/*.mts`, so nothing else loads it either. Adds the trigger path, a
`runner` filter group and a step that runs the script against the PR's own diff.

* 🔗 feat: Add Circular Dependency and TypeScript Gates

Both already run in CI as jobs of the Backend Unit Tests workflow; this brings
them to the local runner so they land before a push rather than after.

Circular dependencies (`node config/circular-deps.mjs`) is fast enough at 0.9s
to sit in the per-commit tier, gated on the same paths that trigger the CI job.

TypeScript stays opt-in behind `--full`: the five projects cost between 2.3s
and 20.9s each, which is too much per commit. Each project declares the paths
that can affect it — its own sources plus its upstream packages — so an edit to
data-provider still typechecks data-schemas, api, packages/client and client,
while an `api/**`-only change runs none of them, since no typechecked project
includes that directory. The builds a project's imports resolve through are
made first, mirroring the CI jobs' dependency on the build artifacts, through a
helper the config suite now shares.

Also addresses codex round 3:

Reject conflicting target selectors. `--against origin/dev package.json`
silently checked only the file, and `--against <bad-ref> --commit HEAD` never
resolved the bad base, so a caller could believe a range had been checked.

Require a clean worktree in `--commit` mode. The HEAD-only restriction was not
enough: contents still come from the working tree, so an uncommitted edit was
scored against the named commit — an invalid uncommitted package.json failing a
valid HEAD, or an uncommitted fix masking a defect in it.

The summary now names how many checks were skipped rather than reporting a
bare pass, and a typecheck failure carries the stale-workspace-build hint —
inside a git worktree `librechat-data-provider` resolves to the main checkout,
whose dist can predate the branch and shows up as missing properties.

* 🩹 fix: Address Codex Round 4 on the Static Checks Runner

Diff `--against` from the merge base. A two-dot diff reports the base branch's
own commits in reverse once it advances, so `--against origin/dev` scored 64
files for a branch that changed 7, activating gates for files the branch never
touched. Three dots makes the documented PR-style command mean what it says.

Typecheck on root manifest changes. Both review workflows trigger their
TypeScript jobs on package.json and package-lock.json, because a dependency or
@types bump breaks compilation on its own; the local filter ignored them, so
`static-checks:full` passed where CI would fail.

Validate every workspace manifest. The list mirrored the four the CI step
happens to name, so a malformed packages/api, data-provider or data-schemas
manifest passed validation in the revision modes, which have no lint-staged
pass behind them. Both lists now cover all seven.

Make the runner smoke execute a check. `--list` never runs one, and a
script-only PR activates no group, so the CI coverage added for exactly that
case could pass with the execution path untouched. It now runs against an
explicit target.

* 🩹 fix: Address Codex Round 5 on the Static Checks Runner

Activate the JSON gate for every manifest it validates. Round 4 added the four
workspace manifests to the validation list but not to the filter that turns the
gate on, so a malformed packages/data-provider or data-schemas manifest still
passed when it was the only changed file — the list grew and the trigger did
not. The same two entries also feed the unused-package calculation, reached
through api/package.json's @librechat/data-schemas dependency.

Include the owning workflows in the imported gates' filters. Circular
dependencies and TypeScript come from the review workflows, both of which list
their own YAML in `on.paths` and therefore rerun those jobs when the workflow
changes; locally the gates stayed inactive, so a change to how they are built
or invoked could bypass the local equivalent. Added to the group filters and to
the per-project predicates, since a workflow-only change would otherwise
activate the group and then select no project.

Bound command batches by characters rather than file count. Windows caps a
command line at 32767 characters, far below POSIX ARG_MAX, and a count does not
bound that: 400 of this repository's longer paths already come to 30176
characters before the executable and fixed arguments. Verified that a list
spanning several batches still reports a defect in its final file.

2026-08-28 10:08:37 -04:00

9.9 KiB

Raw Blame History

Contributor Guidelines

Thank you to all the contributors who have helped make this project possible! We welcome various types of contributions, such as bug reports, documentation improvements, feature requests, and code contributions.

Contributing Guidelines

If the feature you would like to contribute has not already received prior approval from the project maintainers (i.e., the feature is currently on the roadmap), please submit a request in the Feature Requests & Suggestions category of the discussions board before beginning work on it. The requests should include specific implementation details, including areas of the application that will be affected by the change (including designs if applicable), and any other relevant information that might be required for a speedy review. However, proposals are not required for small changes, bug fixes, or documentation improvements. Small changes and bug fixes should be tied to an issue and included in the corresponding pull request for tracking purposes.

Please note that a pull request involving a feature that has not been reviewed and approved by the project maintainers may be rejected. We appreciate your understanding and cooperation.

If you would like to discuss the changes you wish to make, join our Discord community, where you can engage with other contributors and seek guidance from the community.

Our Standards

We strive to maintain a positive and inclusive environment within our project community. We expect all contributors to adhere to the following standards:

Using welcoming and inclusive language.
Being respectful of differing viewpoints and experiences.
Gracefully accepting constructive criticism.
Focusing on what is best for the community.
Showing empathy towards other community members.

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that do not align with these standards.

To contribute to this project, please adhere to the following guidelines:

1. Development Setup

Use Node.js v24.16.0.
Run npm run smart-reinstall to install dependencies (uses Turborepo). Use npm run reinstall for a clean install, or npm ci for a fresh lockfile-based install.
Build all compiled code: npm run build.
Setup and run unit tests:
- Copy .env.test: cp api/test/.env.test.example api/test/.env.test.
- Run backend unit tests: npm run test:api.
- Run frontend unit tests: npm run test:client.
Setup and run integration tests:
- Create .env: cp .env.example .env.
- Install MongoDB Community Edition, ensure that mongosh connects to your local instance.
- Run: npx install playwright, then npx playwright install.
- Copy config.local: cp e2e/config.local.example.ts e2e/config.local.ts.
- Copy librechat.yaml: cp librechat.example.yaml librechat.yaml.
- Run: npm run e2e.

2. Development Notes

Before starting work, make sure your main branch has the latest commits with npm run update.
Run linting command to find errors: npm run lint. Alternatively, ensure husky pre-commit checks are functioning.
- npm install sets the hooks up for you; set HUSKY=0 to opt out.
- The pre-commit hook runs the Static Checks CI job locally, scoped to the files in the commit. Run it by hand with npm run static-checks, against a base ref with npm run static-checks -- --against origin/dev, or with the slow gates (TypeScript, config migration tests, unused i18n keys, unused npm packages) via npm run static-checks:full.
- Every commit gets ESLint, Prettier, import order and circular-dependency detection; the slower gates stay opt-in so commits stay fast.
After your changes, reinstall packages in your current branch using npm run reinstall and ensure everything still works.
- Restart the ESLint server ("ESLint: Restart ESLint Server" in VS Code command bar) and your IDE after reinstalling or updating.
Clear web app localStorage and cookies before and after changes.
To check for introduced errors, build all compiled code: npm run build.
Run backend unit tests: npm run test:api.
Run frontend unit tests: npm run test:client.
Run integration tests: npm run e2e.

3. Git Workflow

We utilize a GitFlow workflow to manage changes to this project's codebase. Follow these general steps when contributing code:

Fork the repository and create a new branch with a descriptive slash-based name (e.g., new/feature/x).
Implement your changes and ensure that all tests pass.
Commit your changes using conventional commit messages with GitFlow flags. Begin the commit message with a tag indicating the change type, such as "feat" (new feature), "fix" (bug fix), "docs" (documentation), or "refactor" (code refactoring), followed by a brief summary of the changes (e.g., feat: Add new feature X to the project).
Submit a pull request with a clear and concise description of your changes and the reasons behind them.
We will review your pull request, provide feedback as needed, and eventually merge the approved changes into the main branch.

4. Commit Message Format

We follow the semantic format for commit messages.

Example

feat: add hat wobble
^--^  ^------------^
|     |
|     +-> Summary in present tense.
|
+-------> Type: chore, docs, feat, fix, refactor, style, or test.

Commit Guidelines

Do your best to reduce the number of commits, organizing them as much possible. Look into squashing commits in order to keep a neat history.
For those that care about maximizing commits for stats, adhere to the above as I 'squash and merge' an unorganized and/or unformatted commit history, which reduces the number of your commits to 1,:

* Update Br.tsx

* Update Es.tsx

* Update Br.tsx

5. Pull Request Process

When submitting a pull request, please follow these guidelines:

Ensure that any installation or build dependencies are removed before the end of the layer when doing a build.
Update the README.md with details of changes to the interface, including new environment variables, exposed ports, useful file locations, and container parameters.
Increase the version numbers in any example files and the README.md to reflect the new version that the pull request represents. We use SemVer for versioning.

Ensure that your changes meet the following criteria:

All tests pass as highlighted above.
The code is well-formatted and adheres to our coding standards.
The commit history is clean and easy to follow. You can use git rebase or git merge --squash to clean your commit history before submitting the pull request.
The pull request description clearly outlines the changes and the reasons behind them. Be sure to include the steps to test the pull request.

6. Naming Conventions

Apply the following naming conventions to branches, labels, and other Git-related entities:

Branch names: Descriptive and slash-based (e.g., new/feature/x).
Labels: Descriptive and kebab case (e.g., bug-fix).
JS/TS: Directories and file names: Descriptive and camelCase. First letter uppercased for React files (e.g., helperFunction.ts, ReactComponent.tsx).
Docs: Directories and file names: Descriptive and snake_case (e.g., config_files.md).

7. Coding Standards

For detailed coding conventions, workspace boundaries, and architecture guidance, refer to the AGENTS.md file at the project root. It covers code style, type safety, import ordering, iteration/performance expectations, frontend rules, testing, and development commands.

8. TypeScript Conversion

Original State: The project was initially developed entirely in JavaScript (JS).
Frontend: Fully transitioned to TypeScript.
Backend:
- The legacy Express.js server remains in /api as JavaScript.
- All new backend code is written in TypeScript under /packages/api, which is compiled and consumed by /api.
- Shared database logic lives in /packages/data-schemas (TypeScript).
- Shared frontend/backend API types and services live in /packages/data-provider (TypeScript).
- Minimize direct changes to /api; prefer adding TypeScript code to /packages/api and importing it.

9. Module Import Conventions

Imports are organized into three sections (in order):

Package imports — sorted from shortest to longest line length.
- react is always the first import.
- Multi-line (stacked) imports count their total character length across all lines for sorting.
import type imports — sorted from longest to shortest line length.
- Package type imports come first, then local type imports.
- Line length sorting resets between the package and local sub-groups.
Local/project imports — sorted from longest to shortest line length.
- Multi-line (stacked) imports count their total character length across all lines for sorting.
- Imports with alias ~ are treated the same as relative imports with respect to line length.

Consolidate value imports from the same module as much as possible.
Always use standalone import type { ... } for type imports; never use inline type keyword inside value imports (e.g., import { Foo, type Bar } is wrong).

Note: ESLint will automatically enforce these import conventions when you run npm run lint --fix or through pre-commit hooks.

For the full set of coding standards, see AGENTS.md.

9.9 KiB Raw Blame History