feat: Add ESLint rule enforcing PageShell/PageHeader in feature pages (#1621)

* feat: Add ESLint rule enforcing PageShell/PageHeader in feature pages

Custom ESLint rule that warns when feature page files under
src/features/**/pages/ don't import PageShell and PageHeader from
@/shared. Set to "warn" to avoid blocking other teammates' PRs
while pages are being aligned. Excludes dashboard, economy, cookbook,
mcp-config, tenants, manifests pages per PRD, plus test files,
dialogs, tab components, and .ts utility files.

* fix: Address CodeRabbit review feedback on ESLint rule

- Normalize filename separators for Windows compatibility
- Remove overly broad 'component' substring exclusion
- Support relative imports (../page-header, ../../page-shell) for
  nested page files
- Add test case for nested relative imports

* fix: Tighten ESLint rule exclusion patterns and import matching

- Anchor dialog exclusion to file-name pattern (*-dialog.tsx) instead
  of broad substring match
- Anchor excluded features to /features/<name>/pages/ path pattern
- Require @/shared boundary (exact or prefix) instead of substring
- Require relative prefix in page-header/page-shell import regexes

* test: Add Windows path normalization test case

---------

Co-authored-by: Ben Coombs <bjcoombs@users.noreply.github.com>

Author: bjcoombs

frontend/eslint-rules/require-page-structure.cjs

@@ -0,0 +1,73 @@
+module.exports = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Enforce PageShell and PageHeader usage in feature pages',
+    },
+    schema: [],
+  },
+  create(context) {
+    const filename = (context.filename || context.getFilename()).replace(/\\/g, '/')
+    // Only apply to feature page files
+    if (!filename.includes('/features/') || !filename.includes('/pages/')) {
+      return {}
+    }
+    // Only apply to .tsx files (skip .ts utility/types files)
+    if (!filename.endsWith('.tsx')) {
+      return {}
+    }
+    // Skip test files, dialog files, and tab components
+    const isDialogFile =
+      /(?:^|\/)[^/]*-dialog\.tsx$/.test(filename) || /\/dialogs?\//.test(filename)
+    if (
+      filename.includes('.test.') ||
+      filename.includes('.spec.') ||
+      isDialogFile ||
+      filename.includes('/tabs/')
+    ) {
+      return {}
+    }
+    // Skip hub/dashboard pages (excluded from alignment per PRD)
+    if (
+      /\/features\/(?:dashboard|economy|cookbook|mcp-config|tenants|manifests)\/pages\//.test(
+        filename,
+      )
+    ) {
+      return {}
+    }
+
+    let hasPageShell = false
+    let hasPageHeader = false
+
+    return {
+      ImportDeclaration(node) {
+        const source = node.source.value
+        const isPageImport =
+          source === '@/shared' ||
+          source.startsWith('@/shared/') ||
+          /^(?:\.\/|\.\.\/)+page-header$/.test(source) ||
+          /^(?:\.\/|\.\.\/)+page-shell$/.test(source)
+        if (isPageImport) {
+          node.specifiers.forEach((spec) => {
+            if (spec.imported && spec.imported.name === 'PageShell') hasPageShell = true
+            if (spec.imported && spec.imported.name === 'PageHeader') hasPageHeader = true
+          })
+        }
+      },
+      'Program:exit'() {
+        if (!hasPageShell) {
+          context.report({
+            loc: { line: 1, column: 0 },
+            message: 'Feature pages must import PageShell from @/shared',
+          })
+        }
+        if (!hasPageHeader) {
+          context.report({
+            loc: { line: 1, column: 0 },
+            message: 'Feature pages must import PageHeader from @/shared',
+          })
+        }
+      },
+    }
+  },
+}

frontend/eslint-rules/require-page-structure.test.cjs

