validate-searchable-fields.test.ts

// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.

import { describe, it, expect } from 'vitest';
import {
  validateSearchableFields,
  SEARCHABLE_FIELD_UNKNOWN,
  SEARCHABLE_FIELD_UNSEARCHABLE,
} from './validate-searchable-fields.js';

/**
 * The drift this rule exists for: `email` was renamed to `billing_email` and
 * the old name stayed behind in `searchableFields`. Zod-valid, shipped, and
 * pointing at a column that no longer exists.
 */
const staleStack = {
  objects: [
    {
      name: 'crm_account',
      fields: {
        name: { type: 'text', label: 'Name' },
        billing_email: { type: 'email', label: 'Billing Email' },
        status: { type: 'select', label: 'Status' },
      },
      searchableFields: ['name', 'email', 'status'],
    },
  ],
};

/** The same object after the rename was carried through. */
const cleanStack = {
  objects: [
    {
      name: 'crm_account',
      fields: {
        name: { type: 'text', label: 'Name' },
        billing_email: { type: 'email', label: 'Billing Email' },
        status: { type: 'select', label: 'Status' },
      },
      searchableFields: ['name', 'billing_email', 'status'],
    },
  ],
};

describe('validateSearchableFields — object declaration', () => {
  it('flags an entry that names no field on the object', () => {
    const findings = validateSearchableFields(staleStack);

    expect(findings).toHaveLength(1);
    expect(findings[0].rule).toBe(SEARCHABLE_FIELD_UNKNOWN);
    expect(findings[0].where).toBe('object "crm_account"');
    // The index is part of the path so the author can go straight to the entry.
    expect(findings[0].path).toBe('objects[0].searchableFields[1]');
    expect(findings[0].message).toContain('"email"');
    expect(findings[0].message).toContain('crm_account');
  });

  it('gates the build (error), unlike the advisory field-existence rules', () => {
    // A stale entry either narrows the searched set below the declaration or —
    // once every entry is stale — falls through to the auto-default and
    // searches a set nobody wrote. Neither is something a yellow line should
    // ship. Pinned because a downgrade to `warning` would be invisible: `os
    // validate` only exits non-zero on `error`.
    expect(validateSearchableFields(staleStack)[0].severity).toBe('error');
  });

  it('explains the fix and names the fields that do exist', () => {
    const [finding] = validateSearchableFields(staleStack);

    expect(finding.hint).toContain('billing_email');
    // The declaration is echoed verbatim by clients as `$searchFields`, so the
    // hint must say why this is not merely a quietly narrowed search.
    expect(finding.hint).toContain('400 INVALID_FIELD');
  });

  it('suggests the renamed field when the stale name is close to a real one', () => {
    const findings = validateSearchableFields({
      objects: [
        {
          name: 'crm_account',
          fields: { billing_email: { type: 'email' } },
          searchableFields: ['biling_email'],
        },
      ],
    });

    expect(findings[0].message).toContain('Did you mean "billing_email"?');
  });

  it('reports every stale entry, not just the first', () => {
    const findings = validateSearchableFields({
      objects: [
        {
          name: 'crm_account',
          fields: { name: { type: 'text' } },
          searchableFields: ['name', 'email', 'phone'],
        },
      ],
    });

    expect(findings.map((f) => f.path)).toEqual([
      'objects[0].searchableFields[1]',
      'objects[0].searchableFields[2]',
    ]);
  });

  it('passes a declaration whose every entry resolves', () => {
    expect(validateSearchableFields(cleanStack)).toEqual([]);
  });

  it('reads the legacy array field map as well as the name-keyed one', () => {
    const asArrayFields = {
      objects: [
        {
          name: 'crm_account',
          fields: [
            { name: 'name', type: 'text' },
            { name: 'billing_email', type: 'email' },
          ],
          searchableFields: ['billing_email'],
        },
      ],
    };

    expect(validateSearchableFields(asArrayFields)).toEqual([]);
  });
});

