feat(query-enhancements): PPL lint backend — feature flag + explain/calcite proxy routes

src/plugins/query_enhancements/common/config.ts

@@ -31,6 +31,11 @@ export const configSchema = schema.object({
       }),
     }),
   }),
+  // PPL linter feature flag, read at runtime via DynamicConfigService and
+  // surfaced as the queryEnhancements.pplLint capability. Disabled by default.
+  pplLint: schema.object({
+    enabled: schema.boolean({ defaultValue: false }),
+  }),
 });
 
 export type ConfigSchema = TypeOf<typeof configSchema>;

src/plugins/query_enhancements/common/constants.ts

@@ -44,6 +44,8 @@ export const API = {
   },
   PPL_CANCEL: `${BASE_API}/ppl/cancel`,
   PPL_GRAMMAR: `${BASE_API}/ppl/grammar`,
+  PPL_CALCITE_SETTINGS: `${BASE_API}/ppl/calcite_settings`,
+  PPL_EXPLAIN: `${BASE_API}/ppl/explain`,
   AGENT_API: {
     CONFIG_EXISTS: `${BASE_API_ASSISTANT}/agent_config/_exists`,
   },

src/plugins/query_enhancements/server/plugin.test.ts

@@ -0,0 +1,143 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { coreMock, dynamicConfigServiceMock } from '../../../core/server/mocks';
+import { dataPluginMock } from '../../data/server/mocks';
+import { QueryEnhancementsPlugin } from './plugin';
+
+describe('QueryEnhancementsPlugin pplLint capability', () => {
+  const baseCapabilities = () =>
+    ({
+      navLinks: {},
+      management: {},
+      catalogue: {},
+      queryEnhancements: { pplLint: false },
+    } as any);
+
+  // Run the real setup() against core mocks and hand back the registered
+  // capability switcher plus the plugin's logger so the catch path is
+  // observable. No production change is needed — the switcher is captured from
+  // the registerSwitcher mock.
+  const setupPlugin = () => {
+    const initializerContext = coreMock.createPluginInitializerContext();
+    const plugin = new QueryEnhancementsPlugin(initializerContext);
+    const core = coreMock.createSetup();
+    const deps = { data: dataPluginMock.createSetupContract() } as any;
+
+    plugin.setup(core, deps);
+
+    const registerSwitcher = core.capabilities.registerSwitcher as jest.Mock;
+    const switcher = registerSwitcher.mock.calls[0][0];
+    // this.logger = initializerContext.logger.get(); the loggingSystem mock
+    // shares one logger instance, so this is the same logger the plugin holds.
+    const logger = initializerContext.logger.get();
+    return { core, switcher, logger };
+  };
+
+  const stubConfig = (
+    core: any,
+    getConfig: Record<string, any>,
+    asyncLocalStore?: Map<string, any>
+  ) => {
+    const startContract = dynamicConfigServiceMock.createStartContract(
+      {
+        getConfig,
+        bulkGetConfigs: new Map(),
+        listConfigs: new Map(),
+      },
+      asyncLocalStore
+    );
+    core.dynamicConfigService.getStartService.mockResolvedValue(startContract);
+    return startContract;
+  };
+
+  it('registers a disabled-by-default pplLint capability provider', () => {
+    const { core } = setupPlugin();
+    const registerProvider = core.capabilities.registerProvider as jest.Mock;
+    const provided = registerProvider.mock.calls[0][0]();
+    expect(provided).toEqual({ queryEnhancements: { pplLint: false } });
+  });
+
+  it('enables pplLint when the dynamic config flag is on', async () => {
+    const { core, switcher } = setupPlugin();
+    const startContract = stubConfig(core, { pplLint: { enabled: true } });
+
+    const result = await switcher({} as any, baseCapabilities());
+
+    expect(result.queryEnhancements.pplLint).toBe(true);
+    // Guard the documented footgun: the lookup MUST use pluginConfigPath, not
+    // { name: 'queryEnhancements' } (which snake-cases to the wrong namespace,
+    // throws, gets swallowed, and disables pplLint forever). The shared mock
+    // returns the stub for any argument, so without this assertion a regression
+    // to { name } would pass every test.
+    const getConfigMock = startContract.getClient().getConfig as jest.Mock;
+    expect(getConfigMock).toHaveBeenCalledTimes(1);
+    expect(getConfigMock.mock.calls[0][0]).toEqual({ pluginConfigPath: ['queryEnhancements'] });
+  });
+
+  it('passes the async local store as context when one is present', async () => {
+    const { core, switcher } = setupPlugin();
+    const store = new Map<string, any>([['k', 'v']]);
+    const startContract = stubConfig(core, { pplLint: { enabled: true } }, store);
+
+    await switcher({} as any, baseCapabilities());
+
+    const getConfigMock = startContract.getClient().getConfig as jest.Mock;
+    expect(getConfigMock.mock.calls[0][1]).toEqual({ asyncLocalStorageContext: store });
+  });
+
+  it('omits the options object when no async local store is present', async () => {
+    const { core, switcher } = setupPlugin();
+    // No store passed → getAsyncLocalStore() returns undefined. The switcher
+    // must pass `undefined` rather than { asyncLocalStorageContext: undefined }.
+    const startContract = stubConfig(core, { pplLint: { enabled: true } });
+
+    await switcher({} as any, baseCapabilities());
+
+    const getConfigMock = startContract.getClient().getConfig as jest.Mock;
+    expect(getConfigMock.mock.calls[0][1]).toBeUndefined();
+  });
+
+  it('coerces a non-boolean stored flag to false (unvalidated dynamic config)', async () => {
+    const { core, switcher } = setupPlugin();
+    // Dynamic config writes are not schema-validated, so the store can hold a
+    // string. Only a real boolean `true` may enable the flag.
+    stubConfig(core, { pplLint: { enabled: 'true' } } as any);
+
+    const result = await switcher({} as any, baseCapabilities());
+
+    expect(result.queryEnhancements.pplLint).toBe(false);
+  });
+
+  it('leaves pplLint off when the dynamic config flag is false', async () => {
+    const { core, switcher } = setupPlugin();
+    stubConfig(core, { pplLint: { enabled: false } });
+
+    const result = await switcher({} as any, baseCapabilities());
+
+    expect(result.queryEnhancements.pplLint).toBe(false);
+  });
+
+  it('leaves pplLint off when the dynamic config is absent', async () => {
+    const { core, switcher } = setupPlugin();
+    stubConfig(core, {});
+
+    const result = await switcher({} as any, baseCapabilities());
+
+    expect(result.queryEnhancements.pplLint).toBe(false);
+  });
+
+  it('returns capabilities unchanged and logs when loading dynamic config throws', async () => {
+    const { core, switcher, logger } = setupPlugin();
+    core.dynamicConfigService.getStartService.mockRejectedValue(new Error('no config store'));
+
+    const capabilities = baseCapabilities();
+    const result = await switcher({} as any, capabilities);
+
+    expect(result).toBe(capabilities);
+    expect(result.queryEnhancements.pplLint).toBe(false);
+    expect(logger.error).toHaveBeenCalled();
+  });
+});

