Skip to content

A local-first personal finance app

[AI] Add enforce-boundaries ESLint rule for architectural boundaries (#7467)

Matiss Janis Aboltins3c77b3d0d587
diff --git a/.oxlintrc.json b/.oxlintrc.json
index eb07b4dca9..20ad0812cd 100644
--- a/.oxlintrc.json
+++ b/.oxlintrc.json
@@ -37,6 +37,7 @@
"actual/no-anchor-tag": "error",
"actual/no-react-default-import": "error",
"actual/prefer-subpath-imports": "error",
+ "actual/enforce-boundaries": "error",
"actual/no-extraneous-dependencies": "error",
// JSX A11y rules
@@ -372,6 +373,12 @@
"actual/prefer-logger-over-console": "off"
}
},
+ {
+ "files": ["packages/eslint-plugin-actual/lib/rules/__tests__/**/*"],
+ "rules": {
+ "actual/enforce-boundaries": "off"
+ }
+ },
{
"files": [
"packages/api/migrations/*",
diff --git a/packages/component-library/.storybook/preview.tsx b/packages/component-library/.storybook/preview.tsx
index 61bf13af28..f3cb369460 100644
--- a/packages/component-library/.storybook/preview.tsx
+++ b/packages/component-library/.storybook/preview.tsx
@@ -4,8 +4,11 @@ import type { Preview } from '@storybook/react-vite';
// Not ideal to import from desktop-client, but we need a source of truth for theme variables
// TODO: this needs refactoring
+// oxlint-disable-next-line actual/enforce-boundaries
import * as darkTheme from '../../desktop-client/src/style/themes/dark';
+// oxlint-disable-next-line actual/enforce-boundaries
import * as lightTheme from '../../desktop-client/src/style/themes/light';
+// oxlint-disable-next-line actual/enforce-boundaries
import * as midnightTheme from '../../desktop-client/src/style/themes/midnight';
const THEMES = {
diff --git a/packages/desktop-client/package.json b/packages/desktop-client/package.json
index c9872ae3fb..3bf1087e93 100644
--- a/packages/desktop-client/package.json
+++ b/packages/desktop-client/package.json
@@ -30,6 +30,7 @@
"#gocardless": "./src/gocardless.ts",
"#i18n": "./src/i18n.ts",
"#mocks": "./src/mocks.tsx",
+ "#mocks/*": "./src/mocks/*.ts",
"#polyfills": "./src/polyfills.ts",
"#components/forms": "./src/components/forms/index.tsx",
"#components/banksync": "./src/components/banksync/index.tsx",
diff --git a/packages/desktop-client/src/components/reports/reports/Formula.tsx b/packages/desktop-client/src/components/reports/reports/Formula.tsx
index f770d54089..8483304e52 100644
--- a/packages/desktop-client/src/components/reports/reports/Formula.tsx
+++ b/packages/desktop-client/src/components/reports/reports/Formula.tsx
@@ -27,7 +27,7 @@ import { useDispatch } from '#redux';
import { useUpdateDashboardWidgetMutation } from '#reports/mutations';
const FormulaEditor = lazy(() =>
- import('../../formula/FormulaEditor').then(module => ({
+ import('#components/formula/FormulaEditor').then(module => ({
default: module.FormulaEditor,
})),
);
diff --git a/packages/desktop-client/src/components/transactions/TransactionsTable.test.tsx b/packages/desktop-client/src/components/transactions/TransactionsTable.test.tsx
index 7da77ab0f1..28df62f75a 100644
--- a/packages/desktop-client/src/components/transactions/TransactionsTable.test.tsx
+++ b/packages/desktop-client/src/components/transactions/TransactionsTable.test.tsx
@@ -38,7 +38,7 @@ const queryClient = createTestQueryClient();
vi.mock(
'@actual-app/core/platform/client/connection',
- () => import('../../mocks/connection'),
+ () => import('#mocks/connection'),
);
vi.mock('../../hooks/useSyncedPref', () => ({
useSyncedPref: vi.fn().mockReturnValue([undefined, vi.fn()]),
diff --git a/packages/eslint-plugin-actual/lib/index.js b/packages/eslint-plugin-actual/lib/index.js
index edccaac142..9a187798b5 100644
--- a/packages/eslint-plugin-actual/lib/index.js
+++ b/packages/eslint-plugin-actual/lib/index.js
@@ -15,6 +15,7 @@ module.exports = eslintCompatPlugin({
'no-anchor-tag': require('./rules/no-anchor-tag'),
'no-react-default-import': require('./rules/no-react-default-import'),
'prefer-subpath-imports': require('./rules/prefer-subpath-imports'),
+ 'enforce-boundaries': require('./rules/enforce-boundaries'),
'no-extraneous-dependencies': require('./rules/no-extraneous-dependencies'),
},
});
diff --git a/packages/eslint-plugin-actual/lib/rules/__tests__/enforce-boundaries.test.js b/packages/eslint-plugin-actual/lib/rules/__tests__/enforce-boundaries.test.js
new file mode 100644
index 0000000000..a91665703b
--- /dev/null
+++ b/packages/eslint-plugin-actual/lib/rules/__tests__/enforce-boundaries.test.js
@@ -0,0 +1,183 @@
+//------------------------------------------------------------------------------
+// Requirements
+//------------------------------------------------------------------------------
+
+import { runClassic } from 'eslint-vitest-rule-tester';
+
+import * as rule from '../enforce-boundaries';
+
+//------------------------------------------------------------------------------
+// Tests
+//------------------------------------------------------------------------------
+
+void runClassic(
+ 'enforce-boundaries',
+ rule,
+ {
+ valid: [
+ // ── Imports that are fine ───────────────────────────────────
+ `import foo from './sibling'`,
+ `import foo from '../nearby'`,
+ `import foo from '#components/Button'`,
+ `import foo from '@actual-app/components'`,
+ `import foo from 'react'`,
+
+ // require with acceptable paths
+ `const foo = require('./local')`,
+ `const foo = require('../nearby')`,
+ `const foo = require('some-package')`,
+
+ // Dynamic import with acceptable path
+ `const mod = import('./local')`,
+
+ // re-exports with acceptable paths
+ `export { bar } from './sibling'`,
+ `export * from '../nearby'`,
+
+ // Config objects without forbidden properties
+ `const config = { compilerOptions: { strict: true } }`,
+ `const config = { resolve: { conditions: ['module'] } }`,
+
+ // Export without source clause
+ `const foo = 1; export { foo }`,
+
+ // Non-literal require/import arguments
+ `const foo = require(variable)`,
+ `const mod = import(variable)`,
+
+ // Properties named paths/alias but NOT in forbidden context
+ `const config = { paths: { foo: 'bar' } }`,
+ `const config = { alias: { foo: 'bar' } }`,
+ `const config = { options: { paths: ['/usr/bin'] } }`,
+ `const config = { other: { alias: 'something' } }`,
+ ],
+
+ invalid: [
+ // ── Backtracked imports ─────────────────────────────────────
+ {
+ code: `import foo from '../../deep/path'`,
+ output: null,
+ errors: [
+ {
+ messageId: 'noBacktrackedImport',
+ data: { source: '../../deep/path' },
+ },
+ ],
+ },
+ {
+ code: `import bar from '../../../even/deeper'`,
+ output: null,
+ errors: [
+ {
+ messageId: 'noBacktrackedImport',
+ data: { source: '../../../even/deeper' },
+ },
+ ],
+ },
+
+ // Backtracked re-exports
+ {
+ code: `export { bar } from '../../somewhere'`,
+ output: null,
+ errors: [
+ {
+ messageId: 'noBacktrackedImport',
+ data: { source: '../../somewhere' },
+ },
+ ],
+ },
+ {
+ code: `export * from '../../somewhere'`,
+ output: null,
+ errors: [
+ {
+ messageId: 'noBacktrackedImport',
+ data: { source: '../../somewhere' },
+ },
+ ],
+ },
+
+ // Backtracked require
+ {
+ code: `const x = require('../../deep')`,
+ output: null,
+ errors: [
+ {
+ messageId: 'noBacktrackedImport',
+ data: { source: '../../deep' },
+ },
+ ],
+ },
+
+ // Backtracked dynamic import
+ {
+ code: `const mod = import('../../deep')`,
+ output: null,
+ errors: [
+ {
+ messageId: 'noBacktrackedImport',
+ data: { source: '../../deep' },
+ },
+ ],
+ },
+
+ // ── tsconfig compilerOptions.paths ──────────────────────────
+ {
+ code: `const config = { compilerOptions: { paths: { "@/*": ["./src/*"] } } }`,
+ output: null,
+ errors: [{ messageId: 'noTsconfigPaths' }],
+ },
+ {
+ code: `module.exports = { compilerOptions: { paths: { "~/*": ["./src/*"] } } }`,
+ output: null,
+ errors: [{ messageId: 'noTsconfigPaths' }],
+ },
+
+ // ── Vite resolve.alias ──────────────────────────────────────
+ {
+ code: `const config = { resolve: { alias: { "@": "./src" } } }`,
+ output: null,
+ errors: [{ messageId: 'noResolveAlias' }],
+ },
+ {
+ code: `export default { resolve: { alias: { "~": "/src" } } }`,
+ output: null,
+ errors: [{ messageId: 'noResolveAlias' }],
+ },
+
+ // ── String-keyed config properties ─────────────────────────
+ {
+ code: `const config = { "compilerOptions": { "paths": { "@/*": ["./src/*"] } } }`,
+ output: null,
+ errors: [{ messageId: 'noTsconfigPaths' }],
+ },
+ {
+ code: `const config = { "resolve": { "alias": { "@": "./src" } } }`,
+ output: null,
+ errors: [{ messageId: 'noResolveAlias' }],
+ },
+
+ // ── Multiple violations in one file ─────────────────────────
+ {
+ code: `import a from '../../foo';\nimport b from '../../bar';`,
+ output: null,
+ errors: [
+ {
+ messageId: 'noBacktrackedImport',
+ data: { source: '../../foo' },
+ },
+ {
+ messageId: 'noBacktrackedImport',
+ data: { source: '../../bar' },
+ },
+ ],
+ },
+ ],
+ },
+ {
+ parserOptions: {
+ ecmaVersion: 2022,
+ sourceType: 'module',
+ },
+ },
+);
diff --git a/packages/eslint-plugin-actual/lib/rules/enforce-boundaries.js b/packages/eslint-plugin-actual/lib/rules/enforce-boundaries.js
new file mode 100644
index 0000000000..e304f99b08
--- /dev/null
+++ b/packages/eslint-plugin-actual/lib/rules/enforce-boundaries.js
@@ -0,0 +1,106 @@
+/** @type {import('eslint').Rule.RuleModule} */
+module.exports = {
+ meta: {
+ type: 'problem',
+ docs: {
+ description:
+ 'Enforce architectural boundaries: no tsconfig paths, no Vite resolve.alias, no backtracked imports (../../)',
+ },
+ fixable: null,
+ schema: [],
+ messages: {
+ noTsconfigPaths:
+ 'tsconfig "compilerOptions.paths" is not allowed. Use package.json subpath imports (#path) instead.',
+ noResolveAlias:
+ 'Vite "resolve.alias" is not allowed. Use package.json subpath imports (#path) instead.',
+ noBacktrackedImport:
+ 'Backtracked import "{{source}}" is not allowed. Use subpath imports (#path) or package imports instead.',
+ },
+ },
+
+ create(context) {
+ function getPropertyName(node) {
+ if (!node || !node.key) return null;
+ if (node.key.type === 'Identifier') return node.key.name;
+ if (node.key.type === 'Literal') return String(node.key.value);
+ return null;
+ }
+
+ function isBacktrackedImport(source) {
+ return typeof source === 'string' && source.startsWith('../../');
+ }
+
+ function reportBacktrackedImport(node, source) {
+ if (!source || !isBacktrackedImport(source.value)) return;
+ context.report({
+ node: source,
+ messageId: 'noBacktrackedImport',
+ data: { source: source.value },
+ });
+ }
+
+ return {
+ Property(node) {
+ const name = getPropertyName(node);
+ if (name !== 'paths' && name !== 'alias') return;
+
+ const parentObject = node.parent;
+ if (!parentObject || parentObject.type !== 'ObjectExpression') return;
+
+ const grandparent = parentObject.parent;
+ if (!grandparent || grandparent.type !== 'Property') return;
+
+ const grandparentName = getPropertyName(grandparent);
+
+ if (name === 'paths' && grandparentName === 'compilerOptions') {
+ context.report({ node, messageId: 'noTsconfigPaths' });
+ }
+
+ if (name === 'alias' && grandparentName === 'resolve') {
+ context.report({ node, messageId: 'noResolveAlias' });
+ }
+ },
+
+ ImportDeclaration(node) {
+ reportBacktrackedImport(node, node.source);
+ },
+
+ ExportNamedDeclaration(node) {
+ reportBacktrackedImport(node, node.source);
+ },
+
+ ExportAllDeclaration(node) {
+ reportBacktrackedImport(node, node.source);
+ },
+
+ CallExpression(node) {
+ if (
+ node.callee.type === 'Identifier' &&
+ node.callee.name === 'require' &&
+ node.arguments.length > 0 &&
+ node.arguments[0].type === 'Literal' &&
+ isBacktrackedImport(node.arguments[0].value)
+ ) {
+ context.report({
+ node: node.arguments[0],
+ messageId: 'noBacktrackedImport',
+ data: { source: node.arguments[0].value },
+ });
+ }
+ },
+
+ ImportExpression(node) {
+ if (
+ node.source.type === 'Literal' &&
+ isBacktrackedImport(node.source.value)
+ ) {
+ context.report({
+ node: node.source,
+ messageId: 'noBacktrackedImport',
+ data: { source: node.source.value },
+ });
+ }
+ },
+ };
+ },
+};
diff --git a/packages/loot-core/package.json b/packages/loot-core/package.json
index 6b7515fb44..f20005ee4a 100644
--- a/packages/loot-core/package.json
+++ b/packages/loot-core/package.json
@@ -84,6 +84,7 @@
"#shared/*": "./src/shared/*.ts",
"#types/*": "./src/types/*.ts",
"#mocks/*": "./src/mocks/*.ts",
+ "#migrations/*": "./migrations/*.js",
"#*": "./src/*.ts"
},
"exports": {
diff --git a/packages/loot-core/src/server/migrate/migrations.ts b/packages/loot-core/src/server/migrate/migrations.ts
index 81b445cf24..50c6eb8110 100644
--- a/packages/loot-core/src/server/migrate/migrations.ts
+++ b/packages/loot-core/src/server/migrate/migrations.ts
@@ -4,15 +4,15 @@
// we can remove this migration.
import type { Database } from '@jlongster/sql.js';
+import m1632571489012 from '#migrations/1632571489012_remove_cache';
+import m1722717601000 from '#migrations/1722717601000_reports_move_selected_categories';
+import m1722804019000 from '#migrations/1722804019000_create_dashboard_table';
+import m1723665565000 from '#migrations/1723665565000_prefs';
+import m1765518577215 from '#migrations/1765518577215_multiple_dashboards';
import * as fs from '#platform/server/fs';
import { logger } from '#platform/server/log';
import * as sqlite from '#platform/server/sqlite';
import * as prefs from '#server/prefs';
-import m1632571489012 from '../../../migrations/1632571489012_remove_cache';
-import m1722717601000 from '../../../migrations/1722717601000_reports_move_selected_categories';
-import m1722804019000 from '../../../migrations/1722804019000_create_dashboard_table';
-import m1723665565000 from '../../../migrations/1723665565000_prefs';
-import m1765518577215 from '../../../migrations/1765518577215_multiple_dashboards';
let MIGRATIONS_DIR = fs.migrationsPath;
diff --git a/packages/loot-core/vite.desktop.config.mts b/packages/loot-core/vite.desktop.config.mts
index fea833691f..23512b40cc 100644
--- a/packages/loot-core/vite.desktop.config.mts
+++ b/packages/loot-core/vite.desktop.config.mts
@@ -34,6 +34,7 @@ export default defineConfig(({ mode }) => {
},
resolve: {
conditions: ['electron'],
+ // oxlint-disable-next-line actual/enforce-boundaries -- handlebars types only resolve from the root entry; the alias forces the pre-compiled dist bundle at build time
alias: [
{
find: 'handlebars',
diff --git a/upcoming-release-notes/7467.md b/upcoming-release-notes/7467.md
new file mode 100644
index 0000000000..4fb5672e69
--- /dev/null
+++ b/upcoming-release-notes/7467.md
@@ -0,0 +1,6 @@
+---
+category: Maintenance
+authors: [MatissJanis]
+---
+
+Add ESLint rule to enforce architectural boundaries and prevent import violations.