dd-trace 5.116.0 → 5.118.0

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

@@ -1,14 +1,44 @@
 'use strict'
 
-/* eslint-disable eslint-rules/eslint-process-env */
-
 const fs = require('node:fs')
 const path = require('node:path')
 
 const { runDiagnosis } = require('../diagnose')
+const cucumber = require('./framework-adapters/cucumber')
+const cypress = require('./framework-adapters/cypress')
+const playwright = require('./framework-adapters/playwright')
+const {
+  GENERATED_SCENARIOS,
+  getGeneratedRetryStatePath,
+  getGeneratedTestContent,
+} = require('./generated-test-contract')
 const { validateManifest } = require('./manifest-schema')
+const {
+  getProjectNodeRunner,
+  getRunnerContract,
+  getRunnerSearchRoots,
+} = require('./runner-contract')
 
-const SUPPORTED_SCAFFOLD_FRAMEWORKS = new Set(['jest', 'mocha', 'vitest'])
+const SUPPORTED_FRAMEWORKS = new Set(['cucumber', 'cypress', 'jest', 'mocha', 'playwright', 'vitest'])
+const MAX_DISCOVERY_ENTRIES = 5000
+const MAX_DIRECTORY_ENTRIES = 1024
+const MAX_FILE_BYTES = 512 * 1024
+const MAX_CI_FILES = 256
+const MAX_CI_REVIEW_TARGETS = 3
+const SKIPPED_DIRECTORIES = new Set([
+  '.git',
+  '.hg',
+  '.svn',
+  '.yarn',
+  'build',
+  'coverage',
+  'dd-test-optimization-validation-results',
+  'dist',
+  'node_modules',
+  'out',
+  'target',
+  'vendor',
+])
 const CI_PATHS = [
   '.github/workflows',
   '.gitlab-ci.yml',
@@ -18,9 +48,43 @@ const CI_PATHS = [
   'azure-pipelines.yml',
   'Jenkinsfile',
 ]
+const CONFIG_PATTERNS = {
+  cucumber: cucumber.CONFIG_PATTERN,
+  cypress: cypress.CONFIG_PATTERN,
+  jest: /^(?:jest|config-jest)\.config\.(?:[cm]?[jt]s|json)$/,
+  mocha: /^\.mocharc\.(?:json|ya?ml|[cm]?js)$/,
+  playwright: playwright.CONFIG_PATTERN,
+  vitest: /^(?:vite|vitest)\.config\.[cm]?[jt]s$/,
+}
+const JS_CONFIG_EXTENSIONS = ['js', 'cjs', 'mjs', 'ts', 'cts', 'mts']
+const IMPLICIT_CONFIG_FILENAMES = {
+  cucumber: ['json', 'yaml', 'yml', ...JS_CONFIG_EXTENSIONS].map(extension => `cucumber.${extension}`),
+  cypress: ['json', ...JS_CONFIG_EXTENSIONS].flatMap(extension => [
+    `cypress.${extension}`,
+    `cypress.config.${extension}`,
+  ]),
+  jest: ['json', ...JS_CONFIG_EXTENSIONS].flatMap(extension => [
+    `jest.config.${extension}`,
+    `config-jest.config.${extension}`,
+  ]),
+  mocha: ['json', 'yaml', 'yml', ...JS_CONFIG_EXTENSIONS].map(extension => `.mocharc.${extension}`),
+  playwright: JS_CONFIG_EXTENSIONS.map(extension => `playwright.config.${extension}`),
+  vitest: JS_CONFIG_EXTENSIONS.flatMap(extension => [
+    `vite.config.${extension}`,
+    `vitest.config.${extension}`,
+  ]),
+}
+const TEST_FILE_PATTERN = /^.+[._-](?:test|spec)\.[cm]?[jt]sx?$/
+const BARE_TEST_FILE_PATTERN = /^test\.[cm]?[jt]sx?$/
+const TYPE_ONLY_TEST_PATTERN = /\.(?:test|spec)-d\.[cm]?tsx?$|\.d\.[cm]?ts$/i
+const TYPE_ONLY_DIRECTORY_PATTERN = /(?:^|\/)(?:type[-_]?tests?|typetests?|test-dts?)(?:\/|$)/i
+const LOCAL_SOCKET_PATTERN =
+  /(?:\bcreateServer\s*\(|\.listen\s*\(|\b(?:localhost|127\.0\.0\.1)\b|\bcy\.(?:visit|request)\s*\()/
+const CYPRESS_LOCAL_ORIGIN_PATTERN =
+  /\bcy\.(?:visit|request)\s*\([\s\S]{0,512}\b(?:https?:\/\/)?(?:localhost|127\.0\.0\.1)(?=[:/'"`\s}])/i
 
 /**
- * Creates a schema-valid starting manifest without executing project code.
+ * Creates a schema-valid data-only manifest without executing project code.
  *
  * @param {object} input scaffold inputs
  * @param {string} input.root repository root
@@ -28,39 +92,37 @@ const CI_PATHS = [
  * @returns {object} validation manifest scaffold
  */
 function createManifestScaffold ({ root, frameworks = new Set() }) {
-  const repositoryRoot = path.resolve(root)
+  const repositoryRoot = fs.realpathSync(path.resolve(root))
   const diagnosis = runDiagnosis({ root: repositoryRoot, env: {} })
-  const selected = diagnosis.eligibleFrameworks.filter(framework => {
-    return frameworks.size === 0 || frameworks.has(framework.id) || frameworks.has(framework.id.split(':')[0])
+  const ciDiscovery = discoverCiFiles(repositoryRoot)
+  const eligible = diagnosis.eligibleFrameworks.filter(detection => isSelected(detection.id, frameworks))
+  const eligibleKinds = new Set(eligible.map(detection => detection.id))
+  const detectedOnly = diagnosis.supportedFrameworks.filter(detection => {
+    return !eligibleKinds.has(detection.id) && isSelected(detection.id, frameworks)
   })
-  const unsupported = diagnosis.unsupportedFrameworks.filter(framework => {
-    return frameworks.size === 0 || frameworks.has(framework.id) || frameworks.has(framework.id.split(':')[0])
-  })
-  if (selected.length === 0 && unsupported.length === 0) {
+  const unsupported = diagnosis.unsupportedFrameworks.filter(detection => isSelected(detection.id, frameworks))
+
+  if (eligible.length === 0 && detectedOnly.length === 0 && unsupported.length === 0) {
     throw new Error('No test framework was detected for manifest scaffolding.')
   }
 
   const manifest = {
-    schemaVersion: '1.0',
+    schemaVersion: '2.0',
     generatedAt: new Date().toISOString(),
     repository: {
       root: repositoryRoot,
-      gitRemote: null,
-      gitSha: null,
       packageManager: detectPackageManager(repositoryRoot),
       workspaceManager: detectWorkspaceManager(repositoryRoot),
     },
     environment: {
-      os: getManifestOs(process.platform),
-      shell: process.env.SHELL || null,
       nodeVersion: process.version,
-      requiredEnvVars: [],
-      safeEnv: {},
+      os: getManifestOs(process.platform),
     },
-    ciDiscovery: discoverCiFiles(repositoryRoot),
+    ciDiscovery,
     frameworks: [
-      ...selected.map(framework => buildFrameworkScaffold(repositoryRoot, framework)),
-      ...unsupported.map(framework => buildUnsupportedFrameworkScaffold(repositoryRoot, framework)),
+      ...eligible.map(detection => buildFramework(repositoryRoot, detection, ciDiscovery)),
+      ...detectedOnly.map(detection => buildDetectedOnlyFramework(repositoryRoot, detection, ciDiscovery)),
+      ...unsupported.map(detection => buildUnsupportedFramework(repositoryRoot, detection, ciDiscovery)),
     ],
     omitted: [],
   }
@@ -73,666 +135,905 @@ function createManifestScaffold ({ root, frameworks = new Set() }) {
 }
 
 /**
- * Builds a diagnostic-only entry for a detected runner the validator cannot execute.
+ * Builds one runnable direct-runner framework or a precise setup blocker.
  *
  * @param {string} repositoryRoot repository root
- * @param {object} detection static framework detection
- * @returns {object} non-runnable framework manifest entry
+ * @param {object} detection eligible framework detection
+ * @param {object} ciDiscovery bounded CI discovery result
+ * @returns {object} framework manifest entry
  */
-function buildUnsupportedFrameworkScaffold (repositoryRoot, detection) {
-  const packageJsonPath = getDetectionPackageJson(repositoryRoot, detection.locations)
-  const projectRoot = path.dirname(packageJsonPath)
-  const packageJson = readJson(packageJsonPath) || {}
-  const framework = detection.id === 'node-test' ? 'node:test' : detection.id
-
-  return {
-    id: `${detection.id}:${getProjectIdentifier(packageJson, projectRoot, repositoryRoot)}`,
-    framework,
-    frameworkVersion: getInstalledFrameworkVersion(detection.id, projectRoot, packageJson),
-    language: 'unknown',
-    status: 'unsupported_by_validator',
-    supportLevel: 'detected_only',
-    project: getProject({ packageJson, packageJsonPath, projectRoot, repositoryRoot, framework }),
-    notes: [
-      `${detection.name} was detected at ${detection.locations.join(', ') || 'an unknown location'}, but is not ` +
-        'supported by this Test Optimization validator.',
-    ],
-  }
-}
-
-function buildFrameworkScaffold (repositoryRoot, detection) {
-  const packageJsonPath = path.resolve(repositoryRoot, detection.commandLocation || 'package.json')
-  const projectRoot = path.dirname(packageJsonPath)
-  const packageJson = readJson(packageJsonPath) || {}
+function buildFramework (repositoryRoot, detection, ciDiscovery) {
   const framework = detection.id
+  const packageJson = getDetectionPackageJson(repositoryRoot, detection.commandLocation)
+  const projectRoot = path.dirname(packageJson.path)
+  const base = getFrameworkBase({
+    ciDiscovery,
+    detection,
+    framework,
+    packageJson,
+    projectRoot,
+    repositoryRoot,
+  })
 
-  if (!SUPPORTED_SCAFFOLD_FRAMEWORKS.has(framework)) {
+  if (!SUPPORTED_FRAMEWORKS.has(framework)) {
     return {
-      id: `${framework}:${getProjectIdentifier(packageJson, projectRoot, repositoryRoot)}`,
-      framework,
-      frameworkVersion: detection.version,
-      status: 'detected_not_runnable',
-      project: getProject({ packageJson, packageJsonPath, projectRoot, repositoryRoot, framework }),
-      notes: [`${detection.name} was detected, but automatic generated-test scaffolding is not available.`],
+      ...base,
+      status: 'unsupported_by_validator',
+      notes: [`${detection.name} is supported by dd-trace, but this validator has no direct-runner adapter.`],
     }
   }
 
-  const runner = tryResolveRunner(framework, projectRoot)
+  const projectRunner = getProjectNodeRunner(detection.command, projectRoot, repositoryRoot)
+  const runner = projectRunner || resolveRunner(framework, projectRoot, repositoryRoot)
   if (!runner) {
     return {
-      id: `${framework}:${getProjectIdentifier(packageJson, projectRoot, repositoryRoot)}`,
-      framework,
-      frameworkVersion: detection.version,
+      ...base,
       status: 'requires_manual_setup',
-      project: getProject({ packageJson, packageJsonPath, projectRoot, repositoryRoot, framework }),
       notes: [
-        `${detection.name} was detected, but its executable package could not be resolved from ` +
-          `${path.relative(repositoryRoot, projectRoot) || 'the repository root'}.`,
+        `${detection.name} is detected, but its repository-contained executable is unavailable. Install this ` +
+        'package normally, then create a fresh validation plan.',
       ],
     }
   }
-  const scriptName = getPackageScriptName(packageJson, detection.command)
-  const preserveProjectWrapper = Boolean(scriptName) && !usesBareFrameworkRunner(detection.command, framework)
-  const baseCommand = buildExistingCommand({
+
+  const runnerContract = getRunnerContract(framework, detection.command, projectRoot, repositoryRoot)
+  if (runnerContract.error) {
+    return {
+      ...base,
+      status: 'requires_manual_setup',
+      notes: [
+        `${detection.name} runner configuration was not retained because ${runnerContract.error}. ` +
+          'Choose a representative test command manually or adjust the project setup, then create a fresh plan.',
+      ],
+    }
+  }
+  const commandRoots = getRunnerSearchRoots(framework, detection.command, projectRoot, repositoryRoot)
+  const representativeRoot = commandRoots[0] || findPreferredRepresentativeRoot(projectRoot, repositoryRoot)
+  const representativePackage = readJson(path.join(representativeRoot, 'package.json')) || packageJson.json
+  const projectFiles = collectProjectFiles(projectRoot)
+  const candidateFiles = representativeRoot === projectRoot
+    ? projectFiles
+    : collectProjectFiles(representativeRoot)
+  const candidate = selectRepresentativeTest(
+    candidateFiles,
     framework,
-    projectRoot,
-    repositoryRoot,
-    runner,
-    scriptName,
-    preserveProjectWrapper,
-  })
-  const representative = findRepresentativeTestFile(projectRoot)
-  const command = representative
-    ? buildFocusedCommand(baseCommand, framework, representative, Boolean(scriptName), preserveProjectWrapper)
-    : baseCommand
+    representativeRoot,
+    representativePackage.name,
+    commandRoots.length > 0
+  )
+  if (!candidate) {
+    return {
+      ...base,
+      status: 'requires_manual_setup',
+      notes: [
+        `No single ${detection.name} test file could be selected confidently. Choose a normal framework-owned ` +
+        'test file or validate this framework manually.',
+      ],
+    }
+  }
+  if (candidate.requiresExternalService) {
+    return {
+      ...base,
+      status: 'requires_manual_setup',
+      notes: [
+        `No self-contained ${detection.name} spec could be selected. The available spec accesses a localhost ` +
+        'application that discovery will not start. Start the application through the project\'s normal setup and ' +
+        'validate Cypress manually, or add a self-contained spec before creating a fresh plan.',
+      ],
+    }
+  }
 
   const generatedTestStrategy = buildGeneratedTestStrategy({
-    baseCommand: preserveProjectWrapper ? baseCommand : undefined,
     framework,
-    packageJson,
     projectRoot,
-    representative,
-    runner,
+    representative: candidate.path,
   })
+  const configFiles = [...new Set([
+    ...runnerContract.inputFiles,
+    ...getImplicitConfigFiles(framework, projectRoot, repositoryRoot),
+    ...(representativeRoot === projectRoot
+      ? []
+      : getImplicitConfigFiles(framework, representativeRoot, repositoryRoot)),
+    ...projectFiles.filter(filename => CONFIG_PATTERNS[framework]?.test(path.basename(filename))).slice(0, 5),
+  ])]
+  if (configFiles.length > 20) {
+    return {
+      ...base,
+      status: 'requires_manual_setup',
+      notes: [
+        `${detection.name} loads more configuration files than the validator can approval-bind safely. ` +
+          'Use a narrower project setup before creating a fresh plan.',
+      ],
+    }
+  }
+  const runnerDescription = projectRunner ? 'repository test wrapper' : `installed ${framework} runner`
+  const browserRequired = framework === 'cypress' ||
+    framework === 'playwright' ||
+    (framework === 'vitest' && runnerContract.runnerArgs.includes('--browser'))
 
   return {
-    id: `${framework}:${getProjectIdentifier(packageJson, projectRoot, repositoryRoot)}`,
-    framework,
-    frameworkVersion: detection.version,
-    language: /\.tsx?$/.test(generatedTestStrategy.fileExtension) ? 'typescript' : 'javascript',
+    ...base,
+    browserRequired,
+    language: /\.[cm]?tsx?$/.test(candidate.path) ? 'typescript' : 'javascript',
+    localSocketRequired: candidate.requiresLocalSocket,
     status: 'runnable',
-    supportLevel: 'validator_supported',
-    project: getProject({ packageJson, packageJsonPath, projectRoot, repositoryRoot, framework }),
-    setup: { commands: [], services: [] },
-    existingTestCommand: command,
-    preflight: { status: 'pending', maxTestCount: 50 },
-    ciWiring: {
-      status: 'unknown',
-      replayability: 'not_replayable',
-      replayBlocker: 'CI command selection has not been completed. Inspect the discovered CI configuration and ' +
-        'replace this with a concrete technical blocker only when the selected test command cannot be replayed.',
-      diagnosis: 'Select one replayable CI test step and record its exact command and environment before live CI ' +
-        'wiring validation.',
-      initialization: {
-        status: 'unknown',
-        evidence: [],
-      },
+    supportLevel: 'validator_direct_runner',
+    project: {
+      ...base.project,
+      configFiles,
     },
+    validation: {
+      environment: runnerContract.environment,
+      ...(runnerContract.omittedOptions?.length > 0
+        ? { omittedRunnerOptions: runnerContract.omittedOptions }
+        : {}),
+      requiredEnvVars: [],
+      runner,
+      runnerArgs: runnerContract.runnerArgs,
+      selectorScope: projectRunner ? 'instrumented_event_identity' : 'bounded_direct_runner',
+      testFile: candidate.path,
+      timeoutMs: browserRequired ? 300_000 : 180_000,
+    },
+    preflight: { status: 'pending' },
     generatedTestStrategy,
     notes: [
-      representative
-        ? `Generated by --init-manifest using representative test ${path.relative(repositoryRoot, representative)}.`
-        : 'Generated by --init-manifest. Narrow existingTestCommand if the detected command runs a broad suite.',
-      preserveProjectWrapper
-        ? `Basic Reporting preserves package script ${scriptName} because it uses a custom test wrapper.`
-        : `Basic Reporting invokes the installed ${framework} runner directly; record the CI wrapper separately.`,
-      'CI command selection still requires repository-specific evidence.',
+      `Basic Reporting will invoke the ${runnerDescription} ` +
+        'directly for ' +
+        `${path.relative(repositoryRoot, candidate.path)}.`,
+      'The validator retained only allowlisted runner configuration from the detected package script.',
+      ...(projectRunner
+        ? [
+            'Basic Reporting will remain incomplete unless captured test events identify only the approved ' +
+              'representative file.',
+          ]
+        : []),
+      ...(candidate.requiresLocalSocket
+        ? [
+            'The selected test appears to require localhost. A restricted sandbox may leave local validation ' +
+              'incomplete.',
+          ]
+        : []),
     ],
   }
 }
 
-function getProject ({ packageJson, packageJsonPath, projectRoot, repositoryRoot, framework }) {
+function getImplicitConfigFiles (framework, projectRoot, repositoryRoot) {
+  const files = []
+  for (const basename of IMPLICIT_CONFIG_FILENAMES[framework] || []) {
+    const filename = path.join(projectRoot, basename)
+    try {
+      const stat = fs.lstatSync(filename)
+      const physical = fs.realpathSync(filename)
+      if (stat.isFile() && !stat.isSymbolicLink() &&
+        fs.statSync(physical).isFile() &&
+        isPathInside(fs.realpathSync(repositoryRoot), physical)) files.push(physical)
+    } catch {}
+  }
+  return files
+}
+
+/**
+ * Builds a diagnostic-only supported framework entry.
+ *
+ * @param {string} repositoryRoot repository root
+ * @param {object} detection supported framework detection
+ * @param {object} ciDiscovery bounded CI discovery result
+ * @returns {object} framework manifest entry
+ */
+function buildDetectedOnlyFramework (repositoryRoot, detection, ciDiscovery) {
+  const packageJson = getDetectionPackageJson(repositoryRoot, detection.locations?.[0])
+  const projectRoot = path.dirname(packageJson.path)
+  const version = detection.supportedVersion?.version ||
+    detection.versionDetections?.[0]?.version ||
+    detection.versionDetections?.[0]?.rawVersion
+  return {
+    ...getFrameworkBase({
+      ciDiscovery,
+      detection: { ...detection, version },
+      framework: detection.id,
+      packageJson,
+      projectRoot,
+      repositoryRoot,
+    }),
+    status: 'detected_not_runnable',
+    notes: [
+      detection.supportedVersion
+        ? `A supported ${detection.name} installation was detected, but no project-local validation target was found.`
+        : `${detection.name} was detected, but no supported installed version was confirmed.`,
+    ],
+  }
+}
+
+/**
+ * Builds an unsupported framework entry.
+ *
+ * @param {string} repositoryRoot repository root
+ * @param {object} detection unsupported framework detection
+ * @param {object} ciDiscovery bounded CI discovery result
+ * @returns {object} framework manifest entry
+ */
+function buildUnsupportedFramework (repositoryRoot, detection, ciDiscovery) {
+  const packageJson = getDetectionPackageJson(repositoryRoot, detection.locations?.[0])
+  const projectRoot = path.dirname(packageJson.path)
+  const framework = detection.id === 'node-test' ? 'node:test' : detection.id
   return {
-    name: packageJson.name || getProjectIdentifier(packageJson, projectRoot, repositoryRoot),
-    root: projectRoot,
-    packageJson: packageJsonPath,
-    configFiles: findConfigFiles(projectRoot, framework),
-    evidence: [`Detected ${framework} from ${path.relative(repositoryRoot, packageJsonPath) || 'package.json'}.`],
+    ...getFrameworkBase({
+      ciDiscovery,
+      detection,
+      framework,
+      packageJson,
+      projectRoot,
+      repositoryRoot,
+    }),
+    status: 'unsupported_by_validator',
+    notes: [`${detection.name} is not supported by this Test Optimization validator.`],
   }
 }
 
-function buildExistingCommand ({
+/**
+ * Returns fields shared by runnable and diagnostic framework entries.
+ *
+ * @param {object} input framework inputs
+ * @param {object} input.ciDiscovery bounded CI discovery
+ * @param {object} input.detection framework detection
+ * @param {string} input.framework framework name
+ * @param {object} input.packageJson package metadata
+ * @param {string} input.projectRoot project root
+ * @param {string} input.repositoryRoot repository root
+ * @returns {object} shared framework fields
+ */
+function getFrameworkBase ({
+  ciDiscovery,
+  detection,
   framework,
+  packageJson,
   projectRoot,
   repositoryRoot,
-  runner,
-  scriptName,
-  preserveProjectWrapper,
 }) {
-  const packageManager = preserveProjectWrapper ? detectPackageManager(repositoryRoot) : undefined
-  const argv = preserveProjectWrapper
-    ? getPackageScriptArgv(packageManager, scriptName, repositoryRoot)
-    : getDirectRunnerArgv(framework, runner)
   return {
-    description: preserveProjectWrapper
-      ? `Detected custom package script ${scriptName}`
-      : `Direct installed ${framework} runner for local capability validation`,
-    cwd: projectRoot,
-    argv,
-    env: {},
-    requiredEnvVars: [],
-    timeoutMs: 300_000,
-    usesShell: false,
+    id: `${framework}:${getProjectId(packageJson.json, projectRoot, repositoryRoot)}`,
+    framework,
+    frameworkVersion: detection.version || detection.supportedVersion?.version || null,
+    language: 'unknown',
+    supportLevel: 'detected_only',
+    project: {
+      configFiles: [],
+      name: packageJson.json.name || path.basename(projectRoot) || 'root',
+      packageJson: packageJson.path,
+      root: projectRoot,
+    },
+    ciWiring: buildCiWiring(ciDiscovery),
   }
 }
 
-function buildGeneratedTestStrategy ({ baseCommand, framework, packageJson, projectRoot, representative, runner }) {
-  const convention = getGeneratedTestConvention(representative, projectRoot)
-  const packageType = getNearestPackageType(convention.testDirectory, projectRoot, packageJson.type)
-  const moduleSystem = getGeneratedModuleSystem(framework, convention.fileExtension, packageType)
-  const definitions = getGeneratedDefinitions({ framework, convention, moduleSystem })
-
+/**
+ * Builds inert CI review fields. The agent may populate only this evidence section.
+ *
+ * @param {object} ciDiscovery bounded CI discovery result
+ * @returns {object} CI evidence scaffold
+ */
+function buildCiWiring (ciDiscovery) {
+  const unresolved = ciDiscovery.reviewRequired
+    ? ['The exact CI test job and its effective environment have not been reviewed.']
+    : ['No supported CI configuration file was found by bounded discovery.']
   return {
-    status: 'planned',
-    reason: 'Standard isolated scenarios generated by the validator manifest scaffold.',
-    adapter: framework,
-    testDirectory: convention.testDirectory,
-    moduleSystem,
-    fileExtension: convention.fileExtension,
-    supportsFocusedSingleFileRun: true,
-    usesMultipleFiles: true,
-    files: definitions.map(definition => ({
-      path: definition.file,
-      role: 'test',
-      contentLines: definition.content.split('\n'),
-    })),
-    scenarios: definitions.map(definition => ({
-      id: definition.id,
-      purpose: definition.purpose,
-      runCommand: baseCommand
-        ? buildFocusedCommand(baseCommand, framework, definition.file, true, true, moduleSystem)
-        : buildGeneratedRunCommand(framework, projectRoot, definition.file, runner, moduleSystem),
-      expectedWithoutDatadog: {
-        exitCode: definition.id === 'atr-fail-once' ? 1 : 0,
-        observedTestCount: 1,
-      },
-      testIdentities: [{
-        suite: null,
-        name: definition.testName,
-        file: definition.file,
-        parameters: null,
-      }],
-    })),
-    cleanupPaths: [
-      ...definitions.map(definition => definition.file),
-      path.join(path.dirname(definitions.find(definition => definition.id === 'atr-fail-once').file),
-        '.dd-test-optimization-validation-atr-state'),
-    ],
+    command: null,
+    configFile: null,
+    initialization: { evidence: [], status: 'unknown' },
+    job: null,
+    reviewComplete: false,
+    step: null,
+    transport: { evidence: [], mode: 'unknown' },
+    unresolved,
+    workingDirectory: null,
   }
 }
 
-function getGeneratedModuleSystem (framework, fileExtension, packageType) {
-  if (/\.(?:cjs|cts)$/.test(fileExtension)) return 'commonjs'
-  if (framework === 'vitest' || /\.(?:mjs|mts)$/.test(fileExtension)) return 'esm'
-  return packageType === 'module' ? 'esm' : 'commonjs'
-}
-
 /**
- * Returns the package module type that applies to a generated test directory.
+ * Builds canonical generated test data without embedding executable commands.
  *
- * @param {string} testDirectory generated test directory
- * @param {string} projectRoot detected project root
- * @param {string|undefined} fallbackType detected project package type
- * @returns {string|undefined} nearest package module type
+ * @param {object} input generated-test inputs
+ * @param {string} input.framework framework name
+ * @param {string} input.projectRoot project root
+ * @param {string} input.representative representative test file
+ * @returns {object} generated test strategy
  */
-function getNearestPackageType (testDirectory, projectRoot, fallbackType) {
-  const root = path.resolve(projectRoot)
-  let directory = path.resolve(testDirectory)
+function buildGeneratedTestStrategy ({ framework, projectRoot, representative }) {
+  const convention = getGeneratedTestConvention(framework, representative, projectRoot)
+  const testDirectory = convention.testDirectory
+  const extension = convention.fileExtension
+  const moduleSystem = getModuleSystem(representative, projectRoot)
+  const files = []
+  const scenarios = []
+  const cleanupPaths = []
 
-  while (directory === root || isPathInside(root, directory)) {
-    const packageJson = readJson(path.join(directory, 'package.json'))
-    if (typeof packageJson?.type === 'string') return packageJson.type
-    if (directory === root) break
-    directory = path.dirname(directory)
+  for (const [id, scenario] of Object.entries(GENERATED_SCENARIOS)) {
+    const prefix = `dd-test-optimization-validation-${framework}-${id}`
+    const filename = convention.exactFilename
+      ? path.join(testDirectory, prefix, convention.exactFilename)
+      : path.join(testDirectory, `${prefix}${extension}`)
+    const content = getGeneratedTestContent({
+      framework,
+      moduleSystem,
+      scenarioId: id,
+      stateFile: ['cucumber', 'cypress', 'playwright'].includes(framework)
+        ? undefined
+        : getGeneratedRetryStatePath(framework, filename),
+    })
+    files.push({ path: filename, contentLines: content.split('\n') })
+    cleanupPaths.push(filename)
+    scenarios.push({
+      id,
+      expectedWithoutDatadog: scenario.expectedWithoutDatadog,
+      testIdentities: [{
+        file: filename,
+        name: scenario.testName,
+        suite: scenario.suiteName,
+      }],
+    })
   }
 
-  return fallbackType
-}
-
-function getGeneratedTestConvention (representative, projectRoot) {
-  if (!representative) {
-    return {
-      exactFilename: undefined,
-      fileExtension: '.test.js',
-      testDirectory: path.join(projectRoot, 'test'),
-    }
+  if (framework === 'cucumber') {
+    const stepsFile = cucumber.getGeneratedStepsPath(testDirectory)
+    files.push({ path: stepsFile, contentLines: cucumber.getGeneratedStepsContent().split('\n') })
+    cleanupPaths.push(stepsFile)
   }
-
-  const basename = path.basename(representative)
-  if (/^test\.[cm]?[jt]s$/.test(basename)) {
-    const representativeDirectory = path.dirname(representative)
-    return {
-      exactFilename: basename,
-      fileExtension: path.extname(basename),
-      testDirectory: representativeDirectory === projectRoot
-        ? projectRoot
-        : path.dirname(representativeDirectory),
-    }
+  if (framework === 'playwright') {
+    const configFile = playwright.getGeneratedConfigPath(testDirectory)
+    files.push({ path: configFile, contentLines: playwright.getGeneratedConfigContent().split('\n') })
+    cleanupPaths.push(configFile)
+  }
+  if (['jest', 'mocha', 'vitest'].includes(framework)) {
+    cleanupPaths.push(getGeneratedRetryStatePath(framework, scenarios[1].testIdentities[0].file))
   }
 
   return {
-    exactFilename: undefined,
-    fileExtension: getTestExtension(representative),
-    testDirectory: path.dirname(representative),
+    cleanupPaths,
+    fileExtension: extension,
+    files,
+    moduleSystem,
+    reason: 'Validator-owned direct-runner recipes.',
+    scenarios,
+    status: 'planned',
+    testDirectory,
   }
 }
 
-function getGeneratedDefinitions ({ framework, convention, moduleSystem }) {
-  const stateFileExpression = moduleSystem === 'esm'
-    ? "join(dirname(fileURLToPath(import.meta.url)), '.dd-test-optimization-validation-atr-state')"
-    : "path.join(__dirname, '.dd-test-optimization-validation-atr-state')"
-  const definitions = [
-    { id: 'basic-pass', purpose: 'basic_reporting|efd_candidate', testName: 'basic-pass' },
-    { id: 'atr-fail-once', purpose: 'auto_test_retries_candidate', testName: 'atr-fail-once' },
-    { id: 'test-management-target', purpose: 'test_management_candidate', testName: 'test-management-target' },
-  ]
+/**
+ * Selects one representative framework-owned test file.
+ *
+ * @param {string[]} files bounded project files
+ * @param {string} framework framework name
+ * @param {string} projectRoot project root
+ * @param {string} packageName project package name
+ * @param {boolean} allowDirectoryConvention whether a literal runner selector chose this root
+ * @returns {{path: string, requiresExternalService: boolean, requiresLocalSocket: boolean}|undefined} selected test
+ */
+function selectRepresentativeTest (files, framework, projectRoot, packageName, allowDirectoryConvention) {
+  const candidates = []
+  for (const filename of files) {
+    const source = readText(filename)
+    if (source === undefined ||
+      !isTestFile(filename, source, framework, projectRoot, allowDirectoryConvention) ||
+      hasConflictingFramework(source, framework)) continue
+    if (framework === 'cucumber'
+      ? cucumber.getScenarioCount(source) === 0
+      : getStaticTestCount(source) === 0) continue
+    if (!hasFrameworkOwnership(filename, source, framework, packageName)) continue
+    candidates.push({
+      path: filename,
+      rank: getTestRank(filename, source, projectRoot),
+      requiresExternalService: framework === 'cypress' && CYPRESS_LOCAL_ORIGIN_PATTERN.test(source),
+      requiresLocalSocket: LOCAL_SOCKET_PATTERN.test(source),
+    })
+  }
+  candidates.sort((left, right) => {
+    return Number(left.requiresExternalService) - Number(right.requiresExternalService) ||
+      left.rank - right.rank ||
+      left.path.localeCompare(right.path)
+  })
+  return candidates[0]
+}
 
-  return definitions.map(definition => {
-    const prefix = `dd-test-optimization-validation-${definition.id}`
-    const filename = convention.exactFilename
-      ? path.join(prefix, convention.exactFilename)
-      : `${prefix}${convention.fileExtension}`
-    return {
-      ...definition,
-      file: path.join(convention.testDirectory, filename),
-      content: getGeneratedTestContent({ framework, definition, moduleSystem, stateFileExpression }),
-    }
+/**
+ * Reports whether a file follows a selected framework's test convention.
+ *
+ * @param {string} filename candidate file
+ * @param {string} source candidate source
+ * @param {string} framework framework name
+ * @param {string} projectRoot project root
+ * @param {boolean} allowDirectoryConvention whether a literal runner selector chose this root
+ * @returns {boolean} whether the file is a candidate
+ */
+function isTestFile (filename, source, framework, projectRoot, allowDirectoryConvention) {
+  const basename = path.basename(filename)
+  const normalized = filename.replaceAll('\\', '/')
+  if (normalized.includes('/dd-test-optimization-validation-')) return false
+  if (TYPE_ONLY_TEST_PATTERN.test(basename) || TYPE_ONLY_DIRECTORY_PATTERN.test(normalized)) return false
+  if (framework === 'cucumber') return cucumber.isTestFile(filename)
+  if (framework === 'cypress') return cypress.isTestFile(basename, path.dirname(filename), projectRoot)
+  if (framework === 'playwright') return playwright.isTestFile(basename, path.dirname(filename), projectRoot)
+  if (TEST_FILE_PATTERN.test(basename)) return true
+  const directories = [
+    path.basename(projectRoot),
+    ...path.relative(projectRoot, path.dirname(filename)).split(path.sep),
+  ]
+  const inTestDirectory = directories.some(directory => {
+    return ['__tests__', 'spec', 'test', 'tests'].includes(directory)
   })
+  if (BARE_TEST_FILE_PATTERN.test(basename)) {
+    return inTestDirectory || hasExplicitFrameworkImport(source, framework)
+  }
+  return allowDirectoryConvention && inTestDirectory && /\.[cm]?[jt]sx?$/.test(basename)
 }
 
-function getGeneratedTestContent ({ framework, definition, moduleSystem, stateFileExpression }) {
-  const imports = []
-  if (framework === 'vitest' && moduleSystem === 'esm') {
-    imports.push("import { describe, expect, it } from 'vitest'")
+/**
+ * Reports whether an unconventional test file imports the selected framework directly.
+ *
+ * @param {string} source candidate source
+ * @param {string} framework framework name
+ * @returns {boolean} whether ownership is explicit
+ */
+function hasExplicitFrameworkImport (source, framework) {
+  if (framework === 'vitest') {
+    return /(?:from\s+|require\s*\(\s*)['"]vitest['"]/.test(source)
   }
-  if (framework === 'mocha') {
-    imports.push(moduleSystem === 'esm'
-      ? "import assert from 'node:assert/strict'"
-      : "const assert = require('node:assert/strict')")
-  }
-  if (definition.id === 'atr-fail-once') {
-    if (moduleSystem === 'esm') {
-      imports.push(
-        "import { existsSync, writeFileSync } from 'node:fs'",
-        "import { dirname, join } from 'node:path'",
-        "import { fileURLToPath } from 'node:url'"
-      )
-    } else {
-      imports.push("const fs = require('node:fs')", "const path = require('node:path')")
-    }
+  if (framework === 'jest') {
+    return /(?:from\s+|require\s*\(\s*)['"]@jest\/globals['"]/.test(source)
   }
-  const assertion = framework === 'mocha' ? 'assert.equal(1, 1)' : 'expect(true).toBe(true)'
-  const testFunction = framework === 'jest' ? 'test' : 'it'
-  const body = definition.id === 'atr-fail-once'
-    ? getAtrBody({ moduleSystem, stateFileExpression, assertion })
-    : `    ${assertion}`
-
-  return [
-    ...imports,
-    imports.length > 0 ? '' : undefined,
-    "describe('dd-test-optimization-validation', () => {",
-    `  ${testFunction}('${definition.testName}', () => {`,
-    body,
-    '  })',
-    '})',
-  ].filter(line => line !== undefined).join('\n')
-}
-
-function getAtrBody ({ moduleSystem, stateFileExpression, assertion }) {
-  const exists = moduleSystem === 'esm' ? 'existsSync' : 'fs.existsSync'
-  const write = moduleSystem === 'esm' ? 'writeFileSync' : 'fs.writeFileSync'
-  return [
-    `    const stateFile = ${stateFileExpression}`,
-    `    if (!${exists}(stateFile)) {`,
-    `      ${write}(stateFile, 'failed-once')`,
-    "      throw new Error('dd-test-optimization-validation atr first failure')",
-    '    }',
-    `    ${assertion}`,
-  ].join('\n')
-}
-
-function buildGeneratedRunCommand (framework, projectRoot, filename, runner, moduleSystem) {
-  const args = {
-    jest: ['--runTestsByPath', filename, '--runInBand', '--silent', '--no-watchman'],
-    mocha: ['--reporter', 'spec', filename],
-    vitest: ['run', filename, ...(moduleSystem === 'commonjs' ? ['--globals'] : [])],
-  }[framework]
-  return {
-    cwd: projectRoot,
-    argv: [process.execPath, runner, ...args],
-    env: {},
-    requiredEnvVars: [],
-    timeoutMs: 300_000,
-    usesShell: false,
+  if (framework === 'mocha') {
+    return /(?:from\s+|require\s*\(\s*)['"]mocha['"]/.test(source)
   }
+  return false
 }
 
 /**
- * Adds a single test file selection to a detected project command.
+ * Conservatively associates a test source with one framework.
  *
- * @param {object} baseCommand detected project command
- * @param {string} framework detected test framework
- * @param {string} filename selected test file
- * @param {boolean} packageScript whether the command invokes a package script
- * @param {boolean} preserveDefaultReporter whether a repository wrapper owns reporter selection
- * @param {string} [moduleSystem] generated test module system
- * @returns {object} focused project command
+ * @param {string} filename candidate filename
+ * @param {string} source file source
+ * @param {string} framework framework name
+ * @param {string} packageName project package name
+ * @returns {boolean} whether ownership is plausible
  */
-function buildFocusedCommand (
-  baseCommand,
-  framework,
-  filename,
-  packageScript,
-  preserveDefaultReporter,
-  moduleSystem
-) {
-  const argv = [...baseCommand.argv]
-  if (packageScript && path.basename(argv[0]).toLowerCase() === 'npm') argv.push('--')
-  argv.push(...getFocusedTestArgs(framework, filename, preserveDefaultReporter, moduleSystem))
-
-  return {
-    ...baseCommand,
-    description: `${baseCommand.description} targeting ${path.basename(filename)}`,
-    argv,
+function hasFrameworkOwnership (filename, source, framework, packageName) {
+  const normalized = filename.replaceAll('\\', '/').toLowerCase()
+  if (framework === 'cucumber') return /^\s*(?:Feature|Rule):/m.test(source)
+  if (framework === 'cypress') return /\.cy\./.test(filename) || normalized.includes('/cypress/')
+  if (framework === 'playwright') {
+    return /@playwright\/test/.test(source) || normalized.includes('/playwright/') ||
+      normalized.includes('/e2e/')
   }
+  if (framework === 'vitest') return /\bvitest\b/.test(source) || /\b(?:describe|it|test)\s*\(/.test(source)
+  if (framework === 'jest') return /\bjest\b/.test(source) || /\b(?:describe|it|test)\s*\(/.test(source)
+  if (framework === 'mocha') {
+    return /\bmocha\b/.test(source) || /\bdescribe\s*\(/.test(source) ||
+      packageName === 'mocha'
+  }
+  return false
 }
 
 /**
- * Returns framework arguments that select exactly one test file.
+ * Rejects files visibly owned by another supported runner.
  *
- * @param {string} framework detected test framework
- * @param {string} filename selected test file
- * @param {boolean} preserveDefaultReporter whether a repository wrapper owns reporter selection
- * @param {string} [moduleSystem] generated test module system
- * @returns {string[]} focused test arguments
+ * @param {string} source candidate source
+ * @param {string} framework selected framework
+ * @returns {boolean} whether source ownership conflicts
  */
-function getFocusedTestArgs (framework, filename, preserveDefaultReporter, moduleSystem) {
-  if (framework === 'jest') {
-    return [
-      '--runTestsByPath',
-      filename,
-      '--runInBand',
-      ...(preserveDefaultReporter ? [] : ['--silent']),
-      '--no-watchman',
-    ]
+function hasConflictingFramework (source, framework) {
+  const markers = {
+    cypress: /\bcy\.(?:visit|request|get)\b|from\s+['"]cypress/,
+    jest: /@jest\/globals|\bjest\.(?:mock|fn|spyOn)\b/,
+    'node:test': /(?:from\s+|require\s*\(\s*)['"]node:test['"]/,
+    playwright: /@playwright\/test/,
+    vitest: /from\s+['"]vitest['"]|require\s*\(\s*['"]vitest['"]\s*\)|\bvi\./,
   }
-  return [filename, ...(framework === 'vitest' && moduleSystem === 'commonjs' ? ['--globals'] : [])]
+  return Object.entries(markers).some(([name, pattern]) => name !== framework && pattern.test(source))
 }
 
 /**
- * Resolves an installed framework executable without making the whole scaffold fail when a nested package only
- * declares the dependency.
+ * Ranks simpler unit tests ahead of integration and service-dependent tests.
  *
- * @param {string} framework detected framework
- * @param {string} projectRoot detected project root
- * @returns {string|undefined} resolved executable path
+ * @param {string} filename candidate filename
+ * @param {string} source candidate source
+ * @param {string} projectRoot project root
+ * @returns {number} lower-is-better rank
  */
-function tryResolveRunner (framework, projectRoot) {
-  try {
-    return resolveRunner(framework, projectRoot)
-  } catch {}
+function getTestRank (filename, source, projectRoot) {
+  const relative = path.relative(projectRoot, filename).replaceAll('\\', '/').toLowerCase()
+  let rank = relative.split('/').length
+  if (/(?:^|\/)(?:test|tests|__tests__|spec)\//.test(relative)) rank -= 20
+  if (/(?:^|[._/-])unit(?:[._/-]|$)/.test(relative)) rank -= 15
+  if (/(?:e2e|integration|acceptance|browser|conformance|fixtures?)/.test(relative)) rank += 20
+  if (LOCAL_SOCKET_PATTERN.test(source)) rank += 30
+  rank += Math.min(getStaticTestCount(source), 50)
+  return rank
 }
 
-function resolveRunner (framework, projectRoot) {
-  const packageName = framework === 'jest' ? 'jest' : framework
-  const packageJsonPath = require.resolve(`${packageName}/package.json`, { paths: [projectRoot] })
-  const packageJson = readJson(packageJsonPath)
-  const bin = typeof packageJson.bin === 'string' ? packageJson.bin : packageJson.bin[packageName]
-  return path.resolve(path.dirname(packageJsonPath), bin)
+/**
+ * Counts static test declarations for preferring small representative files.
+ *
+ * @param {string} source test source
+ * @returns {number} approximate test declaration count
+ */
+function getStaticTestCount (source) {
+  return [...source.matchAll(/\b(?:it|test)((?:\.[A-Za-z]+)*)\s*\(/g)]
+    .filter(match => !/\.(?:skip|todo)\b/.test(match[1]))
+    .length
 }
 
-function getPackageScriptArgv (packageManager, scriptName, repositoryRoot) {
-  if (packageManager === 'yarn') {
-    const release = findYarnRelease(repositoryRoot)
-    return release ? [process.execPath, release, 'run', scriptName] : ['yarn', 'run', scriptName]
+/**
+ * Narrows a repository root to the conventional package matching its identity.
+ *
+ * @param {string} projectRoot detected project root
+ * @param {string} repositoryRoot repository root
+ * @returns {string} preferred representative root
+ */
+function findPreferredRepresentativeRoot (projectRoot, repositoryRoot) {
+  if (path.resolve(projectRoot) !== path.resolve(repositoryRoot)) return projectRoot
+  const repositoryName = normalizeProjectIdentity(path.basename(repositoryRoot))
+
+  for (const containerName of ['packages', 'pkgs', 'modules']) {
+    const container = path.join(repositoryRoot, containerName)
+    for (const entry of readDirectoryEntries(container)) {
+      if (!entry.isDirectory()) continue
+      const candidate = path.join(container, entry.name)
+      const packageJson = readJson(path.join(candidate, 'package.json'))
+      if (normalizeProjectIdentity(packageJson?.name || entry.name) === repositoryName) return candidate
+    }
   }
-  return [packageManager, 'run', scriptName]
+  return projectRoot
 }
 
 /**
- * Finds the package script whose value produced the detected framework command.
+ * Normalizes repository and package names for exact identity comparison.
  *
- * @param {object} packageJson project package metadata
- * @param {string} command detected framework command
- * @returns {string|undefined} package script name
+ * @param {string} value package identity
+ * @returns {string} normalized identity
  */
-function getPackageScriptName (packageJson, command) {
-  return Object.entries(packageJson.scripts || {}).find(([, value]) => value === command)?.[0]
+function normalizeProjectIdentity (value) {
+  const unscoped = String(value || '').toLowerCase().replace(/^@[^/]+\//, '')
+  return unscoped.replaceAll(/[^a-z0-9]+/g, '').replace(/js$/, '')
 }
 
 /**
- * Reports whether a package script invokes the framework binary without a repository wrapper.
+ * Collects bounded regular project files without following symbolic links.
  *
- * @param {string} command detected framework command
- * @param {string} framework detected test framework
- * @returns {boolean} whether the command starts with the framework binary
+ * @param {string} root project root
+ * @returns {string[]} absolute files
  */
-function usesBareFrameworkRunner (command, framework) {
-  const tokens = String(command || '').trim().split(/\s+/)
-  const executable = path.basename(tokens[0] || '').replace(/\.cmd$/i, '').toLowerCase()
-  if (executable !== framework) return false
-  return tokens.length === 1 || framework === 'vitest' && tokens.length === 2 && tokens[1] === 'run'
-}
-
-function getDirectRunnerArgv (framework, runner) {
-  return [process.execPath, runner, ...(framework === 'vitest' ? ['run'] : [])]
-}
-
-function findRepresentativeTestFile (root) {
-  const stack = [root]
-  const candidates = []
-  const packageRanks = new Map()
+function collectProjectFiles (root) {
+  const files = []
+  const pending = [root]
   let visited = 0
-  while (stack.length > 0 && visited < 5000) {
-    const directory = stack.pop()
-    let entries
-    try {
-      entries = fs.readdirSync(directory, { withFileTypes: true })
-        .sort((left, right) => left.name.localeCompare(right.name))
-    } catch {
-      continue
-    }
-    for (const entry of entries) {
-      if (['.git', 'node_modules', 'coverage', 'dist', 'build'].includes(entry.name)) continue
+
+  while (pending.length > 0 && visited < MAX_DISCOVERY_ENTRIES) {
+    const directory = pending.shift()
+    for (const entry of readDirectoryEntries(directory)) {
+      if (++visited > MAX_DISCOVERY_ENTRIES) break
       const filename = path.join(directory, entry.name)
+      if (entry.isSymbolicLink()) continue
       if (entry.isDirectory()) {
-        stack.push(filename)
-        continue
-      }
-      visited++
-      const inTestsDirectory = path.relative(root, directory).split(path.sep).includes('__tests__')
-      if (/^(?:test\.(?:[cm]?[jt]s|[jt]sx)|.+[.-](?:test|spec)\.(?:[cm]?[jt]s|[jt]sx))$/.test(entry.name) ||
-        (inTestsDirectory && /\.(?:[cm]?[jt]s|[jt]sx)$/.test(entry.name))) {
-        candidates.push(filename)
+        if (!SKIPPED_DIRECTORIES.has(entry.name)) pending.push(filename)
+      } else if (entry.isFile()) {
+        files.push(filename)
       }
     }
   }
+  return files
+}
 
-  candidates.sort((left, right) => {
-    return getTestDirectoryRank(left, root) - getTestDirectoryRank(right, root) ||
-      getTestAreaRank(left, root) - getTestAreaRank(right, root) ||
-      getIndependentTestProjectRank(left, root, packageRanks) -
-        getIndependentTestProjectRank(right, root, packageRanks) ||
-      left.localeCompare(right)
-  })
-  return candidates[0]
+/**
+ * Resolves a framework package executable only inside the repository.
+ *
+ * @param {string} framework framework name
+ * @param {string} projectRoot project root
+ * @param {string} repositoryRoot repository root
+ * @returns {string|undefined} physical runner path
+ */
+function resolveRunner (framework, projectRoot, repositoryRoot) {
+  const packageName = getRunnerPackageName(framework)
+  const packageRoot = findPackageRoot(packageName, projectRoot, repositoryRoot)
+  if (!packageRoot) return
+
+  const packageJson = readJson(path.join(packageRoot, 'package.json'))
+  const binName = framework === 'cucumber' ? 'cucumber-js' : framework === 'playwright' ? 'playwright' : framework
+  const bin = typeof packageJson?.bin === 'string' ? packageJson.bin : packageJson?.bin?.[binName]
+  if (typeof bin !== 'string') return
+
+  try {
+    const runner = fs.realpathSync(path.resolve(packageRoot, bin))
+    return isPathInside(fs.realpathSync(repositoryRoot), runner) && fs.statSync(runner).isFile()
+      ? runner
+      : undefined
+  } catch {}
 }
 
 /**
- * Ranks established test directories ahead of source-adjacent test-looking files.
+ * Finds an installed package or a framework source checkout.
  *
- * @param {string} filename candidate test file
- * @param {string} root detected project root
- * @returns {number} directory preference rank
+ * @param {string} packageName runner package name
+ * @param {string} projectRoot project root
+ * @param {string} repositoryRoot repository root
+ * @returns {string|undefined} physical package root
  */
-function getTestDirectoryRank (filename, root) {
-  const directories = path.relative(root, path.dirname(filename)).split(path.sep)
-  if (directories.includes('__tests__')) return 0
-  if (directories.some(directory => directory === 'test' || directory === 'tests')) return 1
-  return 2
+function findPackageRoot (packageName, projectRoot, repositoryRoot) {
+  const ownPackage = readJson(path.join(projectRoot, 'package.json'))
+  if (ownPackage?.name === packageName) return projectRoot
+
+  let directory = projectRoot
+  while (isPathInside(repositoryRoot, directory)) {
+    const candidate = path.join(directory, 'node_modules', ...packageName.split('/'))
+    try {
+      const physical = fs.realpathSync(candidate)
+      if (isPathInside(fs.realpathSync(repositoryRoot), physical)) return physical
+    } catch {}
+    if (directory === repositoryRoot) break
+    directory = path.dirname(directory)
+  }
+}
+
+/**
+ * Returns a runner package name.
+ *
+ * @param {string} framework framework name
+ * @returns {string} package name
+ */
+function getRunnerPackageName (framework) {
+  return {
+    cucumber: '@cucumber/cucumber',
+    playwright: '@playwright/test',
+  }[framework] || framework
+}
+
+/**
+ * Returns a generated-test location that follows the representative discovery convention.
+ *
+ * @param {string} framework framework name
+ * @param {string} representative representative test
+ * @param {string} projectRoot detected project root
+ * @returns {{exactFilename: string|undefined, fileExtension: string, testDirectory: string}} convention
+ */
+function getGeneratedTestConvention (framework, representative, projectRoot) {
+  const basename = path.basename(representative)
+  if (/^test\.[cm]?[jt]s$/.test(basename)) {
+    const representativeDirectory = path.dirname(representative)
+    return {
+      exactFilename: basename,
+      fileExtension: path.extname(basename),
+      testDirectory: representativeDirectory === projectRoot
+        ? projectRoot
+        : path.dirname(representativeDirectory),
+    }
+  }
+  return {
+    exactFilename: undefined,
+    fileExtension: getTestExtension(framework, representative),
+    testDirectory: path.dirname(representative),
+  }
 }
 
 /**
- * Ranks conventional project areas ahead of auxiliary repository trees.
+ * Returns the complete suffix needed for framework discovery.
  *
- * @param {string} filename candidate test file
- * @param {string} root detected project root
- * @returns {number} project area preference rank
+ * @param {string} framework framework name
+ * @param {string} representative representative test
+ * @returns {string} generated test suffix
  */
-function getTestAreaRank (filename, root) {
-  const [topLevelDirectory] = path.relative(root, filename).split(path.sep)
-  return ['packages', 'src', 'test', 'tests'].includes(topLevelDirectory) ? 0 : 1
+function getTestExtension (framework, representative) {
+  if (framework === 'cucumber') return '.feature'
+  if (framework === 'cypress') return cypress.getTestExtension(representative)
+  if (framework === 'playwright') return playwright.getTestExtension(representative)
+  const match = /((?:[.-](?:test|spec))\.[cm]?[jt]sx?)$/.exec(representative)
+  if (match) return match[1]
+  const moduleExtension = /\.((?:[cm]js|[cm]ts))$/.exec(representative)?.[1]
+  return moduleExtension ? `.test.${moduleExtension}` : '.test.js'
 }
 
 /**
- * Ranks independently tested nested packages behind tests owned by the detected root command.
+ * Determines the generated JavaScript module system.
  *
- * @param {string} filename candidate test file
- * @param {string} root detected project root
- * @param {Map<string, number>} cache package-directory rank cache
- * @returns {number} independent test project rank
+ * @param {string} representative representative test
+ * @param {string} projectRoot project root
+ * @returns {'commonjs'|'esm'} module system
  */
-function getIndependentTestProjectRank (filename, root, cache) {
-  let directory = path.dirname(filename)
-  while (directory !== root && directory.startsWith(`${root}${path.sep}`)) {
-    if (cache.has(directory)) return cache.get(directory)
+function getModuleSystem (representative, projectRoot) {
+  if (/\.(?:mjs|mts)$/.test(representative)) return 'esm'
+  if (/\.(?:cjs|cts)$/.test(representative)) return 'commonjs'
 
+  let directory = path.dirname(representative)
+  while (isPathInside(projectRoot, directory)) {
     const packageJson = readJson(path.join(directory, 'package.json'))
-    if (packageJson) {
-      const rank = typeof packageJson.scripts?.test === 'string' ? 1 : 0
-      cache.set(directory, rank)
-      return rank
-    }
+    if (packageJson) return packageJson.type === 'module' ? 'esm' : 'commonjs'
+    if (directory === projectRoot) break
     directory = path.dirname(directory)
   }
-  return 0
+  return 'commonjs'
 }
 
-function getTestExtension (filename) {
-  const match = /((?:\.test|\.spec)\.(?:[cm]?[jt]s|[jt]sx))$/.exec(filename)
-  return match?.[1] || '.test.js'
+/**
+ * Discovers bounded CI configuration paths without interpreting them.
+ *
+ * @param {string} root repository root
+ * @returns {object} CI discovery data
+ */
+function discoverCiFiles (root) {
+  const found = []
+  for (const relativePath of CI_PATHS) {
+    const absolutePath = path.join(root, relativePath)
+    try {
+      const stat = fs.lstatSync(absolutePath)
+      if (stat.isSymbolicLink()) continue
+      if (stat.isFile()) {
+        found.push(relativePath)
+      } else if (stat.isDirectory()) {
+        for (const entry of readDirectoryEntries(absolutePath).slice(0, MAX_CI_FILES)) {
+          if (entry.isFile() && /\.ya?ml$/i.test(entry.name)) found.push(path.join(relativePath, entry.name))
+        }
+      }
+    } catch {}
+  }
+  const normalized = found.map(filename => filename.split(path.sep).join('/')).sort()
+  return {
+    found: normalized,
+    reviewRequired: normalized.length > 0,
+    reviewTargets: rankCiReviewTargets(normalized).slice(0, MAX_CI_REVIEW_TARGETS),
+    searched: CI_PATHS,
+  }
+}
+
+/**
+ * Ranks likely test workflows first.
+ *
+ * @param {string[]} files discovered CI paths
+ * @returns {string[]} ranked paths
+ */
+function rankCiReviewTargets (files) {
+  return [...files].sort((left, right) => getCiRank(left) - getCiRank(right) || left.localeCompare(right))
+}
+
+/**
+ * Returns a lower-is-better CI review rank.
+ *
+ * @param {string} filename CI path
+ * @returns {number} rank
+ */
+function getCiRank (filename) {
+  const value = filename.toLowerCase()
+  if (/(?:test|ci|build|unit|integration)/.test(value)) return 0
+  return 10
+}
+
+/**
+ * Finds the package manifest that owns a detection.
+ *
+ * @param {string} repositoryRoot repository root
+ * @param {string|undefined} location detected relative path
+ * @returns {{json: object, path: string}} package metadata
+ */
+function getDetectionPackageJson (repositoryRoot, location) {
+  const candidate = typeof location === 'string' && path.basename(location) === 'package.json'
+    ? path.resolve(repositoryRoot, location)
+    : path.join(repositoryRoot, 'package.json')
+  const json = readJson(candidate)
+  if (json) return { json, path: candidate }
+  return {
+    json: readJson(path.join(repositoryRoot, 'package.json')) || {},
+    path: path.join(repositoryRoot, 'package.json'),
+  }
 }
 
-function findConfigFiles (root, framework) {
-  const patterns = {
-    jest: /^jest\.config\./,
-    mocha: /^\.mocharc\./,
-    vitest: /^(?:vite|vitest)\.config\./,
-  }[framework]
-  if (!patterns) return []
+/**
+ * Safely reads a bounded directory.
+ *
+ * @param {string} directory directory path
+ * @returns {fs.Dirent[]} entries
+ */
+function readDirectoryEntries (directory) {
   try {
-    return fs.readdirSync(root).filter(filename => patterns.test(filename)).map(filename => path.join(root, filename))
+    return fs.readdirSync(directory, { withFileTypes: true }).slice(0, MAX_DIRECTORY_ENTRIES)
   } catch {
     return []
   }
 }
 
 /**
- * Resolves the package.json associated with a framework detection.
+ * Reads bounded UTF-8 source.
  *
- * @param {string} repositoryRoot repository root
- * @param {string[]} locations detected evidence paths
- * @returns {string} absolute package.json path
+ * @param {string} filename file path
+ * @returns {string|undefined} source
  */
-function getDetectionPackageJson (repositoryRoot, locations = []) {
-  const location = locations.find(value => path.basename(value) === 'package.json')
-  return path.resolve(repositoryRoot, location || 'package.json')
+function readText (filename) {
+  try {
+    const stat = fs.lstatSync(filename)
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_FILE_BYTES) return
+    return fs.readFileSync(filename, 'utf8')
+  } catch {}
 }
 
 /**
- * Resolves a detected runner version without executing repository code.
+ * Reads JSON without throwing.
  *
- * @param {string} framework detected framework package name
- * @param {string} projectRoot detected project root
- * @param {object} packageJson detected project package.json
- * @returns {string|null} installed or declared framework version
+ * @param {string} filename JSON path
+ * @returns {object|undefined} parsed object
  */
-function getInstalledFrameworkVersion (framework, projectRoot, packageJson) {
-  if (framework === 'node-test') return process.version
+function readJson (filename) {
+  const source = readText(filename)
+  if (source === undefined) return
   try {
-    const filename = require.resolve(`${framework}/package.json`, { paths: [projectRoot] })
-    return readJson(filename)?.version || null
+    return JSON.parse(source)
   } catch {}
+}
 
-  for (const field of ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies']) {
-    if (typeof packageJson[field]?.[framework] === 'string') return packageJson[field][framework]
-  }
-  return null
+/**
+ * Returns whether a framework target was selected.
+ *
+ * @param {string} framework framework id
+ * @param {Set<string>} selected selected ids
+ * @returns {boolean} selection result
+ */
+function isSelected (framework, selected) {
+  return selected.size === 0 || selected.has(framework)
 }
 
-function discoverCiFiles (root) {
-  const found = []
-  for (const relativePath of CI_PATHS) {
-    const filename = path.join(root, relativePath)
-    if (!fs.existsSync(filename)) continue
-    const stat = fs.statSync(filename)
-    if (stat.isDirectory()) {
-      for (const entry of fs.readdirSync(filename).sort()) {
-        if (/\.ya?ml$/.test(entry)) found.push(path.posix.join(relativePath, entry))
-      }
-    } else {
-      found.push(relativePath)
-    }
-  }
-  return {
-    searched: [...CI_PATHS],
-    found,
-    method: 'deterministic-known-ci-paths',
-    warnings: [],
-    notes: ['Generated by --init-manifest; select and record one replayable CI test step before live validation.'],
-  }
+/**
+ * Returns a stable project identifier.
+ *
+ * @param {object} packageJson package metadata
+ * @param {string} projectRoot project root
+ * @param {string} repositoryRoot repository root
+ * @returns {string} project id
+ */
+function getProjectId (packageJson, projectRoot, repositoryRoot) {
+  const value = packageJson.name || path.relative(repositoryRoot, projectRoot) || 'root'
+  return value.replace(/^@/, '').replaceAll(/[^A-Za-z0-9_.-]+/g, '-')
 }
 
+/**
+ * Detects package-manager metadata for reporting only.
+ *
+ * @param {string} root repository root
+ * @returns {string} package manager
+ */
 function detectPackageManager (root) {
   if (fs.existsSync(path.join(root, 'pnpm-lock.yaml'))) return 'pnpm'
   if (fs.existsSync(path.join(root, 'yarn.lock'))) return 'yarn'
-  return 'npm'
+  if (fs.existsSync(path.join(root, 'package-lock.json'))) return 'npm'
+  return 'unknown'
 }
 
+/**
+ * Detects workspace metadata for reporting only.
+ *
+ * @param {string} root repository root
+ * @returns {string} workspace manager
+ */
 function detectWorkspaceManager (root) {
   if (fs.existsSync(path.join(root, 'pnpm-workspace.yaml'))) return 'pnpm'
   const packageJson = readJson(path.join(root, 'package.json'))
   return packageJson?.workspaces ? detectPackageManager(root) : 'none'
 }
 
+/**
+ * Returns a manifest operating-system name.
+ *
+ * @param {string} platform Node.js platform
+ * @returns {string} OS name
+ */
 function getManifestOs (platform) {
-  if (platform === 'win32') return 'windows'
-  if (platform === 'darwin' || platform === 'linux') return platform
-  return 'unknown'
-}
-
-function findYarnRelease (root) {
-  const directory = path.join(root, '.yarn', 'releases')
-  try {
-    const release = fs.readdirSync(directory).find(filename => /^yarn-.+\.cjs$/.test(filename))
-    return release && path.join(directory, release)
-  } catch {}
-}
-
-function getProjectIdentifier (packageJson, projectRoot, repositoryRoot) {
-  if (packageJson.name) return packageJson.name.replaceAll(/[^A-Za-z0-9._-]+/g, '-')
-  return (path.relative(repositoryRoot, projectRoot) || 'root').replaceAll(path.sep, '-')
+  return platform === 'win32' ? 'windows' : platform
 }
 
+/**
+ * Checks lexical path containment.
+ *
+ * @param {string} root root path
+ * @param {string} filename candidate path
+ * @returns {boolean} whether the candidate is contained
+ */
 function isPathInside (root, filename) {
-  const relative = path.relative(root, filename)
-  return relative !== '' && relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative)
-}
-
-function readJson (filename) {
-  try {
-    return JSON.parse(fs.readFileSync(filename, 'utf8'))
-  } catch {}
+  const relative = path.relative(path.resolve(root), path.resolve(filename))
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative))
 }
 
 module.exports = { createManifestScaffold }