src/plugins/query_enhancements/server/plugin.ts

@@ -50,6 +50,49 @@ export class QueryEnhancementsPlugin
 
   public setup(core: CoreSetup, { data, dataSource }: QueryEnhancementsPluginSetupDependencies) {
     this.logger.debug('queryEnhancements: Setup');
+
+    // PPL lint capability — disabled by default until an operator enables it via
+    // the queryEnhancements.pplLint dynamic app config flag (see the switcher
+    // below). A follow-up PR will have the public plugin read
+    // capabilities.queryEnhancements.pplLint to decide whether to register the
+    // lint bridge; nothing consumes this capability yet.
+    core.capabilities.registerProvider(() => ({
+      queryEnhancements: { pplLint: false },
+    }));
+
+    // Override the default with the value from DynamicConfigService.
+    core.capabilities.registerSwitcher(async (request, capabilities) => {
+      try {
+        const dynamicConfigServiceStart = await core.dynamicConfigService.getStartService();
+        const client = dynamicConfigServiceStart.getClient();
+        const store = dynamicConfigServiceStart.getAsyncLocalStore();
+
+        // Use pluginConfigPath, NOT { name: 'queryEnhancements' }: pathToString
+        // runs _.snakeCase on `name`, turning 'queryEnhancements' into
+        // 'query_enhancements' — the wrong namespace, which would throw, be
+        // swallowed here, and leave pplLint off forever. pluginConfigPath joins
+        // verbatim and matches configPath: ['queryEnhancements'] in the manifest.
+        const config = await client.getConfig(
+          { pluginConfigPath: ['queryEnhancements'] },
+          store ? { asyncLocalStorageContext: store } : undefined
+        );
+
+        // Return only the changed subtree; recursiveApplyChanges merges it onto
+        // the resolved capabilities. `=== true` coerces explicitly — dynamic
+        // config writes are not schema-validated, so the stored value could be a
+        // non-boolean (e.g. the string 'true') that must not leak into the flag.
+        return {
+          queryEnhancements: {
+            ...(capabilities.queryEnhancements || {}),
+            pplLint: config.pplLint?.enabled === true,
+          },
+        };
+      } catch (error) {
+        this.logger.error('Failed to load queryEnhancements dynamic config, using defaults', error);
+        return capabilities;
+      }
+    });
+
     const router = core.http.createRouter();
     // Register server side APIs
     const client = core.opensearch.legacy.createClient('opensearch_enhancements', {

src/plugins/query_enhancements/server/routes/index.ts

@@ -8,6 +8,8 @@ import {
   IOpenSearchDashboardsResponse,
   IRouter,
   Logger,
+  OpenSearchClient,
+  RequestHandlerContext,
   ResponseError,
 } from '../../../../core/server';
 import { IDataFrameResponse, IOpenSearchDashboardsSearchRequest } from '../../../data/common';
@@ -17,16 +19,40 @@ import { registerQueryAssistRoutes } from './query_assist';
 import { registerDataSourceConnectionsRoutes } from './data_source_connection';
 import { registerResourceRoutes } from './resources';
 import { registerPPLCancelRoute } from './ppl_cancel';
+import { definePPLCalciteSettingsRoute } from './ppl_calcite_settings';
+import { definePPLExplainRoute } from './ppl_explain';
 
 /**
  * Coerce status code to 503 for 500 errors from dependency services. Only use
  * this function to handle errors throw by other services, and not from OSD.
  */
-export const coerceStatusCode = (statusCode: number) => {
+export const coerceStatusCode = (statusCode?: number) => {
   if (statusCode === 500) return 503;
   return statusCode || 503;
 };
 
+export const DATASOURCE_UNAVAILABLE_MESSAGE =
+  'dataSourceId is not supported because data source plugin is unavailable';
+
+/**
+ * Resolves the OpenSearch client for an optional dataSourceId. Returns the
+ * data source's client when a dataSourceId is given, the current-user client
+ * otherwise, or `null` when a dataSourceId is requested but the data source
+ * plugin is unavailable (the caller should respond 400 in that case).
+ */
+export async function resolveOpenSearchClient(
+  context: RequestHandlerContext,
+  dataSourceId?: string
+): Promise<OpenSearchClient | null> {
+  if (dataSourceId) {
+    if (!context.dataSource?.opensearch?.getClient) {
+      return null;
+    }
+    return context.dataSource.opensearch.getClient(dataSourceId);
+  }
+  return context.core.opensearch.client.asCurrentUser;
+}
+
 /**
  * @experimental
  *
@@ -192,4 +218,6 @@ export function defineRoutes(
   registerPPLCancelRoute(router, logger);
 
   definePPLBundleRoute(logger, router);
+  definePPLCalciteSettingsRoute(logger, router);
+  definePPLExplainRoute(logger, router);
 }