@mettlecast/eslint-plugin-domain-module 0.2.22 → 0.2.23

package/dist/__tests__/api-needs-fixture.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/api-needs-fixture.test.js

@@ -0,0 +1,61 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import { existsSync } from 'node:fs';
+import { afterAll, afterEach, beforeEach, describe, it, vi } from 'vitest';
+import { apiNeedsFixture } from '../rules/api-needs-fixture.js';
+vi.mock('node:fs', async (importOriginal) => {
+    const actual = await importOriginal();
+    return {
+        ...actual,
+        existsSync: vi.fn(actual.existsSync),
+    };
+});
+RuleTester.afterAll = afterAll;
+RuleTester.describe = describe;
+RuleTester.it = it;
+const existsSyncMock = vi.mocked(existsSync);
+const FIXTURE_DIRS_WITH_FIXTURE = new Set([
+    '/repo/domains/auth/api/__tests__/get-user.fixture.json',
+]);
+const FIXTURE_DIRS_WITHOUT_FIXTURE = new Set([
+    '/repo/domains/payments/api/__tests__/charge-card.fixture.json',
+]);
+beforeEach(() => {
+    existsSyncMock.mockReset();
+    existsSyncMock.mockImplementation((p) => {
+        const s = String(p);
+        if (FIXTURE_DIRS_WITH_FIXTURE.has(s))
+            return true;
+        if (FIXTURE_DIRS_WITHOUT_FIXTURE.has(s))
+            return false;
+        return false;
+    });
+});
+afterEach(() => {
+    existsSyncMock.mockReset();
+});
+const tester = new RuleTester({
+    languageOptions: { ecmaVersion: 2022, sourceType: 'module' },
+});
+tester.run('api-needs-fixture', apiNeedsFixture, {
+    valid: [
+        {
+            filename: '/repo/domains/auth/api/get-user.ts',
+            code: "import { defineApi } from '@mettlecast/domain-runtime'; export const getUser = defineApi({ id: 'get-user', path: '/v1/users/{id}', method: 'GET', tenancy: 'required', versions: { v1: { status: 'stable', input: z.object({}), output: z.object({}), handler: async () => ({}) } } });",
+        },
+        {
+            filename: '/repo/domains/auth/domain.config.ts',
+            code: "export const config = { id: 'auth', name: 'Auth' };",
+        },
+        {
+            filename: '/repo/domains/auth/api/utils.ts',
+            code: "export function helper() { return 1; }",
+        },
+    ],
+    invalid: [
+        {
+            filename: '/repo/domains/payments/api/charge-card.ts',
+            code: "import { defineApi } from '@mettlecast/domain-runtime'; export const chargeCard = defineApi({ id: 'charge-card', path: '/v1/charge', method: 'POST', tenancy: 'required', versions: { v1: { status: 'stable', input: z.object({}), output: z.object({}), handler: async () => ({}) } } });",
+            errors: [{ messageId: 'apiNeedsFixture' }],
+        },
+    ],
+});

package/dist/__tests__/no-raw-fetch.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/no-raw-fetch.test.js

@@ -0,0 +1,37 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import { afterAll, describe, it } from 'vitest';
+import { noRawFetch } from '../rules/no-raw-fetch.js';
+RuleTester.afterAll = afterAll;
+RuleTester.describe = describe;
+RuleTester.it = it;
+const tester = new RuleTester({
+    languageOptions: { ecmaVersion: 2022, sourceType: 'module' },
+});
+tester.run('no-raw-fetch', noRawFetch, {
+    valid: [
+        {
+            filename: '/repo/domains/auth/api/get-user.ts',
+            code: "export const get = defineApi({ handler: async (input, ctx) => { return await ctx.fetch('https://example.com'); } });",
+        },
+        {
+            filename: '/repo/domains/auth/api/get-user.ts',
+            code: "import ky from 'ky'; const r = await ky.get('https://example.com');",
+        },
+        {
+            filename: '/repo/domains/auth/api/get-user.ts',
+            code: "const r = await globalThis.fetch('https://example.com');",
+        },
+    ],
+    invalid: [
+        {
+            filename: '/repo/domains/auth/api/get-user.ts',
+            code: "const r = await fetch('https://example.com');",
+            errors: [{ messageId: 'noRawFetch' }],
+        },
+        {
+            filename: '/repo/domains/payments/api/charge.ts',
+            code: "fetch('https://api.stripe.com/v1/charges', { method: 'POST' });",
+            errors: [{ messageId: 'noRawFetch' }],
+        },
+    ],
+});

