diagnose.js

'use strict'

/* eslint-disable eslint-rules/eslint-process-env */

const fs = require('node:fs')
const path = require('node:path')
const { execFileSync } = require('node:child_process')

const satisfies = require('../vendor/dist/semifies')
const { DD_MAJOR, VERSION } = require('../version')

const MAX_TEXT_FILE_SIZE = 512 * 1024
const MAX_SCANNED_FILES = 1500
const MAX_SCANNED_TEXT_BYTES = 32 * 1024 * 1024

const PACKAGE_SECTIONS = [
  'dependencies',
  'devDependencies',
  'optionalDependencies',
  'peerDependencies',
]

const SKIPPED_DIRECTORIES = new Set([
  '.cache',
  '.git',
  '.hg',
  '.next',
  '.nuxt',
  '.output',
  '.parcel-cache',
  '.serverless',
  '.svn',
  '.turbo',
  '.yarn',
  'build',
  'coverage',
  'dd-test-optimization-validation-results',
  'dist',
  'node_modules',
  'out',
  'target',
  'tmp',
  'vendor',
])

const SKIPPED_FILES = new Set([
  'ci/diagnose.js',
])

const TEXT_EXTENSIONS = new Set([
  '.cjs',
  '.cts',
  '.js',
  '.json',
  '.mjs',
  '.mts',
  '.sh',
  '.ts',
  '.tsx',
  '.yaml',
  '.yml',
])

const TEXT_FILE_NAMES = new Set([
  'Dockerfile',
  'Jenkinsfile',
  'Makefile',
  'docker-compose.yml',
  'docker-compose.yaml',
  'package.json',
])

const NODE_OPTIONS_RE = /\bNODE_OPTIONS\b/
const INIT_PRELOAD_TARGET =
  String.raw`(?:dd-trace/ci/init|(?:[^\s'"]*[/\\])?node_modules[/\\]dd-trace[/\\]ci[/\\]init|\./ci/init)`
const INIT_PRELOAD_RE =
  new RegExp(String.raw`(?:^|[\s='"])(?:-r|--require)(?:=|\s+)['"]?${INIT_PRELOAD_TARGET}(?:\.js)?['"]?(?=$|[\s"'])`)
