@yemi33/minions 0.1.2423 → 0.1.2425

package/engine/pr-issue-validation.js

@@ -0,0 +1,653 @@
+'use strict';
+
+const path = require('path');
+const apiValidation = require('./api-validation');
+const issues = require('./issues');
+const prAction = require('./pr-action');
+const prFixTarget = require('./pr-fix-target');
+const prResolve = require('./pr-resolve');
+const shared = require('./shared');
+
+const MAX_PR_REFERENCE_LENGTH = 2048;
+const MAX_CONTEXT_LENGTH = 16 * 1024;
+const MAX_ISSUE_DESCRIPTION_LENGTH = 64 * 1024;
+const MAX_ISSUE_LABELS = 20;
+const MAX_ISSUE_LABEL_LENGTH = 50;
+
+function hasOwn(value, key) {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+
+function inputError(message, options = {}) {
+  return new apiValidation.ApiInputError(message, {
+    statusCode: options.statusCode,
+    code: options.code || 'invalid-input',
+    field: options.field,
+    path: options.path || options.field,
+    expected: options.expected,
+    rejectedValue: options.rejectedValue,
+    allowedValues: options.allowedValues,
+    secret: options.secret === true,
+    cause: options.cause,
+  });
+}
+
+function validateBody(body) {
+  return apiValidation.validatePlainObject(body, {
+    field: 'body',
+    message: 'request body must be a JSON object',
+  });
+}
+
+function requiredString(value, field, options = {}) {
+  return apiValidation.validateString(value, {
+    field,
+    trim: options.trim !== false,
+    allowEmpty: false,
+    maxLength: options.maxLength,
+    secret: options.secret === true,
+    message: `${field} is required and must be a string`,
+  });
+}
+
+function optionalString(body, field, options = {}) {
+  if (!hasOwn(body, field) || body[field] === undefined || body[field] === null) {
+    return options.defaultValue;
+  }
+  return apiValidation.validateString(body[field], {
+    field,
+    trim: options.trim === true,
+    allowEmpty: options.allowEmpty !== false,
+    maxLength: options.maxLength,
+    message: `${field} must be a string`,
+  });
+}
+
+function optionalBoolean(body, field, defaultValue = false) {
+  if (!hasOwn(body, field) || body[field] === undefined) return defaultValue;
+  return apiValidation.validateBoolean(body[field], {
+    field,
+    message: `${field} must be a boolean`,
+  });
+}
+
+function positiveInteger(value, field) {
+  let candidate = value;
+  if (typeof candidate === 'string' && /^[0-9]+$/.test(candidate.trim())) {
+    candidate = Number(candidate.trim());
+  }
+  try {
+    return shared.validatePrNum(candidate);
+  } catch {
+    throw inputError(`${field} must be a positive safe integer`, {
+      field,
+      code: 'invalid-integer',
+      expected: 'positive safe integer',
+      rejectedValue: value,
+    });
+  }
+}
+
+function validatePrReference(value, field = 'url') {
+  const raw = requiredString(value, field, {
+    maxLength: MAX_PR_REFERENCE_LENGTH,
+    secret: true,
+  });
+  try {
+    const ref = prResolve.resolvePrActionRef({ url: raw }, prAction.PrActionError);
+    return { raw, ref };
+  } catch (cause) {
+    if (!(cause instanceof prAction.PrActionError)) throw cause;
+    throw inputError(`${field} must be a valid GitHub/ADO PR reference`, {
+      field,
+      code: 'invalid-pr-reference',
+      expected: 'GitHub/ADO PR URL or canonical PR id',
+      rejectedValue: raw,
+      secret: true,
+      cause,
+    });
+  }
+}
+
+function validateCanonicalPrId(value, field = 'prId') {
+  const raw = requiredString(value, field, {
+    maxLength: MAX_PR_REFERENCE_LENGTH,
+    secret: true,
+  });
+  if (!/^(github|ado):/i.test(raw)) {
+    throw inputError(`${field} must be a canonical GitHub/ADO PR id`, {
+      field,
+      code: 'invalid-pr-reference',
+      expected: 'github:owner/repo#number or ado:org/project/repo#number',
+      rejectedValue: raw,
+      secret: true,
+    });
+  }
+  try {
+    const { ref } = validatePrReference(raw, field);
+    return ref.id;
+  } catch (cause) {
+    if (!apiValidation.isApiInputError(cause)) throw cause;
+    throw inputError(`${field} must be a canonical GitHub/ADO PR id with a positive number`, {
+      field,
+      code: 'invalid-pr-reference',
+      expected: 'github:owner/repo#number or ado:org/project/repo#number',
+      rejectedValue: raw,
+      secret: true,
+      cause,
+    });
+  }
+}
+
+function validatePrDetailId(value) {
+  const raw = requiredString(value, 'id', {
+    maxLength: MAX_PR_REFERENCE_LENGTH,
+    secret: true,
+  });
+  if (/^[0-9]+$/.test(raw)) {
+    const number = positiveInteger(raw, 'id');
+    return { lookupId: String(number), canonicalId: null, number };
+  }
+  const canonicalId = validateCanonicalPrId(raw, 'id');
+  const ref = prResolve.normalizePrRef(canonicalId);
+  return { lookupId: canonicalId, canonicalId, number: ref.number };
+}
+
+function validatePrActionRequest(body) {
+  validateBody(body);
+  const { raw: url } = validatePrReference(body.url);
+  const execute = optionalBoolean(body, 'execute');
+  const draftOnly = optionalBoolean(body, 'draftOnly');
+  const resolved = prAction.resolvePrActionRequest({
+    url,
+    action: body.action,
+  });
+  if (draftOnly && resolved.action !== 'comment') {
+    throw inputError('draftOnly is only valid for the comment action', {
+      field: 'draftOnly',
+      code: 'invalid-combination',
+      rejectedValue: draftOnly,
+    });
+  }
+  return {
+    url,
+    action: resolved.action,
+    ref: resolved.ref,
+    execute,
+    draftOnly,
+  };
+}
+
+function validatePrFixRequest(body) {
+  validateBody(body);
+  const { raw: url, ref } = validatePrReference(body.url);
+  const remember = optionalBoolean(body, 'remember');
+  const reprompt = optionalBoolean(body, 'reprompt');
+  let target;
+  if (hasOwn(body, 'target')) {
+    target = requiredString(body.target, 'target', { maxLength: 64 }).toLowerCase();
+    if (!prFixTarget.EXECUTION_TARGET_IDS.includes(target)) {
+      throw inputError(`unknown execution target: ${JSON.stringify(body.target)}. Valid targets: ${prFixTarget.EXECUTION_TARGET_IDS.join(', ')}`, {
+        field: 'target',
+        code: 'invalid-enum',
+        rejectedValue: body.target,
+        allowedValues: prFixTarget.EXECUTION_TARGET_IDS,
+      });
+    }
+  }
+  if (remember && !target) {
+    throw inputError('remember requires an explicit target', {
+      field: 'remember',
+      code: 'invalid-combination',
+      rejectedValue: remember,
+    });
+  }
+  if (reprompt && target) {
+    throw inputError('reprompt cannot be combined with an explicit target', {
+      field: 'reprompt',
+      code: 'invalid-combination',
+      rejectedValue: reprompt,
+    });
+  }
+  return { url, ref, target, remember, reprompt };
+}
+
+function validatePrUrlRequest(body) {
+  validateBody(body);
+  const { raw: url, ref } = validatePrReference(body.url);
+  return { url, ref };
+}
+
+function resolveProject(projectName, projects) {
+  const name = requiredString(projectName, 'project', { maxLength: 128 });
+  const project = shared.findProjectByName(Array.isArray(projects) ? projects : [], name);
+  if (!project) {
+    throw inputError(`unknown project: ${name}`, {
+      statusCode: 404,
+      code: 'project-not-found',
+      field: 'project',
+      rejectedValue: name,
+    });
+  }
+  return { name: project.name, project };
+}
+
+function extractLinkedWorkItemId(context, workItemId) {
+  if (typeof workItemId === 'string' && workItemId.trim()) return workItemId.trim();
+  if (!context) return null;
+  if (typeof context === 'object' && !Array.isArray(context)
+      && typeof context.workItemId === 'string' && context.workItemId.trim()) {
+    return context.workItemId.trim();
+  }
+  if (typeof context === 'string') {
+    const match = context.match(/\b(P-[a-z0-9]{6,}|W-[a-z0-9]{6,}|PL-[a-z0-9]{6,})\b/i);
+    return match ? match[1] : null;
+  }
+  return null;
+}
+
+function validateLinkContext(context) {
+  if (context === undefined || context === null) return context;
+  if (typeof context === 'string') {
+    return apiValidation.validateString(context, {
+      field: 'context',
+      maxLength: MAX_CONTEXT_LENGTH,
+      message: 'context must be a string or plain object',
+    });
+  }
+  apiValidation.validatePlainObject(context, {
+    field: 'context',
+    message: 'context must be a string or plain object',
+  });
+  let encoded;
+  try { encoded = JSON.stringify(context); } catch {
+    throw inputError('context must be JSON serializable', {
+      field: 'context',
+      rejectedValue: context,
+    });
+  }
+  if (encoded.length > MAX_CONTEXT_LENGTH) {
+    throw inputError('context is too large', {
+      field: 'context',
+      code: 'invalid-string',
+      rejectedValue: context,
+    });
+  }
+  if (context && typeof context === 'object' && hasOwn(context, 'workItemId')) {
+    requiredString(context.workItemId, 'context.workItemId', { maxLength: 128 });
+  }
+  return context;
+}
+
+function validateWorkItemLink(workItemId, projectName, workItems) {
+  if (!workItemId) return;
+  const matches = (Array.isArray(workItems) ? workItems : [])
+    .filter(item => item && item.id === workItemId);
+  if (matches.length === 0) {
+    throw inputError(`work item ${workItemId} not found`, {
+      statusCode: 404,
+      code: 'work-item-not-found',
+      field: 'workItemId',
+      rejectedValue: workItemId,
+    });
+  }
+  if (!projectName && matches.length > 1) {
+    throw inputError(`work item ${workItemId} is ambiguous; specify project`, {
+      statusCode: 409,
+      code: 'work-item-link-conflict',
+      field: 'workItemId',
+      rejectedValue: workItemId,
+    });
+  }
+  if (projectName) {
+    const matchesProject = matches.some(item => {
+      const itemProject = String(item.project || item._source || '').trim();
+      return !itemProject || itemProject === 'central' || itemProject === projectName;
+    });
+    if (!matchesProject) {
+      throw inputError(`work item ${workItemId} does not belong to project ${projectName}`, {
+        statusCode: 409,
+        code: 'work-item-link-conflict',
+        field: 'workItemId',
+        rejectedValue: workItemId,
+      });
+    }
+  }
+}
+
+function inferProjectNameForRef(ref, projects) {
+  const matches = (Array.isArray(projects) ? projects : []).filter(project => {
+    if (shared.getProjectAllPrScopes(project).includes(ref.scope)) return true;
+    return ref.host === 'ado' && shared.isAdoPrScopeCompatible(ref.scope, project);
+  });
+  return matches.length === 1 ? matches[0].name : null;
+}
+
+function validatePrLinkRequest(body, options = {}) {
+  validateBody(body);
+  const { raw: url, ref } = validatePrReference(body.url);
+  const context = validateLinkContext(body.context);
+  const explicitWorkItemId = hasOwn(body, 'workItemId')
+    ? requiredString(body.workItemId, 'workItemId', { maxLength: 128 })
+    : null;
+  const nestedWorkItemId = extractLinkedWorkItemId(context, null);
+  if (explicitWorkItemId && nestedWorkItemId && explicitWorkItemId !== nestedWorkItemId) {
+    throw inputError('workItemId conflicts with context.workItemId', {
+      statusCode: 409,
+      code: 'work-item-link-conflict',
+      field: 'workItemId',
+      rejectedValue: explicitWorkItemId,
+    });
+  }
+  let project;
+  if (hasOwn(body, 'project') && body.project !== undefined && body.project !== null && body.project !== '') {
+    const resolved = resolveProject(body.project, options.projects);
+    project = resolved.name;
+    if (!shared.isPrCompatibleWithProject(resolved.project, ref)) {
+      throw inputError(`PR ${ref.id} does not belong to project ${project}`, {
+        statusCode: 409,
+        code: 'project-link-conflict',
+        field: 'project',
+        rejectedValue: project,
+      });
+    }
+  }
+  const workItemId = explicitWorkItemId || nestedWorkItemId || null;
+  const effectiveProject = project
+    || inferProjectNameForRef(ref, options.projects)
+    || 'central';
+  validateWorkItemLink(workItemId, effectiveProject, options.workItems);
+  const contextOnly = hasOwn(body, 'contextOnly')
+    ? apiValidation.validateBoolean(body.contextOnly, {
+      field: 'contextOnly',
+      message: 'contextOnly must be a boolean',
+    })
+    : undefined;
+  const title = optionalString(body, 'title', {
+    trim: true,
+    maxLength: 120,
+    defaultValue: undefined,
+  });
+  return {
+    ...body,
+    url,
+    ref,
+    ...(project ? { project } : {}),
+    ...(title !== undefined ? { title } : {}),
+    ...(contextOnly !== undefined ? { contextOnly } : {}),
+    ...(workItemId ? { workItemId } : {}),
+    ...(context !== undefined ? { context } : {}),
+  };
+}
+
+function validateGitBranch(value) {
+  const branch = requiredString(value, 'branch', { maxLength: 256 });
+  if (branch === 'HEAD') {
+    throw inputError('branch must be a valid non-reserved git branch name', {
+      field: 'branch',
+      code: 'invalid-git-ref',
+      rejectedValue: value,
+    });
+  }
+  try {
+    return shared.validateGitRef(branch);
+  } catch {
+    throw inputError('branch must be a valid git ref', {
+      field: 'branch',
+      code: 'invalid-git-ref',
+      rejectedValue: value,
+    });
+  }
+}
+
+function validateCreatePrRequest(body, options = {}) {
+  validateBody(body);
+  const kind = options.kind;
+  if (!['offer', 'prepare', 'cleanup'].includes(kind)) {
+    throw new TypeError(`unknown create-PR request kind: ${kind}`);
+  }
+  const { name: projectName, project } = resolveProject(body.project, options.projects);
+  const result = { projectName, project };
+  if (kind === 'offer') {
+    result.contextOnly = optionalBoolean(body, 'contextOnly');
+  }
+  if ((kind === 'offer' || kind === 'prepare') && hasOwn(body, 'branch')) {
+    result.branch = validateGitBranch(body.branch);
+  }
+  if (kind === 'cleanup') {
+    const worktreePath = requiredString(body.worktreePath, 'worktreePath', { maxLength: 4096 });
+    if (/[\u0000-\u001f\u007f]/.test(worktreePath)) {
+      throw inputError('worktreePath must not contain control characters', {
+        field: 'worktreePath',
+        code: 'invalid-path',
+        rejectedValue: worktreePath,
+      });
+    }
+    if (/^(?:\\\\|\/\/)/.test(worktreePath)) {
+      throw inputError('worktreePath must not be a network or device path', {
+        field: 'worktreePath',
+        code: 'invalid-path',
+        rejectedValue: worktreePath,
+      });
+    }
+    if (!path.isAbsolute(worktreePath)) {
+      throw inputError('worktreePath must be an absolute path', {
+        field: 'worktreePath',
+        code: 'invalid-path',
+        rejectedValue: worktreePath,
+      });
+    }
+    const resolvedPath = path.resolve(worktreePath);
+    const projectRoot = shared.resolveProjectRootDir(project.localPath, options.minionsDir);
+    const worktreeRoot = path.resolve(
+      projectRoot,
+      options.engine?.worktreeRoot || shared.ENGINE_DEFAULTS.worktreeRoot,
+    );
+    if (!shared.isPathInside(resolvedPath, worktreeRoot)) {
+      throw inputError('worktreePath must be inside the configured worktree root', {
+        field: 'worktreePath',
+        code: 'invalid-path',
+        rejectedValue: worktreePath,
+      });
+    }
+    result.worktreePath = resolvedPath;
+  }
+  return result;
+}
+
+function validatePrObserveRequest(body) {
+  validateBody(body);
+  const host = requiredString(body.host, 'host', { maxLength: 16 }).toLowerCase();
+  apiValidation.validateEnum(host, {
+    field: 'host',
+    values: ['github', 'ado'],
+    message: 'host must be "github" or "ado"',
+  });
+  const slug = requiredString(body.slug, 'slug', { maxLength: 512 });
+  const number = positiveInteger(body.number, 'number');
+  const ref = prResolve.normalizePrRef(`${host}:${slug}#${number}`);
+  if (!ref || ref.host !== host) {
+    throw inputError(`slug must match the canonical ${host} repository shape`, {
+      field: 'slug',
+      code: 'invalid-pr-scope',
+      rejectedValue: slug,
+    });
+  }
+  const hasContextOnly = hasOwn(body, 'contextOnly') && body.contextOnly !== undefined;
+  const hasObserve = hasOwn(body, 'observe') && body.observe !== undefined;
+  const contextOnly = hasContextOnly
+    ? apiValidation.validateBoolean(body.contextOnly, {
+      field: 'contextOnly',
+      message: 'contextOnly must be a boolean',
+    })
+    : undefined;
+  const observe = hasObserve
+    ? apiValidation.validateBoolean(body.observe, {
+      field: 'observe',
+      message: 'observe must be a boolean',
+    })
+    : undefined;
+  if (!hasContextOnly && !hasObserve) {
+    throw inputError('contextOnly (or legacy observe) must be a boolean', {
+      field: 'contextOnly',
+      code: 'missing-field',
+    });
+  }
+  return {
+    host: ref.host,
+    slug: ref.slug,
+    number: ref.number,
+    contextOnly: hasContextOnly ? contextOnly : !observe,
+  };
+}
+
+function validatePrDeleteRequest(body, options = {}) {
+  validateBody(body);
+  const rawId = requiredString(body.id, 'id', { maxLength: MAX_PR_REFERENCE_LENGTH });
+  let id;
+  if (/^(github|ado):/i.test(rawId)) {
+    id = validateCanonicalPrId(rawId, 'id');
+  } else {
+    const match = rawId.match(/^PR-([0-9]+)$/i) || rawId.match(/^([0-9]+)$/);
+    if (!match) {
+      throw inputError('id must be a canonical PR id, PR-number alias, or bare number', {
+        field: 'id',
+        code: 'invalid-pr-reference',
+        rejectedValue: rawId,
+      });
+    }
+    id = `PR-${positiveInteger(match[1], 'id')}`;
+  }
+  let project;
+  if (hasOwn(body, 'project') && body.project !== undefined && body.project !== null && body.project !== '') {
+    const projectName = requiredString(body.project, 'project', { maxLength: 128 });
+    const configured = shared.findProjectByName(
+      Array.isArray(options.projects) ? options.projects : [],
+      projectName,
+    );
+    if (!configured && !(options.trackedScopes || []).includes(projectName)) {
+      throw inputError(`unknown project: ${projectName}`, {
+        statusCode: 404,
+        code: 'project-not-found',
+        field: 'project',
+        rejectedValue: projectName,
+      });
+    }
+    project = configured?.name || projectName;
+  }
+  return { id, ...(project ? { project } : {}) };
+}
+
+function validatePauseClearRequest(body, options = {}) {
+  validateBody(body);
+  const kind = options.kind;
+  const result = { prId: validateCanonicalPrId(body.prId, 'prId') };
+  if (kind === 'cause') {
+    const cause = requiredString(body.cause, 'cause', { maxLength: 64 });
+    const allowed = Object.values(shared.PR_FIX_CAUSE);
+    apiValidation.validateEnum(cause, {
+      field: 'cause',
+      values: allowed,
+      message: `cause must be one of: ${allowed.join(', ')}`,
+    });
+    result.cause = cause;
+  } else if (kind === 'build-fix-ineffective') {
+    const headSha = optionalString(body, 'headSha', {
+      trim: true,
+      maxLength: 64,
+      defaultValue: '',
+    });
+    if (headSha && !/^[0-9a-f]{7,64}$/i.test(headSha)) {
+      throw inputError('headSha must be a 7-64 character hexadecimal commit id', {
+        field: 'headSha',
+        code: 'invalid-identifier',
+        rejectedValue: headSha,
+      });
+    }
+    result.headSha = headSha;
+  } else if (kind !== 'worktree-held') {
+    throw new TypeError(`unknown pause-clear request kind: ${kind}`);
+  }
+  return result;
+}
+
+function validateNoInputRequest(body, label = 'request') {
+  validateBody(body);
+  if (Object.keys(body).length > 0) {
+    throw inputError(`${label} does not accept request body fields`, {
+      field: 'body',
+      code: 'unexpected-input',
+      rejectedValue: body,
+    });
+  }
+  return {};
+}
+
+function validateIssueLabels(labels) {
+  if (labels === undefined || labels === null) return undefined;
+  if (typeof labels !== 'string' && !Array.isArray(labels)) {
+    throw inputError('labels must be a comma-separated string or an array of strings', {
+      field: 'labels',
+      code: 'invalid-array',
+      rejectedValue: labels,
+    });
+  }
+  const raw = typeof labels === 'string' ? labels.split(',') : labels;
+  apiValidation.validateArray(raw, {
+    field: 'labels',
+    maxLength: MAX_ISSUE_LABELS,
+    itemValidator: (entry, context) => {
+      const label = apiValidation.validateString(entry, {
+        field: 'labels',
+        path: context.path,
+        trim: true,
+        allowEmpty: false,
+        maxLength: MAX_ISSUE_LABEL_LENGTH,
+        message: 'labels entries must be non-empty strings',
+      });
+      if (/[\u0000-\u001f\u007f]/.test(label)) {
+        throw inputError('labels entries must not contain control characters', {
+          field: 'labels',
+          path: context.path,
+          rejectedValue: label,
+        });
+      }
+    },
+  });
+  const normalized = issues.normalizeLabels(raw, []);
+  return normalized;
+}
+
+function validateIssueCreateRequest(body) {
+  validateBody(body);
+  const title = requiredString(body.title, 'title', { maxLength: 256 });
+  if (/[\u0000-\u001f\u007f]/.test(title)) {
+    throw inputError('title must not contain control characters', {
+      field: 'title',
+      code: 'invalid-string',
+      rejectedValue: title,
+    });
+  }
+  const description = optionalString(body, 'description', {
+    maxLength: MAX_ISSUE_DESCRIPTION_LENGTH,
+    defaultValue: '',
+  });
+  const labels = validateIssueLabels(body.labels);
+  return { title, description, labels };
+}
+
+module.exports = {
+  MAX_ISSUE_LABELS,
+  validatePrDetailId,
+  validatePrActionRequest,
+  validatePrFixRequest,
+  validatePrUrlRequest,
+  validatePrLinkRequest,
+  validateCreatePrRequest,
+  validatePrObserveRequest,
+  validatePrDeleteRequest,
+  validatePauseClearRequest,
+  validateNoInputRequest,
+  validateIssueCreateRequest,
+  extractLinkedWorkItemId,
+};