package/dist/__tests__/prefer-result-over-throw.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/prefer-result-over-throw.test.js

@@ -0,0 +1,79 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import { afterAll, describe, it } from 'vitest';
+import { preferResultOverThrow } from '../rules/prefer-result-over-throw.js';
+RuleTester.afterAll = afterAll;
+RuleTester.describe = describe;
+RuleTester.it = it;
+const ruleTester = new RuleTester({
+    languageOptions: { ecmaVersion: 2022, sourceType: 'module' },
+});
+ruleTester.run('prefer-result-over-throw', preferResultOverThrow, {
+    valid: [
+        {
+            filename: 'domains/auth/api/me.ts',
+            code: `
+import { ok, err } from '@mettlecast/domain-runtime';
+export const me = defineApi({
+  handler: async (_input, _ctx) => {
+    return ok({ id: 'usr_1' });
+  },
+});`,
+        },
+        {
+            filename: 'domains/auth/api/me.ts',
+            code: `
+import { redirect } from '@tanstack/react-router';
+// TSR redirect is not a domain error — it's a navigation directive
+throw redirect({ to: '/dashboard' });`,
+        },
+        {
+            filename: 'packages/domain-cli/src/commands/upgrade.ts',
+            code: `throw new Error('Upgrade failed');`,
+        },
+        {
+            filename: 'domains/auth/api/me.ts',
+            code: `
+import { ok, err, notFound } from '@mettlecast/domain-runtime';
+export const me = defineApi({
+  handler: async (_input, _ctx) => {
+    const user = await ctx.db.query(...);
+    if (!user) return notFound('user', input.userId);
+    return ok(user);
+  },
+});`,
+        },
+    ],
+    invalid: [
+        {
+            filename: 'domains/auth/api/me.ts',
+            code: `
+export const me = defineApi({
+  handler: async () => {
+    throw new Error('User not found');
+  },
+});`,
+            errors: [{ messageId: 'preferResult' }],
+        },
+        {
+            filename: 'domains/orgs/api/list-orgs.ts',
+            code: `
+export const listOrgs = defineApi({
+  handler: async (_input, _ctx) => {
+    if (!ctx.tenant) throw new Error('Missing tenant');
+    return { items: [] };
+  },
+});`,
+            errors: [{ messageId: 'preferResult' }],
+        },
+        {
+            filename: 'domains/tenants/api/create-tenant.ts',
+            code: `
+export const createTenant = defineApi({
+  handler: async () => {
+    throw { kind: 'not_found' }; // raw object throw — no stack trace
+  },
+});`,
+            errors: [{ messageId: 'preferResult' }],
+        },
+    ],
+});

package/dist/__tests__/tanstack-query-options.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/tanstack-query-options.test.js

@@ -0,0 +1,29 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import { afterAll, describe, it } from 'vitest';
+import { tanstackQueryOptions } from '../rules/tanstack-query-options.js';
+RuleTester.afterAll = afterAll;
+RuleTester.describe = describe;
+RuleTester.it = it;
+const tester = new RuleTester({
+    languageOptions: { ecmaVersion: 2022, sourceType: 'module' },
+});
+tester.run('tanstack-query-options', tanstackQueryOptions, {
+    valid: [
+        {
+            code: "import { useQuery, queryOptions } from '@tanstack/react-query'; const opts = queryOptions({ queryKey: ['agents'], queryFn: fetchAgents }); useQuery(opts);",
+        },
+        {
+            code: "useQuery(agentListOptions);",
+        },
+    ],
+    invalid: [
+        {
+            code: "useQuery({ queryKey: ['agents'], queryFn: fetchAgents });",
+            errors: [{ messageId: 'tanstackQueryOptions' }],
+        },
+        {
+            code: "const x = useQuery({ queryKey: ['x'], queryFn: () => fetchX() });",
+            errors: [{ messageId: 'tanstackQueryOptions' }],
+        },
+    ],
+});

