feat(lint): enforce definePage layout meta on pages-v2

Adds a custom ESLint rule (local-rules/require-v2-layout-meta) that
fails any src/pages-v2/**.vue page missing
definePage({ meta: { layout: 'OrganizerLayoutV2' } }) (or PortalLayoutV2
under pages-v2/portal), preventing a silent wrong-shell fallback to the
default layout (RFC-WS-GUI-REDESIGN AD-G2). Wires eslint-plugin-local-rules
+ a pages-v2 override. The RuleTester spec is called at top level (ESLint
RuleTester self-manages describe/it under Vitest) and vitest.config.ts
gains the eslint-rules test glob so the spec is discovered.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

apps/app/.eslintrc.cjs

@@ -33,6 +33,7 @@ module.exports = {
     'regex',
     'regexp',
     'boundaries',
+    'local-rules',
   ],
   ignorePatterns: [
     'src/plugins/iconify/*.js',
@@ -328,6 +329,12 @@ module.exports = {
     'boundaries/include': ['src/**/*.{ts,vue,tsx}'],
   },
   overrides: [
+    {
+      files: ['src/pages-v2/**/*.vue'],
+      rules: {
+        'local-rules/require-v2-layout-meta': 'error',
+      },
+    },
     // Vue SFCs: the base lines-around-comment rule conflicts with
     // vue/block-tag-newline at the <script setup>/comment boundary
     // (the <script> tag isn't a JS block-start so allowBlockStart

apps/app/eslint-local-rules.cjs

@@ -0,0 +1,5 @@
+'use strict'
+
+module.exports = {
+  'require-v2-layout-meta': require('./eslint-rules/require-v2-layout-meta.cjs'),
+}

apps/app/eslint-rules/__tests__/require-v2-layout-meta.spec.ts

@@ -0,0 +1,43 @@
+import { createRequire } from 'node:module'
+import { RuleTester } from 'eslint'
+
+// Project is ESLint 8.57 — RuleTester uses the legacy `parser` +
+// `parserOptions` shape (NOT ESLint-9 `languageOptions`). createRequire
+// gives us a CJS `require` inside this ESM test for the .cjs rule + the
+// parser path.
+//
+// RuleTester.run internally calls describe/it itself — do NOT wrap it in
+// an `it()` block; call it directly inside (or at the top level of) the
+// describe so Vitest does not see a describe-inside-it violation.
+const require = createRequire(import.meta.url)
+const rule = require('../require-v2-layout-meta.cjs')
+
+const ruleTester = new RuleTester({
+  parser: require.resolve('vue-eslint-parser'),
+  parserOptions: { ecmaVersion: 2022, sourceType: 'module' },
+})
+
+ruleTester.run('require-v2-layout-meta', rule, {
+  valid: [
+    {
+      filename: 'src/pages-v2/dashboard.vue',
+      code: '<script setup lang="ts">definePage({ meta: { layout: \'OrganizerLayoutV2\' } })</script><template><div/></template>',
+    },
+    {
+      filename: 'src/pages/dashboard.vue',
+      code: '<script setup lang="ts">const x = 1</script><template><div/></template>',
+    },
+  ],
+  invalid: [
+    {
+      filename: 'src/pages-v2/dashboard.vue',
+      code: '<script setup lang="ts">const x = 1</script><template><div/></template>',
+      errors: [{ messageId: 'missing' }],
+    },
+    {
+      filename: 'src/pages-v2/events/index.vue',
+      code: '<script setup lang="ts">definePage({ meta: { layout: \'default\' } })</script><template><div/></template>',
+      errors: [{ messageId: 'wrongLayout' }],
+    },
+  ],
+})

apps/app/eslint-rules/require-v2-layout-meta.cjs

@@ -0,0 +1,59 @@
+/**
+ * Enforces that every src/pages-v2/**.vue page declares
+ *   definePage({ meta: { layout: 'OrganizerLayoutV2' } })
+ * (or 'PortalLayoutV2' for src/pages-v2/portal/**). Without this a v2
+ * page silently falls back to the `default` layout — a no-error
+ * wrong-shell bug. RFC-WS-GUI-REDESIGN AD-G2.
+ */
+'use strict'
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: { description: 'require definePage layout meta on pages-v2' },
+    messages: {
+      missing: 'pages-v2 page must call definePage({ meta: { layout: ... } }).',
+      wrongLayout: 'pages-v2 layout must be {{expected}} (got {{actual}}).',
+    },
+    schema: [],
+  },
+  create(context) {
+    const filename = (context.filename || context.getFilename() || '').replace(/\\/g, '/')
+    if (!filename.includes('src/pages-v2/'))
+      return {}
+
+    const expected = filename.includes('src/pages-v2/portal/')
+      ? 'PortalLayoutV2'
+      : 'OrganizerLayoutV2'
+
+    let sawDefinePage = false
+
+    return {
+      CallExpression(node) {
+        if (node.callee.type !== 'Identifier' || node.callee.name !== 'definePage')
+          return
+        sawDefinePage = true
+
+        const arg = node.arguments[0]
+        const metaProp = arg && arg.type === 'ObjectExpression'
+          ? arg.properties.find(p => p.key && p.key.name === 'meta')
+          : null
+        const layoutProp = metaProp && metaProp.value.type === 'ObjectExpression'
+          ? metaProp.value.properties.find(p => p.key && p.key.name === 'layout')
+          : null
+
+        if (!layoutProp || layoutProp.value.value !== expected) {
+          context.report({
+            node,
+            messageId: 'wrongLayout',
+            data: { expected, actual: layoutProp ? String(layoutProp.value.value) : 'none' },
+          })
+        }
+      },
+      'Program:exit': function (node) {
+        if (!sawDefinePage)
+          context.report({ node, messageId: 'missing' })
+      },
+    }
+  },
+}

