velocious 1.0.666 → 1.0.668

package/src/testing/test-filter-parser.js

@@ -1,269 +1,50 @@
+// @ts-check
+
+import {
+  extractTestCliArguments,
+  normalizeExamplePatterns
+} from "@velocious/testing/node"
+
 /**
- * ParseFiltersResult type.
  * @typedef {object} ParseFiltersResult
  * @property {string[]} includeTags - Tags to include.
  * @property {string[]} excludeTags - Tags to exclude.
  * @property {string[]} examplePatterns - Example name patterns.
- * @property {string[]} filteredProcessArgs - Remaining process args with filter flags removed.
+ * @property {string[]} filteredProcessArgs - Remaining process args with package-owned flags removed.
  * @property {number | undefined} groups - Total number of groups for test splitting.
  * @property {number | undefined} groupNumber - Which group to run (1-indexed).
  * @property {boolean} profile - Whether test profiling is enabled.
  * @property {string | undefined} profileJsonPath - Rich profile output path.
  * @property {string | undefined} timingManifestPath - JSON timing manifest path.
  * @property {string | undefined} timingManifestOutputPath - Timing manifest output path.
+ * @property {number | undefined} retries - Default retry count.
+ * @property {string[]} setupFiles - Setup files imported before test files.
+ * @property {number | undefined} timeoutMs - Default lifecycle timeout.
  */