package/dist/__tests__/use-tanstack-router.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/use-tanstack-router.test.js

@@ -0,0 +1,37 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import { afterAll, describe, it } from 'vitest';
+import { useTanstackRouter } from '../rules/use-tanstack-router.js';
+RuleTester.afterAll = afterAll;
+RuleTester.describe = describe;
+RuleTester.it = it;
+const tester = new RuleTester({
+    languageOptions: { ecmaVersion: 2022, sourceType: 'module' },
+});
+tester.run('use-tanstack-router', useTanstackRouter, {
+    valid: [
+        {
+            filename: '/repo/frontend/src/main.tsx',
+            code: "import { createRouter, RouterProvider } from '@tanstack/react-router';",
+        },
+        {
+            filename: '/repo/frontend/src/pages/Agents.tsx',
+            code: "import { useNavigate } from '@tanstack/react-router';",
+        },
+        {
+            filename: '/repo/scaffold-src/modules/shared/lib/legacy-helper.ts',
+            code: "import { HashRouter } from 'react-router-dom';",
+        },
+    ],
+    invalid: [
+        {
+            filename: '/repo/frontend/src/main.tsx',
+            code: "import { createBrowserRouter, RouterProvider } from 'react-router-dom';",
+            errors: [{ messageId: 'useTanstackRouter' }],
+        },
+        {
+            filename: '/repo/frontend/src/components/Shell.tsx',
+            code: "import { useNavigate, useParams } from 'react-router-dom';",
+            errors: [{ messageId: 'useTanstackRouter' }],
+        },
+    ],
+});

package/dist/__tests__/zod-defaults-required.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/zod-defaults-required.test.js

@@ -0,0 +1,29 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import { afterAll, describe, it } from 'vitest';
+import { zodDefaultsRequired } from '../rules/zod-defaults-required.js';
+RuleTester.afterAll = afterAll;
+RuleTester.describe = describe;
+RuleTester.it = it;
+const tester = new RuleTester({
+    languageOptions: { ecmaVersion: 2022, sourceType: 'module' },
+});
+tester.run('zod-defaults-required', zodDefaultsRequired, {
+    valid: [
+        {
+            code: "const input = z.object({ name: z.string() }).default({ name: 'Alice' });",
+        },
+        {
+            code: "const input = z.object({ pageSize: z.number() }).default({ pageSize: 20 });",
+        },
+    ],
+    invalid: [
+        {
+            code: "const input = z.object({ name: z.string() }).optional();",
+            errors: [{ messageId: 'zodOptionalTopLevel' }],
+        },
+        {
+            code: "const output = z.object({ ok: z.boolean() }).optional();",
+            errors: [{ messageId: 'zodOptionalTopLevel' }],
+        },
+    ],
+});

package/dist/index.d.ts

@@ -20,6 +20,24 @@ declare const _default: {
         readonly 'flow-domain-ownership': import("@typescript-eslint/utils/ts-eslint").RuleModule<"owningDomainMismatch" | "missingOwningDomain", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
             name: string;
         };
