Upgrade kolibri-format to 3.0.1 and migrate ESLint to flat config

❌ This issue is not open for contribution. Visit Contributing guidelines to learn about the contributing process and how to find suitable issues.

Overview

kolibri-format 3.0.1 runs ESLint 9 and uses flat configuration. Flat configuration is the eslint.config.mjs format that replaced .eslintrc. Studio runs kolibri-format 1.0.1 and loads kolibri-format/.eslintrc, a file the package stopped shipping in version 2.4.0.

This issue moves Studio onto the new toolchain and keeps CI green. The new rules that version 3.0.1 adds stay off.

Complexity: High
Target branch: unstable

Context

What changed between the two versions:

Item	1.0.1	3.0.1
ESLint	^8.57 with .eslintrc	^9.39 with flat configuration
Configuration file	.eslintrc.js	eslint.config.mjs
Import plugin	eslint-plugin-import	eslint-plugin-import-x, new rule names
eslint-plugin-kolibri	0.18.0	1.3.0
Added plugins	none	jsdoc, vuejs-accessibility, n, small-import
Added dependency	none	kolibri-css-variables
Node engine	18.x	20.19.0 or later

Version 1.3.0 of eslint-plugin-kolibri removes vue-no-unused-methods. It adds tests-no-hardcoded-strings, tests-no-stubs, no-undefined-translator-keys, vue-no-root-v-if-with-style-v-bind, and two theming rules.

Measured results across 943 frontend files. Autofix is the set of fixes that --write applies without help. Autofix rewrites 230 files. 2425 problems will remain in 364 files:

Plugin	Problems	Autofix clears	Files
jsdoc	1890	938	177
kolibri	833	203	135
vue	422	0	103
jest	170	155	19
vuejs-accessibility	51	0	28
import-x, n, core	59	14	44

Import resolution depends on the resolver settings. Measured counts for import-x/no-unresolved and import-x/order:

• No webpack resolver: 1284 and 530.
• Webpack resolver only: 518 and 0.
• Webpack resolver and node resolver: 0 and 0.

The linting job in CI runs pre-commit run --all-files. The frontend-lint hook calls pnpm run lint-frontend:format, which writes fixes to disk and fails when it changes a file. A commit that changes the configuration and leaves 230 files unformatted will fail that job on unstable.

Prettier 3.9 on its own wants to change 345 files, because it removes blank lines inside single file component blocks. The rule kolibri/vue-component-block-padding puts those lines back in the same pass. The result is 230 files, not 345.

The Change

• eslint.config.mjs must carry everything that .eslintrc.js carries today: the six globals, the webpack resolver, the node resolver that pnpm needs, and the three rule overrides for kolibri/vue-component-class-name-casing, vue/no-v-text-v-html-on-component, and vue/attribute-hyphenation.
• package.json must keep eslint-import-resolver-webpack, because the new configuration calls it, and the stylelint-config-* packages, because stylelint resolves extends against the repository root.
• The lint dependencies in package.json must stop conflicting with ESLint 9. eslint ^8.57.0, eslint-plugin-kolibri 0.18.0, eslint-plugin-import, and eslint-plugin-jest ^29 each need a bump or a removal.
• Thirteen disable comments name import/* rules. They must name import-x/* instead.
• Nine comments name kolibri/vue-no-unused-methods. Seven of them also name vue/no-unused-properties, which stays, so those seven need an edit and not a delete. The pair in shared/views/Tabs.vue at lines 30 and 107 can go.
• Those nine comments must change in the same commit as the version bump. The rule is live in 0.18.0, so the comments still do work until the bump lands.
• Two files use /* eslint-env jest */. Flat configuration ignores it and ESLint 10 fails on it. Both must use /* global jest */.
• The scripts lint-frontend:watch and lint-frontend:watch:format pass --monitor. No version of the command line tool accepts that flag, so both scripts should be removed.
• The 45 import-x, n, and core problems that autofix leaves behind must be fixed by hand. They are the evidence that the resolver settings work.
• Every rule whose output autofix cannot clear must be turned off, each with a comment that names the follow-up issue: all jsdoc rules, kolibri/tests-no-hardcoded-strings, vue/no-restricted-static-attribute, vue/no-bare-strings-in-template, the vuejs-accessibility rules, the two theming rules, and the jest rules that still report after autofix.
• .github/dependabot.yml must exclude kolibri-glob and kolibri-css-variables from cooldown.
• The formatting rewrite must land in the same pull request as the configuration change. It must be a commit of its own, and that commit must go in .git-blame-ignore-revs.

