dd-trace 6.4.0 → 6.6.0

package/ci/test-optimization-validation/manifest-schema.js

@@ -0,0 +1,862 @@
+'use strict'
+
+const path = require('path')
+
+const { getArtifactId } = require('./artifact-id')
+const {
+  MAX_GENERATED_FILES,
+  getGeneratedFileContentError,
+} = require('./generated-file-policy')
+const { getInlineDatadogInitialization } = require('./local-command')
+const {
+  hasUnsafeExecutionCharacter,
+  hasUnsafeInvisibleCharacter,
+  isSensitiveName,
+  sanitizeForReport,
+  sanitizeString,
+} = require('./redaction')
+
+const FRAMEWORKS = new Set([
+  'jest',
+  'vitest',
+  'mocha',
+  'cucumber',
+  'cypress',
+  'playwright',
+  'node:test',
+  'ava',
+  'tap',
+  'jasmine',
+  'karma',
+  'uvu',
+  'testcafe',
+  'custom',
+  'unknown',
+])
+
+const STATUSES = new Set([
+  'runnable',
+  'detected_not_runnable',
+  'requires_external_service',
+  'requires_manual_setup',
+  'unsupported_by_validator',
+  'unknown',
+])
+const CI_WIRING_STATUSES = new Set([
+  'pass',
+  'fail',
+  'skip',
+  'unknown',
+])
+const CI_WIRING_REPLAYABILITIES = new Set(['replayable', 'not_replayable'])
+const CI_INITIALIZATION_STATUSES = new Set(['configured', 'not_configured', 'unknown'])
+const UNRESOLVED_PLACEHOLDER_PATTERN = /\$\{[^}]+\}/
+const ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/
+const MAX_COMMAND_TIMEOUT_MS = 30 * 60 * 1000
+const MAX_FRAMEWORKS = 100
+const MAX_MANIFEST_ARRAY_ENTRIES = 1000
+const MAX_SETUP_COMMANDS = 100
+const MAX_VALIDATION_ERRORS = 50
+const MAX_REPRESENTATIVE_TESTS = 1000
+const SECRET_PLACEHOLDER = 'dd-validation-placeholder'
+const SAFE_SECRET_FIELD_VALUES = new Set(['', '0', '1', 'false', 'true', 'none', 'disabled'])
+const COMMAND_FIELDS = new Set([
+  'argv',
+  'cwd',
+  'description',
+  'env',
+  'required',
+  'requiredEnvVars',
+  'shell',
+  'shellCommand',
+  'shellReason',
+  'timeoutMs',
+  'usesShell',
+  'id',
+  'outputPaths',
+])
+
+const GENERATED_SCENARIO_IDS = new Set([
+  'basic-pass',
+  'atr-fail-once',
+  'test-management-target',
+])
+const GENERATED_SCENARIO_EXIT_CODES = {
+  'basic-pass': 0,
+  'atr-fail-once': 1,
+  'test-management-target': 0,
+}
+
+function validateManifest (manifest) {
+  const errors = createErrorCollector()
+
+  if (!manifest || typeof manifest !== 'object') {
+    return ['Manifest must be a JSON object.']
+  }
+
+  requiredString(manifest, 'schemaVersion', errors)
+  requiredObject(manifest, 'repository', errors)
+  requiredObject(manifest, 'environment', errors)
+  requiredArray(manifest, 'frameworks', errors)
+  if (Array.isArray(manifest.frameworks) && manifest.frameworks.length === 0) {
+    errors.push('frameworks must include at least one framework entry.')
+  }
+  validateArrayLimit(manifest, 'frameworks', MAX_FRAMEWORKS, errors)
+  validateArrayLimit(manifest, 'omitted', MAX_MANIFEST_ARRAY_ENTRIES, errors)
+  validateArrayLimit(manifest, 'omittedTestCommands', MAX_MANIFEST_ARRAY_ENTRIES, errors)
+
+  if (manifest.repository) {
+    requiredAbsolutePath(manifest.repository, 'root', errors)
+  }
+
+  if (manifest.ciDiscovery) {
+    validateCiDiscovery(manifest.ciDiscovery, 'ciDiscovery', errors)
+  }
+
+  if (Array.isArray(manifest.frameworks)) {
+    const frameworks = manifest.frameworks.slice(0, MAX_FRAMEWORKS)
+    validateUniqueFrameworkIds(frameworks, errors)
+    validateUniqueArtifactIds(frameworks, errors)
+    validateDuplicateRunnableCoverage(frameworks, errors)
+    validateGeneratedPathCollisions(frameworks, errors)
+    for (const [index, framework] of frameworks.entries()) {
+      validateFramework(framework, index, errors)
+    }
+  }
+
+  validateRepositoryContainedPaths(manifest, errors)
+
+  return errors.finalize()
+}
+
+/**
+ * Rejects generated files or cleanup targets shared by multiple framework entries.
+ *
+ * @param {object[]} frameworks manifest framework entries
+ * @param {{push: function(string): void}} errors bounded validation error collector
+ * @returns {void}
+ */
+function validateGeneratedPathCollisions (frameworks, errors) {
+  const seen = new Map()
+  for (const [index, framework] of frameworks.entries()) {
+    const strategy = framework?.generatedTestStrategy
+    const frameworkPaths = new Map([
+      ...limitedArray(strategy?.files, MAX_GENERATED_FILES).map(file => file?.path),
+      ...limitedArray(strategy?.cleanupPaths, MAX_MANIFEST_ARRAY_ENTRIES),
+    ].filter(filename => typeof filename === 'string' && path.isAbsolute(filename))
+      .map(filename => [path.normalize(filename), filename]))
+
+    for (const [key, filename] of frameworkPaths) {
+      const previous = seen.get(key)
+      if (previous === undefined) {
+        seen.set(key, index)
+        continue
+      }
+      errors.push(
+        `frameworks[${index}].generatedTestStrategy path ${JSON.stringify(filename)} conflicts with ` +
+        `frameworks[${previous}].generatedTestStrategy. Generated files and cleanup paths must be unique across ` +
+        'framework entries.'
+      )
+    }
+  }
+}
+
+function validateDuplicateRunnableCoverage (frameworks, errors) {
+  const seen = new Map()
+  for (const [index, framework] of frameworks.entries()) {
+    if (framework?.status !== 'runnable' || !framework.ciWiringCommand) continue
+    const key = JSON.stringify({
+      framework: framework.framework,
+      projectRoot: framework.project?.root,
+      existingTestCommand: commandExecutionShape(framework.existingTestCommand),
+      ciWiringCommand: commandExecutionShape(framework.ciWiringCommand),
+      ciInitializesDatadog: commandInitializesDatadog(framework.ciWiringCommand),
+    })
+    const previous = seen.get(key)
+    if (previous === undefined) {
+      seen.set(key, index)
+      continue
+    }
+    errors.push(
+      `frameworks[${index}] duplicates runnable framework and CI command coverage from frameworks[${previous}]. ` +
+      'Keep one representative framework entry and record the other CI job as an omitted or duplicate candidate.'
+    )
+  }
+}
+
+function validateUniqueArtifactIds (frameworks, errors) {
+  const seen = new Map()
+  for (const [index, framework] of frameworks.entries()) {
+    if (typeof framework?.id !== 'string') continue
+    const artifactId = getArtifactId(framework.id)
+    const previous = seen.get(artifactId)
+    if (previous !== undefined && previous !== framework.id) {
+      errors.push(
+        `frameworks[${index}].id collides with another framework artifact identifier after normalization.`
+      )
+    } else {
+      seen.set(artifactId, framework.id)
+    }
+  }
+}
+
+function commandExecutionShape (command) {
+  if (!command) return null
+  return {
+    argv: command.argv,
+    cwd: command.cwd,
+    shell: command.shell,
+    shellCommand: command.shellCommand,
+    usesShell: Boolean(command.usesShell),
+  }
+}
+
+function commandInitializesDatadog (command) {
+  const values = [
+    ...(command?.argv || []),
+    command?.shellCommand,
+    command?.env?.NODE_OPTIONS,
+  ].filter(Boolean).join(' ')
+  return /dd-trace\/ci\/init/.test(values)
+}
+
+function validateRepositoryContainedPaths (manifest, errors) {
+  const repositoryRoot = manifest.repository?.root
+  if (typeof repositoryRoot !== 'string' || !path.isAbsolute(repositoryRoot)) return
+
+  const frameworks = Array.isArray(manifest.frameworks) ? manifest.frameworks.slice(0, MAX_FRAMEWORKS) : []
+  for (const [index, framework] of frameworks.entries()) {
+    if (!framework || typeof framework !== 'object' || Array.isArray(framework)) continue
+    const prefix = `frameworks[${index}]`
+    containedPath(repositoryRoot, framework.project?.root, `${prefix}.project.root`, errors)
+    containedPath(repositoryRoot, framework.project?.packageJson, `${prefix}.project.packageJson`, errors)
+    for (const [configIndex, configFile] of
+      limitedArray(framework.project?.configFiles, MAX_MANIFEST_ARRAY_ENTRIES).entries()) {
+      containedPath(repositoryRoot, configFile, `${prefix}.project.configFiles[${configIndex}]`, errors)
+    }
+
+    for (const [name, command] of getFrameworkCommands(framework)) {
+      containedPath(repositoryRoot, command?.cwd, `${prefix}.${name}.cwd`, errors)
+    }
+
+    containedPath(repositoryRoot, framework.ciWiring?.configFile, `${prefix}.ciWiring.configFile`, errors)
+    containedPath(repositoryRoot, framework.ciWiring?.workingDirectory, `${prefix}.ciWiring.workingDirectory`, errors)
+
+    const strategy = framework.generatedTestStrategy
+    containedPath(repositoryRoot, strategy?.testDirectory, `${prefix}.generatedTestStrategy.testDirectory`, errors)
+    for (const [fileIndex, file] of limitedArray(strategy?.files, MAX_GENERATED_FILES).entries()) {
+      containedPath(repositoryRoot, file?.path, `${prefix}.generatedTestStrategy.files[${fileIndex}].path`, errors)
+    }
+    for (const [cleanupIndex, cleanupPath] of
+      limitedArray(strategy?.cleanupPaths, MAX_MANIFEST_ARRAY_ENTRIES).entries()) {
+      containedPath(
+        repositoryRoot,
+        cleanupPath,
+        `${prefix}.generatedTestStrategy.cleanupPaths[${cleanupIndex}]`,
+        errors
+      )
+    }
+    for (const [scenarioIndex, scenario] of
+      limitedArray(strategy?.scenarios, GENERATED_SCENARIO_IDS.size).entries()) {
+      for (const [identityIndex, identity] of
+        limitedArray(scenario?.testIdentities, MAX_MANIFEST_ARRAY_ENTRIES).entries()) {
+        containedPath(
+          repositoryRoot,
+          identity?.file,
+          `${prefix}.generatedTestStrategy.scenarios[${scenarioIndex}].testIdentities[${identityIndex}].file`,
+          errors
+        )
+      }
+    }
+  }
+}
+
+function getFrameworkCommands (framework) {
+  const commands = []
+  for (const name of ['existingTestCommand', 'ciWiringCommand']) {
+    if (framework[name]) commands.push([name, framework[name]])
+  }
+  for (const [index, command] of limitedArray(framework.setup?.commands, MAX_SETUP_COMMANDS).entries()) {
+    commands.push([`setup.commands[${index}]`, command])
+  }
+  for (const [index, scenario] of
+    limitedArray(framework.generatedTestStrategy?.scenarios, GENERATED_SCENARIO_IDS.size).entries()) {
+    if (scenario?.runCommand) {
+      commands.push([`generatedTestStrategy.scenarios[${index}].runCommand`, scenario.runCommand])
+    }
+  }
+  return commands
+}
+
+function containedPath (root, candidate, key, errors) {
+  if (typeof candidate !== 'string' || !path.isAbsolute(candidate)) return
+  const relative = path.relative(path.resolve(root), path.resolve(candidate))
+  if (relative === '' || (relative && !relative.startsWith('..') && !path.isAbsolute(relative))) return
+  errors.push(`${key} must be inside repository.root.`)
+}
+
+function validateCiDiscovery (ciDiscovery, prefix, errors) {
+  if (!ciDiscovery || typeof ciDiscovery !== 'object' || Array.isArray(ciDiscovery)) {
+    errors.push(`${prefix} must be an object when present.`)
+    return
+  }
+
+  for (const field of ['searched', 'found', 'staticFound', 'warnings', 'notes', 'contradictions']) {
+    if (ciDiscovery[field] !== undefined) {
+      if (Array.isArray(ciDiscovery[field])) {
+        validateStringArray(ciDiscovery, field, errors, prefix)
+      } else {
+        errors.push(`${prefix}.${field} must be an array when present.`)
+      }
+    }
+  }
+
+  if (ciDiscovery.method !== undefined && typeof ciDiscovery.method !== 'string') {
+    errors.push(`${prefix}.method must be a string when present.`)
+  }
+}
+
+function validateFramework (framework, index, errors) {
+  const prefix = `frameworks[${index}]`
+  if (!framework || typeof framework !== 'object' || Array.isArray(framework)) {
+    errors.push(`${prefix} must be an object.`)
+    return
+  }
+  requiredString(framework, 'id', errors, prefix)
+  enumString(framework, 'framework', FRAMEWORKS, errors, prefix)
+  enumString(framework, 'status', STATUSES, errors, prefix)
+  requiredObject(framework, 'project', errors, prefix)
+
+  if (framework.project) {
+    requiredAbsolutePath(framework.project, 'root', errors, `${prefix}.project`)
+    optionalAbsolutePath(framework.project, 'packageJson', errors, `${prefix}.project`)
+    optionalAbsolutePathArray(framework.project, 'configFiles', errors, `${prefix}.project`)
+    validateArrayLimit(framework.project, 'configFiles', MAX_MANIFEST_ARRAY_ENTRIES, errors, `${prefix}.project`)
+  }
+
+  if (framework.status === 'runnable') {
+    requiredCommand(framework, 'existingTestCommand', errors, prefix, { datadogClean: true })
+    validateDatadogCleanCommand(framework.existingTestCommand, `${prefix}.existingTestCommand`, errors)
+    requiredObject(framework, 'preflight', errors, prefix)
+    validatePreflight(framework.preflight, `${prefix}.preflight`, errors)
+    requiredObject(framework, 'ciWiring', errors, prefix)
+  } else {
+    requireNonEmptyNotes(framework, errors, prefix)
+  }
+
+  if (framework.ciWiringCommand) {
+    requiredCommand(framework, 'ciWiringCommand', errors, prefix)
+  }
+
+  if (framework.ciWiring) {
+    validateCiWiring(framework, prefix, errors)
+  }
+
+  if (framework.forcedLocalCommand !== undefined) {
+    errors.push(
+      `${prefix}.forcedLocalCommand is not supported. Use the focused existingTestCommand for Basic Reporting ` +
+      'and ciWiringCommand for the CI-shaped replay.'
+    )
+  }
+
+  if (framework.setup?.commands) {
+    if (Array.isArray(framework.setup.commands)) {
+      validateArrayLimit(framework.setup, 'commands', MAX_SETUP_COMMANDS, errors, `${prefix}.setup`)
+      for (const [commandIndex, command] of framework.setup.commands.slice(0, MAX_SETUP_COMMANDS).entries()) {
+        requiredCommand({ command }, 'command', errors, `${prefix}.setup.commands[${commandIndex}]`)
+      }
+    } else {
+      errors.push(`${prefix}.setup.commands must be an array.`)
+    }
+  }
+
+  if (framework.generatedTestStrategy) {
+    validateGeneratedTestStrategy(framework.generatedTestStrategy, `${prefix}.generatedTestStrategy`, errors)
+  }
+}
+
+/**
+ * Validates the approved upper bound for a representative test command.
+ *
+ * @param {object} preflight preflight declaration
+ * @param {string} prefix manifest field path
+ * @param {{push: function(string): void}} errors bounded validation error collector
+ * @returns {void}
+ */
+function validatePreflight (preflight, prefix, errors) {
+  if (!preflight || typeof preflight !== 'object' || Array.isArray(preflight)) return
+
+  if (!Number.isInteger(preflight.maxTestCount) || preflight.maxTestCount < 1) {
+    errors.push(`${prefix}.maxTestCount must be a positive integer.`)
+  } else if (preflight.maxTestCount > MAX_REPRESENTATIVE_TESTS) {
+    errors.push(`${prefix}.maxTestCount must not exceed ${MAX_REPRESENTATIVE_TESTS}.`)
+  }
+}
+
+function validateGeneratedTestStrategy (strategy, prefix, errors) {
+  if (!['planned', 'verified', 'proposed', 'not_possible'].includes(strategy.status)) {
+    errors.push(`${prefix}.status must be planned, verified, proposed, or not_possible.`)
+  }
+
+  const completeStrategy = strategy.status === 'planned' || strategy.status === 'verified'
+  if (completeStrategy) {
+    requiredArray(strategy, 'files', errors, prefix)
+    requiredArray(strategy, 'scenarios', errors, prefix)
+    requiredArray(strategy, 'cleanupPaths', errors, prefix)
+    validateCompleteGeneratedScenarioSet(strategy, prefix, errors)
+  } else if ((strategy.status === 'proposed' || strategy.status === 'not_possible') &&
+    (typeof strategy.reason !== 'string' || strategy.reason.trim() === '')) {
+    errors.push(`${prefix}.reason must explain why the generated test strategy is ${strategy.status}.`)
+  }
+
+  if (Array.isArray(strategy.files)) {
+    if (strategy.files.length > MAX_GENERATED_FILES) {
+      errors.push(`${prefix}.files must contain at most ${MAX_GENERATED_FILES} generated files.`)
+    }
+    for (const [index, file] of strategy.files.slice(0, MAX_GENERATED_FILES).entries()) {
+      requiredAbsolutePath(file, 'path', errors, `${prefix}.files[${index}]`)
+      requiredArray(file, 'contentLines', errors, `${prefix}.files[${index}]`)
+      validateStringArray(file, 'contentLines', errors, `${prefix}.files[${index}]`)
+      const policyError = getGeneratedFileContentError(file.contentLines)
+      if (policyError) errors.push(`${prefix}.files[${index}].contentLines ${policyError}.`)
+    }
+  }
+
+  if (Array.isArray(strategy.scenarios)) {
+    validateArrayLimit(strategy, 'scenarios', GENERATED_SCENARIO_IDS.size, errors, prefix)
+    for (const [index, scenario] of strategy.scenarios.slice(0, GENERATED_SCENARIO_IDS.size).entries()) {
+      requiredString(scenario, 'id', errors, `${prefix}.scenarios[${index}]`)
+      enumString(scenario, 'id', GENERATED_SCENARIO_IDS, errors, `${prefix}.scenarios[${index}]`)
+      requiredCommand(scenario, 'runCommand', errors, `${prefix}.scenarios[${index}]`, { datadogClean: true })
+      validateDatadogCleanCommand(scenario.runCommand, `${prefix}.scenarios[${index}].runCommand`, errors)
+      validateScenarioIdentities(
+        scenario,
+        `${prefix}.scenarios[${index}]`,
+        errors,
+        completeStrategy
+      )
+      if (completeStrategy) {
+        validateGeneratedScenarioOutcome(scenario, `${prefix}.scenarios[${index}]`, errors)
+      }
+    }
+  }
+
+  optionalAbsolutePath(strategy, 'testDirectory', errors, prefix)
+  optionalAbsolutePathArray(strategy, 'cleanupPaths', errors, prefix)
+}
+
+function validateCiWiring (framework, prefix, errors) {
+  const ciWiring = framework.ciWiring
+  if (!ciWiring || typeof ciWiring !== 'object' || Array.isArray(ciWiring)) {
+    errors.push(`${prefix}.ciWiring must be an object when present.`)
+    return
+  }
+
+  if (!CI_WIRING_STATUSES.has(ciWiring.status)) {
+    errors.push(`${prefix}.ciWiring.status must be pass, fail, skip, or unknown.`)
+  }
+
+  if (!CI_WIRING_REPLAYABILITIES.has(ciWiring.replayability)) {
+    errors.push(`${prefix}.ciWiring.replayability must be replayable or not_replayable.`)
+  }
+  if (Object.hasOwn(ciWiring, 'ciWiringCommand')) {
+    errors.push(`${prefix}.ciWiring.ciWiringCommand is misplaced; use ${prefix}.ciWiringCommand.`)
+  }
+  if (ciWiring.replayability === 'replayable' && !framework.ciWiringCommand) {
+    errors.push(`${prefix}.ciWiringCommand is required when ${prefix}.ciWiring.replayability is replayable.`)
+  }
+  if (ciWiring.replayability === 'not_replayable') {
+    if (ciWiring.status === 'pass' || ciWiring.status === 'fail') {
+      errors.push(`${prefix}.ciWiring.status must be skip or unknown when replayability is not_replayable.`)
+    }
+    if (framework.ciWiringCommand) {
+      errors.push(`${prefix}.ciWiringCommand must be omitted when ${prefix}.ciWiring.replayability is not_replayable.`)
+    }
+    if (!hasNonEmptyString(ciWiring.replayBlocker)) {
+      errors.push(`${prefix}.ciWiring.replayBlocker must explain why CI replay is not_replayable.`)
+    }
+  }
+
+  if (ciWiring.initialization !== undefined) {
+    validateCiInitialization(ciWiring.initialization, `${prefix}.ciWiring.initialization`, errors)
+  }
+
+  if (ciWiring.initialization?.status === 'not_configured' &&
+    commandInitializesDatadog(framework.ciWiringCommand)) {
+    errors.push(
+      `${prefix}.ciWiring.initialization.status is not_configured, but ${prefix}.ciWiringCommand adds dd-trace ` +
+      'initialization. The replay command must preserve the discovered CI configuration; remove the added ' +
+      'initialization or correct the initialization status and evidence.'
+    )
+  }
+
+  if (framework.ciWiringCommand) {
+    for (const field of ['provider', 'configFile', 'job', 'step', 'whySelected']) {
+      requiredString(ciWiring, field, errors, `${prefix}.ciWiring`)
+    }
+    requiredAbsolutePath(ciWiring, 'configFile', errors, `${prefix}.ciWiring`)
+    requiredAbsolutePath(ciWiring, 'workingDirectory', errors, `${prefix}.ciWiring`)
+    if (path.resolve(ciWiring.workingDirectory || '') !== path.resolve(framework.ciWiringCommand.cwd || '')) {
+      errors.push(`${prefix}.ciWiringCommand.cwd must match ${prefix}.ciWiring.workingDirectory.`)
+    }
+    if (ciWiring.shell !== undefined && ciWiring.shell !== null) {
+      if (typeof ciWiring.shell !== 'string' || ciWiring.shell.trim() === '') {
+        errors.push(`${prefix}.ciWiring.shell must be a non-empty string when present.`)
+      } else if (hasUnsafeExecutionCharacter(ciWiring.shell)) {
+        errors.push(`${prefix}.ciWiring.shell must not contain invisible or control characters.`)
+      }
+    }
+  }
+
+  if ((ciWiring.status === 'skip' || ciWiring.status === 'unknown') &&
+    !hasNonEmptyString(ciWiring.diagnosis) && !hasNonEmptyString(ciWiring.reason)) {
+    errors.push(`${prefix}.ciWiring must explain why CI wiring is ${ciWiring.status}.`)
+  }
+}
+
+function validateCiInitialization (initialization, prefix, errors) {
+  if (!initialization || typeof initialization !== 'object' || Array.isArray(initialization)) {
+    errors.push(`${prefix} must be an object when present.`)
+    return
+  }
+
+  if (!CI_INITIALIZATION_STATUSES.has(initialization.status)) {
+    errors.push(`${prefix}.status must be configured, not_configured, or unknown.`)
+  }
+  if (Array.isArray(initialization.evidence)) {
+    validateStringArray(initialization, 'evidence', errors, prefix)
+    if (initialization.status !== 'unknown' && initialization.evidence.length === 0) {
+      errors.push(`${prefix}.evidence must explain the ${initialization.status} conclusion.`)
+    }
+  } else {
+    errors.push(`${prefix}.evidence must be an array.`)
+  }
+}
+
+function hasNonEmptyString (value) {
+  return typeof value === 'string' && value.trim() !== ''
+}
+
+function validateDatadogCleanCommand (command, prefix, errors) {
+  for (const [name, value] of Object.entries(command?.env || {})) {
+    if (name.startsWith('DD_') || (name === 'NODE_OPTIONS' && /dd-trace/.test(String(value)))) {
+      errors.push(`${prefix}.env.${name} must not configure Datadog initialization for local validation.`)
+    }
+  }
+
+  const inlineInitialization = getInlineDatadogInitialization(command)
+  if (inlineInitialization) {
+    errors.push(
+      `${prefix} ${inlineInitialization} and must be Datadog-clean for local validation. ` +
+      'Remove the inline initialization; preserve exact CI initialization only in ciWiringCommand.'
+    )
+  }
+}
+
+function validateGeneratedScenarioOutcome (scenario, prefix, errors) {
+  const expected = scenario.expectedWithoutDatadog
+  if (!expected || typeof expected !== 'object' || Array.isArray(expected)) {
+    errors.push(`${prefix}.expectedWithoutDatadog must be an object when generatedTestStrategy is planned or verified.`)
+    return
+  }
+
+  const expectedExitCode = GENERATED_SCENARIO_EXIT_CODES[scenario.id]
+  if (expectedExitCode !== undefined && expected.exitCode !== expectedExitCode) {
+    errors.push(`${prefix}.expectedWithoutDatadog.exitCode must be ${expectedExitCode} for ${scenario.id}.`)
+  }
+  if (expected.observedTestCount !== 1) {
+    errors.push(`${prefix}.expectedWithoutDatadog.observedTestCount must be 1 so the command isolates this scenario.`)
+  }
+}
+
+function validateCompleteGeneratedScenarioSet (strategy, prefix, errors) {
+  if (!Array.isArray(strategy.scenarios)) return
+
+  const seen = new Set()
+  for (const scenario of strategy.scenarios.slice(0, GENERATED_SCENARIO_IDS.size)) {
+    if (typeof scenario?.id === 'string') seen.add(scenario.id)
+  }
+
+  for (const scenarioId of GENERATED_SCENARIO_IDS) {
+    if (!seen.has(scenarioId)) {
+      errors.push(`${prefix}.scenarios must include generated scenario "${scenarioId}" when status is planned or ` +
+        'verified.')
+    }
+  }
+}
+
+function validateUniqueFrameworkIds (frameworks, errors) {
+  const seen = new Set()
+  for (const [index, framework] of frameworks.entries()) {
+    if (typeof framework?.id !== 'string') continue
+    if (seen.has(framework.id)) {
+      errors.push(`frameworks[${index}].id must be unique; duplicate "${framework.id}".`)
+    }
+    seen.add(framework.id)
+  }
+}
+
+function requireNonEmptyNotes (framework, errors, prefix) {
+  if (!Array.isArray(framework.notes) || framework.notes.length === 0) {
+    errors.push(`${prefix}.notes must include a reason when status is ${framework.status}.`)
+    return
+  }
+  validateStringArray(framework, 'notes', errors, prefix)
+}
+
+function validateScenarioIdentities (scenario, prefix, errors, required = false) {
+  if (!Array.isArray(scenario.testIdentities)) {
+    if (required) {
+      errors.push(`${prefix}.testIdentities must be a non-empty array when generatedTestStrategy is planned or ` +
+        'verified.')
+    }
+    return
+  }
+
+  if (required && scenario.testIdentities.length === 0) {
+    errors.push(`${prefix}.testIdentities must be a non-empty array when generatedTestStrategy is planned or verified.`)
+  }
+  validateArrayLimit(
+    { testIdentities: scenario.testIdentities },
+    'testIdentities',
+    MAX_MANIFEST_ARRAY_ENTRIES,
+    errors,
+    prefix
+  )
+
+  for (const [index, identity] of scenario.testIdentities.slice(0, MAX_MANIFEST_ARRAY_ENTRIES).entries()) {
+    const identityPrefix = `${prefix}.testIdentities[${index}]`
+    if (!identity || typeof identity !== 'object' || Array.isArray(identity)) {
+      errors.push(`${identityPrefix} must be an object.`)
+      continue
+    }
+    requiredString(identity, 'name', errors, identityPrefix)
+    if (identity.suite !== undefined && identity.suite !== null && typeof identity.suite !== 'string') {
+      errors.push(`${identityPrefix}.suite must be a string or null when present.`)
+    }
+    optionalAbsolutePath(identity, 'file', errors, identityPrefix)
+  }
+}
+
+function requiredCommand (target, field, errors, prefix = '', options = {}) {
+  const value = target && target[field]
+  const key = join(prefix, field)
+  if (!value || typeof value !== 'object') {
+    errors.push(`${key} must be an object.`)
+    return
+  }
+  for (const name of Object.keys(value)) {
+    if (!COMMAND_FIELDS.has(name)) errors.push(`${key}.${name} is not an allowed command field.`)
+  }
+  if (value.usesShell !== undefined && typeof value.usesShell !== 'boolean') {
+    errors.push(`${key}.usesShell must be a boolean when present.`)
+  }
+  if (value.required !== undefined && typeof value.required !== 'boolean') {
+    errors.push(`${key}.required must be a boolean when present.`)
+  }
+  requiredAbsolutePath(value, 'cwd', errors, key)
+  rejectUnresolvedPlaceholder(value.cwd, `${key}.cwd`, errors)
+  if (value.shell !== undefined) {
+    requiredString(value, 'shell', errors, key)
+    rejectUnresolvedPlaceholder(value.shell, `${key}.shell`, errors)
+    if (!value.usesShell) errors.push(`${key}.shell requires usesShell to be true.`)
+    if (typeof value.shell === 'string' && hasUnsafeExecutionCharacter(value.shell)) {
+      errors.push(`${key}.shell must not contain invisible or control characters.`)
+    }
+  }
+  if (value.usesShell) {
+    requiredString(value, 'shellCommand', errors, key)
+    rejectUnresolvedPlaceholder(value.shellCommand, `${key}.shellCommand`, errors)
+    if (typeof value.shellCommand === 'string' && hasUnsafeInvisibleCharacter(value.shellCommand)) {
+      errors.push(`${key}.shellCommand must not contain invisible or control characters.`)
+    } else if (typeof value.shellCommand === 'string' && sanitizeString(value.shellCommand) !== value.shellCommand) {
+      errors.push(`${key}.shellCommand must not contain inline secret-like values. Put safe placeholders in env.`)
+    }
+  } else if (!Array.isArray(value.argv) || value.argv.length === 0) {
+    errors.push(`${key}.argv must be a non-empty array unless usesShell is true.`)
+  } else {
+    validateStringArray(value, 'argv', errors, key)
+    for (const [index, arg] of value.argv.slice(0, MAX_MANIFEST_ARRAY_ENTRIES).entries()) {
+      rejectUnresolvedPlaceholder(arg, `${key}.argv[${index}]`, errors)
+    }
+    if (value.argv.some(hasUnsafeExecutionCharacter)) {
+      errors.push(`${key}.argv must not contain invisible or control characters.`)
+    } else if (JSON.stringify(sanitizeForReport(value.argv)) !== JSON.stringify(value.argv)) {
+      errors.push(`${key}.argv must not contain inline secret-like values. Put safe placeholders in env.`)
+    }
+  }
+  if (value.env !== undefined) {
+    if (!value.env || typeof value.env !== 'object' || Array.isArray(value.env)) {
+      errors.push(`${key}.env must be an object when present.`)
+    } else {
+      const environmentEntries = Object.entries(value.env)
+      if (environmentEntries.length > MAX_MANIFEST_ARRAY_ENTRIES) {
+        errors.push(`${key}.env must contain at most ${MAX_MANIFEST_ARRAY_ENTRIES} entries.`)
+      }
+      for (const [name, envValue] of environmentEntries.slice(0, MAX_MANIFEST_ARRAY_ENTRIES)) {
+        if (!ENV_NAME_PATTERN.test(name)) {
+          errors.push(`${key}.env contains invalid variable name ${JSON.stringify(name)}.`)
+        }
+        if (typeof envValue !== 'string') errors.push(`${key}.env.${name} must be a string.`)
+        const validatePlaceholder = !(options.datadogClean && name.startsWith('DD_'))
+        if (typeof envValue === 'string' && hasUnsafeExecutionCharacter(envValue)) {
+          errors.push(`${key}.env.${name} must not contain invisible or control characters.`)
+        } else if (validatePlaceholder && typeof envValue === 'string' && containsSecretValue(name, envValue) &&
+          envValue !== SECRET_PLACEHOLDER) {
+          errors.push(`${key}.env.${name} must use the safe placeholder ${JSON.stringify(SECRET_PLACEHOLDER)}.`)
+        }
+        rejectUnresolvedPlaceholder(envValue, `${key}.env.${name}`, errors)
+      }
+    }
+  }
+  if (value.requiredEnvVars !== undefined) {
+    if (Array.isArray(value.requiredEnvVars)) {
+      validateArrayLimit(value, 'requiredEnvVars', MAX_MANIFEST_ARRAY_ENTRIES, errors, key)
+      for (const [index] of value.requiredEnvVars.slice(0, MAX_MANIFEST_ARRAY_ENTRIES).entries()) {
+        requiredString(value.requiredEnvVars, index, errors, `${key}.requiredEnvVars`)
+      }
+    } else {
+      errors.push(`${key}.requiredEnvVars must be an array when present.`)
+    }
+  }
+  optionalAbsolutePathArray(value, 'outputPaths', errors, key)
+  if (value.timeoutMs !== undefined && (!Number.isFinite(value.timeoutMs) || value.timeoutMs <= 0)) {
+    errors.push(`${key}.timeoutMs must be a positive number when present.`)
+  } else if (value.timeoutMs > MAX_COMMAND_TIMEOUT_MS) {
+    errors.push(`${key}.timeoutMs must not exceed ${MAX_COMMAND_TIMEOUT_MS} ms.`)
+  }
+}
+
+function containsSecretValue (name, value) {
+  if (SAFE_SECRET_FIELD_VALUES.has(value.toLowerCase())) return false
+  return isSensitiveName(name) || sanitizeString(value) !== value
+}
+
+function rejectUnresolvedPlaceholder (value, key, errors) {
+  if (typeof value !== 'string' || !UNRESOLVED_PLACEHOLDER_PATTERN.test(value)) return
+  errors.push(`${key} contains an unresolved placeholder. Resolve it before live validation.`)
+}
+
+function requiredObject (target, field, errors, prefix = '') {
+  const value = target && target[field]
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    errors.push(`${join(prefix, field)} must be an object.`)
+  }
+}
+
+function requiredArray (target, field, errors, prefix = '') {
+  if (!Array.isArray(target && target[field])) {
+    errors.push(`${join(prefix, field)} must be an array.`)
+  }
+}
+
+function requiredString (target, field, errors, prefix = '') {
+  if (typeof (target && target[field]) !== 'string' || target[field].length === 0) {
+    errors.push(`${join(prefix, field)} must be a non-empty string.`)
+  }
+}
+
+function enumString (target, field, values, errors, prefix = '') {
+  if (!values.has(target && target[field])) {
+    errors.push(`${join(prefix, field)} must be one of: ${[...values].join(', ')}.`)
+  }
+}
+
+function requiredAbsolutePath (target, field, errors, prefix = '') {
+  const value = target && target[field]
+  if (typeof value !== 'string' || !path.isAbsolute(value)) {
+    errors.push(`${join(prefix, field)} must be an absolute path.`)
+  } else if (hasUnsafeExecutionCharacter(value)) {
+    errors.push(`${join(prefix, field)} must not contain invisible or control characters.`)
+  }
+}
+
+function optionalAbsolutePath (target, field, errors, prefix = '') {
+  const value = target && target[field]
+  if (value === undefined || value === null) return
+  if (typeof value !== 'string' || !path.isAbsolute(value)) {
+    errors.push(`${join(prefix, field)} must be an absolute path when present.`)
+  } else if (hasUnsafeExecutionCharacter(value)) {
+    errors.push(`${join(prefix, field)} must not contain invisible or control characters.`)
+  }
+}
+
+function optionalAbsolutePathArray (target, field, errors, prefix = '') {
+  const value = target && target[field]
+  if (value === undefined) return
+  if (!Array.isArray(value)) {
+    errors.push(`${join(prefix, field)} must be an array when present.`)
+    return
+  }
+
+  validateArrayLimit(target, field, MAX_MANIFEST_ARRAY_ENTRIES, errors, prefix)
+  for (const [index, item] of value.slice(0, MAX_MANIFEST_ARRAY_ENTRIES).entries()) {
+    if (typeof item !== 'string' || !path.isAbsolute(item)) {
+      errors.push(`${join(prefix, field)}[${index}] must be an absolute path.`)
+    } else if (hasUnsafeExecutionCharacter(item)) {
+      errors.push(`${join(prefix, field)}[${index}] must not contain invisible or control characters.`)
+    }
+  }
+}
+
+function validateStringArray (target, field, errors, prefix = '') {
+  const value = target && target[field]
+  if (!Array.isArray(value)) return
+
+  validateArrayLimit(target, field, MAX_MANIFEST_ARRAY_ENTRIES, errors, prefix)
+  for (const [index, item] of value.slice(0, MAX_MANIFEST_ARRAY_ENTRIES).entries()) {
+    if (typeof item !== 'string') {
+      errors.push(`${join(prefix, field)}[${index}] must be a string.`)
+    }
+  }
+}
+
+function validateArrayLimit (target, field, limit, errors, prefix = '') {
+  const value = target && target[field]
+  if (Array.isArray(value) && value.length > limit) {
+    errors.push(`${join(prefix, field)} must contain at most ${limit} entries.`)
+  }
+}
+
+function limitedArray (value, limit) {
+  return Array.isArray(value) ? value.slice(0, limit) : []
+}
+
+function createErrorCollector () {
+  const errors = []
+  let omitted = 0
+  Object.defineProperties(errors, {
+    push: {
+      value (...messages) {
+        for (const message of messages) {
+          if (this.length < MAX_VALIDATION_ERRORS - 1) {
+            Array.prototype.push.call(this, message)
+          } else {
+            omitted++
+          }
+        }
+        return this.length
+      },
+    },
+    finalize: {
+      value () {
+        if (omitted > 0) {
+          Array.prototype.push.call(this, `${omitted} additional validation error(s) omitted.`)
+        }
+        return this
+      },
+    },
+  })
+  return errors
+}
+
+function join (prefix, field) {
+  return prefix ? `${prefix}.${field}` : field
+}
+
+module.exports = {
+  MAX_FRAMEWORKS,
+  MAX_REPRESENTATIVE_TESTS,
+  MAX_VALIDATION_ERRORS,
+  validateManifest,
+}