+        readonly 'no-raw-fetch': import("@typescript-eslint/utils/ts-eslint").RuleModule<"noRawFetch", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+            name: string;
+        };
+        readonly 'use-tanstack-router': import("@typescript-eslint/utils/ts-eslint").RuleModule<"useTanstackRouter", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+            name: string;
+        };
+        readonly 'tanstack-query-options': import("@typescript-eslint/utils/ts-eslint").RuleModule<"tanstackQueryOptions", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+            name: string;
+        };
+        readonly 'zod-defaults-required': import("@typescript-eslint/utils/ts-eslint").RuleModule<"zodOptionalTopLevel", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+            name: string;
+        };
+        readonly 'api-needs-fixture': import("@typescript-eslint/utils/ts-eslint").RuleModule<"apiNeedsFixture", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+            name: string;
+        };
+        readonly 'prefer-result-over-throw': import("@typescript-eslint/utils/ts-eslint").RuleModule<"preferResult", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+            name: string;
+        };
     };
     configs: {
         recommended: {
@@ -41,6 +59,24 @@ declare const _default: {
                         readonly 'flow-domain-ownership': import("@typescript-eslint/utils/ts-eslint").RuleModule<"owningDomainMismatch" | "missingOwningDomain", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
                             name: string;
                         };
+                        readonly 'no-raw-fetch': import("@typescript-eslint/utils/ts-eslint").RuleModule<"noRawFetch", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+                            name: string;
+                        };
+                        readonly 'use-tanstack-router': import("@typescript-eslint/utils/ts-eslint").RuleModule<"useTanstackRouter", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+                            name: string;
+                        };
+                        readonly 'tanstack-query-options': import("@typescript-eslint/utils/ts-eslint").RuleModule<"tanstackQueryOptions", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+                            name: string;
+                        };
+                        readonly 'zod-defaults-required': import("@typescript-eslint/utils/ts-eslint").RuleModule<"zodOptionalTopLevel", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+                            name: string;
+                        };
+                        readonly 'api-needs-fixture': import("@typescript-eslint/utils/ts-eslint").RuleModule<"apiNeedsFixture", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+                            name: string;
+                        };
+                        readonly 'prefer-result-over-throw': import("@typescript-eslint/utils/ts-eslint").RuleModule<"preferResult", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+                            name: string;
+                        };
                     };
                 };
             };
@@ -50,6 +86,12 @@ declare const _default: {
                 readonly '@mettlecast/domain-module/require-define-primitive': "warn";
                 readonly '@mettlecast/domain-module/no-cross-domain-internal-import': "error";
                 readonly '@mettlecast/domain-module/flow-domain-ownership': "error";
+                readonly '@mettlecast/domain-module/no-raw-fetch': "error";
+                readonly '@mettlecast/domain-module/use-tanstack-router': "error";
+                readonly '@mettlecast/domain-module/tanstack-query-options': "warn";
+                readonly '@mettlecast/domain-module/zod-defaults-required': "error";
+                readonly '@mettlecast/domain-module/api-needs-fixture': "error";
+                readonly '@mettlecast/domain-module/prefer-result-over-throw': "error";
             };
         };
     };

package/dist/index.js

@@ -3,6 +3,12 @@ import { noRawHttpServer } from './rules/no-raw-http-server.js';
 import { requireDefinePrimitive } from './rules/require-define-primitive.js';
 import { noCrossDomainInternalImport } from './rules/no-cross-domain-internal-import.js';
 import { flowDomainOwnership } from './rules/flow-domain-ownership.js';
+import { noRawFetch } from './rules/no-raw-fetch.js';
+import { useTanstackRouter } from './rules/use-tanstack-router.js';
+import { tanstackQueryOptions } from './rules/tanstack-query-options.js';
+import { zodDefaultsRequired } from './rules/zod-defaults-required.js';
+import { apiNeedsFixture } from './rules/api-needs-fixture.js';
+import { preferResultOverThrow } from './rules/prefer-result-over-throw.js';
 /**
  * All rules exported by @mettlecast/eslint-plugin-domain-module.
  */
