@mettlecast/domain-cli 0.2.58 → 0.2.60

package/src/__tests__/validate.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, vi } from 'vitest';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
 
 vi.mock('../utils/logger.js', () => ({
   cliLogger: {
@@ -9,10 +9,661 @@ vi.mock('../utils/logger.js', () => ({
   },
 }));
 
+vi.mock('../builder/load-module.js', () => ({
+  loadModuleExports: vi.fn(),
+}));
+vi.mock('../utils/file-helpers.js', () => ({
+  walkDomainDir: vi.fn(),
+}));
+
 import { runValidate } from '../commands/validate.js';
+import { buildRegistry } from '../builder/build-registry.js';
+import { loadModuleExports } from '../builder/load-module.js';
+import { walkDomainDir } from '../utils/file-helpers.js';
+
+const mockLoadModuleExports = vi.mocked(loadModuleExports);
+const mockWalkDomainDir = vi.mocked(walkDomainDir);
 
 describe('runValidate error shape', () => {
   it('throws when domain root has no domain.config.ts', async () => {
     await expect(runValidate('/nonexistent-path', false)).rejects.toThrow();
   });
 });
+
+/**
+ * Action-first migration (#4619, Wave 1 Task 1.2):
+ *
+ * `runValidate` ultimately delegates to `buildRegistry` for the
+ * registry assembly. These tests exercise the action mapping directly
+ * through `buildRegistry` (mocked file walker + module loader) so we
+ * catch regressions in how legacy `visibility` maps to `backendAccess`
+ * and how `exposure` is serialized.
+ */
+describe('buildRegistry action mapping (action-first migration)', () => {
+  const DOMAIN_ROOT = '/fake/domains/billing';
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('reads backendAccess directly when raw action exposes it', async () => {
+    mockWalkDomainDir.mockResolvedValue({
+      domain: '/fake/domains/billing/domain.config.ts',
+      apis: [],
+      webhooks: [],
+      subscribers: [],
+      actions: ['/fake/domains/billing/actions/charge-card.ts'],
+      schedules: [],
+      jobs: [],
+      integrations: [],
+      publishes: undefined,
+    });
+    mockLoadModuleExports
+      .mockResolvedValueOnce([
+        { _kind: 'domain', _exportName: 'default', id: 'billing', name: 'Billing', tenancy: 'required' },
+      ])
+      .mockResolvedValueOnce([
+        {
+          _kind: 'action',
+          _exportName: 'chargeCard',
+          id: 'charge-card',
+          backendAccess: 'domain',
+          exposure: {
+            type: 'api',
+            path: '/v1/tenants/{tenantId}/billing/charges',
+            method: 'POST',
+            auth: 'required',
+            tenancy: 'required',
+          },
+          idempotent: true,
+        },
+      ]);
+
+    const { registry } = await buildRegistry(DOMAIN_ROOT);
+
+    expect(registry.actions).toHaveLength(1);
+    const action = registry.actions[0]!;
+    expect(action.id).toBe('charge-card');
+    expect(action.backendAccess).toBe('domain');
+    expect(action.exposure.type).toBe('api');
+    if (action.exposure.type === 'api') {
+      expect(action.exposure.path).toBe('/v1/tenants/{tenantId}/billing/charges');
+      expect(action.exposure.method).toBe('POST');
+      expect(action.exposure.auth).toBe('required');
+      expect(action.exposure.tenancy).toBe('required');
+    }
+  });
+
+  it('falls back from legacy visibility to backendAccess and collapses workspace -> domain', async () => {
+    mockWalkDomainDir.mockResolvedValue({
+      domain: '/fake/domains/billing/domain.config.ts',
+      apis: [],
+      webhooks: [],
+      subscribers: [],
+      actions: [
+        '/fake/domains/billing/actions/verify-token.ts',
+        '/fake/domains/billing/actions/provision-tenant.ts',
+      ],
+      schedules: [],
+      jobs: [],
+      integrations: [],
+      publishes: undefined,
+    });
+    mockLoadModuleExports
+      .mockResolvedValueOnce([
+        { _kind: 'domain', _exportName: 'default', id: 'billing', name: 'Billing', tenancy: 'required' },
+      ])
+      // First call resolves the actions array (Promise.all maps in order).
+      .mockResolvedValueOnce([
+        { _kind: 'action', _exportName: 'verifyToken', id: 'verify-token', visibility: 'workspace', idempotent: false },
+        { _kind: 'action', _exportName: 'provisionTenant', id: 'provision-tenant', visibility: 'domain', idempotent: true },
+      ]);
+
+    const { registry } = await buildRegistry(DOMAIN_ROOT);
+
+    expect(registry.actions).toHaveLength(2);
+    const verify = registry.actions.find(a => a.id === 'verify-token');
+    const provision = registry.actions.find(a => a.id === 'provision-tenant');
+    expect(verify?.backendAccess).toBe('domain');
+    expect(verify?.exposure).toEqual({ type: 'internal' });
+    expect(provision?.backendAccess).toBe('domain');
+    expect(provision?.exposure).toEqual({ type: 'internal' });
+  });
+
+  it('defaults missing exposure to { type: internal } for legacy actions', async () => {
+    mockWalkDomainDir.mockResolvedValue({
+      domain: '/fake/domains/billing/domain.config.ts',
+      apis: [],
+      webhooks: [],
+      subscribers: [],
+      actions: ['/fake/domains/billing/actions/legacy.ts'],
+      schedules: [],
+      jobs: [],
+      integrations: [],
+      publishes: undefined,
+    });
+    mockLoadModuleExports
+      .mockResolvedValueOnce([
+        { _kind: 'domain', _exportName: 'default', id: 'billing', name: 'Billing', tenancy: 'required' },
+      ])
+      .mockResolvedValueOnce([
+        { _kind: 'action', _exportName: 'legacy', id: 'legacy', visibility: 'private', idempotent: false },
+      ]);
+
+    const { registry } = await buildRegistry(DOMAIN_ROOT);
+
+    expect(registry.actions[0]?.exposure).toEqual({ type: 'internal' });
+    expect(registry.actions[0]?.backendAccess).toBe('private');
+  });
+
+  it('preserves inputSchema and outputSchema extraction', async () => {
+    mockWalkDomainDir.mockResolvedValue({
+      domain: '/fake/domains/billing/domain.config.ts',
+      apis: [],
+      webhooks: [],
+      subscribers: [],
+      actions: ['/fake/domains/billing/actions/charge-card.ts'],
+      schedules: [],
+      jobs: [],
+      integrations: [],
+      publishes: undefined,
+    });
+    mockLoadModuleExports
+      .mockResolvedValueOnce([
+        { _kind: 'domain', _exportName: 'default', id: 'billing', name: 'Billing', tenancy: 'required' },
+      ])
+      .mockResolvedValueOnce([
+        {
+          _kind: 'action',
+          _exportName: 'chargeCard',
+          id: 'charge-card',
+          backendAccess: 'domain',
+          exposure: { type: 'internal' },
+          idempotent: true,
+          input: { type: 'object', properties: { amount: { type: 'number' } } },
+          output: { type: 'object', properties: { id: { type: 'string' } } },
+        },
+      ]);
+
+    const { registry } = await buildRegistry(DOMAIN_ROOT);
+
+    expect(registry.actions[0]?.inputSchema).toEqual({ type: 'object', properties: { amount: { type: 'number' } } });
+    expect(registry.actions[0]?.outputSchema).toEqual({ type: 'object', properties: { id: { type: 'string' } } });
+  });
+});
+
+/**
+ * Action-first security validation rules (#4619, Wave 6 Task 6.1).
+ *
+ * These tests exercise the new validation gates added to `runValidate`.
+ * Each test mocks `buildRegistry` consumers so the assertions target the
+ * rule codes (`ACTION_EXPOSURE_REQUIRED`, `TENANT_API_PATH_REQUIRED`,
+ * `AUTH_NONE_REQUIRES_EXCEPTION`, etc.) without needing a real
+ * domain on disk.
+ */
+describe('runValidate action-first security rules (#4619 / Wave 6)', () => {
+  const DOMAIN_ROOT = '/fake/domains/billing';
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  /**
+   * Helper that wires the two file-walker / module-loader mocks so
+   * `buildRegistry` returns the supplied actions (plus the canonical
+   * domain row) and the supplied apis list. Returns the ValidationResult
+   * produced by `runValidate`.
+   */
+  async function runValidateWith({
+    actions = [],
+    apis = [],
+  }: {
+    actions?: Record<string, unknown>[];
+    apis?: Record<string, unknown>[];
+  }): Promise<{ errors: { code: string; message: string }[]; warnings: string[]; valid: boolean; }> {
+    mockWalkDomainDir.mockResolvedValue({
+      domain: '/fake/domains/billing/domain.config.ts',
+      apis: apis.map(() => '/fake/domains/billing/api/x.ts'),
+      webhooks: [],
+      subscribers: [],
+      actions: actions.map(() => '/fake/domains/billing/actions/x.ts'),
+      schedules: [],
+      jobs: [],
+      integrations: [],
+      publishes: undefined,
+    });
+    // Mock consumption order inside buildRegistry:
+    //   1. domain (paths.domain)        -> mock #1
+    //   2. apis files (paths.apis)      -> mock #2 (if any)
+    //   3. webhooks/subscribers/schedules/jobs/integrations -> empty arrays, no calls
+    //   4. actions files (paths.actions)-> mock #N (if any)
+    //   5. publishes (paths.publishes)  -> undefined, no call
+    // Each non-empty slot consumes exactly one mock per file (we
+    // generate one synthetic file path per item so the slot has length
+    // equal to the supplied arrays).
+    mockLoadModuleExports.mockResolvedValueOnce([
+      { _kind: 'domain', _exportName: 'default', id: 'billing', name: 'Billing', tenancy: 'required' },
+    ]);
+    if (apis.length > 0) {
+      mockLoadModuleExports.mockResolvedValueOnce(apis as never);
+    }
+    if (actions.length > 0) {
+      mockLoadModuleExports.mockResolvedValueOnce(actions as never);
+    }
+
+    const result = await runValidate(DOMAIN_ROOT, false);
+    return { errors: result.errors, warnings: result.warnings, valid: result.valid };
+  }
+
+  it('ACTION_EXPOSURE_REQUIRED — fires when a non-private action omits exposure', async () => {
+    const { errors } = await runValidateWith({
+      actions: [
+        // `backendAccess: 'platform'` is the strongest "new-style" signal;
+        // omitting `exposure` should now fail the build.
+        {
+          _kind: 'action', _exportName: 'sysReset',
+          id: 'sys-reset', backendAccess: 'platform', idempotent: false,
+        },
+      ],
+    });
+    const rule = errors.find(e => e.code === 'ACTION_EXPOSURE_REQUIRED');
+    expect(rule).toBeDefined();
+    expect(rule?.message).toContain("'sys-reset'");
+  });
+
+  it('ACTION_EXPOSURE_REQUIRED — does NOT fire for explicit internal exposure', async () => {
+    const { errors } = await runValidateWith({
+      actions: [
+        {
+          _kind: 'action', _exportName: 'sysReset',
+          id: 'sys-reset', backendAccess: 'platform',
+          exposure: { type: 'internal' },
+          idempotent: false,
+        },
+      ],
+    });
+    expect(errors.find(e => e.code === 'ACTION_EXPOSURE_REQUIRED')).toBeUndefined();
+  });
+
+  it('ACTION_EXPOSURE_REQUIRED — silent on legacy private action (migration compatibility)', async () => {
+    // Legacy `visibility: 'private'` actions map to `backendAccess: 'private'`
+    // and default `exposure` to `{ type: 'internal' }`. The rule must not
+    // flag these so the migration window stays unblocked.
+    const { errors } = await runValidateWith({
+      actions: [
+        {
+          _kind: 'action', _exportName: 'legacyPrivate',
+          id: 'legacy-private', visibility: 'private', idempotent: false,
+        },
+      ],
+    });
+    expect(errors.find(e => e.code === 'ACTION_EXPOSURE_REQUIRED')).toBeUndefined();
+  });
+
+  it('TENANT_API_PATH_REQUIRED — fires when tenancy is required but path lacks tenant placeholder', async () => {
+    const { errors } = await runValidateWith({
+      actions: [
+        {
+          _kind: 'action', _exportName: 'listAll',
+          id: 'list-all', backendAccess: 'platform',
+          exposure: {
+            type: 'api', path: '/v1/admin/users', method: 'GET',
+            auth: 'required', tenancy: 'required',
+          },
+          idempotent: false,
+        },
+      ],
+    });
+    const rule = errors.find(e => e.code === 'TENANT_API_PATH_REQUIRED');
+    expect(rule).toBeDefined();
+    expect(rule?.message).toContain("'list-all'");
+    expect(rule?.message).toContain('/v1/tenants/{tenantId}/');
+  });
+
+  it('TENANT_API_PATH_REQUIRED — passes when tenancy is required AND path includes placeholder', async () => {
+    const { errors } = await runValidateWith({
+      actions: [
+        {
+          _kind: 'action', _exportName: 'listUsers',
+          id: 'list-users', backendAccess: 'domain',
+          exposure: {
+            type: 'api', path: '/v1/tenants/{tenantId}/users', method: 'GET',
+            auth: 'required', tenancy: 'required',
+          },
+          idempotent: false,
+        },
+      ],
+    });
+    expect(errors.find(e => e.code === 'TENANT_API_PATH_REQUIRED')).toBeUndefined();
+  });
+
+  it('API_EXPOSURE_AUTH_REQUIRED — fires when auth was defaulted (not declared in source)', async () => {
+    // Source did NOT include `auth` — the builder will default to
+    // 'required' and the validator must surface the omission.
+    const { errors } = await runValidateWith({
+      actions: [
+        {
+          _kind: 'action', _exportName: 'listUsers',
+          id: 'list-users', backendAccess: 'domain',
+          exposure: {
+            type: 'api', path: '/v1/tenants/{tenantId}/users', method: 'GET',
+            tenancy: 'required',
+            // auth omitted on purpose
+          },
+          idempotent: false,
+        },
+      ],
+    });
+    const rule = errors.find(e => e.code === 'API_EXPOSURE_AUTH_REQUIRED');
+    expect(rule).toBeDefined();
+    expect(rule?.message).toContain("'list-users'");
+  });
+
+  it('API_EXPOSURE_AUTH_REQUIRED — silent when auth is explicitly declared', async () => {
+    const { errors } = await runValidateWith({
+      actions: [
+        {
+          _kind: 'action', _exportName: 'listUsers',
+          id: 'list-users', backendAccess: 'domain',
+          exposure: {
+            type: 'api', path: '/v1/tenants/{tenantId}/users', method: 'GET',
+            auth: 'required', tenancy: 'required',
+          },
+          idempotent: false,
+        },
+      ],
+    });
+    expect(errors.find(e => e.code === 'API_EXPOSURE_AUTH_REQUIRED')).toBeUndefined();
+  });
+
+  it('AUTH_NONE_REQUIRES_EXCEPTION — fires when auth is none without securityException', async () => {
+    const { errors } = await runValidateWith({
+      actions: [
+        {
+          _kind: 'action', _exportName: 'health',
+          id: 'health', backendAccess: 'platform',
+          exposure: {
+            type: 'api', path: '/v1/health', method: 'GET',
+            auth: 'none', tenancy: 'none',
+          },
+          idempotent: false,
+        },
+      ],
+    });
+    const rule = errors.find(e => e.code === 'AUTH_NONE_REQUIRES_EXCEPTION');
+    expect(rule).toBeDefined();
+    expect(rule?.message).toContain("'health'");
+  });
+
+  it('AUTH_NONE_REQUIRES_EXCEPTION — passes when auth is none WITH securityException.reason', async () => {
+    const { errors } = await runValidateWith({
+      actions: [
+        {
+          _kind: 'action', _exportName: 'health',
+          id: 'health', backendAccess: 'platform',
+          exposure: {
+            type: 'api', path: '/v1/health', method: 'GET',
+            auth: 'none', tenancy: 'none',
+            securityException: { reason: 'public liveness probe; no PII; ticket OPS-123' },
+          },
+          idempotent: false,
+        },
+      ],
+    });
+    expect(errors.find(e => e.code === 'AUTH_NONE_REQUIRES_EXCEPTION')).toBeUndefined();
+  });
+
+  it('AUTH_NONE_REQUIRES_EXCEPTION — fires when securityException.reason is whitespace-only', async () => {
+    const { errors } = await runValidateWith({
+      actions: [
+        {
+          _kind: 'action', _exportName: 'health',
+          id: 'health', backendAccess: 'platform',
+          exposure: {
+            type: 'api', path: '/v1/health', method: 'GET',
+            auth: 'none', tenancy: 'none',
+            securityException: { reason: '   ' },
+          },
+          idempotent: false,
+        },
+      ],
+    });
+    expect(errors.find(e => e.code === 'AUTH_NONE_REQUIRES_EXCEPTION')).toBeDefined();
+  });
+
+  it('TENANCY_NONE_REQUIRES_REASON_WHEN_PUBLIC — fires when tenancy is none without securityException', async () => {
+    const { errors } = await runValidateWith({
+      actions: [
+        {
+          _kind: 'action', _exportName: 'publicLookup',
+          id: 'public-lookup', backendAccess: 'platform',
+          exposure: {
+            type: 'api', path: '/v1/public/lookup', method: 'GET',
+            auth: 'required', tenancy: 'none',
+          },
+          idempotent: false,
+        },
+      ],
+    });
+    const rule = errors.find(e => e.code === 'TENANCY_NONE_REQUIRES_REASON_WHEN_PUBLIC');
+    expect(rule).toBeDefined();
+    expect(rule?.message).toContain("'public-lookup'");
+  });
+
+  it('SYSTEM_API_REQUIRES_ROLE — fires when system tenancy + required auth without roles', async () => {
+    const { errors } = await runValidateWith({
+      actions: [
+        {
+          _kind: 'action', _exportName: 'adminPing',
+          id: 'admin-ping', backendAccess: 'platform',
+          exposure: {
+            type: 'api', path: '/v1/admin/ping', method: 'GET',
+            auth: 'required', tenancy: 'system',
+          },
+          idempotent: false,
+        },
+      ],
+    });
+    const rule = errors.find(e => e.code === 'SYSTEM_API_REQUIRES_ROLE');
+    expect(rule).toBeDefined();
+    expect(rule?.message).toContain("'admin-ping'");
+  });
+
+  it('SYSTEM_API_REQUIRES_ROLE — passes when system tenancy has non-empty roles', async () => {
+    const { errors } = await runValidateWith({
+      actions: [
+        {
+          _kind: 'action', _exportName: 'adminPing',
+          id: 'admin-ping', backendAccess: 'platform',
+          exposure: {
+            type: 'api', path: '/v1/admin/ping', method: 'GET',
+            auth: 'required', tenancy: 'system',
+            roles: ['sys-admin'],
+          },
+          idempotent: false,
+        },
+      ],
+    });
+    expect(errors.find(e => e.code === 'SYSTEM_API_REQUIRES_ROLE')).toBeUndefined();
+  });
+
+  it('SYSTEM_API_REQUIRES_ROLE — silent when auth is service (service-only route, no role narrowing required)', async () => {
+    const { errors } = await runValidateWith({
+      actions: [
+        {
+          _kind: 'action', _exportName: 'replicationHook',
+          id: 'replication-hook', backendAccess: 'platform',
+          exposure: {
+            type: 'api', path: '/v1/admin/replicate', method: 'POST',
+            auth: 'service', tenancy: 'system',
+          },
+          idempotent: false,
+        },
+      ],
+    });
+    expect(errors.find(e => e.code === 'SYSTEM_API_REQUIRES_ROLE')).toBeUndefined();
+  });
+
+  it('DEFINE_API_LEGACY_USAGE — fires once per legacy defineApi entry', async () => {
+    // Stub out the api builder checks (requestSchema, examples, etc.)
+    // because the test fixture intentionally provides a minimal api
+    // shape. We only assert on the new DEFINE_API_LEGACY_USAGE rule
+    // here; other rules are covered by build-registry.test.ts and the
+    // existing validate.test.ts suite.
+    const { errors } = await runValidateWith({
+      actions: [],
+      apis: [
+        {
+          _kind: 'api', _exportName: 'legacyList',
+          id: 'legacy-list', path: '/v1/list', method: 'GET',
+          auth: { type: 'jwt' },
+          versions: {
+            v1: {
+              status: 'stable',
+              input: { type: 'object', properties: {}, default: {} },
+              output: { type: 'object', properties: {}, default: {} },
+              handler: () => undefined,
+            },
+          },
+          examples: { request: {}, response: {} },
+        },
+      ],
+    });
+    const rules = errors.filter(e => e.code === 'DEFINE_API_LEGACY_USAGE');
+    expect(rules).toHaveLength(1);
+    expect(rules[0]?.message).toContain("'legacy-list'");
+  });
+
+  it('DEFINE_API_LEGACY_USAGE — silent when registry has no defineApi rows', async () => {
+    const { errors } = await runValidateWith({
+      actions: [
+        {
+          _kind: 'action', _exportName: 'internalOnly',
+          id: 'internal-only', backendAccess: 'domain',
+          exposure: { type: 'internal' },
+          idempotent: false,
+        },
+      ],
+      apis: [],
+    });
+    expect(errors.find(e => e.code === 'DEFINE_API_LEGACY_USAGE')).toBeUndefined();
+  });
+
+  it('combined: well-formed api action passes every rule', async () => {
+    const { errors } = await runValidateWith({
+      actions: [
+        {
+          _kind: 'action', _exportName: 'chargeCard',
+          id: 'charge-card', backendAccess: 'domain',
+          exposure: {
+            type: 'api', path: '/v1/tenants/{tenantId}/billing/charges', method: 'POST',
+            auth: 'required', tenancy: 'required',
+            roles: ['billing-admin'],
+          },
+          idempotent: true,
+        },
+      ],
+    });
+    const securityCodes = [
+      'ACTION_EXPOSURE_REQUIRED', 'API_EXPOSURE_AUTH_REQUIRED',
+      'TENANT_API_PATH_REQUIRED', 'AUTH_NONE_REQUIRES_EXCEPTION',
+      'TENANCY_NONE_REQUIRES_REASON_WHEN_PUBLIC', 'SYSTEM_API_REQUIRES_ROLE',
+      'DEFINE_API_LEGACY_USAGE',
+    ];
+    const firedSecurityRules = errors.filter(e => securityCodes.includes(e.code));
+    expect(firedSecurityRules).toHaveLength(0);
+    // Non-security rules (e.g. MISSING_HANDLER_FILE on the synthetic
+    // mock file path) may legitimately fire; we only assert that the
+    // Wave 6 security gates are clean.
+  });
+});
+
+/**
+ * Deployment-time security rules (#4662 Task D).
+ *
+ * These mirror the CDK aspect's synth-time checks so CI can gate the
+ * build BEFORE synth is attempted. Each rule emits a structured
+ * `ValidationError` whose `code` matches the aspect annotation code,
+ * making the two layers correlatable.
+ */
+describe('runValidate deployment-time security rules (#4662 Task D)', () => {
+  const DOMAIN_ROOT = '/fake/domains/billing';
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  async function runValidateWith({
+    actions = [],
+    apis = [],
+  }: {
+    actions?: Record<string, unknown>[];
+    apis?: Record<string, unknown>[];
+  }): Promise<{ errors: { code: string; message: string }[]; warnings: string[]; valid: boolean; }> {
+    mockWalkDomainDir.mockResolvedValue({
+      domain: '/fake/domains/billing/domain.config.ts',
+      apis: apis.map(() => '/fake/domains/billing/api/x.ts'),
+      webhooks: [],
+      subscribers: [],
+      actions: actions.map(() => '/fake/domains/billing/actions/x.ts'),
+      schedules: [],
+      jobs: [],
+      integrations: [],
+      publishes: undefined,
+    });
+    mockLoadModuleExports.mockResolvedValueOnce([
+      { _kind: 'domain', _exportName: 'default', id: 'billing', name: 'Billing', tenancy: 'required' },
+    ]);
+    if (apis.length > 0) {
+      mockLoadModuleExports.mockResolvedValueOnce(apis as never);
+    }
+    if (actions.length > 0) {
+      mockLoadModuleExports.mockResolvedValueOnce(actions as never);
+    }
+
+    const result = await runValidate(DOMAIN_ROOT, false);
+    return { errors: result.errors, warnings: result.warnings, valid: result.valid };
+  }
+
+  it('SECURITY_MISSING_TENANT_PATH — fires for an API whose path lacks the tenant placeholder', async () => {
+    const { errors } = await runValidateWith({
+      apis: [
+        {
+          _kind: 'api', _exportName: 'listUsers',
+          id: 'list-users', path: '/v1/users', method: 'GET',
+          authType: 'jwt',
+        },
+      ],
+    });
+    const rule = errors.find(e => e.code === 'SECURITY_MISSING_TENANT_PATH');
+    expect(rule).toBeDefined();
+    expect(rule?.message).toContain("'list-users'");
+    expect(rule?.message).toContain('/v1/tenants/{tenantId}/');
+  });
+
+  it('SECURITY_MISSING_TENANT_PATH — silent when the API path includes the placeholder', async () => {
+    const { errors } = await runValidateWith({
+      apis: [
+        {
+          _kind: 'api', _exportName: 'listUsers',
+          id: 'list-users', path: '/v1/tenants/{tenantId}/users', method: 'GET',
+          authType: 'jwt',
+        },
+      ],
+    });
+    expect(errors.find(e => e.code === 'SECURITY_MISSING_TENANT_PATH')).toBeUndefined();
+  });
+
+  it('SECURITY_MISSING_TENANT_PATH — silent for anonymous (authType=none) APIs', async () => {
+    const { errors } = await runValidateWith({
+      apis: [
+        {
+          _kind: 'api', _exportName: 'health',
+          id: 'health', path: '/v1/health', method: 'GET',
+          auth: { type: 'none' },
+        },
+      ],
+    });
+    expect(errors.find(e => e.code === 'SECURITY_MISSING_TENANT_PATH')).toBeUndefined();
+  });
+});