Check these two things before writing any code:

1. Make sure that pnpm links the Kolibri Design System into kolibri-css-variables. That package declares kolibri-design-system as an optional peer dependency and reads theme names from it. The Kolibri Design System is not in the hoisted node_modules/.pnpm/node_modules/. If the link is missing, each theming rule reports This rule cannot check theme names once per file and finds nothing. If the link is missing, add kolibri-css-variables as a direct development dependency.
2. Read the autofix output for the four files that raise ESLintCircularFixesWarning. Two fixers disagree in each one. The files are shared/composables/useChannelVersionHistory.js, shared/composables/useSpecialPermissions.js, shared/views/SidePanelModal/index.vue, and shared/vuex/draggablePlugin/module/getters.js.

Out of Scope

• The two theming rules.
• kolibri/tests-no-hardcoded-strings at 606 problems, vue/no-restricted-static-attribute at 261, vue/no-bare-strings-in-template at 161, vuejs-accessibility at 51, and the jsdoc rules. Autofix for jsdoc/require-param inserts @param stubs. Those stubs raise jsdoc/require-param-description from 359 to 551. Leave the jsdoc block off until enabled it rule by rule.
• kolibri/vue-no-rtl-breaking-inline-styles, which kolibri-format does not enable.
• Changes to how the application behaves. If a rule cannot be satisfied by autofix or a small edit, turn it off and record it.

Acceptance Criteria

General

• package.json lists kolibri-format at 3.0.1.
• .eslintrc.js is gone and eslint.config.mjs holds every setting it carried.
• pnpm install runs under pnpm, and kolibri-css-variables resolves kolibri-design-system.
• The two theming rules report real violations when switched on by hand, and not This rule cannot check theme names.
• import-x/no-unresolved and import-x/order each report 0 across the frontend.
• No lint dependency in package.json conflicts with ESLint 9.
• eslint-import-resolver-webpack and the stylelint-config-* packages are still listed.
• No /* eslint-env */ comment is left in the frontend.
• No disable comment names an import/* rule or kolibri/vue-no-unused-methods.
• The seven comments that also name vue/no-unused-properties still name it.
• Every rule turned off in eslint.config.mjs carries a comment that names the follow-up issue.
• The formatting rewrite is a separate commit and its hash is in .git-blame-ignore-revs.
• .github/dependabot.yml excludes kolibri-glob and kolibri-css-variables from cooldown.
• package.json no longer contains lint-frontend:watch or lint-frontend:watch:format.

Testing

• pre-commit run --all-files passes from a clean tree.
• A second pre-commit run --all-files changes no file.
• pnpm test passes.
• pnpm run build succeeds.
• ESLintCircularFixesWarning no longer appears, and the four files it named are correct.

Testing

pnpm install
pnpm run lint-frontend
pre-commit run --all-files
pnpm test
pnpm run build

Run pnpm install with pnpm and not with npm. The link between kolibri-css-variables and the Kolibri Design System is what the install is checking.

To confirm that link, turn the two theming rules on for one run. They must report about 155 and 58 problems. If there is a cannot check theme names error per file means the link is missing.

References

• .github/workflows/pre-commit.yml runs the lint job across all files.
• .pre-commit-config.yaml holds the frontend-lint hook that writes fixes.
• .git-blame-ignore-revs already lists two formatting commits.
• CI runs Node 20.x, which meets the new engine requirement. Local machines on Node 18 need an upgrade.

AI usage

I ran the kolibri-format 3.0.1 toolchain against Studio's frontend from a scratch install to produce the counts in this issue, with the repo working tree untouched. I used Claude Code to draft the issue from those results. I checked its claims about the CI lint job, the nine vue-no-unused-methods comments, and the resolver counts against the repository myself.