@@ -12,10 +18,16 @@ const rules = {
     'require-define-primitive': requireDefinePrimitive,
     'no-cross-domain-internal-import': noCrossDomainInternalImport,
     'flow-domain-ownership': flowDomainOwnership,
+    'no-raw-fetch': noRawFetch,
+    'use-tanstack-router': useTanstackRouter,
+    'tanstack-query-options': tanstackQueryOptions,
+    'zod-defaults-required': zodDefaultsRequired,
+    'api-needs-fixture': apiNeedsFixture,
+    'prefer-result-over-throw': preferResultOverThrow,
 };
 /**
  * Recommended flat config preset.
- * Enables all five rules at their default severity levels.
+ * Enables all rules at their default severity levels.
  */
 const recommended = {
     plugins: {
@@ -27,6 +39,12 @@ const recommended = {
         '@mettlecast/domain-module/require-define-primitive': 'warn',
         '@mettlecast/domain-module/no-cross-domain-internal-import': 'error',
         '@mettlecast/domain-module/flow-domain-ownership': 'error',
+        '@mettlecast/domain-module/no-raw-fetch': 'error',
+        '@mettlecast/domain-module/use-tanstack-router': 'error',
+        '@mettlecast/domain-module/tanstack-query-options': 'warn',
+        '@mettlecast/domain-module/zod-defaults-required': 'error',
+        '@mettlecast/domain-module/api-needs-fixture': 'error',
+        '@mettlecast/domain-module/prefer-result-over-throw': 'error',
     },
 };
 /**

package/dist/rules/api-needs-fixture.d.ts

@@ -0,0 +1,4 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+export declare const apiNeedsFixture: ESLintUtils.RuleModule<"apiNeedsFixture", [], unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};

package/dist/rules/api-needs-fixture.js

@@ -0,0 +1,82 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+const createRule = ESLintUtils.RuleCreator((name) => `https://github.com/LawrenceGeeHouse/Mettlecast/blob/develop/packages/eslint-plugin-domain-module/docs/${name}.md`);
+const DOMAIN_API_FILE_PATTERN = /[/\\]domains[/\\][^/\\]+[/\\]api[/\\][^/\\]+\.ts$/;
+function extractFixtureIdFromDefineApi(node) {
+    const arg = node.arguments[0];
+    if (!arg || arg.type !== 'ObjectExpression')
+        return undefined;
+    const idProp = arg.properties.find((p) => p.type === 'Property' &&
+        'name' in p.key &&
+        !p.computed &&
+        p.key.name === 'id');
+    if (!idProp)
+        return undefined;
+    const val = idProp.value;
+    if (val.type === 'Literal' && typeof val.value === 'string')
+        return val.value;
+    if (val.type === 'TemplateLiteral' && val.expressions.length === 0 && val.quasis.length === 1) {
+        return val.quasis[0]?.value.cooked ?? undefined;
+    }
+    return undefined;
+}
+function isDefineApiCall(node) {
+    if (!node)
+        return false;
+    return node.callee.type === 'Identifier' && node.callee.name === 'defineApi';
+}
+export const apiNeedsFixture = createRule({
+    name: 'api-needs-fixture',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Every exported defineApi({...}) in domains/{x}/api/*.ts must have a matching __tests__/{id}.fixture.json sibling file.',
+        },
+        messages: {
+            apiNeedsFixture: 'API handler "{{name}}" is missing a __tests__/{{name}}.fixture.json sibling file.\n  fixHint: Create `domains/<domain>/api/__tests__/{{name}}.fixture.json` with realistic input/output examples. This file is consumed by `mc-domain-module test` to drive the handler in a local fixture run.\n  kNodeRef: K:runbook:fixture-driven-tests',
+        },
+        schema: [],
+    },
+    defaultOptions: [],
+    create(context) {
+        const filename = context.filename ?? context.getFilename?.() ?? '';
+        if (!filename || !DOMAIN_API_FILE_PATTERN.test(filename))
+            return {};
+        const apiDir = dirname(filename);
+        return {
+            ExportNamedDeclaration(node) {
+                const decl = node.declaration;
+                if (!decl)
+                    return;
+                let callNode;
+                if (decl.type === 'VariableDeclaration') {
+                    for (const d of decl.declarations) {
+                        if (d.init && d.init.type === 'CallExpression' && isDefineApiCall(d.init)) {
+                            callNode = d.init;
+                            break;
+                        }
+                    }
+                }
+                else {
+                    // The declaration union is narrow — use a runtime type-check
+                    // with a double-cast through unknown to avoid TS's
+                    // "may be a mistake" error on discriminated unions.
+                    const d = decl;
+                    if (d.type === 'CallExpression' && isDefineApiCall(decl)) {
+                        callNode = decl;
+                    }
+                }
+                if (!callNode)
+                    return;
+                const id = extractFixtureIdFromDefineApi(callNode);
+                if (!id)
+                    return;
+                const fixturePath = join(apiDir, '__tests__', `${id}.fixture.json`);
+                if (!existsSync(fixturePath)) {
+                    context.report({ node, messageId: 'apiNeedsFixture', data: { name: id } });
+                }
+            },
+        };
+    },
+});

package/dist/rules/no-raw-fetch.d.ts

@@ -0,0 +1,4 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+export declare const noRawFetch: ESLintUtils.RuleModule<"noRawFetch", [], unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};

package/dist/rules/no-raw-fetch.js

@@ -0,0 +1,41 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+const createRule = ESLintUtils.RuleCreator((name) => `https://github.com/LawrenceGeeHouse/Mettlecast/blob/develop/packages/eslint-plugin-domain-module/docs/${name}.md`);
+const FETCH_ALLOWED_OBJECT_NAMES = new Set(['ctx', 'globalThis']);
+export const noRawFetch = createRule({
+    name: 'no-raw-fetch',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow raw fetch() calls in domain handler files. Use ctx.fetch or a shared HTTP client (ky) instead.',
+        },
+        messages: {
+            noRawFetch: 'Raw fetch() is not allowed in domain handlers. Use ctx.fetch or a shared HTTP client (e.g. ky).\n  fixHint: Replace `fetch(url, opts)` with `await ctx.fetch(url, opts)` (or `ky(...)` for non-domain code). ctx.fetch is provided by DomainContext and is mockable in local dev.\n  kNodeRef: K:convention:tier-1-foundations',
+        },
+        schema: [],
+    },
+    defaultOptions: [],
+    create(context) {
+        function isAllowedMemberAccess(callee) {
+            const obj = callee.object;
+            if (obj.type !== 'Identifier')
+                return false;
+            return obj.name === 'ctx' || FETCH_ALLOWED_OBJECT_NAMES.has(obj.name);
+        }
+        return {
+            CallExpression(node) {
+                const callee = node.callee;
+                if (callee.type === 'Identifier' && callee.name === 'fetch') {
+                    context.report({ node, messageId: 'noRawFetch' });
+                    return;
+                }
+                if (callee.type === 'MemberExpression' &&
+                    callee.property.type === 'Identifier' &&
+                    callee.property.name === 'fetch') {
+                    if (isAllowedMemberAccess(callee))
+                        return;
+                    context.report({ node, messageId: 'noRawFetch' });
+                }
+            },
+        };
+    },
+});

package/dist/rules/prefer-result-over-throw.d.ts

@@ -0,0 +1,4 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+export declare const preferResultOverThrow: ESLintUtils.RuleModule<"preferResult", [], unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};

package/dist/rules/prefer-result-over-throw.js

@@ -0,0 +1,37 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+const createRule = ESLintUtils.RuleCreator((name) => `https://github.com/LawrenceGeeHouse/Mettlecast/blob/develop/packages/eslint-plugin-domain-module/docs/${name}.md`);
+const DOMAIN_API_FILE_PATTERN = /[/\\]domains[/\\][^/\\]+[/\\]api[/\\][^/\\]+\.ts$/;
+/** Returns true when a throw statement is a TSR redirect (allowed). */
+function isTsrRedirect(node) {
+    const arg = node.argument;
+    if (!arg || arg.type !== 'CallExpression')
+        return false;
+    const callee = arg.callee;
+    return callee.type === 'Identifier' && callee.name === 'redirect';
+}
+export const preferResultOverThrow = createRule({
+    name: 'prefer-result-over-throw',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Domain API handlers must return Result<T, AppError> instead of throwing raw errors. Thrown errors escape the handler and produce untyped 500 responses.',
+        },
+        messages: {
+            preferResult: 'Domain API handler should return `err({ ... })` instead of throwing. Thrown errors produce untraceable 500s with no structured error information.\n  fixHint: Wrap the throw in a `try/catch` or replace with `return err({ kind: "internal", traceId, message: err.message })`.\n  kNodeRef: K:convention:typed-errors',
+        },
+        schema: [],
+    },
+    defaultOptions: [],
+    create(context) {
+        const filename = context.filename ?? context.getFilename?.() ?? '';
+        if (!filename || !DOMAIN_API_FILE_PATTERN.test(filename))
+            return {};
+        return {
+            ThrowStatement(node) {
+                if (isTsrRedirect(node))
+                    return;
+                context.report({ node, messageId: 'preferResult' });
+            },
+        };
+    },
+});