-// @ts-check
-
-const INCLUDE_TAG_FLAGS = new Set(["--tag", "--include-tag", "-t"])
-const EXCLUDE_TAG_FLAGS = new Set(["--exclude-tag", "--skip-tag", "-x"])
-const EXAMPLE_FLAGS = new Set(["--example", "--name", "-e"])
-const GROUPS_FLAGS = new Set(["--groups"])
-const GROUP_NUMBER_FLAGS = new Set(["--group-number"])
-const TIMING_MANIFEST_FLAGS = new Set(["--timing-manifest"])
-const PROFILE_JSON_FLAGS = new Set(["--profile-json"])
-const TIMING_MANIFEST_OUTPUT_FLAGS = new Set(["--timing-manifest-output"])
-
-/**
- * Runs split tags.
- * @param {string | undefined} value - Tag argument value.
- * @returns {string[]} - Tags list.
- */
-function splitTags(value) {
-  if (!value) return []
-
-  return value
-    .split(",")
-    .map((tag) => tag.trim())
-    .filter(Boolean)
-}
-
-/**
- * Runs escape reg exp.
- * @param {string} value - Value.
- * @returns {string} - Escaped value for regex.
- */
-function escapeRegExp(value) {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
-}
-
-/**
- * Runs the normalizeExamplePatterns helper.
- * @param {string[]} patterns - Patterns.
- * @returns {RegExp[]} - Normalized patterns.
- */
-export function normalizeExamplePatterns(patterns) {
-  const normalized = []
-
-  for (const pattern of patterns) {
-    const regexMatch = pattern.match(/^\/(.+)\/([gimsuy]*)$/)
 
-    if (regexMatch) {
-      normalized.push(new RegExp(regexMatch[1], regexMatch[2]))
-    } else {
-      normalized.push(new RegExp(escapeRegExp(pattern)))
-    }
-  }
-
-  return normalized
-}
+export { normalizeExamplePatterns }
 
 /**
- * Runs the parseFilters helper.
- * @param {string[]} processArgs - Process args.
- * @returns {ParseFiltersResult} - Parsed tags, group options, and process args.
+ * Preserves the Velocious parser result while delegating package-owned option parsing.
+ * @param {string[]} processArgs - Raw process arguments including the command name.
+ * @returns {ParseFiltersResult} - Package options and downstream process arguments.
  */
 export function parseFilters(processArgs) {
-  const includeTags = []
-  const excludeTags = []
-  const filteredProcessArgs = processArgs.length > 0 ? [processArgs[0]] : []
-  const examplePatterns = []
-
-  /**
-   * Defines groups.
-   * @type {number | undefined} */
-  let groups
-  /**
-   * Defines groupNumber.
-   * @type {number | undefined} */
-  let groupNumber
-  let profile = false
-  /** @type {string | undefined} */
-  let profileJsonPath
-  /** @type {string | undefined} */
-  let timingManifestPath
-  /** @type {string | undefined} */
-  let timingManifestOutputPath
-
-  let inRestArgs = false
-
-  for (let i = 1; i < processArgs.length; i++) {
-    const arg = processArgs[i]
-
-    if (arg === "--") {
-      inRestArgs = true
-      filteredProcessArgs.push(arg)
-      continue
-    }
-
-    if (!inRestArgs) {
-      if (INCLUDE_TAG_FLAGS.has(arg)) {
-        const nextValue = processArgs[i + 1]
-
-        if (nextValue && !nextValue.startsWith("-")) {
-          includeTags.push(...splitTags(nextValue))
-          i++
-        }
-        continue
-      }
-
-      if (EXCLUDE_TAG_FLAGS.has(arg)) {
-        const nextValue = processArgs[i + 1]
-
-        if (nextValue && !nextValue.startsWith("-")) {
-          excludeTags.push(...splitTags(nextValue))
-          i++
-        }
-        continue
-      }
-
-      if (arg.startsWith("--tag=")) {
-        includeTags.push(...splitTags(arg.slice("--tag=".length)))
-        continue
-      }
-
-      if (arg.startsWith("--include-tag=")) {
-        includeTags.push(...splitTags(arg.slice("--include-tag=".length)))
-        continue
-      }
-
-      if (arg.startsWith("--exclude-tag=")) {
-        excludeTags.push(...splitTags(arg.slice("--exclude-tag=".length)))
-        continue
-      }
-
-      if (arg.startsWith("--skip-tag=")) {
-        excludeTags.push(...splitTags(arg.slice("--skip-tag=".length)))
-        continue
-      }
-
-      if (EXAMPLE_FLAGS.has(arg)) {
-        const nextValue = processArgs[i + 1]
-
-        if (nextValue && !nextValue.startsWith("-")) {
-          examplePatterns.push(nextValue)
-          i++
-        }
-        continue
-      }
-
-      if (arg.startsWith("--example=")) {
-        examplePatterns.push(arg.slice("--example=".length))
-        continue
-      }
-
-      if (arg.startsWith("--name=")) {
-        examplePatterns.push(arg.slice("--name=".length))
-        continue
-      }
-
-      if (GROUPS_FLAGS.has(arg)) {
-        const nextValue = processArgs[i + 1]
-
-        if (nextValue && !nextValue.startsWith("-")) {
-          groups = parseInt(nextValue, 10)
-          i++
-        }
-        continue
-      }
-
-      if (arg.startsWith("--groups=")) {
-        groups = parseInt(arg.slice("--groups=".length), 10)
-        continue
-      }
-
-      if (GROUP_NUMBER_FLAGS.has(arg)) {
-        const nextValue = processArgs[i + 1]
-
-        if (nextValue && !nextValue.startsWith("-")) {
-          groupNumber = parseInt(nextValue, 10)
-          i++
-        }
-        continue
-      }
-
-      if (arg.startsWith("--group-number=")) {
-        groupNumber = parseInt(arg.slice("--group-number=".length), 10)
-        continue
-      }
-
-      if (TIMING_MANIFEST_FLAGS.has(arg)) {
-        const nextValue = processArgs[i + 1]
-
-        if (!nextValue || nextValue.startsWith("-")) throw new Error("--timing-manifest requires a path")
-        timingManifestPath = nextValue
-        i++
-        continue
-      }
-
-      if (arg.startsWith("--timing-manifest=")) {
-        timingManifestPath = arg.slice("--timing-manifest=".length)
-        if (!timingManifestPath) throw new Error("--timing-manifest requires a path")
-        continue
-      }
-
-      if (arg === "--profile") {
-        profile = true
-        continue
-      }
-
-      if (PROFILE_JSON_FLAGS.has(arg)) {
-        const nextValue = processArgs[i + 1]
-
-        if (!nextValue || nextValue.startsWith("-")) throw new Error("--profile-json requires a path")
-        profileJsonPath = nextValue
-        profile = true
-        i++
-        continue
-      }
-
-      if (arg.startsWith("--profile-json=")) {
-        profileJsonPath = arg.slice("--profile-json=".length)
-        if (!profileJsonPath) throw new Error("--profile-json requires a path")
-        profile = true
-        continue
-      }
-
-      if (TIMING_MANIFEST_OUTPUT_FLAGS.has(arg)) {
-        const nextValue = processArgs[i + 1]
-
-        if (!nextValue || nextValue.startsWith("-")) throw new Error("--timing-manifest-output requires a path")
-        timingManifestOutputPath = nextValue
-        profile = true
-        i++
-        continue
-      }
-
-      if (arg.startsWith("--timing-manifest-output=")) {
-        timingManifestOutputPath = arg.slice("--timing-manifest-output=".length)
-        if (!timingManifestOutputPath) throw new Error("--timing-manifest-output requires a path")
-        profile = true
-        continue
-      }
-    }
-
-    filteredProcessArgs.push(arg)
-  }
+  const {options, remainingArguments} = extractTestCliArguments(processArgs)
 
   return {
-    includeTags: Array.from(new Set(includeTags)),
-    excludeTags: Array.from(new Set(excludeTags)),
-    examplePatterns,
-    filteredProcessArgs,
-    groups,
-    groupNumber,
-    profile,
-    profileJsonPath,
-    timingManifestPath,
-    timingManifestOutputPath
+    includeTags: options.includeTags,
+    excludeTags: options.excludeTags,
+    examplePatterns: options.examples,
+    filteredProcessArgs: remainingArguments,
+    groups: options.groups,
+    groupNumber: options.groupNumber,
+    profile: options.profile === true,
+    profileJsonPath: options.profileJsonPath,
+    timingManifestPath: options.timingManifestPath,
+    timingManifestOutputPath: options.timingManifestOutputPath,
+    retries: options.retries,
+    setupFiles: options.setupFiles,
+    timeoutMs: options.timeoutMs
   }
 }