describe('validateSearchableFields — what it deliberately does not flag', () => {
  it('accepts registry-injected system columns absent from authored fields', () => {
    // `created_at` / `owner_id` are injected by the objectql registry, so they
    // are searchable at runtime while never appearing in `fields`. Flagging
    // them would be the false positive that makes authors stop reading lint.
    const findings = validateSearchableFields({
      objects: [
        {
          name: 'crm_account',
          fields: { name: { type: 'text' } },
          searchableFields: ['name', 'created_at', 'owner_id'],
        },
      ],
    });

    expect(findings).toEqual([]);
  });

  it('leaves an object with no authored field map alone', () => {
    // External objects and datasource-introspected schemas resolve their
    // columns at runtime; there is nothing here to judge against.
    const findings = validateSearchableFields({
      objects: [
        { name: 'external_invoice', external: { datasource: 'erp' }, searchableFields: ['doc_no'] },
      ],
    });

    expect(findings).toEqual([]);
  });

  it('does not flag a field that exists but is an odd search target', () => {
    // An explicit `searchableFields` is authoritative — the engine scans
    // exactly what it names — so declaring a json column is a choice, not
    // drift. This rule answers existence only.
    const findings = validateSearchableFields({
      objects: [
        {
          name: 'crm_account',
          fields: { name: { type: 'text' }, payload: { type: 'json' } },
          searchableFields: ['name', 'payload'],
        },
      ],
    });

    expect(findings).toEqual([]);
  });

  it('ignores a non-string entry — that is a shape error the schema owns', () => {
    const findings = validateSearchableFields({
      objects: [
        { name: 'crm_account', fields: { name: { type: 'text' } }, searchableFields: [null, 42] },
      ],
    });

    expect(findings).toEqual([]);
  });

  it('returns nothing for an empty stack, a missing declaration, or an empty one', () => {
    expect(validateSearchableFields({})).toEqual([]);
    expect(validateSearchableFields({ objects: [{ name: 'a', fields: { n: { type: 'text' } } }] })).toEqual([]);
    expect(
      validateSearchableFields({
        objects: [{ name: 'a', fields: { n: { type: 'text' } }, searchableFields: [] }],
      }),
    ).toEqual([]);
  });
});

describe('validateSearchableFields — dotted paths', () => {
  it('flags a related-record path, which search cannot resolve', () => {
    // Every sibling rule skips `owner_id.name` because the query engine
    // resolves the traversal. Search does not: `resolveSearchFields` matches
    // the field map by exact string, so a dotted entry is dropped exactly like
    // a typo — and it is the spelling most likely borrowed from `select`.
    const findings = validateSearchableFields({
      objects: [
        {
          name: 'crm_account',
          fields: { name: { type: 'text' }, owner_id: { type: 'lookup', reference: 'sys_user' } },
          searchableFields: ['name', 'owner_id.name'],
        },
      ],
    });

    expect(findings).toHaveLength(1);
    expect(findings[0].path).toBe('objects[0].searchableFields[1]');
    expect(findings[0].hint).toContain("scans this object's own columns");
  });
});