package/dist/rules/tanstack-query-options.d.ts

@@ -0,0 +1,4 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+export declare const tanstackQueryOptions: ESLintUtils.RuleModule<"tanstackQueryOptions", [], unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};

package/dist/rules/tanstack-query-options.js

@@ -0,0 +1,30 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+const createRule = ESLintUtils.RuleCreator((name) => `https://github.com/LawrenceGeeHouse/Mettlecast/blob/develop/packages/eslint-plugin-domain-module/docs/${name}.md`);
+export const tanstackQueryOptions = createRule({
+    name: 'tanstack-query-options',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Inline useQuery({...}) call sites should wrap their options in queryOptions() for typed query keys and shared query definitions.',
+        },
+        messages: {
+            tanstackQueryOptions: 'useQuery() is being called with an inline object literal. Wrap the options in queryOptions() for typed query keys and shared definitions.\n  fixHint: Replace `useQuery({ queryKey, queryFn, ... })` with `useQuery(queryOptions({ queryKey, queryFn, ... }))` and export the queryOptions() from a queries module so multiple components can share it.\n  kNodeRef: K:convention:react-query-options',
+        },
+        schema: [],
+    },
+    defaultOptions: [],
+    create(context) {
+        return {
+            CallExpression(node) {
+                if (node.callee.type !== 'Identifier' || node.callee.name !== 'useQuery')
+                    return;
+                const first = node.arguments[0];
+                if (!first)
+                    return;
+                if (first.type === 'ObjectExpression') {
+                    context.report({ node, messageId: 'tanstackQueryOptions' });
+                }
+            },
+        };
+    },
+});