package/src/testing/test-profile-activity.js

@@ -1,14 +1,3 @@
 // @ts-check
 
-/**
- * Validates a low-cardinality activity label suitable for profile output.
- * @param {string} name - Activity name.
- * @returns {string} - Validated name.
- */
-export function validateTestActivityName(name) {
-  if (typeof name !== "string" || !/^[a-z][a-z0-9]*(?:[._:-][a-z0-9]+)*$/.test(name) || name.length > 64) {
-    throw new Error("Test profile activity name must be a lowercase identifier of at most 64 characters")
-  }
-
-  return name
-}
+export { validateTestActivityName } from "@velocious/testing/profiling"

package/src/testing/test-profile-output.js

@@ -1,255 +1,10 @@
 // @ts-check
 
-import fs from "node:fs/promises"
-import path from "node:path"
-import { roundProfileDuration } from "./test-profiler.js"
-import { validateTimingManifest } from "./timing-manifest.js"
-
-const FORBIDDEN_PROFILE_FIELDS = new Set([
-  "bind",
-  "binds",
-  "checkoutname",
-  "credential",
-  "credentials",
-  "databasename",
-  "error",
-  "host",
-  "password",
-  "reusekey",
-  "sql",
-  "stack",
-  "tenant",
-  "username"
-])
-const PHASE_ORDER = [
-  "discovery",
-  "imports",
-  "testing config/global setup",
-  "beforeAll",
-  "beforeEach",
-  "test body",
-  "afterEach",
-  "afterAll",
-  "custom",
-  "runner overhead",
-  "total"
-]
-let atomicWriteSequence = 0
-
-/**
- * Recursively rejects fields that are forbidden from rich profile output.
- * @param {ReturnType<typeof JSON.parse>} value - Profile value.
- * @param {string} [pathName] - Diagnostic field path.
- * @returns {void}
- */
-function assertProfilePrivacy(value, pathName = "profile") {
-  if (!value || typeof value !== "object") return
-
-  if (Array.isArray(value)) {
-    for (let index = 0; index < value.length; index++) {
-      assertProfilePrivacy(value[index], `${pathName}[${index}]`)
-    }
-    return
-  }
-
-  for (const [key, childValue] of Object.entries(value)) {
-    if (FORBIDDEN_PROFILE_FIELDS.has(key.toLowerCase())) {
-      throw new Error(`Forbidden profile field: ${pathName}.${key}`)
-    }
-
-    assertProfilePrivacy(childValue, `${pathName}.${key}`)
-  }
-}
-
-/**
- * Recursively rounds duration fields and rejects invalid duration values.
- * @param {ReturnType<typeof JSON.parse>} value - Profile value.
- * @param {string | undefined} [parentKey] - Parent field name.
- * @returns {void}
- */
-function normalizeDurations(value, parentKey) {
-  if (!value || typeof value !== "object") return
-
-  if (Array.isArray(value)) {
-    for (const childValue of value) normalizeDurations(childValue, parentKey)
-    return
-  }
-
-  for (const [key, childValue] of Object.entries(value)) {
-    const durationField = key.endsWith("Ms") || parentKey === "cpuMs"
-
-    if (durationField && typeof childValue === "number") {
-      if (typeof childValue !== "number" || !Number.isFinite(childValue) || childValue < 0) {
-        throw new Error(`Invalid test profile duration field: ${key}`)
-      }
-
-      value[key] = roundProfileDuration(childValue)
-      continue
-    }
-
-    if (key.endsWith("Ms") && key !== "cpuMs") {
-      throw new Error(`Invalid test profile duration field: ${key}`)
-    }
-
-    normalizeDurations(childValue, key)
-  }
-}
-
-/**
- * Returns a normalized JSON-safe rich profile.
- * @param {ReturnType<typeof JSON.parse>} profile - Rich profile document.
- * @returns {ReturnType<typeof JSON.parse>} - Normalized document.
- */
-function normalizedProfile(profile) {
-  if (profile?.schema !== "velocious.test-profile" || profile?.schemaVersion !== 1) {
-    throw new Error("Invalid Velocious test profile schema")
-  }
-
-  assertProfilePrivacy(profile)
-  const normalized = JSON.parse(JSON.stringify(profile))
-
-  normalizeDurations(normalized)
-  return normalized
-}
-
-/**
- * Writes text through a same-directory temporary file and atomic rename.
- * @param {string} outputPath - Final output path.
- * @param {string} content - Complete output content.
- * @returns {Promise<void>} - Resolves after rename.
- */
-async function atomicWrite(outputPath, content) {
-  const directory = path.dirname(outputPath)
-  const sequence = ++atomicWriteSequence
-  const temporaryPath = path.join(directory, `.${path.basename(outputPath)}.${process.pid}.${sequence}.tmp`)
-  let temporaryFileCreated = false
-
-  await fs.mkdir(directory, {recursive: true})
-
-  try {
-    await fs.writeFile(temporaryPath, content, {encoding: "utf8", flag: "wx"})
-    temporaryFileCreated = true
-    await fs.rename(temporaryPath, outputPath)
-  } catch (error) {
-    if (temporaryFileCreated) {
-      try {
-        await fs.unlink(temporaryPath)
-      } catch (cleanupError) {
-        if (!(cleanupError instanceof Error) || !("code" in cleanupError) || cleanupError.code !== "ENOENT") {
-          throw new AggregateError(
-            [error, cleanupError],
-            `Failed to write and clean up test profile output: ${outputPath}`,
-            {cause: cleanupError}
-          )
-        }
-      }
-    }
-
-    throw error
-  }
-}
-
-/**
- * Creates a sorted plain timing manifest.
- * @param {ReturnType<typeof JSON.parse>} profile - Rich profile document.
- * @returns {Record<string, number>} - Sorted file-duration map.
- */
-export function timingManifestFromProfile(profile) {
-  /** @type {Record<string, number>} */
-  const manifest = {}
-  const validatedManifest = validateTimingManifest(profile.timingManifest || {}, {source: "Test profile timing manifest"})
-
-  for (const [filePath, durationMs] of Object.entries(validatedManifest)) {
-    manifest[filePath] = roundProfileDuration(durationMs)
-  }
-
-  return manifest
-}
-
-/**
- * Atomically writes a canonical splitter-compatible timing manifest.
- * @param {object} args - Output arguments.
- * @param {string} args.outputPath - Final output path.
- * @param {Record<string, number>} args.timingManifest - Validated or candidate timing manifest.
- * @returns {Promise<void>} - Resolves after atomic replacement.
- */
-export async function writeTimingManifest({outputPath, timingManifest}) {
-  const normalized = validateTimingManifest(timingManifest)
-  /** @type {Record<string, number>} */
-  const rounded = {}
-
-  for (const [filePath, durationMs] of Object.entries(normalized)) {
-    rounded[filePath] = roundProfileDuration(durationMs)
-  }
-
-  await atomicWrite(outputPath, `${JSON.stringify(rounded, null, 2)}\n`)
-}
-
-/**
- * Atomically writes requested test profile outputs.
- * @param {object} args - Output options.
- * @param {ReturnType<typeof JSON.parse>} args.profile - Rich profile document.
- * @param {string} [args.profileJsonPath] - Rich JSON path.
- * @param {string} [args.timingManifestOutputPath] - Plain timing manifest path.
- * @returns {Promise<void>} - Resolves after all requested writes.
- */
-export async function writeTestProfileOutputs({profile, profileJsonPath, timingManifestOutputPath}) {
-  const normalized = normalizedProfile(profile)
-  const timingManifest = timingManifestFromProfile(normalized)
-
-  normalized.timingManifest = timingManifest
-
-  if (profileJsonPath) {
-    await atomicWrite(profileJsonPath, `${JSON.stringify(normalized, null, 2)}\n`)
-  }
-
-  if (timingManifestOutputPath) {
-    await writeTimingManifest({outputPath: timingManifestOutputPath, timingManifest})
-  }
-}
-
-/**
- * Formats a compact Benchmark-style console summary.
- * @param {ReturnType<typeof JSON.parse>} profile - Rich profile document.
- * @param {{profileJsonPath?: string, timingManifestOutputPath?: string}} [outputs] - Written output paths.
- * @returns {string} - Console summary.
- */
-export function formatTestProfileSummary(profile, outputs = {}) {
-  const lines = [
-    "Test profile",
-    "Phase".padEnd(31) + "Count".padStart(5) + "Real ms".padStart(13) + "CPU ms".padStart(13)
-  ]
-
-  for (const phase of PHASE_ORDER) {
-    const aggregate = profile.phases?.[phase]
-
-    if (!aggregate) continue
-
-    lines.push(
-      phase.padEnd(31) +
-      String(aggregate.count).padStart(5) +
-      aggregate.totalMs.toFixed(3).padStart(13) +
-      aggregate.cpuMs.total.toFixed(3).padStart(13)
-    )
-  }
-
-  if (profile.pools?.length > 0) {
-    lines.push("Pools")
-
-    for (const pool of profile.pools) {
-      lines.push(
-        `Pool ${pool.identifier}: created=${pool.connectionCreation.count}` +
-        ` failed=${pool.connectionCreation.failedCount}` +
-        ` wait=${pool.checkoutWait.count}/${pool.checkoutWait.totalMs.toFixed(3)}ms` +
-        ` timeouts=${pool.checkoutTimeoutCount}` +
-        ` reaped=${pool.idleReap.disposalCount}` +
-        ` peak=${pool.peakLiveConnections}`
-      )
-    }
-  }
-
-  if (outputs.profileJsonPath) lines.push(`Rich JSON: ${outputs.profileJsonPath}`)
-  if (outputs.timingManifestOutputPath) lines.push(`Timing manifest: ${outputs.timingManifestOutputPath}`)
-
-  return lines.join("\n")
-}
+export {
+  formatTestProfileSummary,
+  loadTimingManifest,
+  resolveTestProfileOptions,
+  timingManifestFromProfile,
+  writeTestProfileOutputs,
+  writeTimingManifest
+} from "@velocious/testing/node"