[9.2] Add shared validation runner package (#258768)

.github/CODEOWNERS

@@ -483,6 +483,7 @@ src/platform/packages/shared/kbn-dev-cli-errors @elastic/kibana-operations
 src/platform/packages/shared/kbn-dev-cli-runner @elastic/kibana-operations
 src/platform/packages/shared/kbn-dev-proc-runner @elastic/kibana-operations
 src/platform/packages/shared/kbn-dev-utils @elastic/kibana-operations
+src/platform/packages/shared/kbn-dev-validation-runner @elastic/kibana-operations
 src/platform/packages/shared/kbn-discover-contextual-components @elastic/obs-exploration-team @elastic/kibana-data-discovery
 src/platform/packages/shared/kbn-discover-utils @elastic/kibana-data-discovery
 src/platform/packages/shared/kbn-doc-links @elastic/docs

package.json

@@ -1577,6 +1577,7 @@
     "@kbn/dev-cli-runner": "link:src/platform/packages/shared/kbn-dev-cli-runner",
     "@kbn/dev-proc-runner": "link:src/platform/packages/shared/kbn-dev-proc-runner",
     "@kbn/dev-utils": "link:src/platform/packages/shared/kbn-dev-utils",
+    "@kbn/dev-validation-runner": "link:src/platform/packages/shared/kbn-dev-validation-runner",
     "@kbn/docs-utils": "link:packages/kbn-docs-utils",
     "@kbn/dot-text": "link:src/platform/packages/private/kbn-dot-text",
     "@kbn/dot-text-loader": "link:src/platform/packages/private/kbn-dot-text-loader",

packages/kbn-moon/moon.yml

@@ -19,6 +19,7 @@ project:
     sourceRoot: packages/kbn-moon
 dependsOn:
   - '@kbn/repo-info'
+  - '@kbn/dev-utils'
   - '@kbn/dev-cli-runner'
   - '@kbn/repo-packages'
   - '@kbn/tooling-log'

packages/kbn-moon/src/index.ts

@@ -8,5 +8,29 @@
  */
 
 import { regenerateMoonProjects } from './cli/regenerate_moon_projects';
+import {
+  getAffectedMoonProjectsFromChangedFiles,
+  getMoonExecutablePath,
+  normalizeRepoRelativePath,
+  resolveMoonAffectedBase,
+  ROOT_MOON_PROJECT_ID,
+  summarizeAffectedMoonProjects,
+} from './query_projects';
+import { getMoonChangedFiles } from './query_changed_files';
 
-export { regenerateMoonProjects };
+export {
+  regenerateMoonProjects,
+  getAffectedMoonProjectsFromChangedFiles,
+  getMoonChangedFiles,
+  getMoonExecutablePath,
+  normalizeRepoRelativePath,
+  resolveMoonAffectedBase,
+  ROOT_MOON_PROJECT_ID,
+  summarizeAffectedMoonProjects,
+};
+export type {
+  MoonProject,
+  MoonDownstreamMode,
+  MoonAffectedBase,
+  MoonAffectedProjectSummary,
+} from './query_projects';

packages/kbn-moon/src/query_changed_files.ts

@@ -0,0 +1,78 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+import { existsSync } from 'fs';
+import Path from 'path';
+
+import { REPO_ROOT } from '@kbn/repo-info';
+
+import { getMoonExecutablePath, normalizeRepoRelativePath } from './query_projects';
+
+type ChangedFilesScope = 'local' | 'staged' | 'branch';
+
+export interface GetMoonChangedFilesOptions {
+  scope: ChangedFilesScope;
+  base?: string;
+  head?: string;
+}
+
+interface MoonChangedFilesResponse {
+  files: string[];
+}
+
+/** Builds CLI args for `moon query changed-files` based on scope. */
+export const buildChangedFilesArgs = ({ scope, base, head }: GetMoonChangedFilesOptions) => {
+  const args = ['query', 'changed-files'];
+
+  switch (scope) {
+    case 'local':
+      args.push('--local');
+      break;
+    case 'staged':
+      args.push('--local', '--status', 'staged');
+      break;
+    case 'branch':
+      if (base) args.push('--base', base);
+      if (head) args.push('--head', head);
+      break;
+  }
+
+  return args;
+};
+
+/**
+ * Queries Moon for changed files in the given scope.
+ *
+ * Returns repo-relative paths of files that exist on disk (deleted files are excluded).
+ */
+export const getMoonChangedFiles = async ({
+  scope,
+  base,
+  head,
+}: GetMoonChangedFilesOptions): Promise<string[]> => {
+  const execa = (await import('execa')).default;
+  const moonExec = await getMoonExecutablePath();
+  const args = buildChangedFilesArgs({ scope, base, head });
+
+  const { stdout } = await execa(moonExec, args, {
+    cwd: REPO_ROOT,
+    stdin: 'ignore',
+    env: {
+      ...process.env,
+      CI_STATS_DISABLED: 'true',
+    },
+  });
+
+  const { files } = JSON.parse(stdout) as MoonChangedFilesResponse;
+
+  return files
+    .map(normalizeRepoRelativePath)
+    .filter((file) => existsSync(Path.resolve(REPO_ROOT, file)))
+    .sort((a, b) => a.localeCompare(b));
+};

packages/kbn-moon/src/query_projects.ts

@@ -0,0 +1,180 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+import Path from 'path';
+import { existsSync } from 'fs';
+
+import {
+  getRemoteDefaultBranchRefs,
+  resolveNearestMergeBase,
+  type ValidationDownstreamMode,
+} from '@kbn/dev-utils';
+import { REPO_ROOT } from '@kbn/repo-info';
+
+export type MoonDownstreamMode = ValidationDownstreamMode;
+
+/** Minimal Moon project metadata needed for affected-source resolution. */
+export interface MoonProject {
+  id: string;
+  sourceRoot: string;
+}
+
+/** Derived summary of affected projects for root-project escalation handling. */
+export interface MoonAffectedProjectSummary {
+  sourceRoots: string[];
+  isRootProjectAffected: boolean;
+}
+
+/** Resolved base revision metadata for Moon affected queries. */
+export interface MoonAffectedBase {
+  base: string;
+  baseRef: string;
+}
+
+interface MoonQueryProjectsResponse {
+  projects: Array<{
+    id: string;
+    source: string;
+    config?: {
+      project?: {
+        metadata?: {
+          sourceRoot?: string;
+        };
+      };
+    };
+  }>;
+}
+
+/** Options for resolving the affected base revision from git state. */
+export interface ResolveMoonAffectedBaseOptions {
+  headRef?: string;
+}
+
+export const ROOT_MOON_PROJECT_ID = 'kibana';
+
+let moonExecutablePath: string | undefined;
+
+/** Normalizes repository-relative paths to POSIX separators for stable matching. */
+export const normalizeRepoRelativePath = (pathValue: string) =>
+  Path.normalize(pathValue).split(Path.sep).join('/');
+
+/** Resolves the path to the Moon executable. */
+export const getMoonExecutablePath = async () => {
+  if (moonExecutablePath) {
+    return moonExecutablePath;
+  }
+
+  const moonBinPath = Path.resolve(REPO_ROOT, 'node_modules/.bin/moon');
+  if (existsSync(moonBinPath)) {
+    moonExecutablePath = moonBinPath;
+    return moonExecutablePath;
+  }
+
+  const execa = (await import('execa')).default;
+  const { stdout } = await execa('yarn', ['--silent', 'which', 'moon'], {
+    cwd: REPO_ROOT,
+    stdin: 'ignore',
+  });
+
+  moonExecutablePath = stdout.trim();
+  return moonExecutablePath;
+};
+
+/** Resolves the base revision used for Moon affected comparisons. */
+export const resolveMoonAffectedBase = async ({
+  headRef = 'HEAD',
+}: ResolveMoonAffectedBaseOptions = {}): Promise<MoonAffectedBase> => {
+  const envBase = process.env.GITHUB_PR_MERGE_BASE?.trim();
+  if (envBase) {
+    return {
+      base: envBase,
+      baseRef: 'GITHUB_PR_MERGE_BASE',
+    };
+  }
+
+  const baseRefs = await getRemoteDefaultBranchRefs();
+  if (baseRefs.length === 0) {
+    throw new Error(
+      'Unable to resolve a remote default branch for affected type check. Set GITHUB_PR_MERGE_BASE to override.'
+    );
+  }
+
+  const bestCandidate = await resolveNearestMergeBase({
+    baseRefs,
+    headRef,
+  });
+  if (!bestCandidate) {
+    throw new Error(
+      `Unable to resolve merge-base for affected type check from remote default branches: ${baseRefs.join(
+        ', '
+      )}.`
+    );
+  }
+
+  return {
+    base: bestCandidate.mergeBase,
+    baseRef: bestCandidate.baseRef,
+  };
+};
+
+const parseMoonProjectsResponse = (stdout: string): MoonProject[] => {
+  const response = JSON.parse(stdout) as MoonQueryProjectsResponse;
+  return response.projects.map((project) => {
+    const sourceRoot = project.config?.project?.metadata?.sourceRoot ?? project.source;
+    return {
+      id: project.id,
+      sourceRoot: normalizeRepoRelativePath(sourceRoot),
+    };
+  });
+};
+
+/**
+ * Queries Moon for affected projects by piping pre-resolved changed files JSON
+ * into `moon query projects --affected`.
+ *
+ * Use this when changed files have already been resolved to avoid duplicate Moon queries.
+ */
+export const getAffectedMoonProjectsFromChangedFiles = async ({
+  changedFilesJson,
+  downstream = 'none',
+}: {
+  changedFilesJson: string;
+  downstream?: MoonDownstreamMode;
+}): Promise<MoonProject[]> => {
+  const execa = (await import('execa')).default;
+  const moonExec = await getMoonExecutablePath();
+
+  const projectArgs = ['query', 'projects', '--affected'];
+  if (downstream !== 'none') {
+    projectArgs.push('--downstream', downstream);
+  }
+
+  const { stdout } = await execa(moonExec, projectArgs, {
+    cwd: REPO_ROOT,
+    input: changedFilesJson,
+    env: {
+      ...process.env,
+      CI_STATS_DISABLED: 'true',
+    },
+  });
+
+  return parseMoonProjectsResponse(stdout);
+};
+
+/** Summarizes affected Moon projects into non-root source roots and root-project flag. */
+export const summarizeAffectedMoonProjects = (
+  projects: MoonProject[]
+): MoonAffectedProjectSummary => {
+  const nonRootProjects = projects.filter((project) => project.id !== ROOT_MOON_PROJECT_ID);
+
+  return {
+    sourceRoots: nonRootProjects.map((project) => project.sourceRoot),
+    isRootProjectAffected: projects.some((project) => project.id === ROOT_MOON_PROJECT_ID),
+  };
+};

packages/kbn-moon/tsconfig.json

@@ -17,6 +17,7 @@
   ],
   "kbn_references": [
     "@kbn/repo-info",
+    "@kbn/dev-utils",
     "@kbn/dev-cli-runner",
     "@kbn/repo-packages",
     "@kbn/tooling-log"

src/platform/packages/shared/kbn-dev-utils/index.ts

@@ -32,4 +32,13 @@ export * from './src/streams';
 export * from './src/extract';
 export * from './src/diff_strings';
 export * from './src/git';
+export {
+  parseAndResolveValidationContract,
+  VALIDATION_PROFILE_DEFAULTS,
+  type ValidationDownstreamMode,
+  type ValidationProfile,
+  type ResolvedValidationContract,
+  type ValidationScope,
+  type ValidationTestMode,
+} from './src/validation_run_contract';
 export * from './src/worker';

src/platform/packages/shared/kbn-dev-validation-runner/README.md

@@ -0,0 +1,3 @@
+# @kbn/dev-validation-runner
+
+Shared orchestration helpers for validation-style developer CLIs.

src/platform/packages/shared/kbn-dev-validation-runner/index.ts

@@ -0,0 +1,28 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+export {
+  describeValidationScope,
+  describeValidationNoTargetsScope,
+  describeValidationScoping,
+  resolveValidationBaseContext,
+} from './src/run_validation_command';
+export type { ValidationBaseContext } from './src/run_validation_command';
+export {
+  resolveValidationAffectedProjects,
+  type ValidationAffectedProjectsContext,
+} from './src/resolve_validation_run_context';
+export {
+  buildValidationCliArgs,
+  formatReproductionCommand,
+  hasValidationRunFlags,
+  readValidationRunFlags,
+  VALIDATION_RUN_HELP,
+  VALIDATION_RUN_STRING_FLAGS,
+} from './src/validation_run_cli';

src/platform/packages/shared/kbn-dev-validation-runner/jest.config.js

@@ -0,0 +1,14 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+module.exports = {
+  preset: '@kbn/test',
+  rootDir: '../../../../..',
+  roots: ['<rootDir>/src/platform/packages/shared/kbn-dev-validation-runner'],
+};

src/platform/packages/shared/kbn-dev-validation-runner/kibana.jsonc

@@ -0,0 +1,10 @@
+{
+  "type": "shared-common",
+  "id": "@kbn/dev-validation-runner",
+  "owner": [
+    "@elastic/kibana-operations"
+  ],
+  "group": "platform",
+  "visibility": "shared",
+  "devOnly": true
+}