package/dist/rules/use-tanstack-router.d.ts

@@ -0,0 +1,4 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+export declare const useTanstackRouter: ESLintUtils.RuleModule<"useTanstackRouter", [], unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};

package/dist/rules/use-tanstack-router.js

@@ -0,0 +1,30 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+const createRule = ESLintUtils.RuleCreator((name) => `https://github.com/LawrenceGeeHouse/Mettlecast/blob/develop/packages/eslint-plugin-domain-module/docs/${name}.md`);
+const FRONTEND_PATH_PATTERN = /[/\\](?:frontend|dashboard[\\/]src|src)[\\/]/;
+export const useTanstackRouter = createRule({
+    name: 'use-tanstack-router',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow react-router-dom imports in frontend source. Use @tanstack/react-router instead.',
+        },
+        messages: {
+            useTanstackRouter: 'Import from "react-router-dom" is not allowed. Use @tanstack/react-router in frontend code.\n  fixHint: Replace `from \'react-router-dom\'` with `from \'@tanstack/react-router\'` and update API usage (e.g. createRootRoute/createRoute/Outlet). See K:convention:router-stack.\n  kNodeRef: K:convention:router-stack',
+        },
+        schema: [],
+    },
+    defaultOptions: [],
+    create(context) {
+        const filename = context.filename ?? context.getFilename?.() ?? '';
+        if (!FRONTEND_PATH_PATTERN.test(filename))
+            return {};
+        return {
+            ImportDeclaration(node) {
+                const source = node.source.value;
+                if (typeof source === 'string' && source === 'react-router-dom') {
+                    context.report({ node, messageId: 'useTanstackRouter' });
+                }
+            },
+        };
+    },
+});