@@ -0,0 +1,113 @@
+const { RuleTester } = require('eslint')
+const rule = require('./require-page-structure.cjs')
+
+const ruleTester = new RuleTester({
+  languageOptions: {
+    ecmaVersion: 2022,
+    sourceType: 'module',
+  },
+})
+
+ruleTester.run('require-page-structure', rule, {
+  valid: [
+    {
+      code: `
+        import { PageShell } from '@/shared/page-shell'
+        import { PageHeader } from '@/shared/page-header'
+        export default function AccountsPage() { return null }
+      `,
+      filename: '/app/src/features/accounts/pages/index.tsx',
+    },
+    {
+      code: `
+        import { PageShell, PageHeader } from '@/shared'
+        export default function AccountsPage() { return null }
+      `,
+      filename: '/app/src/features/accounts/pages/index.tsx',
+    },
+    {
+      // Windows path normalization
+      code: `
+        import { PageShell } from '@/shared/page-shell'
+        import { PageHeader } from '@/shared/page-header'
+        export default function AccountsPage() { return null }
+      `,
+      filename: 'C:\\app\\src\\features\\accounts\\pages\\index.tsx',
+    },
+    {
+      // Non-feature file should be ignored
+      code: `export default function App() { return null }`,
+      filename: '/app/src/components/App.tsx',
+    },
+    {
+      // Dashboard page is excluded
+      code: `export default function Dashboard() { return null }`,
+      filename: '/app/src/features/dashboard/pages/index.tsx',
+    },
+    {
+      // Test file is excluded
+      code: `import { render } from '@testing-library/react'`,
+      filename: '/app/src/features/accounts/pages/index.test.tsx',
+    },
+    {
+      // Dialog file is excluded
+      code: `export function CreateDialog() { return null }`,
+      filename: '/app/src/features/accounts/pages/create-dialog.tsx',
+    },
+    {
+      // Nested page importing via relative path
+      code: `
+        import { PageShell } from '../../page-shell'
+        import { PageHeader } from '../../page-header'
+        export default function NodePage() { return null }
+      `,
+      filename: '/app/src/features/reference-data/pages/nodes/index.tsx',
+    },
+    {
+      // Economy page is excluded
+      code: `export default function EconomyPage() { return null }`,
+      filename: '/app/src/features/economy/pages/economy-overview-page.tsx',
+    },
+    {
+      // .ts utility files are excluded
+      code: `export const COLUMNS = ['name', 'status']`,
+      filename: '/app/src/features/accounts/pages/types.ts',
+    },
+    {
+      // Tab component files are excluded
+      code: `export function OverviewTab() { return null }`,
+      filename: '/app/src/features/parties/pages/tabs/overview-tab.tsx',
+    },
+  ],
+  invalid: [
+    {
+      code: `
+        import { DataTable } from '@/shared/data-table'
+        export default function AccountsPage() { return null }
+      `,
+      filename: '/app/src/features/accounts/pages/index.tsx',
+      errors: [
+        { message: 'Feature pages must import PageShell from @/shared' },
+        { message: 'Feature pages must import PageHeader from @/shared' },
+      ],
+    },
+    {
+      code: `
+        import { PageShell } from '@/shared/page-shell'
+        export default function AccountsPage() { return null }
+      `,
+      filename: '/app/src/features/accounts/pages/index.tsx',
+      errors: [{ message: 'Feature pages must import PageHeader from @/shared' }],
+    },
+    {
+      code: `
+        import { PageHeader } from '@/shared/page-header'
+        export default function AccountsPage() { return null }
+      `,
+      filename: '/app/src/features/accounts/pages/index.tsx',
+      errors: [{ message: 'Feature pages must import PageShell from @/shared' }],
+    },
+  ],
+})
+
+console.log('All tests passed!')

frontend/eslint.config.js

@@ -5,6 +5,9 @@ import reactRefresh from 'eslint-plugin-react-refresh'
 import tseslint from 'typescript-eslint'
 import { defineConfig, globalIgnores } from 'eslint/config'
 import prettier from 'eslint-config-prettier'
+import { createRequire } from 'module'
+const require = createRequire(import.meta.url)
+const requirePageStructure = require('./eslint-rules/require-page-structure.cjs')
 
 export default defineConfig([
   globalIgnores(['dist', 'src/api/gen']),
@@ -34,4 +37,18 @@ export default defineConfig([
       'react-refresh/only-export-components': 'off',
     },
   },
+  // Enforce PageShell and PageHeader usage in feature pages
+  {
+    files: ['src/features/**/pages/**/*.{ts,tsx}'],
+    plugins: {
+      meridian: {
+        rules: {
+          'require-page-structure': requirePageStructure,
+        },
+      },
+    },
+    rules: {
+      'meridian/require-page-structure': 'warn',
+    },
+  },
 ])