Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

Fix: Install only oxlint and oxfmt to ensure CI checks for web files. (#19197)

balibabu68959037f3bf
diff --git a/.github/workflows/sep-tests.yml b/.github/workflows/sep-tests.yml
index 609d34e0ac..837ee36f7b 100644
--- a/.github/workflows/sep-tests.yml
+++ b/.github/workflows/sep-tests.yml
@@ -135,6 +135,13 @@ jobs:
# fi
# fi
+ # lefthook's web-checks hook resolves oxlint/oxfmt through
+ # tools/hooks/web_tools.sh, which needs node and npm on PATH.
+ - name: Set up Node.js
+ uses: actions/setup-node@v4
+ with:
+ node-version: "22"
+
- name: Run Lefthook on changed files
run: |
set -euo pipefail
@@ -159,6 +166,10 @@ jobs:
# applying --fix or `git add`, so CI only checks and reports
# failures instead of rewriting the working tree.
LEFTHOOK_CHECK_ONLY=1 lefthook run pre-commit --files-from-stdin --no-auto-install < "$changed_files"
+ # web-checks is a separate hook because it is not wired into local
+ # commits: it installs a Node toolchain that only CI has a reason to
+ # pay for. It is always check-only, so it needs no CHECK_ONLY flag.
+ lefthook run web-checks --files-from-stdin --no-auto-install < "$changed_files"
fi
- name: Set test level
diff --git a/lefthook.yml b/lefthook.yml
index 606f3fd1e2..727abb5ac2 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -1,4 +1,5 @@
-# There are 8 fix-capable jobs and 6 pure-check jobs.
+# There are 6 fix-capable jobs and 5 pure-check jobs in pre-commit, plus a
+# CI-only `web-checks` hook at the bottom of this file.
# Dual-mode pre-commit: by default (local dev) jobs fix and stage changes
# (`stage_fixed: true` batches the `git add` per job to avoid the index lock
# that parallel `git add` calls would hit). In CI, set LEFTHOOK_CHECK_ONLY=1
@@ -70,43 +71,6 @@ pre-commit:
else
gofmt -w {staged_files}
fi
- - name: web-checks
- group:
- piped: true
- jobs:
- - name: web-deps
- glob: "web/**/*.{css,less,json,js,jsx,ts,tsx}"
- run: |
- TOOL=web/node_modules/.hookbin/node_modules/.bin
- if [ ! -x "$TOOL/oxfmt" ] || [ ! -x "$TOOL/oxlint" ]; then
- exit 0
- fi
- - name: web-oxfmt
- glob: "web/**/*.{css,less,json,js,jsx,ts,tsx}"
- exclude: ["web/**/*.min.js", "web/**/*.min.css", "web/node_modules/**", "web/.next/**", "web/dist/**"]
- root: "web/"
- stage_fixed: true
- run: |
- OXFMT=node_modules/.hookbin/node_modules/.bin/oxfmt
- if ! [ -x "$OXFMT" ]; then exit 0; fi
- if [ "${LEFTHOOK_CHECK_ONLY:-}" = "1" ]; then
- "$OXFMT" --check {staged_files}
- else
- "$OXFMT" {staged_files}
- fi
- - name: web-oxlint
- glob: "web/**/*.{js,jsx,ts,tsx}"
- exclude: ["web/**/*.min.js", "web/node_modules/**", "web/.next/**", "web/dist/**"]
- root: "web/"
- stage_fixed: true
- run: |
- OXLINT=node_modules/.hookbin/node_modules/.bin/oxlint
- if ! [ -x "$OXLINT" ]; then exit 0; fi
- if [ "${LEFTHOOK_CHECK_ONLY:-}" = "1" ]; then
- "$OXLINT" {staged_files}
- else
- "$OXLINT" --fix {staged_files}
- fi
- name: check-yaml
run: python3 tools/hooks/check_files.py yaml
- name: check-json
@@ -117,3 +81,25 @@ pre-commit:
run: python3 tools/hooks/check_files.py merge-conflict
- name: check-symlinks
run: python3 tools/hooks/check_files.py symlinks
+
+# CI-only hook. Local commits deliberately do not lint or format web/: the
+# toolchain is a Node dependency that backend contributors have no other reason
+# to install. sep-tests.yml runs `lefthook run web-checks` on the files a pull
+# request changed, and that run is what blocks. To get the same feedback by
+# hand, run `npm run lint` / `npm run format` from web/.
+web-checks:
+ # Sequential: on a cold cache both jobs would otherwise run the same
+ # `npm install --prefix` into the same directory at once. Piped, the first one
+ # installs and the second reuses.
+ piped: true
+ jobs:
+ - name: web-oxfmt
+ glob: "web/**/*.{css,less,json,js,jsx,ts,tsx}"
+ exclude: &web_exclude ["web/**/*.min.js", "web/**/*.min.css", "web/package-lock.json", "web/node_modules/**", "web/.next/**", "web/dist/**"]
+ root: "web/"
+ run: '"$(../tools/hooks/web_tools.sh)/oxfmt" --check {files}'
+ - name: web-oxlint
+ glob: "web/**/*.{js,jsx,ts,tsx}"
+ exclude: *web_exclude
+ root: "web/"
+ run: '"$(../tools/hooks/web_tools.sh)/oxlint" {files}'
diff --git a/tools/hooks/web_tools.sh b/tools/hooks/web_tools.sh
new file mode 100755
index 0000000000..e6304bc365
--- /dev/null
+++ b/tools/hooks/web_tools.sh
@@ -0,0 +1,63 @@
+#!/bin/sh
+#
+# Resolve the oxlint/oxfmt pair used by the web pre-commit jobs, installing the
+# versions pinned by web/package-lock.json on first use.
+#
+# Prints the directory holding both binaries on stdout; every progress message
+# goes to stderr, so callers can use `BIN=$(tools/hooks/web_tools.sh)`.
+#
+# POSIX sh: lefthook runs `run:` blocks through /bin/sh, which is dash on most
+# Linux runners.
+set -eu
+
+repo_root=$(CDPATH='' cd -- "$(dirname -- "$0")/../.." && pwd)
+web_dir="$repo_root/web"
+lock="$web_dir/package-lock.json"
+
+if ! command -v node >/dev/null 2>&1 || ! command -v npm >/dev/null 2>&1; then
+ echo "web_tools: node/npm not found — they are required to lint and format web/ files" >&2
+ exit 1
+fi
+
+# Version package-lock.json pins $1 to.
+locked_version() {
+ node -p "require('$lock').packages['node_modules/$1'].version"
+}
+
+# Version of an installed package, empty when it is not there.
+installed_version() {
+ node -p "try{require('$1/package.json').version}catch(e){''}"
+}
+
+oxlint_version=$(locked_version oxlint)
+oxfmt_version=$(locked_version oxfmt)
+
+# A contributor who ran `npm install` in web/ already has the pinned pair;
+# reuse it instead of keeping a second copy in sync.
+if [ "$(installed_version "$web_dir/node_modules/oxlint")" = "$oxlint_version" ] &&
+ [ "$(installed_version "$web_dir/node_modules/oxfmt")" = "$oxfmt_version" ]; then
+ echo "$web_dir/node_modules/.bin"
+ exit 0
+fi
+
+# Otherwise keep the binaries in a version-keyed cache OUTSIDE the repo. Inside
+# web/node_modules they would be wiped by the next `npm ci`, and npm would treat
+# the directory as a stray package.
+cache="${XDG_CACHE_HOME:-$HOME/.cache}/ragflow/web-tools/oxlint-$oxlint_version-oxfmt-$oxfmt_version"
+cache_bin="$cache/node_modules/.bin"
+
+if [ ! -x "$cache_bin/oxlint" ] || [ ! -x "$cache_bin/oxfmt" ]; then
+ echo "web_tools: installing oxlint@$oxlint_version oxfmt@$oxfmt_version" >&2
+ mkdir -p "$cache"
+ printf '{"name":"ragflow-web-tools","version":"1.0.0","private":true}\n' >"$cache/package.json"
+ # Read the registry from web/.npmrc explicitly: with --prefix pointing at the
+ # cache, npm's own project-config lookup no longer lands on web/.npmrc.
+ registry=$(cd "$web_dir" && npm config get registry)
+ # oxlint and oxfmt are prebuilt Rust binaries (5 packages, ~35 MB), so this
+ # needs none of web/'s ~1.5 GB dependency tree.
+ npm install --prefix "$cache" --registry "$registry" \
+ --no-audit --no-fund --loglevel=error \
+ "oxlint@$oxlint_version" "oxfmt@$oxfmt_version" >&2
+fi
+
+echo "$cache_bin"
diff --git a/web/src/custom.d.ts b/web/src/custom.d.ts
index 915286fa28..77d8b6fd0a 100644
--- a/web/src/custom.d.ts
+++ b/web/src/custom.d.ts
@@ -23,6 +23,5 @@ declare module '*.md' {
declare module 'jsoneditor' {
const JSONEditor: any;
- export default JSONEditor;
export = JSONEditor;
}
diff --git a/web/src/pages/agent/index.tsx b/web/src/pages/agent/index.tsx
index a2445bd2cd..bb2d5e4f38 100644
--- a/web/src/pages/agent/index.tsx
+++ b/web/src/pages/agent/index.tsx
@@ -25,6 +25,7 @@ import { SharedFrom } from '@/constants/chat';
import { useSetModalState } from '@/hooks/common-hooks';
import { useNavigatePage } from '@/hooks/logic-hooks/navigate-hooks';
import { useSetAgent } from '@/hooks/use-agent-request';
+import { useIsGoBackend } from '@/utils/backend-variant';
import { ReactFlowProvider } from '@xyflow/react';
import {
ChevronDown,
@@ -40,7 +41,6 @@ import {
} from 'lucide-react';
import { ComponentPropsWithoutRef, useCallback, useMemo } from 'react';
import { useTranslation } from 'react-i18next';
-import { useSyncExternalStore } from 'react';
import { useParams } from 'react-router';
import AgentCanvas from './canvas';
import { DropdownProvider } from './canvas/context';
@@ -74,11 +74,7 @@ import { useAgentHistoryManager } from './use-agent-history-manager';
import { VersionDialog } from './version-dialog';
import WebhookSheet from './webhook-sheet';
import { RunTooltip } from './flow-tooltip';
-import {
- debugRunLimitsTooltipKey,
- isGoBackend,
- subscribeBackendLanguage,
-} from '@/utils/backend-runtime';
+import { debugRunLimitsTooltipKey } from './utils/debug-run-limits';
/**
* Standardizes dropdown menu item styling for agent management actions.
@@ -110,14 +106,12 @@ export default function Agent() {
} = useSetModalState();
const { t } = useTranslation();
useAgentHistoryManager();
- // Resolves (and re-renders when it resolves) the i18n key for the canvas
- // "Run" tooltip describing the Go-side debug preview limits. It is shown
- // ONLY for a dataflow (ingestion pipeline) canvas on the golang backend —
- // an agent canvas runs the agent, not an ingestion debug preview, so it
- // must never show this tooltip.
- const runTooltipKey = useSyncExternalStore(subscribeBackendLanguage, () =>
- debugRunLimitsTooltipKey(isGoBackend(), isPipeline),
- );
+ const isGoBackend = useIsGoBackend();
+ // Resolves the i18n key for the canvas "Run" tooltip describing the Go-side
+ // debug preview limits. It is shown ONLY for a dataflow (ingestion pipeline)
+ // canvas on the golang backend — an agent canvas runs the agent, not an
+ // ingestion debug preview, so it must never show this tooltip.
+ const runTooltipKey = debugRunLimitsTooltipKey(isGoBackend, isPipeline);
const { handleExportJson } = useHandleExportJsonFile();
const { saveGraph, loading } = useSaveGraph();
diff --git a/web/src/utils/__tests__/backend-runtime.test.ts b/web/src/pages/agent/utils/debug-run-limits.test.ts
similarity index 90%
rename from web/src/utils/__tests__/backend-runtime.test.ts
rename to web/src/pages/agent/utils/debug-run-limits.test.ts
index 70f77b4e34..14e08ff4f9 100644
--- a/web/src/utils/__tests__/backend-runtime.test.ts
+++ b/web/src/pages/agent/utils/debug-run-limits.test.ts
@@ -1,4 +1,4 @@
-import { debugRunLimitsTooltipKey } from '@/utils/backend-runtime';
+import { debugRunLimitsTooltipKey } from './debug-run-limits';
describe('debugRunLimitsTooltipKey', () => {
it('returns the key only for a dataflow (ingestion pipeline) canvas on golang', () => {
diff --git a/web/src/pages/agent/utils/debug-run-limits.ts b/web/src/pages/agent/utils/debug-run-limits.ts
new file mode 100644
index 0000000000..91c8dd9924
--- /dev/null
+++ b/web/src/pages/agent/utils/debug-run-limits.ts
@@ -0,0 +1,21 @@
+/**
+ * debugRunLimitsTooltipKey returns the i18n key for the canvas "Run" button
+ * tooltip describing the debug (dry-run) preview limits, or null when the
+ * tooltip should not be shown.
+ *
+ * The tooltip applies ONLY to a dataflow (ingestion pipeline) canvas on the
+ * golang backend. An agent canvas runs the agent/chat, not an ingestion
+ * debug preview, so it must never show this tooltip. The python backend's
+ * debug semantics also differ and are out of scope.
+ *
+ * It is a pure function of (backend language, is-pipeline) so it can be
+ * unit-tested without mocking; the caller reads the backend through
+ * `useIsGoBackend()`.
+ *
+ * The tooltip copy itself never names the backend language; only its
+ * visibility is gated on these conditions.
+ */
+export const debugRunLimitsTooltipKey = (
+ isGo: boolean,
+ isPipeline: boolean,
+): string | null => (isGo && isPipeline ? 'flow.debugRunLimits' : null);
diff --git a/web/src/pages/agent/utils/tests/extractor-transform.test.ts b/web/src/pages/agent/utils/tests/extractor-transform.test.ts
index 8b4a47b6c8..9a64835112 100644
--- a/web/src/pages/agent/utils/tests/extractor-transform.test.ts
+++ b/web/src/pages/agent/utils/tests/extractor-transform.test.ts
@@ -3,7 +3,6 @@ import { transformExtractorParams } from '../../utils';
let mockIsGoBackend = true;
jest.mock('@/utils/backend-runtime', () => ({
- isGoBackend: () => mockIsGoBackend,
getBackendLanguage: () => (mockIsGoBackend ? 'go' : 'python'),
}));
diff --git a/web/src/pages/dataset/setting/go/hooks.test.tsx b/web/src/pages/dataset/setting/go/hooks.test.tsx
index 08469f0cc9..6dc1b03fca 100644
--- a/web/src/pages/dataset/setting/go/hooks.test.tsx
+++ b/web/src/pages/dataset/setting/go/hooks.test.tsx
@@ -4,7 +4,6 @@ import { useSaveDatasetSetting } from './hooks';
let mockIsGoBackend = true;
jest.mock('@/utils/backend-runtime', () => ({
- isGoBackend: () => mockIsGoBackend,
getBackendLanguage: () => (mockIsGoBackend ? 'go' : 'python'),
}));
jest.mock('@/hooks/use-knowledge-request', () => ({
diff --git a/web/src/utils/__tests__/pipeline-operator.test.ts b/web/src/utils/__tests__/pipeline-operator.test.ts
index 061d279ca1..8718bc4aac 100644
--- a/web/src/utils/__tests__/pipeline-operator.test.ts
+++ b/web/src/utils/__tests__/pipeline-operator.test.ts
@@ -2,7 +2,6 @@ import { buildOperatorNode } from '@/utils/pipeline-operator';
let mockIsGoBackend = true;
jest.mock('@/utils/backend-runtime', () => ({
- isGoBackend: () => mockIsGoBackend,
getBackendLanguage: () => (mockIsGoBackend ? 'go' : 'python'),
}));
diff --git a/web/src/utils/backend-runtime.ts b/web/src/utils/backend-runtime.ts
index f7bddd9757..aac385b518 100644
--- a/web/src/utils/backend-runtime.ts
+++ b/web/src/utils/backend-runtime.ts
@@ -48,31 +48,6 @@ export const fetchBackendLanguage = (): Promise<string> => promise;
export const getBackendLanguage = (): string | null => backendLanguage;
-export const isGoBackend = (): boolean => backendLanguage === 'go';
-
-/**
- * debugRunLimitsTooltipKey returns the i18n key for the canvas "Run" button
- * tooltip describing the debug (dry-run) preview limits, or null when the
- * tooltip should not be shown.
- *
- * The tooltip applies ONLY to a dataflow (ingestion pipeline) canvas on the
- * golang backend. An agent canvas runs the agent/chat, not an ingestion
- * debug preview, so it must never show this tooltip. The python backend's
- * debug semantics also differ and are out of scope.
- *
- * It is a pure function of (backend language, is-pipeline) so it can be
- * unit-tested without mocking, and the Agent derives it via
- * useSyncExternalStore(subscribeBackendLanguage, () =>
- * debugRunLimitsTooltipKey(isGoBackend(), isPipeline)).
- *
- * The tooltip copy itself never names the backend language; only its
- * visibility is gated on these conditions.
- */
-export const debugRunLimitsTooltipKey = (
- isGo: boolean,
- isPipeline: boolean,
-): string | null => (isGo && isPipeline ? 'flow.debugRunLimits' : null);
-
export const subscribeBackendLanguage = (listener: Listener): (() => void) => {
listeners.add(listener);
return () => {