describe('validateSearchableFields — list views that narrow the set', () => {
  const objectWithFields = {
    name: 'crm_account',
    fields: { name: { type: 'text' }, billing_email: { type: 'email' } },
  };

  it("flags a stale entry on an object's built-in named list view", () => {
    const findings = validateSearchableFields({
      objects: [
        { ...objectWithFields, listViews: { all: { type: 'grid', searchableFields: ['email'] } } },
      ],
    });

    expect(findings).toHaveLength(1);
    expect(findings[0].path).toBe('objects[0].listViews.all.searchableFields[0]');
    expect(findings[0].where).toBe('object "crm_account" › listViews.all');
  });

  it('flags a stale entry on a defineView default list, bound via data.object', () => {
    const findings = validateSearchableFields({
      objects: [objectWithFields],
      views: [
        {
          name: 'account_views',
          list: {
            type: 'grid',
            data: { provider: 'object', object: 'crm_account' },
            searchableFields: ['name', 'email'],
          },
        },
      ],
    });

    expect(findings).toHaveLength(1);
    expect(findings[0].path).toBe('views[0].list.searchableFields[1]');
    expect(findings[0].where).toBe('view "account_views" › list');
  });

  it('flags a stale entry on a named listViews entry', () => {
    const findings = validateSearchableFields({
      objects: [objectWithFields],
      views: [
        {
          objectName: 'crm_account',
          listViews: { active: { type: 'grid', searchableFields: ['email'] } },
        },
      ],
    });

    expect(findings).toHaveLength(1);
    expect(findings[0].path).toBe('views[0].listViews.active.searchableFields[0]');
  });

  it('passes list views whose narrowing resolves', () => {
    const findings = validateSearchableFields({
      objects: [
        {
          ...objectWithFields,
          listViews: { all: { type: 'grid', searchableFields: ['billing_email'] } },
        },
      ],
      views: [
        {
          objectName: 'crm_account',
          list: { type: 'grid', searchableFields: ['name'] },
          listViews: { active: { type: 'grid', searchableFields: ['name', 'billing_email'] } },
        },
      ],
    });

    expect(findings).toEqual([]);
  });

  it('flags a lookup entry the runtime would refuse — the #4830 defect', () => {
    // The issue's repro verbatim: `searchableFields: ['name', '<lookup>']` on a
    // view, validate all green, first keystroke in the toolbar search → the
    // whole query 400s (INVALID_FIELD) for every role. The runtime judgment
    // is `resolveSearchFieldResolution` (@objectstack/spec/data); this rule
    // consults the same function, so declared = enforced.
    const findings = validateSearchableFields({
      objects: [
        {
          name: 'ehr_task',
          fields: {
            name: { type: 'text' },
            project_id: { type: 'lookup', reference: 'ehr_project' },
          },
          listViews: { all: { type: 'grid', searchableFields: ['name', 'project_id'] } },
        },
      ],
    });

    expect(findings).toHaveLength(1);
    expect(findings[0].rule).toBe(SEARCHABLE_FIELD_UNSEARCHABLE);
    expect(findings[0].severity).toBe('error');
    expect(findings[0].path).toBe('objects[0].listViews.all.searchableFields[1]');
    expect(findings[0].message).toContain("type 'lookup'");
    expect(findings[0].message).toContain('400 INVALID_FIELD');
    // The lookup-specific prescription: search cannot cross objects, so the
    // related record's title must be mirrored onto a local text/formula field.
    expect(findings[0].hint).toContain('mirror');
  });

  it('flags a real field outside the object\'s declared searchableFields', () => {
    // Runtime parity, declared branch: the object declares the canonical set,
    // and the #4254 gate refuses a `$searchFields` entry outside it even when
    // the field exists and is text-like.
    const findings = validateSearchableFields({
      objects: [
        {
          name: 'crm_account',
          fields: {
            name: { type: 'text' },
            billing_email: { type: 'email' },
            notes: { type: 'textarea' },
          },
          searchableFields: ['name', 'billing_email'],
          listViews: { all: { type: 'grid', searchableFields: ['notes'] } },
        },
      ],
    });

    expect(findings).toHaveLength(1);
    expect(findings[0].rule).toBe(SEARCHABLE_FIELD_UNSEARCHABLE);
    expect(findings[0].message).toContain('name, billing_email');
    expect(findings[0].hint).toContain('crm_account.searchableFields');
  });

  it('passes a view entry of odd type once the object declares it searchable', () => {
    // The runtime's declared branch filters by EXISTENCE, never by type: a
    // json/lookup column declared on the OBJECT is honored by the engine and
    // admitted by the gate, so the view echoing it must stay green — flagging
    // it would reject metadata the runtime accepts.
    const findings = validateSearchableFields({
      objects: [
        {
          name: 'crm_account',
          fields: { name: { type: 'text' }, payload: { type: 'json' } },
          searchableFields: ['name', 'payload'],
          listViews: { all: { type: 'grid', searchableFields: ['payload'] } },
        },
      ],
    });

    expect(findings).toEqual([]);
  });

  it('flags a hidden field in a view narrowing (auto-default excludes it)', () => {
    const findings = validateSearchableFields({
      objects: [
        {
          name: 'crm_account',
          fields: { name: { type: 'text' }, secret_note: { type: 'text', hidden: true } },
          listViews: { all: { type: 'grid', searchableFields: ['secret_note'] } },
        },
      ],
    });

    expect(findings).toHaveLength(1);
    expect(findings[0].rule).toBe(SEARCHABLE_FIELD_UNSEARCHABLE);
    expect(findings[0].message).toContain('hidden');
  });

  it('checks defineView list and named listViews the same way', () => {
    const findings = validateSearchableFields({
      objects: [
        {
          name: 'crm_account',
          fields: { name: { type: 'text' }, owner_ref: { type: 'lookup', reference: 'sys_user' } },
        },
      ],
      views: [
        {
          objectName: 'crm_account',
          list: { type: 'grid', searchableFields: ['owner_ref'] },
          listViews: { active: { type: 'grid', searchableFields: ['owner_ref'] } },
        },
      ],
    });

    expect(findings.map((f) => [f.rule, f.path])).toEqual([
      [SEARCHABLE_FIELD_UNSEARCHABLE, 'views[0].list.searchableFields[0]'],
      [SEARCHABLE_FIELD_UNSEARCHABLE, 'views[0].listViews.active.searchableFields[0]'],
    ]);
  });

  it('keeps runtime parity when the object declares system columns searchable', () => {
    // The runtime resolves the declared branch against the REGISTRY map, so
    // `searchableFields: ['created_at']` is a non-empty declared set there —
    // NOT a fall-through to the auto-default. A view entry outside that set
    // must be flagged the way the gate refuses it, even though `created_at`
    // is invisible to the authored field map.
    const findings = validateSearchableFields({
      objects: [
        {
          name: 'audit_log',
          fields: { name: { type: 'text' }, detail: { type: 'textarea' } },
          searchableFields: ['created_at'],
          listViews: { all: { type: 'grid', searchableFields: ['detail'] } },
        },
      ],
    });

    expect(findings).toHaveLength(1);
    expect(findings[0].rule).toBe(SEARCHABLE_FIELD_UNSEARCHABLE);
    expect(findings[0].message).toContain('created_at');
  });

  it('leaves a system column in a view narrowing alone (registry meta invisible)', () => {
    // `created_at` in a narrowing would be refused by the runtime, but its
    // registry-side metadata is not visible to the linter — a judgment here
    // risks the false positive ADR-0072 D1 forbids, so it is a documented
    // missed finding instead.
    const findings = validateSearchableFields({
      objects: [
        {
          name: 'crm_account',
          fields: { name: { type: 'text' } },
          listViews: { all: { type: 'grid', searchableFields: ['name', 'created_at'] } },
        },
      ],
    });

    expect(findings).toEqual([]);
  });

  it('does not type-check the object\'s own canonical set (runtime honors it)', () => {
    const findings = validateSearchableFields({
      objects: [
        {
          name: 'crm_account',
          fields: { name: { type: 'text' }, owner_ref: { type: 'lookup', reference: 'sys_user' } },
          searchableFields: ['name', 'owner_ref'],
        },
      ],
    });

    expect(findings).toEqual([]);
  });

  it('skips a view bound to an object this stack does not define', () => {
    // The object may come from another package; a field map we cannot see
    // cannot be judged — the same skip the page/flow/widget rules take.
    const findings = validateSearchableFields({
      objects: [objectWithFields],
      views: [
        {
          name: 'foreign',
          list: {
            type: 'grid',
            data: { provider: 'object', object: 'pkg_contract' },
            searchableFields: ['no_such_field'],
          },
        },
      ],
    });

    expect(findings).toEqual([]);
  });
});