apps/app/package.json

@@ -138,6 +138,7 @@
     "eslint-plugin-jest": "27.9.0",
     "eslint-plugin-jsdoc": "46.10.1",
     "eslint-plugin-jsonc": "2.21.0",
+    "eslint-plugin-local-rules": "3.0.2",
     "eslint-plugin-markdown": "3.0.1",
     "eslint-plugin-n": "16.6.2",
     "eslint-plugin-no-only-tests": "3.3.0",

apps/app/pnpm-lock.yaml

@@ -352,6 +352,9 @@ importers:
       eslint-plugin-jsonc:
         specifier: 2.21.0
         version: 2.21.0(eslint@8.57.1)
+      eslint-plugin-local-rules:
+        specifier: 3.0.2
+        version: 3.0.2
       eslint-plugin-markdown:
         specifier: 3.0.1
         version: 3.0.1(eslint@8.57.1)
@@ -3623,6 +3626,9 @@ packages:
     peerDependencies:
       eslint: '>=6.0.0'
 
+  eslint-plugin-local-rules@3.0.2:
+    resolution: {integrity: sha512-IWME7GIYHXogTkFsToLdBCQVJ0U4kbSuVyDT+nKoR4UgtnVrrVeNWuAZkdEu1nxkvi9nsPccGehEEF6dgA28IQ==}
+
   eslint-plugin-markdown@3.0.1:
     resolution: {integrity: sha512-8rqoc148DWdGdmYF6WSQFT3uQ6PO7zXYgeBpHAOAakX/zpq+NvFYbDA/H7PYzHajwtmaOzAwfxyl++x0g1/N9A==}
     engines: {node: ^12.22.0 || ^14.17.0 || >=16.0.0}
@@ -10061,6 +10067,8 @@ snapshots:
     transitivePeerDependencies:
       - '@eslint/json'
 
+  eslint-plugin-local-rules@3.0.2: {}
+
   eslint-plugin-markdown@3.0.1(eslint@8.57.1):
     dependencies:
       eslint: 8.57.1

apps/app/vitest.config.ts

@@ -43,6 +43,7 @@ export default defineConfig({
             'tests/unit/**/*.{test,spec}.ts',
             'tests/*.{test,spec}.ts',
             'src/**/__tests__/**/*.{test,spec}.ts',
+            'eslint-rules/**/__tests__/**/*.{test,spec}.ts',
           ],
           setupFiles: ['./tests/setup.ts'],
         },