package/dist/rules/zod-defaults-required.d.ts

@@ -0,0 +1,4 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+export declare const zodDefaultsRequired: ESLintUtils.RuleModule<"zodOptionalTopLevel", [], unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};

package/dist/rules/zod-defaults-required.js

@@ -0,0 +1,91 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+const createRule = ESLintUtils.RuleCreator((name) => `https://github.com/LawrenceGeeHouse/Mettlecast/blob/develop/packages/eslint-plugin-domain-module/docs/${name}.md`);
+const ZOD_ROOT = 'z';
+function isZodRootIdentifier(node) {
+    return !!node && node.type === 'Identifier' && node.name === ZOD_ROOT;
+}
+function isZodObjectCall(node) {
+    const callee = node.callee;
+    return (callee.type === 'MemberExpression' &&
+        isZodRootIdentifier(callee.object) &&
+        callee.property.type === 'Identifier' &&
+        callee.property.name === 'object');
+}
+function isOptionalCall(node) {
+    const callee = node.callee;
+    return (callee.type === 'MemberExpression' &&
+        callee.property.type === 'Identifier' &&
+        callee.property.name === 'optional');
+}
+function chainHasDefault(node) {
+    let cur = node.callee;
+    while (cur) {
+        if (cur.type === 'MemberExpression') {
+            if (cur.property.type === 'Identifier' && cur.property.name === 'default') {
+                return true;
+            }
+            cur = cur.object;
+            continue;
+        }
+        if (cur.type === 'CallExpression') {
+            cur = cur.callee;
+            continue;
+        }
+        break;
+    }
+    return false;
+}
+function chainStartsAtZodRoot(node) {
+    let cur = node.callee;
+    while (cur) {
+        if (cur.type === 'CallExpression') {
+            cur = cur.callee;
+            continue;
+        }
+        if (cur.type === 'MemberExpression') {
+            cur = cur.object;
+            continue;
+        }
+        return isZodRootIdentifier(cur);
+    }
+    return false;
+}
+export const zodDefaultsRequired = createRule({
+    name: 'zod-defaults-required',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Top-level Zod input/output schemas must end in .default(...). Field-level .optional() inside z.object({...}) is allowed.',
+        },
+        messages: {
+            zodOptionalTopLevel: 'Top-level Zod input/output schema must end in .default(...). Field-level .optional() inside z.object({...}) is allowed; top-level schemas are not.\n  fixHint: Append `.default({...})` with a realistic example payload to the chain (e.g. `z.object({...}).default({...})`). This is required by validate-domain.yml CI gate.\n  kNodeRef: K:convention:zod-defaults-required',
+        },
+        schema: [],
+    },
+    defaultOptions: [],
+    create(context) {
+        let zodObjectDepth = 0;
+        return {
+            CallExpression(node) {
+                if (isZodObjectCall(node)) {
+                    zodObjectDepth++;
+                    return;
+                }
+                if (zodObjectDepth > 0)
+                    return;
+                if (!isOptionalCall(node))
+                    return;
+                if (chainHasDefault(node))
+                    return;
+                if (!chainStartsAtZodRoot(node))
+                    return;
+                context.report({ node, messageId: 'zodOptionalTopLevel' });
+            },
+            'CallExpression:exit'(node) {
+                if (isZodObjectCall(node)) {
+                    zodObjectDepth--;
+                }
+            },
+        };
+    },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mettlecast/eslint-plugin-domain-module",
-  "version": "0.2.22",
+  "version": "0.2.23",
   "type": "module",
   "files": [
     "dist"