const REGISTER_PRELOAD_RE =
  /(?:^|[\s='"])(?:--import|-r|--require)(?:=|\s+)['"]?dd-trace\/register(?:\.js)?['"]?(?=$|[\s"'])/
const WRONG_INIT_RE = /dd-trace\/(?:init|initialize\.mjs)\b|require\(['"]dd-trace['"]\)\.init\s*\(/
const DIRECT_CI_INIT_RE = /(?:require\(|import\s+)['"]dd-trace\/ci\/init(?:\.js)?['"]/
const CI_DISABLED_RE = /DD_CIVISIBILITY_ENABLED["'\s:=]+(?:false|0)\b/i
const ITR_DISABLED_RE = /DD_CIVISIBILITY_ITR_ENABLED["'\s:=]+(?:false|0)\b/i
const GIT_UPLOAD_DISABLED_RE = /DD_CIVISIBILITY_GIT_UPLOAD_ENABLED["'\s:=]+(?:false|0)\b/i
const AGENTLESS_ENABLED_RE = /DD_CIVISIBILITY_AGENTLESS_ENABLED["'\s:=]+(?:true|1)\b/i
const API_KEY_RE = /\b(?:DD_API_KEY|DATADOG_API_KEY)\b/
const SERVICE_RE = /\bDD_SERVICE\b/
const OTEL_OTLP_RE = /OTEL_TRACES_EXPORTER["'\s:=]+otlp\b/i
const WATCH_MODE_RE = /(?:^|\s)(?:watch|--watch|--watchAll)(?!=false(?:\s|$))(?:\s|=|$)/

const CYPRESS_MANUAL_PLUGIN_RE = /dd-trace\/ci\/cypress\/(?:plugin|after-run|after-spec)\b/
const CYPRESS_SUPPORT_RE = /dd-trace\/ci\/cypress\/support\b/
const CYPRESS_SUPPORT_DISABLED_RE = /supportFile\s*:\s*false|"supportFile"\s*:\s*false/
const CUCUMBER_RUNNER_COMMAND_RE = new RegExp(
  String.raw`(?:^|(?:&&|\|\||[;|])\s*)` +
  String.raw`(?:(?:[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|[^\s"';&|][^\s;&|]*)|` +
  String.raw`cross-env|env|npx|nyc|c8|npm\s+exec|pnpm\s+exec|yarn\s+exec|-[^\s;&|]+)\s+)*` +
  String.raw`(?:(?:[^\s"';&|]+[/\\])?(?:cucumber-js(?:\.cmd)?|cucumber(?:\.cmd)?)|` +
  String.raw`node(?:\.exe)?\s+(?:[^\s"';&|]+[/\\])?bin[/\\]cucumber\.js)` +
  String.raw`(?=$|[\s"';&|])`
)
const CUCUMBER_PARALLEL_RE =
  /\bcucumber(?:-js)?\b[\s\S]{0,200}\s--parallel\b|--parallel\b[\s\S]{1,200}\bcucumber(?:-js)?\b/
const JEST_FORCE_EXIT_RE = /\bforceExit\s*:\s*true\b|--forceExit\b|"forceExit"\s*:\s*true/
const JEST_JASMINE_RE = /jest-jasmine2/

const CURRENT_ENV_PROVIDER_KEYS = [
  'GITHUB_ACTIONS',
  'GITLAB_CI',
  'CIRCLECI',
  'JENKINS_URL',
  'BUILDKITE',
  'TRAVIS',
  'TF_BUILD',
  'BITBUCKET_BUILD_NUMBER',
  'DRONE',
  'TEAMCITY_VERSION',
]

/**
 * Builds the framework support table for the tracer major version that is running this script.
 *
 * @param {number} ddMajor dd-trace major version
 * @returns {Array<object>} supported framework definitions
 */
function getFrameworkDefinitions (ddMajor) {
  return [
    {
      id: 'jest',
      name: 'Jest',
      packages: ['jest', '@jest/core'],
      commandPatterns: [/\bjest\b/],
      configPatterns: [/^jest\.config\./, /^config-jest\./],
      supportedRange: ddMajor >= 6 ? '>=28.0.0' : '>=24.8.0',
      recommendation: 'Use a Jest and dd-trace combination whose documented support ranges overlap; this ' +
        `dd-trace version requires Jest ${ddMajor >= 6 ? '>=28.0.0' : '>=24.8.0'}.`,
    },
    {
      id: 'mocha',
      name: 'Mocha',
      packages: ['mocha'],
      commandPatterns: [/\bmocha\b/],
      configPatterns: [/^\.mocharc\./],
      supportedRange: ddMajor >= 6 ? '>=8.0.0' : '>=5.2.0',
      recommendation: 'Use a Mocha and dd-trace combination whose documented support ranges overlap; this ' +
        `dd-trace version requires Mocha ${ddMajor >= 6 ? '>=8.0.0' : '>=5.2.0'}.`,
      notes: [
        'Impacted tests are detected at suite level for Mocha.',
      ],
    },
    {
      id: 'cucumber',
      name: 'Cucumber',
      packages: ['@cucumber/cucumber'],
      commandPatterns: [CUCUMBER_RUNNER_COMMAND_RE],
      configPatterns: [/^cucumber\./],
      supportedRange: '>=7.0.0',
      recommendation: 'Upgrade @cucumber/cucumber to >=7.0.0.',
    },
    {
      id: 'cypress',
      name: 'Cypress',
      packages: ['cypress'],
      commandPatterns: [/\bcypress\s+(?:run|open)\b/],
      configPatterns: [/^cypress\.config\./, /^cypress\.json$/],
      supportedRange: ddMajor >= 6 ? '>=12.0.0' : '>=6.7.0',
      autoInstrumentationRange: ddMajor >= 6 ? '>=12.0.0' : '>=10.2.0',
      recommendation: 'Use a Cypress and dd-trace combination whose documented support ranges overlap; this ' +
        `dd-trace version requires Cypress ${ddMajor >= 6 ? '>=12.0.0' : '>=6.7.0'}.`,
    },
    {
      id: 'playwright',
      name: 'Playwright',
      packages: ['@playwright/test'],
      commandPatterns: [/\bplaywright\s+test\b/],
      configPatterns: [/^playwright\.config\./],
      supportedRange: ddMajor >= 6 ? '>=1.38.0' : '>=1.18.0',
      recommendation: 'Use a Playwright and dd-trace combination whose documented support ranges overlap; this ' +
        `dd-trace version requires Playwright ${ddMajor >= 6 ? '>=1.38.0' : '>=1.18.0'}.`,
      notes: [
        'Test Impact Analysis suite skipping is not supported for Playwright.',
        'Impacted tests are detected at suite level for Playwright.',
      ],
    },
    {
      id: 'vitest',
      name: 'Vitest',
      packages: ['vitest'],
      commandPatterns: [/\bvitest\b/],
      configPatterns: [/^vitest\.config\./, /^vite\.config\./],
      supportedRange: '>=1.6.0',
      recommendation: 'Upgrade Vitest to >=1.6.0.',
      notes: [
        'Test Impact Analysis suite skipping is not supported for Vitest.',
        'Impacted tests are detected at suite level for Vitest.',
      ],
      esmInitialization: true,
    },
  ]
}

const UNSUPPORTED_FRAMEWORKS = [
  {
    id: 'node-test',
    name: 'Node.js test runner',
    packages: [],
    commandPatterns: [/\bnode\s+--test\b/, /\bnode\s+--experimental-test-coverage\b/, /\bbnt\b/],
  },
  { id: 'ava', name: 'AVA', packages: ['ava'], commandPatterns: [/\bava\b/] },
  { id: 'tap', name: 'tap', packages: ['tap'], commandPatterns: [/\btap\b/] },
  { id: 'jasmine', name: 'Jasmine', packages: ['jasmine'], commandPatterns: [/\bjasmine\b/] },
  { id: 'karma', name: 'Karma', packages: ['karma'], commandPatterns: [/\bkarma\b/] },
  { id: 'uvu', name: 'uvu', packages: ['uvu'], commandPatterns: [/\buvu\b/] },
  {
    id: 'testcafe',
    name: 'TestCafe',
    packages: ['testcafe'],
    commandPatterns: [/\btestcafe\b/],
  },
]

/**
 * Runs all static checks for a repository.
 *
 * @param {object} [options] diagnosis options
 * @param {string} [options.root] repository path to inspect
 * @param {typeof process.env} [options.env] environment to inspect
 * @param {Function} [options.execFile] command runner used for git checks
 * @param {string} [options.gitExecutable] trusted git executable used for git checks
 * @param {number} [options.maxFiles] maximum number of text files to scan
 * @param {number} [options.maxTotalBytes] maximum aggregate bytes of text files to scan
 * @param {string[]} [options.excludePaths] repository paths to exclude from the text scan
 * @returns {object} diagnosis report
 */
function runDiagnosis (options = {}) {
  const root = path.resolve(options.root || process.cwd())
  const physicalRoot = getPhysicalRoot(root)
  const env = options.env || process.env
  const execFile = options.execFile || execFileSync
  const maxFiles = options.maxFiles || MAX_SCANNED_FILES
  const maxTotalBytes = options.maxTotalBytes || MAX_SCANNED_TEXT_BYTES
  const results = []
  const files = collectTextFiles(root, physicalRoot, maxFiles, options.excludePaths)
  const textFiles = readTextFiles(root, physicalRoot, files, maxTotalBytes)
  const truncatedFileScan = files.truncated || textFiles.truncated
  const manifests = readPackageManifests(root, textFiles)
  const rootManifest = manifests.find(manifest => manifest.relativePath === 'package.json')
  const rootPackageJsonState = getRootPackageJsonState(root, physicalRoot)
  const scripts = collectScripts(manifests)
  const workflowFiles = textFiles.filter(file => isWorkflowFile(file.relativePath))
  const definitions = getFrameworkDefinitions(DD_MAJOR)
  const supportedFrameworks = detectSupportedFrameworks(root, definitions, manifests, scripts, textFiles)
  const eligibleFrameworks = getEligibleFrameworks(supportedFrameworks)
  const unsupportedFrameworks = detectUnsupportedFrameworks(UNSUPPORTED_FRAMEWORKS, manifests, scripts)
  const evidence = collectEvidence(textFiles, env)

  checkPackageManifest(results, rootManifest, rootPackageJsonState)
  checkDdTraceDependency(results, manifests, { root, truncatedFileScan, rootPackageJsonState })
  checkSupportedFrameworks(results, supportedFrameworks)
  checkUnsupportedFrameworks(results, unsupportedFrameworks, supportedFrameworks)
  checkInitialization(results, supportedFrameworks, evidence, env)
  checkFrameworkConfiguration(results, supportedFrameworks, evidence, textFiles, manifests)
  checkCiConfiguration(results, workflowFiles, evidence, env)
  const gitExecutable = options.gitExecutable || (options.execFile ? 'git' : findTrustedGitExecutable())
  checkGit(results, root, env, execFile, gitExecutable)
  checkCurrentEnvironment(results, env, evidence)

  return {
    root,
    ddTraceVersion: VERSION,
    ddTraceMajor: DD_MAJOR,
    scannedFileCount: textFiles.length,
    truncatedFileScan,
    supportedFrameworks: supportedFrameworks.map(serializeSupportedFramework),
    eligibleFrameworks: eligibleFrameworks.map(serializeEligibleFramework),
    unsupportedFrameworks: unsupportedFrameworks.map(serializeUnsupportedFramework),
    results,
  }
}

/**
 * Adds a normalized result to the list.
 *
 * @param {Array<object>} results mutable result list
 * @param {string} status result status
 * @param {string} title short title
 * @param {string} message result details
 * @param {object} [extra] optional fields
 */
function addResult (results, status, title, message, extra = {}) {
  results.push({
    status,
    title,
    message,
    ...extra,
  })
}

/**
 * Reads package.json files collected by the repository scan.
 *
 * @param {string} root repository root
 * @param {Array<object>} textFiles scanned text files
 * @returns {Array<object>} parsed package manifests
 */
function readPackageManifests (root, textFiles) {
  const manifests = []

  for (const file of textFiles) {
    if (path.basename(file.relativePath) !== 'package.json') continue

    const json = parseJson(file.content)
    if (!json) continue

    manifests.push({
      path: path.join(root, file.relativePath),
      relativePath: file.relativePath,
      json,
    })
  }

  return manifests
}

/**
 * Checks whether the repository root has a package.json independently from the text-file scan.
 *
 * @param {string} root repository root
 * @param {string|undefined} physicalRoot physical repository root
 * @returns {{ exists: boolean }} root package.json state
 */
function getRootPackageJsonState (root, physicalRoot) {
  return {
    exists: Boolean(getSafeScannedFile(root, physicalRoot, 'package.json')),
  }
}

/**
 * Checks that a root package.json exists.
 *
 * @param {Array<object>} results mutable result list
 * @param {object|undefined} rootManifest parsed root package manifest
 * @param {object} rootPackageJsonState root package.json filesystem state
 */
function checkPackageManifest (results, rootManifest, rootPackageJsonState) {
  if (rootManifest) {
    addResult(results, 'ok', 'Root package.json found', 'Dependency and script checks can inspect package metadata.')
    return
  }

  if (rootPackageJsonState.exists) {
    addResult(
      results,
      'warning',
      'Root package.json not determined',
      'A root package.json file exists, but static diagnosis could not parse it as scanned text.',
      {
        recommendation:
          'Check whether package.json is readable UTF-8 JSON and smaller than the static diagnosis file limit.',
      }
    )
    return
  }

  addResult(
    results,
    'warning',
    'No root package.json found',
    'The diagnosis could not inspect root dependencies or package scripts.',
    { recommendation: 'Run this script from the JavaScript repository root, or pass --path <repository>.' }
  )
}

/**
 * Checks whether dd-trace is declared in repository manifests.
 *
 * @param {Array<object>} results mutable result list
 * @param {Array<object>} manifests package manifests
 * @param {object} options dependency check options
 * @param {string} [options.root] repository root
 * @param {boolean} [options.truncatedFileScan] whether static file discovery was truncated
 * @param {object} [options.rootPackageJsonState] root package manifest state
 */
function checkDdTraceDependency (results, manifests, options = {}) {
  const entries = findDependencyEntries(manifests, ['dd-trace'])

  if (entries.length) {
    addResult(
      results,
      'ok',
      'dd-trace dependency found',
      `Detected dd-trace in ${formatLocations(entries.map(entry => entry.relativePath))}.`
    )
    return
  }

  const installedPackageJson = options.root && path.join(options.root, 'node_modules', 'dd-trace', 'package.json')
  let installed = false
  try {
    installed = installedPackageJson && fs.statSync(installedPackageJson).isFile()
  } catch {}
  if (installed) {
    addResult(
      results,
      'ok',
      'dd-trace package installed',
      'Detected an installed dd-trace package even though it was not declared in the scanned package manifests.'
    )
    return
  }

  if (options.truncatedFileScan || (options.rootPackageJsonState?.exists && !hasParsedRootManifest(manifests))) {
    addResult(
      results,
      'warning',
      'dd-trace dependency not determined',
      'Static diagnosis did not confirm a dd-trace dependency, but the file scan was incomplete or root package ' +
        'metadata could not be parsed.',
      { recommendation: 'Inspect the package that runs tests and install dd-trace there if it is absent.' }
    )
    return
  }

  addResult(
    results,
    'warning',
    'dd-trace dependency not found in package.json',
    'The script did not find dd-trace in dependencies or devDependencies.',
    { recommendation: 'Install dd-trace in the project that runs the tests.' }
  )
}

/**
 * Checks whether static diagnosis parsed the repository root package manifest.
 *
 * @param {Array<object>} manifests parsed package manifests
 * @returns {boolean} true when the root package.json was parsed
 */
function hasParsedRootManifest (manifests) {
  return manifests.some(manifest => manifest.relativePath === 'package.json')
}

/**
 * Checks supported framework detections and versions.
 *
 * @param {Array<object>} results mutable result list
 * @param {Array<object>} frameworks detected supported frameworks
 */
function checkSupportedFrameworks (results, frameworks) {
  if (!frameworks.length) {
    addResult(
      results,
      'warning',
      'No supported test framework detected',
      'No supported Test Optimization framework was found in dependencies, scripts, or config files.',
      {
        recommendation:
          'Use Jest, Mocha, Cucumber, Cypress, Playwright, or Vitest with a supported version.',
      }
    )
    return
  }

  for (const framework of frameworks) {
    if (!framework.versionDetections.length) {
      addResult(
        results,
        'warning',
        `${framework.name} detected but version is unknown`,
        `${framework.name} appears in scripts or config, but no package version could be determined.`,
        {
          locations: framework.locations,
          recommendation:
            `Ensure ${framework.packages.join(' or ')} is installed and matches ${framework.supportedRange}.`,
        }
      )
    }

    for (const detection of framework.versionDetections) {
      if (!detection.version) {
        addResult(
          results,
          'warning',
          `${framework.name} version could not be determined`,
          `Detected ${detection.packageName}@${detection.rawVersion}, but the version is not statically comparable.`,
          {
            locations: [detection.relativePath],
            recommendation: `Verify ${framework.name} satisfies ${framework.supportedRange}.`,
          }
        )
        continue
      }

      const status = satisfies(detection.version, framework.supportedRange) ? 'ok' : 'error'
      const source = detection.source === 'installed' ? 'installed package' : 'package manifest'
      addResult(
        results,
        status,
        `${framework.name} ${detection.version} ${status === 'ok' ? 'is supported' : 'is not supported'}`,
        `Detected ${detection.packageName}@${detection.rawVersion} from ${source}; supported range is ` +
          `${framework.supportedRange}.`,
        {
          locations: detection.relativePath ? [detection.relativePath] : undefined,
          recommendation: status === 'error' ? framework.recommendation : undefined,
        }
      )
    }

    for (const note of framework.notes || []) {
      addResult(results, 'info', `${framework.name} capability note`, note)
    }
  }
}

/**
 * Checks unsupported framework detections.
 *
 * @param {Array<object>} results mutable result list
 * @param {Array<object>} unsupported detected unsupported frameworks
 * @param {Array<object>} supported detected supported frameworks
 */
function checkUnsupportedFrameworks (results, unsupported, supported) {
  for (const framework of unsupported) {
    const status = supported.length ? 'warning' : 'error'
    addResult(
      results,
      status,
      `${framework.name} is not supported by Test Optimization`,
      `${framework.name} was detected in dependencies or test scripts.`,
      {
        locations: framework.locations,
        recommendation:
          'Use a supported JavaScript test framework for automatic Test Optimization instrumentation.',
      }
    )
  }
}

/**
 * Checks Test Optimization initialization.
 *
 * @param {Array<object>} results mutable result list
 * @param {Array<object>} frameworks detected supported frameworks
 * @param {object} evidence repository evidence
 * @param {typeof process.env} env environment
 */
function checkInitialization (results, frameworks, evidence, env) {
  if (!frameworks.length) return

  const hasCiInit = evidence.hasCiInit || hasCiInitInNodeOptions(env.NODE_OPTIONS)
  const hasCypressOnly = frameworks.length === 1 && frameworks[0].id === 'cypress'
  const hasCypressManualPlugin = evidence.cypressManualPluginLocations.length > 0

  if (hasCiInit) {
    addResult(
      results,
      'ok',
      'Test Optimization initialization found',
      'Found dd-trace/ci/init preloaded through NODE_OPTIONS in repository files or the current environment.',
      { locations: evidence.ciInitLocations }
    )
  } else if (hasCypressOnly && hasCypressManualPlugin) {
    addResult(
      results,
      'ok',
      'Cypress manual plugin initialization found',
      'Found the Cypress-specific dd-trace Test Optimization plugin setup.',
      { locations: evidence.cypressManualPluginLocations }
    )
  } else {
    addResult(
      results,
      'error',
      'Missing Test Optimization initialization',
      'No NODE_OPTIONS preload for dd-trace/ci/init was found in repository files or the current environment.',
      {
        recommendation:
          'Run tests with NODE_OPTIONS="-r dd-trace/ci/init". For ESM test runners, also include ' +
          '--import dd-trace/register.js.',
      }
    )
  }

  if (evidence.directCiInitLocations.length) {
    addResult(
      results,
      'error',
      'Test Optimization initialization is imported directly',
      'The diagnosis found require("dd-trace/ci/init") or import "dd-trace/ci/init". ' +
        'That does not preload the tracer early enough for Test Optimization setup.',
      {
        locations: evidence.directCiInitLocations,
        recommendation: 'Set NODE_OPTIONS="-r dd-trace/ci/init" on the test process instead.',
      }
    )
  }

  if (evidence.wrongInitLocations.length) {
    addResult(
      results,
      'error',
      'Plain dd-trace initialization found in test setup',
      'The diagnosis found dd-trace/init, dd-trace/initialize.mjs, or require("dd-trace").init(). ' +
        'That does not initialize the tracer in Test Optimization mode.',
      {
        locations: evidence.wrongInitLocations,
        recommendation: 'Use dd-trace/ci/init for test commands instead of the plain tracing initializer.',
      }
    )
  }

  if (frameworks.some(framework => framework.esmInitialization) && hasCiInit && !evidence.hasRegister &&
    !hasRegisterInNodeOptions(env.NODE_OPTIONS)) {
    addResult(
      results,
      'warning',
      'ESM loader registration not found',
      'Vitest and other ESM-heavy test runners often need dd-trace/register.js before dd-trace/ci/init.',
      {
        recommendation:
          'Use NODE_OPTIONS="--import dd-trace/register.js -r dd-trace/ci/init" for ESM test runs.',
      }
    )
  }
}

/**
 * Checks framework-specific configuration pitfalls.
 *
 * @param {Array<object>} results mutable result list
 * @param {Array<object>} frameworks detected supported frameworks
 * @param {object} evidence repository evidence
 * @param {Array<object>} textFiles scanned text files
 * @param {Array<object>} manifests package manifests
 */
function checkFrameworkConfiguration (results, frameworks, evidence, textFiles, manifests) {
  if (hasFramework(frameworks, 'vitest') && !hasFramework(frameworks, 'playwright') &&
    findDependencyEntries(manifests, ['playwright']).length > 0) {
    addResult(
      results,
      'info',
      'Playwright package is not a Playwright Test runner',
      'The repository uses Vitest and has the playwright package, but no @playwright/test runner was detected. ' +
        'Treat Playwright as Vitest browser-provider infrastructure, not as another test framework.',
      {}
    )
  }

  if (hasFramework(frameworks, 'cypress')) {
    checkCypressConfiguration(results, evidence)
  }

  if (hasFramework(frameworks, 'jest')) {
    const jestLocations = findLocations(textFiles, JEST_FORCE_EXIT_RE)
    if (jestLocations.length) {
      addResult(
        results,
        'warning',
        'Jest forceExit can drop Test Optimization data',
        'Jest\'s forceExit option can terminate before dd-trace flushes all test data.',
        {
          locations: jestLocations,
          recommendation: 'Remove --forceExit or forceExit: true from Jest configuration when possible.',
        }
      )
    }

    const jasmineLocations = findLocations(textFiles, JEST_JASMINE_RE)
    if (jasmineLocations.length) {
      addResult(
        results,
        'info',
        'Jest is configured with jest-jasmine2',
        'dd-trace can avoid crashing with jest-jasmine2, but jest-circus is the better-supported runner.',
        {
          locations: jasmineLocations,
          recommendation: 'Prefer the default jest-circus runner on supported Jest versions.',
        }
      )
    }

    const tsConfigLocations = findJestTypescriptConfigLocations(textFiles)
    const hasTsNode = findDependencyEntries(manifests, ['ts-node']).length > 0
    if (tsConfigLocations.length && !hasTsNode) {
      addResult(
        results,
        'warning',
        'Jest TypeScript config may need ts-node',
        'Jest loads TypeScript configuration files before test transforms. Without ts-node or an equivalent ' +
          'precompiled config, the selected command can fail before collecting tests.',
        {
          locations: tsConfigLocations,
          recommendation:
            'Install ts-node for the diagnostic run, or use a temporary JSON/CommonJS Jest config generated ' +
            'from the repository config.',
        }
      )
    }
  }

  if (hasFramework(frameworks, 'cucumber')) {
    const cucumber = frameworks.find(framework => framework.id === 'cucumber')
    const parallelLocations = findLocations(textFiles, CUCUMBER_PARALLEL_RE)
    const hasOldParallel = cucumber.versionDetections.some(detection =>
      detection.version && !satisfies(detection.version, '>=11.0.0')
    )

    if (parallelLocations.length && hasOldParallel) {
      addResult(
        results,
        'warning',
        'Cucumber parallel mode has feature limits before version 11',
        'Some Test Optimization features for Cucumber parallel mode require @cucumber/cucumber >=11.0.0.',
        {
          locations: parallelLocations,
          recommendation: 'Upgrade @cucumber/cucumber to >=11.0.0 when using --parallel.',
        }
      )
    }
  }
}

/**
 * Checks Cypress-specific setup.
 *
 * @param {Array<object>} results mutable result list
 * @param {object} evidence repository evidence
 */
function checkCypressConfiguration (results, evidence) {
  if (evidence.cypressSupportDisabledLocations.length) {
    addResult(
      results,
      'warning',
      'Cypress support file is disabled',
      'Cypress browser-side hooks cannot be injected when supportFile is false.',
      {
        locations: evidence.cypressSupportDisabledLocations,
        recommendation: 'Use a Cypress support file, or manually require dd-trace/ci/cypress/support.',
      }
    )
    return
  }

  if (evidence.cypressSupportLocations.length) {
    addResult(
      results,
      'ok',
      'Cypress support hook found',
      'Found dd-trace/ci/cypress/support in the repository.',
      { locations: evidence.cypressSupportLocations }
    )
  } else {
    addResult(
      results,
      'info',
      'Cypress support hook not explicitly configured',
      'For supported Cypress versions, dd-trace can inject a temporary support wrapper when dd-trace/ci/init is used.',
      {
        recommendation:
          'If browser-side test events are missing, add require("dd-trace/ci/cypress/support") to the ' +
          'Cypress support file.',
      }
    )
  }
}

/**
 * Checks static CI workflow files.
 *
 * @param {Array<object>} results mutable result list
 * @param {Array<object>} workflowFiles scanned CI workflow files
 * @param {object} evidence repository evidence
 * @param {typeof process.env} env environment
 */
function checkCiConfiguration (results, workflowFiles, evidence, env) {
  if (!workflowFiles.length) {
    addResult(
      results,
      'info',
      'No CI workflow files found',
      'The diagnosis did not find common CI configuration files to inspect.'
    )
    return
  }

  addResult(
    results,
    'ok',
    'CI workflow files found',
    `Inspected ${workflowFiles.length} CI workflow file(s).`,
    { locations: workflowFiles.map(file => file.relativePath) }
  )

  if (!evidence.hasCiInit && !hasCiInitInNodeOptions(env.NODE_OPTIONS)) {
    addResult(
      results,
      'warning',
      'CI workflows do not show Test Optimization initialization',
      'No CI workflow file shows NODE_OPTIONS preloading dd-trace/ci/init.',
      {
        recommendation:
          'Set NODE_OPTIONS="-r dd-trace/ci/init" in the CI job that runs the supported JavaScript test framework.',
      }
    )
  }

  const shallowGithubLocations = []
  const containerGithubLocations = []

  for (const file of workflowFiles) {
    if (!file.relativePath.startsWith('.github/workflows/')) continue

    if (/actions\/checkout/.test(file.content) && !/fetch-depth\s*:\s*0\b/.test(file.content)) {
      shallowGithubLocations.push(file.relativePath)
    }

    if (/\bcontainer\s*:/.test(file.content) && !/safe\.directory/.test(file.content)) {
      containerGithubLocations.push(file.relativePath)
    }
  }

  if (shallowGithubLocations.length) {
    addResult(
      results,
      'warning',
      'GitHub Actions checkout may be shallow',
      'actions/checkout defaults to a shallow checkout, which can limit git metadata and impacted-test detection.',
      {
        locations: shallowGithubLocations,
        recommendation: 'Set fetch-depth: 0 for the checkout step, or keep git unshallowing enabled.',
      }
    )
  }

  if (containerGithubLocations.length) {
    addResult(
      results,
      'info',
      'Containerized GitHub jobs may need Git safe.directory',
      'Git can reject metadata commands in containerized jobs when checkout ownership differs from the container user.',
      {
        locations: containerGithubLocations,
        recommendation: 'Run git config --global --add safe.directory "$GITHUB_WORKSPACE" when needed.',
      }
    )
  }

  if (evidence.hasAgentlessEnabled && !evidence.hasApiKey && !env.DD_API_KEY && !env.DATADOG_API_KEY) {
    addResult(
      results,
      'warning',
      'Agentless mode is enabled but no API key reference was found',
      'DD_CIVISIBILITY_AGENTLESS_ENABLED requires DD_API_KEY or DATADOG_API_KEY at runtime.',
      {
        recommendation: 'Provide DD_API_KEY or DATADOG_API_KEY as a CI secret in the test job.',
      }
    )
  }

  if (evidence.gitStrategyNoneLocations.length) {
    addResult(
      results,
      'warning',
      'CI configuration disables git checkout',
      'Git metadata extraction cannot work when the CI job does not check out the repository.',
      {
        locations: evidence.gitStrategyNoneLocations,
        recommendation: 'Enable repository checkout for Test Optimization jobs.',
      }
    )
  }
}

/**
 * Checks local git availability and repository metadata.
 *
 * @param {Array<object>} results mutable result list
 * @param {string} root repository root
 * @param {typeof process.env} env environment
 * @param {Function} execFile command runner
 * @param {string|undefined} gitExecutable trusted git executable
 */
function checkGit (results, root, env, execFile, gitExecutable) {
  const gitEnv = getGitEnvironment(gitExecutable, env)
  if (!canRunGit(execFile, root, gitExecutable, gitEnv)) {
    addResult(
      results,
      'error',
      'git executable is not available',
      'Test Optimization uses git to extract repository metadata and impacted files.',
      { recommendation: 'Install git in the CI image or runner that executes tests.' }
    )
    return
  }

  addResult(results, 'ok', 'git executable found', 'The current environment can execute git.')

  const insideWorktree = runGit(execFile, root, gitExecutable, gitEnv, ['rev-parse', '--is-inside-work-tree'])
  if (insideWorktree !== 'true') {
    addResult(
      results,
      'warning',
      'Current path is not inside a git worktree',
      'Git metadata extraction needs the checked-out repository.',
      { recommendation: 'Run the test command from inside the checked-out repository.' }
    )
    return
  }

  const head = runGit(execFile, root, gitExecutable, gitEnv, ['rev-parse', 'HEAD'])
  const remote = runGit(execFile, root, gitExecutable, gitEnv, ['config', '--get', 'remote.origin.url'])
  const branch = runGit(execFile, root, gitExecutable, gitEnv, ['branch', '--show-current'])
  const shallow = runGit(execFile, root, gitExecutable, gitEnv, ['rev-parse', '--is-shallow-repository'])

  if (head) {
    addResult(results, 'ok', 'git commit SHA detected', `Current HEAD is ${head.slice(0, 12)}.`)
  } else {
    addResult(
      results,
      'warning',
      'git commit SHA could not be detected',
      'The diagnosis could not read git rev-parse HEAD.',
      { recommendation: 'Ensure the CI checkout includes a valid git repository.' }
    )
  }

  if (!remote) {
    addResult(
      results,
      'warning',
      'git remote origin is not configured',
      'Repository URL metadata may be missing.',
      { recommendation: 'Configure remote.origin.url or provide DD_GIT_REPOSITORY_URL.' }
    )
  }

  if (!branch && !hasBranchMetadata(env)) {
    addResult(
      results,
      'warning',
      'git branch metadata could not be detected',
      'The checkout appears detached and no CI branch metadata was found in the current environment.',
      { recommendation: 'Provide branch metadata through CI provider variables or DD_GIT_BRANCH.' }
    )
  }

  if (shallow === 'true') {
    addResult(
      results,
      'warning',
      'Repository is shallow',
      'A shallow repository can limit metadata upload and impacted-test detection.',
      { recommendation: 'Use a full checkout, or keep DD_CIVISIBILITY_GIT_UNSHALLOW_ENABLED enabled.' }
    )
  }
}

/**
 * Checks current environment variables relevant to Test Optimization.
 *
 * @param {Array<object>} results mutable result list
 * @param {typeof process.env} env environment
 * @param {object} evidence repository evidence
 */
function checkCurrentEnvironment (results, env, evidence) {
  if (isFalseLike(env.DD_CIVISIBILITY_ENABLED) || evidence.hasCiVisibilityDisabled) {
    addResult(
      results,
      'error',
      'Test Optimization is explicitly disabled',
      'DD_CIVISIBILITY_ENABLED is set to false or 0.',
      { recommendation: 'Remove DD_CIVISIBILITY_ENABLED=false from the test job.' }
    )
  }

  if (isFalseLike(env.DD_CIVISIBILITY_ITR_ENABLED) || evidence.hasItrDisabled) {
    addResult(
      results,
      'warning',
      'Test Impact Analysis is disabled',
      'DD_CIVISIBILITY_ITR_ENABLED is set to false or 0.',
      { recommendation: 'Remove DD_CIVISIBILITY_ITR_ENABLED=false if suite skipping should be enabled.' }
    )
  }

  if (isFalseLike(env.DD_CIVISIBILITY_GIT_UPLOAD_ENABLED) || evidence.hasGitUploadDisabled) {
    addResult(
      results,
      'warning',
      'Git metadata upload is disabled',
      'DD_CIVISIBILITY_GIT_UPLOAD_ENABLED is set to false or 0.',
      { recommendation: 'Remove DD_CIVISIBILITY_GIT_UPLOAD_ENABLED=false unless this is intentional.' }
    )
  }

  if (isTrueLike(env.DD_CIVISIBILITY_AGENTLESS_ENABLED) && !env.DD_API_KEY && !env.DATADOG_API_KEY) {
    addResult(
      results,
      'error',
      'Agentless mode is missing an API key',
      'The current environment has DD_CIVISIBILITY_AGENTLESS_ENABLED set, but no DD_API_KEY or DATADOG_API_KEY.',
      { recommendation: 'Set DD_API_KEY or DATADOG_API_KEY in the CI job.' }
    )
  }

  if (!env.DD_SERVICE && !evidence.hasService) {
    addResult(
      results,
      'warning',
      'DD_SERVICE was not found',
      'A missing service name makes Test Optimization data harder to find and group.',
      { recommendation: 'Set DD_SERVICE in the test job.' }
    )
  }

  if ((env.OTEL_TRACES_EXPORTER || '').toLowerCase() === 'otlp' || evidence.hasOtelOtlpExporter) {
    addResult(
      results,
      'warning',
      'OTEL_TRACES_EXPORTER=otlp was found',
      'An OTLP traces exporter can interfere with dd-trace test payloads in instrumented shells.',
      { recommendation: 'Unset OTEL_TRACES_EXPORTER for dd-trace Test Optimization jobs.' }
    )
  }

  if (env.CI) {
    checkCurrentCiMetadata(results, env)
  } else {
    addResult(
      results,
      'info',
      'Current process is not running in CI',
      'Runtime CI metadata checks were skipped because CI is not set in the current environment.'
    )
  }
}

/**
 * Checks current CI provider metadata.
 *
 * @param {Array<object>} results mutable result list
 * @param {typeof process.env} env environment
 */
function checkCurrentCiMetadata (results, env) {
  const providerDetected = CURRENT_ENV_PROVIDER_KEYS.some(key => env[key])
  if (!providerDetected) {
    addResult(
      results,
      'warning',
      'Current CI provider is not recognized',
      'The current environment has CI set, but no known CI provider variables were found.',
      { recommendation: 'Provide CI and git metadata with DD_GIT_* variables if the provider is custom.' }
    )
  }

  if (!hasShaMetadata(env)) {
    addResult(
      results,
      'warning',
      'Current CI commit SHA metadata is missing',
      'The current CI environment does not expose a recognized commit SHA variable.',
      { recommendation: 'Provide DD_GIT_COMMIT_SHA when the CI provider does not expose one.' }
    )
  }

  if (!hasBranchMetadata(env)) {
    addResult(
      results,
      'warning',
      'Current CI branch metadata is missing',
      'The current CI environment does not expose a recognized branch or tag variable.',
      { recommendation: 'Provide DD_GIT_BRANCH or DD_GIT_TAG when the CI provider does not expose one.' }
    )
  }
}

/**
 * Collects package scripts from all manifests.
 *
 * @param {Array<object>} manifests package manifests
 * @returns {Array<object>} scripts
 */
function collectScripts (manifests) {
  const scripts = []

  for (const manifest of manifests) {
    const manifestScripts = manifest.json.scripts || {}
    for (const [name, command] of Object.entries(manifestScripts)) {
      if (typeof command !== 'string') continue

      scripts.push({
        name,
        command,
        relativePath: manifest.relativePath,
      })
    }
  }

  return scripts
}

/**
 * Detects supported test frameworks.
 *
 * @param {string} root repository root
 * @param {Array<object>} definitions framework definitions
 * @param {Array<object>} manifests package manifests
 * @param {Array<object>} scripts package scripts
 * @param {Array<object>} textFiles scanned text files
 * @returns {Array<object>} detected supported frameworks
 */
function detectSupportedFrameworks (root, definitions, manifests, scripts, textFiles) {
  const frameworks = []
  const projectPreferenceScores = getProjectPreferenceScores(root, manifests)

  for (const definition of definitions) {
    const dependencyEntries = [
      ...findDependencyEntries(manifests, definition.packages),
      ...findPackageIdentityEntries(manifests, definition.packages),
    ]
    const scriptMatches = findScriptMatches(scripts, definition.commandPatterns)
    const configMatches = findConfigMatches(textFiles, definition.configPatterns)

    if (!dependencyEntries.length && !scriptMatches.length && !configMatches.length) continue

    frameworks.push({
      ...definition,
      dependencyEntries,
      scriptMatches,
      configMatches,
      projectPreferenceScores,
      locations: unique([
        ...dependencyEntries.map(entry => entry.relativePath),
        ...scriptMatches.map(script => script.relativePath),
        ...configMatches,
      ]),
      versionDetections: getVersionDetections(root, definition.packages, dependencyEntries),
    })
  }

  return frameworks
}

/**
 * Gets frameworks that are eligible live-validation candidates.
 *
 * @param {Array<object>} frameworks detected supported frameworks
 * @returns {Array<object>} eligible frameworks with eligibility details
 */
function getEligibleFrameworks (frameworks) {
  const eligible = []

  for (const framework of frameworks) {
    const command = getEligibleCommandMatch(framework)
    const version = getSupportedVersionDetection(framework, command?.relativePath)
    const reasons = []

    if (!version) reasons.push(`No statically supported ${framework.name} version was found.`)
    if (!command) reasons.push(`No eligible ${framework.name} test command was found.`)

    if (!version || !command) continue

    eligible.push({
      ...framework,
      eligibleCommand: command,
      eligibleVersion: version,
      eligibility: {
        command: command.command,
        commandLocation: command.relativePath,
        version: version.version,
        versionLocation: version.relativePath,
      },
      ineligibleReasons: reasons,
    })
  }

  return eligible
}

/**
 * Gets the first supported version detection for a framework.
 *
 * @param {object} framework detected framework
 * @param {string} [relativePath] package manifest that owns the selected command
 * @returns {object|undefined} supported version detection
 */
function getSupportedVersionDetection (framework, relativePath) {
  const detections = framework.versionDetections || []
  const localDetections = relativePath
    ? detections.filter(detection => detection.relativePath === relativePath)
    : []
  const candidates = localDetections.length > 0 ? localDetections : detections

  for (const detection of candidates) {
    if (detection.version && satisfies(detection.version, framework.supportedRange)) return detection
  }
}

/**
 * Gets an eligible script command for a framework.
 *
 * @param {object} framework detected framework
 * @returns {object|undefined} eligible command match
 */
function getEligibleCommandMatch (framework) {
  const scriptMatches = [...(framework.scriptMatches || [])].sort((left, right) => {
    return compareProjectScope(left, right, framework.projectPreferenceScores) ||
      getFrameworkCommandPreference(framework.id, left) - getFrameworkCommandPreference(framework.id, right) ||
      left.relativePath.localeCompare(right.relativePath)
  })

  for (const script of scriptMatches) {
    if (isIneligibleFrameworkCommand(framework.id, script.command)) continue
    return script
  }

  if (framework.id === 'cucumber' || framework.id === 'cypress' || framework.id === 'jest' ||
    framework.id === 'mocha' || framework.id === 'playwright' || framework.id === 'vitest') {
    const dependencyEntries = [...(framework.dependencyEntries || [])].sort((left, right) => {
      return compareProjectPreference(left, right, framework.projectPreferenceScores)
    })
    return dependencyEntries[0] && {
      command: `direct ${framework.id} binary`,
      relativePath: dependencyEntries[0].relativePath,
    }
  }
}

/**
 * Prefers direct, single-stage framework scripts over aggregate coverage or setup chains.
 *
 * @param {string} frameworkId framework id
 * @param {object} script package script
 * @returns {number} lower is preferred
 */
function getFrameworkCommandPreference (frameworkId, script) {
  let score = 0
  if (/coverage|all|full/i.test(script.name)) score += 4
  if (/[\r\n;&|`]|\$\(/.test(script.command)) score += 4
  const invokesFramework = frameworkId === 'cucumber'
    ? isCucumberRunnerCommand(script.command)
    : script.command.toLowerCase().includes(frameworkId.toLowerCase())
  if (invokesFramework) score--
  return score
}

/**
 * Scores package manifests by how closely their names match the repository directory name.
 *
 * @param {string} root repository root
 * @param {Array<object>} manifests package manifests
 * @returns {Map<string, number>} preference score by package.json path
 */
function getProjectPreferenceScores (root, manifests) {
  const repositoryTokens = getIdentityTokens(path.basename(root))
  const scores = new Map()

  for (const manifest of manifests) {
    const projectName = manifest.json.name || (manifest.relativePath === 'package.json'
      ? path.basename(root)
      : path.basename(path.dirname(manifest.relativePath)))
    const projectTokens = getIdentityTokens(projectName)
    let score = 0
    for (const token of projectTokens) {
      if (repositoryTokens.has(token)) score++
    }
    scores.set(manifest.relativePath, score)
  }

  return scores
}

/**
 * Normalizes repository and package names for conservative identity comparison.
 *
 * @param {string} value repository or package name
 * @returns {Set<string>} normalized identity tokens
 */
function getIdentityTokens (value) {
  const tokens = String(value || '').toLowerCase().split(/[^a-z0-9]+/).filter(Boolean)
  const normalized = new Set()
  for (const token of tokens) {
    if (['monorepo', 'package', 'packages', 'project', 'repo', 'root', 'workspace'].includes(token)) continue
    normalized.add(token.endsWith('js') && token.length > 2 ? token.slice(0, -2) : token)
  }
  return normalized
}

/**
 * Orders command owners by repository identity, then by scope and stable path.
 *
 * @param {object} left first command or dependency entry
 * @param {object} right second command or dependency entry
 * @param {Map<string, number>|undefined} scores package preference scores
 * @returns {number} sort order
 */
function compareProjectPreference (left, right, scores) {
  return compareProjectScope(left, right, scores) ||
    left.relativePath.localeCompare(right.relativePath)
}

/**
 * Orders command owners by repository identity and package depth.
 *
 * @param {object} left first command or dependency entry
 * @param {object} right second command or dependency entry
 * @param {Map<string, number>|undefined} scores package preference scores
 * @returns {number} sort order before stable path tie-breaking
 */
function compareProjectScope (left, right, scores) {
  const scoreDifference = (scores?.get(right.relativePath) || 0) - (scores?.get(left.relativePath) || 0)
  if (scoreDifference !== 0) return scoreDifference

  return left.relativePath.split('/').length - right.relativePath.split('/').length
}

/**
 * Checks whether a framework command is ineligible for live validation.
 *
 * @param {string} frameworkId framework id
 * @param {string} command package script command
 * @returns {boolean} whether the command is ineligible
 */
function isIneligibleFrameworkCommand (frameworkId, command) {
  if (frameworkId === 'cucumber' && !isCucumberRunnerCommand(command)) return true
  if (frameworkId === 'vitest' && /\bvitest\s+bench\b/.test(command)) return true
  if (WATCH_MODE_RE.test(command)) return true

  return false
}

/**
 * Checks whether a package command invokes the Cucumber runner instead of merely naming a Cucumber config file.
 *
 * @param {string} command package script command
 * @returns {boolean} whether the command invokes Cucumber
 */
function isCucumberRunnerCommand (command) {
  return CUCUMBER_RUNNER_COMMAND_RE.test(String(command || ''))
}

/**
 * Detects unsupported test frameworks.
 *
 * @param {Array<object>} definitions unsupported framework definitions
 * @param {Array<object>} manifests package manifests
 * @param {Array<object>} scripts package scripts
 * @returns {Array<object>} detected unsupported frameworks
 */
function detectUnsupportedFrameworks (definitions, manifests, scripts) {
  const frameworks = []

  for (const definition of definitions) {
    const dependencyEntries = findDependencyEntries(manifests, definition.packages)
    const scriptMatches = findScriptMatches(scripts, definition.commandPatterns)

    if (!dependencyEntries.length && !scriptMatches.length) continue

    frameworks.push({
      ...definition,
      locations: unique([
        ...dependencyEntries.map(entry => entry.relativePath),
        ...scriptMatches.map(script => script.relativePath),
      ]),
    })
  }

  return frameworks
}

/**
 * Collects useful boolean evidence from scanned files and environment.
 *
 * @param {Array<object>} textFiles scanned text files
 * @param {typeof process.env} env environment
 * @returns {object} evidence object
 */
function collectEvidence (textFiles, env) {
  const ciInitLocations = findNodeOptionsPreloadLocations(textFiles, INIT_PRELOAD_RE)
  const registerLocations = findNodeOptionsPreloadLocations(textFiles, REGISTER_PRELOAD_RE)

  return {
    ciInitLocations,
    directCiInitLocations: findLocations(textFiles, DIRECT_CI_INIT_RE),
    wrongInitLocations: findLocations(textFiles.filter(isTestSetupOrCiFile), WRONG_INIT_RE),
    cypressManualPluginLocations: findLocations(textFiles, CYPRESS_MANUAL_PLUGIN_RE),
    cypressSupportLocations: findLocations(textFiles, CYPRESS_SUPPORT_RE),
    cypressSupportDisabledLocations: findLocations(textFiles, CYPRESS_SUPPORT_DISABLED_RE),
    gitStrategyNoneLocations: findLocations(textFiles, /GIT_STRATEGY\s*:\s*none\b/i),
    hasCiInit: ciInitLocations.length > 0,
    hasRegister: registerLocations.length > 0,
    hasCiVisibilityDisabled: findLocations(textFiles, CI_DISABLED_RE).length > 0,
    hasItrDisabled: findLocations(textFiles, ITR_DISABLED_RE).length > 0,
    hasGitUploadDisabled: findLocations(textFiles, GIT_UPLOAD_DISABLED_RE).length > 0,
    hasAgentlessEnabled: findLocations(textFiles, AGENTLESS_ENABLED_RE).length > 0 ||
      isTrueLike(env.DD_CIVISIBILITY_AGENTLESS_ENABLED),
    hasApiKey: findLocations(textFiles, API_KEY_RE).length > 0,
    hasService: findLocations(textFiles, SERVICE_RE).length > 0,
    hasOtelOtlpExporter: findLocations(textFiles, OTEL_OTLP_RE).length > 0,
  }
}

/**
 * Finds dependency entries in package manifests.
 *
 * @param {Array<object>} manifests package manifests
 * @param {string[]} packageNames package names
 * @returns {Array<object>} matching dependency entries
 */
function findDependencyEntries (manifests, packageNames) {
  const entries = []
  const packageSet = new Set(packageNames)

  for (const manifest of manifests) {
    for (const section of PACKAGE_SECTIONS) {
      const dependencies = manifest.json[section]
      if (!dependencies) continue

      for (const [name, range] of Object.entries(dependencies)) {
        if (!packageSet.has(name)) continue

        entries.push({
          packageName: name,
          rawVersion: String(range),
          section,
          relativePath: manifest.relativePath,
        })
      }
    }
  }

  return entries
}

/**
 * Treats a repository containing a framework's own package as a local version source.
 *
 * @param {Array<object>} manifests package manifests
 * @param {string[]} packageNames framework package names
 * @returns {Array<object>} local package identities
 */
function findPackageIdentityEntries (manifests, packageNames) {
  const packageSet = new Set(packageNames)
  const entries = []
  for (const manifest of manifests) {
    if (!packageSet.has(manifest.json.name) || typeof manifest.json.version !== 'string') continue
    entries.push({
      packageName: manifest.json.name,
      rawVersion: manifest.json.version,
      section: 'package',
      relativePath: manifest.relativePath,
    })
  }
  return entries
}

/**
 * Resolves framework package versions from installed modules and manifest ranges.
 *
 * @param {string} root repository root
 * @param {string[]} packageNames package names
 * @param {Array<object>} dependencyEntries dependency entries
 * @returns {Array<object>} version detections
 */
function getVersionDetections (root, packageNames, dependencyEntries) {
  const detections = []

  for (const entry of dependencyEntries) {
    const packageRoot = path.dirname(path.resolve(root, entry.relativePath))
    const installedVersion = getInstalledPackageVersion(root, entry.packageName, packageRoot)
    detections.push({
      packageName: entry.packageName,
      rawVersion: installedVersion || entry.rawVersion,
      version: installedVersion || coerceVersion(entry.rawVersion),
      relativePath: entry.relativePath,
      source: installedVersion ? 'installed' : 'manifest',
    })
  }

  if (detections.length > 0) return uniqueVersionDetections(detections)

  for (const packageName of packageNames) {
    const version = getInstalledPackageVersion(root, packageName, root)
    if (!version) continue

    detections.push({
      packageName,
      rawVersion: version,
      version,
      source: 'installed',
    })
  }

  return uniqueVersionDetections(detections)
}

/**
 * Reads an installed package version from node_modules.
 *
 * @param {string} root repository root
 * @param {string} packageName package name
 * @param {string} packageRoot package directory where resolution begins
 * @returns {string|undefined} installed version
 */
function getInstalledPackageVersion (root, packageName, packageRoot) {
  const repositoryRoot = path.resolve(root)
  let directory = path.resolve(packageRoot)
  if (!isPathInside(repositoryRoot, directory)) return

  while (isPathInside(repositoryRoot, directory)) {
    const packageJsonPath = path.join(directory, 'node_modules', ...packageName.split('/'), 'package.json')
    const json = readJsonFile(packageJsonPath)
    if (typeof json?.version === 'string') return json.version
    if (directory === repositoryRoot) return

    const parent = path.dirname(directory)
    if (parent === directory) return
    directory = parent
  }
}

/**
 * Finds scripts matching any pattern.
 *
 * @param {Array<object>} scripts package scripts
 * @param {RegExp[]} patterns command patterns
 * @returns {Array<object>} matching scripts
 */
function findScriptMatches (scripts, patterns) {
  const matches = []

  for (const script of scripts) {
    if (!/test|spec|e2e|integration|unit/i.test(script.name) &&
      !patterns.some(pattern => pattern.test(script.command))) {
      continue
    }

    if (patterns.some(pattern => pattern.test(script.command))) {
      matches.push(script)
    }
  }

  return matches
}

/**
 * Finds scanned config files that match definition patterns.
 *
 * @param {Array<object>} textFiles scanned text files
 * @param {RegExp[]} patterns filename patterns
 * @returns {string[]} matching relative paths
 */
function findConfigMatches (textFiles, patterns) {
  const matches = []

  for (const file of textFiles) {
    const basename = path.basename(file.relativePath)
    if (patterns.some(pattern => pattern.test(basename))) {
      matches.push(file.relativePath)
    }
  }

  return matches
}

/**
 * Finds Jest TypeScript config files.
 *
 * @param {Array<object>} textFiles scanned text files
 * @returns {string[]} matching relative paths
 */
function findJestTypescriptConfigLocations (textFiles) {
  return textFiles
    .map(file => file.relativePath)
    .filter(relativePath => /(?:^|\/)jest\.config\.(?:ts|mts|cts)$/.test(relativePath))
}

/**
 * Finds files where NODE_OPTIONS appears close to a supported Node preload option.
 *
 * @param {Array<object>} textFiles scanned text files
 * @param {RegExp} preloadPattern Node preload option pattern
 * @returns {string[]} matching relative paths
 */
function findNodeOptionsPreloadLocations (textFiles, preloadPattern) {
  const locations = []

  for (const file of textFiles) {
    const lines = file.content.split(/\r?\n/)
    for (let i = 0; i < lines.length; i++) {
      if (!NODE_OPTIONS_RE.test(lines[i])) continue

      const window = lines.slice(i, i + 4).join('\n')
      preloadPattern.lastIndex = 0
      if (preloadPattern.test(window)) {
        locations.push(file.relativePath)
        break
      }
    }
  }

  return unique(locations)
}

/**
 * Finds files whose content matches a pattern.
 *
 * @param {Array<object>} textFiles scanned text files
 * @param {RegExp} pattern content pattern
 * @returns {string[]} matching relative paths
 */
function findLocations (textFiles, pattern) {
  const locations = []

  for (const file of textFiles) {
    pattern.lastIndex = 0
    if (pattern.test(file.content)) {
      locations.push(file.relativePath)
    }
  }

  return unique(locations)
}

/**
 * Collects text-like repository files.
 *
 * @param {string} root repository root
 * @param {string|undefined} physicalRoot physical repository root
 * @param {number} maxFiles maximum number of files
 * @param {string[]} [excludePaths] repository paths excluded from the scan
 * @returns {Array<string> & {truncated?: boolean}} relative paths
 */
function collectTextFiles (root, physicalRoot, maxFiles, excludePaths = []) {
  const files = []
  const seen = new Set()
  const exclusions = getScanExclusions(root, excludePaths)
  files.truncated = false

  addTextFileIfPresent('package.json')

  function walk (dir, relativeDir) {
    if (files.length >= maxFiles) {
      files.truncated = true
      return
    }

    let entries
    try {
      entries = fs.readdirSync(dir, { withFileTypes: true })
    } catch {
      return
    }

    entries.sort((a, b) => a.name.localeCompare(b.name))

    for (const entry of entries) {
      if (files.length >= maxFiles) {
        files.truncated = true
        return
      }

      const relativePath = relativeDir ? path.join(relativeDir, entry.name) : entry.name
      const absolutePath = path.join(root, relativePath)
      if (isScanPathExcluded(relativePath, exclusions)) continue

      if (entry.isDirectory()) {
        if (!SKIPPED_DIRECTORIES.has(entry.name)) {
          walk(absolutePath, relativePath)
        }
        continue
      }

      if (entry.isFile() && isTextFileName(entry.name)) {
        addTextFile(relativePath)
      }
    }
  }

  function addTextFileIfPresent (relativePath) {
    if (!getSafeScannedFile(root, physicalRoot, relativePath)) return
    addTextFile(relativePath)
  }

  function addTextFile (relativePath) {
    const normalizedPath = normalizeRelativePath(relativePath)
    if (seen.has(normalizedPath) || SKIPPED_FILES.has(normalizedPath)) return

    if (files.length >= maxFiles) {
      files.truncated = true
      return
    }

    seen.add(normalizedPath)
    files.push(relativePath)
  }

  walk(root, '')
  return files
}

/**
 * Normalizes caller-provided scan exclusions to repository-relative paths.
 *
 * @param {string} root repository root
 * @param {string[]} excludePaths paths to exclude
 * @returns {Set<string>} normalized repository-relative exclusions
 */
function getScanExclusions (root, excludePaths) {
  const exclusions = new Set()
  for (const candidate of excludePaths) {
    if (typeof candidate !== 'string') continue
    const relative = path.relative(root, path.resolve(root, candidate))
    if (!relative || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) continue
    exclusions.add(normalizeRelativePath(relative))
  }
  return exclusions
}

/**
 * Checks whether a scanned path is inside a caller-provided exclusion.
 *
 * @param {string} relativePath repository-relative path
 * @param {Set<string>} exclusions normalized exclusions
 * @returns {boolean} whether the path must be skipped
 */
function isScanPathExcluded (relativePath, exclusions) {
  const normalizedPath = normalizeRelativePath(relativePath)
  for (const exclusion of exclusions) {
    if (normalizedPath === exclusion || normalizedPath.startsWith(`${exclusion}/`)) return true
  }
  return false
}

/**
 * Reads scanned text files within the size limit.
 *
 * @param {string} root repository root
 * @param {string|undefined} physicalRoot physical repository root
 * @param {string[]} files relative file paths
 * @param {number} maxTotalBytes maximum aggregate bytes to retain
 * @returns {Array<object>} text file records
 */
function readTextFiles (root, physicalRoot, files, maxTotalBytes) {
  const textFiles = []
  let totalBytes = 0
  textFiles.truncated = false

  for (const relativePath of files) {
    const file = getSafeScannedFile(root, physicalRoot, relativePath)
    if (!file) continue

    if (file.stat.size > MAX_TEXT_FILE_SIZE) continue
    if (totalBytes + file.stat.size > maxTotalBytes) {
      textFiles.truncated = true
      break
    }

    try {
      const content = fs.readFileSync(file.filename, 'utf8')
      const contentBytes = Buffer.byteLength(content)
      if (contentBytes > MAX_TEXT_FILE_SIZE) continue
      if (totalBytes + contentBytes > maxTotalBytes) {
        textFiles.truncated = true
        break
      }
      textFiles.push({
        relativePath: normalizeRelativePath(relativePath),
        content,
      })
      totalBytes += contentBytes
    } catch {
      // Ignore files that cannot be read as UTF-8.
    }
  }

  return textFiles
}

/**
 * Resolves the physical repository root used to constrain scanned file reads.
 *
 * @param {string} root repository root
 * @returns {string|undefined} physical directory path
 */
function getPhysicalRoot (root) {
  try {
    const physicalRoot = fs.realpathSync(root)
    return fs.statSync(physicalRoot).isDirectory() ? physicalRoot : undefined
  } catch {}
}

/**
 * Resolves one regular non-symlink file without escaping the physical repository root.
 *
 * @param {string} root lexical repository root
 * @param {string|undefined} physicalRoot physical repository root
 * @param {string} relativePath repository-relative candidate
 * @returns {{filename: string, stat: fs.Stats}|undefined} safe file information
 */
function getSafeScannedFile (root, physicalRoot, relativePath) {
  if (!physicalRoot) return

  const lexicalRoot = path.resolve(root)
  const absolutePath = path.resolve(lexicalRoot, relativePath)
  if (!isPathInside(lexicalRoot, absolutePath)) return

  try {
    const entry = fs.lstatSync(absolutePath)
    if (!entry.isFile() || entry.isSymbolicLink()) return

    const filename = fs.realpathSync(absolutePath)
    if (!isPathInside(physicalRoot, filename)) return

    const stat = fs.statSync(filename)
    return stat.isFile() ? { filename, stat } : undefined
  } catch {}
}

/**
 * Checks lexical or physical path containment.
 *
 * @param {string} root allowed root
 * @param {string} filename candidate path
 * @returns {boolean} whether the candidate is inside the root
 */
function isPathInside (root, filename) {
  const relative = path.relative(root, filename)
  return relative === '' || (relative && !relative.startsWith('..') && !path.isAbsolute(relative))
}

/**
 * Checks whether a filename should be scanned as text.
 *
 * @param {string} name filename
 * @returns {boolean} true if the file is text-like
 */
function isTextFileName (name) {
  return TEXT_FILE_NAMES.has(name) || TEXT_EXTENSIONS.has(path.extname(name))
}

/**
 * Checks whether a file is a common CI workflow file.
 *
 * @param {string} relativePath relative path
 * @returns {boolean} true if the path is a workflow file
 */
function isWorkflowFile (relativePath) {
  return relativePath.startsWith('.github/workflows/') ||
    relativePath === '.gitlab-ci.yml' ||
    relativePath === '.gitlab-ci.yaml' ||
    relativePath === 'bitbucket-pipelines.yml' ||
    relativePath === 'bitbucket-pipelines.yaml' ||
    relativePath === 'azure-pipelines.yml' ||
    relativePath === 'azure-pipelines.yaml' ||
    /^\.azure-pipelines\/.+\.ya?ml$/.test(relativePath) ||
    relativePath === 'Jenkinsfile' ||
    relativePath === '.circleci/config.yml' ||
    relativePath === '.circleci/config.yaml' ||
    relativePath === '.buildkite/pipeline.yml' ||
    relativePath === '.buildkite/pipeline.yaml'
}

/**
 * Checks whether a scanned file is likely to configure test process initialization.
 *
 * @param {object} file scanned text file
 * @returns {boolean} true when plain dd-trace init should be treated as test setup evidence
 */
function isTestSetupOrCiFile (file) {
  const relativePath = file.relativePath
  const basename = path.basename(relativePath)

  if (isWorkflowFile(relativePath)) return true
  if (basename === 'package.json') return true
  if (/^(?:jest|config-jest|vitest|vite|playwright|cypress|cucumber)\.config\./.test(basename)) return true
  if (/^\.mocharc\./.test(basename)) return true
  if (basename === 'cypress.json') return true
  if (/setup|bootstrap/i.test(basename)) return true
  if (relativePath.startsWith('cypress/support/')) return true

  return false
}

/**
 * Runs git --version to check availability.
 *
 * @param {Function} execFile command runner
 * @param {string} root repository root
 * @param {string|undefined} gitExecutable trusted git executable
 * @param {typeof process.env} env credential-free git environment
 * @returns {boolean} true if git runs
 */
function canRunGit (execFile, root, gitExecutable, env) {
  if (!gitExecutable) return false

  try {
    execFile(gitExecutable, ['--version'], { cwd: root, env, stdio: 'pipe', timeout: 2000 })
    return true
  } catch {
    return false
  }
}

/**
 * Runs a git command and trims output.
 *
 * @param {Function} execFile command runner
 * @param {string} root repository root
 * @param {string} gitExecutable trusted git executable
 * @param {typeof process.env} env credential-free git environment
 * @param {string[]} args git arguments
 * @returns {string} command output
 */
function runGit (execFile, root, gitExecutable, env, args) {
  try {
    return String(execFile(gitExecutable, args, { cwd: root, env, stdio: 'pipe', timeout: 2000 })).trim()
  } catch {
    return ''
  }
}

/**
 * Resolves git without trusting repository-controlled PATH entries.
 *
 * @returns {string|undefined} trusted absolute git path
 */
function findTrustedGitExecutable () {
  const candidates = process.platform === 'win32'
    ? [
        String.raw`C:\Program Files\Git\cmd\git.exe`,
        String.raw`C:\Program Files\Git\bin\git.exe`,
        String.raw`C:\Program Files (x86)\Git\cmd\git.exe`,
        String.raw`C:\Program Files (x86)\Git\bin\git.exe`,
      ]
    : ['/usr/bin/git', '/usr/local/bin/git', '/opt/homebrew/bin/git']

  for (const candidate of candidates) {
    let resolved
    try {
      resolved = fs.realpathSync(candidate)
      fs.accessSync(resolved, fs.constants.X_OK)
    } catch {
      continue
    }

    return resolved
  }
}

/**
 * Creates the minimal environment needed by read-only local git metadata commands.
 *
 * @param {string|undefined} gitExecutable trusted git executable
 * @param {typeof process.env} sourceEnv source environment
 * @returns {typeof process.env} credential-free git environment
 */
function getGitEnvironment (gitExecutable, sourceEnv) {
  const env = {
    GIT_CONFIG_GLOBAL: process.platform === 'win32' ? 'NUL' : '/dev/null',
    GIT_CONFIG_NOSYSTEM: '1',
    GIT_OPTIONAL_LOCKS: '0',
    GIT_TERMINAL_PROMPT: '0',
  }

  for (const name of ['COMSPEC', 'ComSpec', 'PATHEXT', 'SystemRoot', 'WINDIR', 'windir']) {
    if (sourceEnv[name] !== undefined) env[name] = sourceEnv[name]
  }
  if (gitExecutable && path.isAbsolute(gitExecutable)) env.PATH = path.dirname(gitExecutable)
  return env
}

/**
 * Reads a JSON file.
 *
 * @param {string} filePath absolute file path
 * @returns {object|undefined} parsed JSON
 */
function readJsonFile (filePath) {
  try {
    return parseJson(fs.readFileSync(filePath, 'utf8'))
  } catch {
    // File is absent or unreadable.
  }
}

/**
 * Parses JSON safely.
 *
 * @param {string} content JSON content
 * @returns {object|undefined} parsed JSON
 */
function parseJson (content) {
  try {
    return JSON.parse(content)
  } catch {
    // Invalid JSON is reported by the checks that depend on it.
  }
}

/**
 * Extracts a comparable semantic version from a package range.
 *
 * @param {string} rawVersion raw package version or range
 * @returns {string|undefined} comparable version
 */
function coerceVersion (rawVersion) {
  const aliasedVersion = rawVersion.match(/^npm:[^@]+@(.+)$/)?.[1] || rawVersion
  if (isAmbiguousRange(aliasedVersion)) return

  const match = aliasedVersion.match(/\d+(?:\.\d+){0,2}/)
  if (!match) return

  const parts = match[0].split('.')
  while (parts.length < 3) {
    parts.push('0')
  }
  return parts.slice(0, 3).join('.')
}

/**
 * Checks whether a manifest dependency range cannot be represented by one comparable version.
 *
 * @param {string} rawVersion package manifest version/range
 * @returns {boolean} true when static diagnosis should ask the user to verify the range
 */
function isAmbiguousRange (rawVersion) {
  const version = String(rawVersion || '').trim()
  if (!version) return true
  if (version.includes('||')) return true
  return /<=?\s*\d/.test(version)
}

/**
 * Checks whether a framework id is present.
 *
 * @param {Array<object>} frameworks detected frameworks
 * @param {string} id framework id
 * @returns {boolean} true if present
 */
function hasFramework (frameworks, id) {
  return frameworks.some(framework => framework.id === id)
}

/**
 * Checks whether NODE_OPTIONS preloads dd-trace/ci/init.
 *
 * @param {string|undefined} nodeOptions NODE_OPTIONS value
 * @returns {boolean} true if dd-trace/ci/init is present
 */
function hasCiInitInNodeOptions (nodeOptions) {
  return !!nodeOptions && INIT_PRELOAD_RE.test(nodeOptions)
}

/**
 * Checks whether NODE_OPTIONS preloads dd-trace/register.js.
 *
 * @param {string|undefined} nodeOptions NODE_OPTIONS value
 * @returns {boolean} true if dd-trace/register.js is present
 */
function hasRegisterInNodeOptions (nodeOptions) {
  return !!nodeOptions && REGISTER_PRELOAD_RE.test(nodeOptions)
}

/**
 * Checks whether environment contains branch or tag metadata.
 *
 * @param {typeof process.env} env environment
 * @returns {boolean} true if branch metadata exists
 */
function hasBranchMetadata (env) {
  return !!(
    env.DD_GIT_BRANCH ||
    env.DD_GIT_TAG ||
    env.GITHUB_HEAD_REF ||
    env.GITHUB_REF_NAME ||
    env.CI_COMMIT_REF_NAME ||
    env.CIRCLE_BRANCH ||
    env.GIT_BRANCH ||
    env.BUILDKITE_BRANCH ||
    env.TRAVIS_BRANCH ||
    env.BITBUCKET_BRANCH ||
    env.DRONE_BRANCH ||
    env.BUDDY_EXECUTION_BRANCH ||
    env.BITRISE_GIT_BRANCH
  )
}

/**
 * Checks whether environment contains commit SHA metadata.
 *
 * @param {typeof process.env} env environment
 * @returns {boolean} true if SHA metadata exists
 */
function hasShaMetadata (env) {
  return !!(
    env.DD_GIT_COMMIT_SHA ||
    env.GITHUB_SHA ||
    env.CI_COMMIT_SHA ||
    env.CIRCLE_SHA1 ||
    env.GIT_COMMIT ||
    env.BUILDKITE_COMMIT ||
    env.TRAVIS_COMMIT ||
    env.BITBUCKET_COMMIT ||
    env.DRONE_COMMIT ||
    env.BUDDY_EXECUTION_REVISION
  )
}

/**
 * Checks truthy string env values.
 *
 * @param {string|undefined} value value to inspect
 * @returns {boolean} true if value is true-like
 */
function isTrueLike (value) {
  return /^(?:1|true)$/i.test(String(value || ''))
}

/**
 * Checks false-like string env values.
 *
 * @param {string|undefined} value value to inspect
 * @returns {boolean} true if value is false-like
 */
function isFalseLike (value) {
  return /^(?:0|false)$/i.test(String(value || ''))
}

/**
 * Formats a list of locations for text output.
 *
 * @param {string[]} locations relative paths
 * @returns {string} formatted locations
 */
function formatLocations (locations) {
  const uniqueLocations = unique(locations).slice(0, 5)
  const suffix = locations.length > uniqueLocations.length
    ? `, and ${locations.length - uniqueLocations.length} more`
    : ''
  return uniqueLocations.join(', ') + suffix
}

/**
 * Serializes a supported framework for JSON output.
 *
 * @param {object} framework detected framework
 * @returns {object} serializable framework summary
 */
function serializeSupportedFramework (framework) {
  const eligibleCommand = getEligibleCommandMatch(framework)
  const supportedVersion = getSupportedVersionDetection(framework, eligibleCommand?.relativePath)
  return {
    id: framework.id,
    name: framework.name,
    packages: framework.packages,
    supportedRange: framework.supportedRange,
    locations: framework.locations,
    versionDetections: framework.versionDetections,
    eligibleCommand,
    supportedVersion,
  }
}

/**
 * Serializes an eligible framework for JSON output.
 *
 * @param {object} framework eligible framework
 * @returns {object} serializable eligible framework summary
 */
function serializeEligibleFramework (framework) {
  return {
    id: framework.id,
    name: framework.name,
    command: framework.eligibility.command,
    commandLocation: framework.eligibility.commandLocation,
    supportedRange: framework.supportedRange,
    version: framework.eligibility.version,
    versionLocation: framework.eligibility.versionLocation,
  }
}

/**
 * Serializes an unsupported framework for JSON output.
 *
 * @param {object} framework detected unsupported framework
 * @returns {object} serializable framework summary
 */
function serializeUnsupportedFramework (framework) {
  return {
    id: framework.id,
    name: framework.name,
    locations: framework.locations,
  }
}

/**
 * Deduplicates values.
 *
 * @param {Array<string>} values values
 * @returns {string[]} unique values
 */
function unique (values) {
  return [...new Set(values.filter(Boolean))]
}

/**
 * Deduplicates version detections.
 *
 * @param {Array<object>} detections version detections
 * @returns {Array<object>} unique detections
 */
function uniqueVersionDetections (detections) {
  const seen = new Set()
  const uniqueDetections = []

  for (const detection of detections) {
    const key = `${detection.packageName}:${detection.rawVersion}:${detection.relativePath || ''}`
    if (seen.has(key)) continue

    seen.add(key)
    uniqueDetections.push(detection)
  }

  return uniqueDetections
}

/**
 * Normalizes relative paths to POSIX separators for stable output.
 *
 * @param {string} relativePath relative path
 * @returns {string} normalized path
 */
function normalizeRelativePath (relativePath) {
  return relativePath.split(path.sep).join('/')
}

module.exports = {
  getFrameworkDefinitions,
  runDiagnosis,
}