velocious 1.0.604 → 1.0.605

package/src/environment-handlers/node/cli/commands/test/timing-manifest/merge.js

@@ -0,0 +1,108 @@
+// @ts-check
+
+import BaseCommand from "../../../../../../cli/base-command.js"
+import fs from "node:fs/promises"
+import path from "node:path"
+import { writeTimingManifest } from "../../../../../../testing/test-profile-output.js"
+import { mergeTestProfileTimingManifests } from "../../../../../../testing/timing-manifest.js"
+
+/**
+ * @typedef {object} TimingManifestMergeArguments
+ * @property {string[]} inputPaths - Rich profile input paths.
+ * @property {string} outputPath - Plain timing manifest output path.
+ */
+
+/** Node implementation for timing-manifest aggregation. */
+export default class TestTimingManifestMerge extends BaseCommand {
+  /**
+   * Runs execute.
+   * @returns {Promise<Record<string, number>>} - Complete merged timing manifest.
+   */
+  async execute() {
+    const {inputPaths, outputPath} = parseTimingManifestMergeArguments(this.processArgs || [], process.cwd())
+    const inputs = []
+
+    for (const inputPath of inputPaths) {
+      let content
+
+      try {
+        content = await fs.readFile(inputPath, "utf8")
+      } catch (error) {
+        throw new Error(`Failed to read test profile: ${inputPath}`, {cause: error})
+      }
+
+      let profile
+
+      try {
+        profile = JSON.parse(content)
+      } catch (error) {
+        throw new Error(`Failed to parse test profile: ${inputPath}`, {cause: error})
+      }
+
+      inputs.push({profile, source: inputPath})
+    }
+
+    const timingManifest = mergeTestProfileTimingManifests(inputs)
+
+    await writeTimingManifest({outputPath, timingManifest})
+    console.log(`Merged ${inputPaths.length} test profile shards into ${outputPath} (${Object.keys(timingManifest).length} files)`)
+
+    return timingManifest
+  }
+}
+
+/**
+ * Recognizes one output option spelling.
+ * @param {string} argument - Current argument.
+ * @param {string | undefined} nextArgument - Following argument.
+ * @returns {{matched: boolean, skipNext: boolean, value: string | undefined}} - Parsed output option.
+ */
+function timingManifestOutputArgument(argument, nextArgument) {
+  if (argument === "--output") {
+    return {matched: true, skipNext: true, value: nextArgument}
+  }
+
+  if (argument.startsWith("--output=")) {
+    return {matched: true, skipNext: false, value: argument.slice("--output=".length)}
+  }
+
+  return {matched: false, skipNext: false, value: undefined}
+}
+
+/**
+ * Parses strict merge arguments and resolves their paths.
+ * @param {string[]} processArgs - Raw CLI arguments, including command name.
+ * @param {string} cwd - Command working directory.
+ * @returns {TimingManifestMergeArguments} - Validated resolved paths.
+ */
+export function parseTimingManifestMergeArguments(processArgs, cwd) {
+  const commandName = processArgs[0] || "test:timing-manifest:merge"
+  const inputPaths = []
+  let outputPath
+
+  for (let index = 1; index < processArgs.length; index++) {
+    const argument = processArgs[index]
+    const outputArgument = timingManifestOutputArgument(argument, processArgs[index + 1])
+
+    if (outputArgument.matched) {
+      if (!outputArgument.value || outputArgument.value.startsWith("-")) throw new Error("Missing value for --output")
+      if (outputPath) throw new Error("--output may only be provided once")
+      outputPath = path.resolve(cwd, outputArgument.value)
+      if (outputArgument.skipNext) index++
+      continue
+    }
+
+    if (argument.startsWith("-")) throw new Error(`Unknown argument for ${commandName}: ${argument}`)
+    inputPaths.push(path.resolve(cwd, argument))
+  }
+
+  if (!outputPath) throw new Error("--output is required")
+  if (inputPaths.length === 0) throw new Error("At least one rich test profile input is required")
+
+  const uniqueInputPaths = new Set(inputPaths)
+
+  if (uniqueInputPaths.size !== inputPaths.length) throw new Error("Each rich test profile input must be provided once")
+  if (uniqueInputPaths.has(outputPath)) throw new Error("Timing manifest output must not overwrite an input profile")
+
+  return {inputPaths, outputPath}
+}

package/src/environment-handlers/node/cli/commands/test.js

@@ -10,6 +10,11 @@ import { formatTestProfileSummary, writeTestProfileOutputs } from "../../../../t
 import TestRunner from "../../../../testing/test-runner.js"
 import TestSuiteSplitter from "../../../../testing/test-suite-splitter.js"
 import { normalizeExamplePatterns, parseFilters } from "../../../../testing/test-filter-parser.js"
+import {
+  canonicalTimingManifestPath,
+  timingManifestFileSetHash,
+  validateTimingManifest
+} from "../../../../testing/timing-manifest.js"
 import { prepareSourcePeerPackage } from "../../source-peer-package.js"
 
 export default class VelociousCliCommandsTest extends BaseCommand {
@@ -95,14 +100,28 @@ export default class VelociousCliCommandsTest extends BaseCommand {
 
     try {
       const discoverTestFiles = async () => {
+        const timingManifest = await loadTimingManifest(profileOptions.timingManifestPath)
         let discoveredTestFiles = await testFilesFinder.findTestFiles()
+        const lineFilters = testFilesFinder.getLineFiltersByFile()
+
+        if (profiler) {
+          const discoveredFilePaths = discoveredTestFiles.map((filePath) => {
+            return canonicalTimingManifestPath(path.relative(directory, filePath))
+          })
+
+          profiler.setSelection({
+            discoveredFileCount: discoveredTestFiles.length,
+            hasLineFilters: Object.keys(lineFilters).length > 0,
+            pathBase: process.env.VELOCIOUS_TEST_DIR ? "test-directory" : "configuration-directory",
+            testFileSetHash: timingManifestFileSetHash(discoveredFilePaths)
+          })
+        }
 
         if (groups !== undefined || groupNumber !== undefined) {
           if (groups === undefined || groupNumber === undefined) {
             throw new Error("Both --groups and --group-number must be provided together")
           }
 
-          const timingManifest = await loadTimingManifest(profileOptions.timingManifestPath)
           const splitter = new TestSuiteSplitter({
             groups,
             groupNumber,
@@ -111,6 +130,15 @@ export default class VelociousCliCommandsTest extends BaseCommand {
             timingManifest
           })
 
+          if (profileOptions.timingManifestPath) {
+            const coverage = splitter.getTimingManifestCoverage()
+
+            console.log(picocolors.cyan(
+              `Timing manifest coverage: measured=${coverage.measuredFiles} ` +
+              `heuristic=${coverage.heuristicFiles} stale=${coverage.staleEntries}`
+            ))
+          }
+
           discoveredTestFiles = splitter.getGroupFiles()
           console.log(picocolors.cyan(`Running group ${groupNumber} of ${groups} (${discoveredTestFiles.length} files)`))
         }
@@ -158,6 +186,9 @@ export default class VelociousCliCommandsTest extends BaseCommand {
       process.once("SIGTERM", () => { void handleSignal("SIGTERM") })
 
       await testRunner.prepare()
+      const effectiveExcludeTagCount = testRunner.getExcludeTagSet().size
+
+      profiler?.setSelection({excludeTagCount: effectiveExcludeTagCount})
 
       if (testRunner.getTestsCount() === 0) {
         await finalizeProfile("no-tests")
@@ -170,7 +201,7 @@ export default class VelociousCliCommandsTest extends BaseCommand {
       const lineFilters = testRunner.getLineFilters()
       const hasLineFilters = Object.keys(lineFilters).length > 0
       const hasExampleFilters = examplePatterns.length > 0
-      const hasTagFilters = includeTags.length > 0 || excludeTags.length > 0
+      const hasTagFilters = includeTags.length > 0 || effectiveExcludeTagCount > 0
 
       if ((hasTagFilters || hasLineFilters || hasExampleFilters) && executedTests === 0) {
         console.error(picocolors.red("\nNo tests matched the provided filters"))
@@ -277,20 +308,30 @@ export function resolveTestProfileOptions({cwd, profile, profileJsonPath, timing
 }
 
 /**
- * Loads an optional JSON timing manifest. Unreadable or malformed input intentionally falls back to heuristics.
+ * Loads and validates an explicitly supplied plain JSON timing manifest.
  * @param {string | undefined} timingManifestPath - Timing manifest path.
- * @returns {Promise<ReturnType<typeof JSON.parse> | undefined>} - Parsed manifest when readable and valid JSON.
+ * @returns {Promise<Record<string, number> | undefined>} - Canonical manifest, or undefined when not requested.
  */
 export async function loadTimingManifest(timingManifestPath) {
   if (!timingManifestPath) return undefined
 
+  let content
+
   try {
-    return JSON.parse(await fs.readFile(timingManifestPath, "utf8"))
+    content = await fs.readFile(timingManifestPath, "utf8")
   } catch (error) {
-    if (error instanceof Error) return undefined
+    throw new Error(`Failed to read timing manifest: ${timingManifestPath}`, {cause: error})
+  }
+
+  let parsed
 
-    throw error
+  try {
+    parsed = JSON.parse(content)
+  } catch (error) {
+    throw new Error(`Failed to parse timing manifest: ${timingManifestPath}`, {cause: error})
   }
+
+  return validateTimingManifest(parsed, {source: `Timing manifest ${timingManifestPath}`})
 }
 
 /**

package/src/environment-handlers/node.js

@@ -14,6 +14,7 @@ import CliCommandsLintRelationships from "./node/cli/commands/lint/relationships
 import CliCommandsRoutes from "./node/cli/commands/routes.js"
 import CliCommandsServer from "./node/cli/commands/server.js"
 import CliCommandsTest from "./node/cli/commands/test.js"
+import CliCommandsTestTimingManifestMerge from "./node/cli/commands/test/timing-manifest/merge.js"
 import CliCommandsBackgroundJobsMain from "./node/cli/commands/background-jobs-main.js"
 import CliCommandsBackgroundJobsWorker from "./node/cli/commands/background-jobs-worker.js"
 import CliCommandsBackgroundJobsRunner from "./node/cli/commands/background-jobs-runner.js"
@@ -830,6 +831,15 @@ export default class VelociousEnvironmentHandlerNode extends Base{
     return await this.forwardCommand(command, CliCommandsTest)
   }
 
+  /**
+   * Runs cli commands test timing manifest merge.
+   * @param {import("../cli/base-command.js").default} command - Command.
+   * @returns {Promise<ReturnType<typeof JSON.parse>>} - Resolves with the command result.
+   */
+  async cliCommandsTestTimingManifestMerge(command) {
+    return await this.forwardCommand(command, CliCommandsTestTimingManifestMerge)
+  }
+
   /**
    * Runs cli commands background jobs main.
    * @param {import("../cli/base-command.js").default} command - Command.

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

@@ -3,6 +3,7 @@
 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",
@@ -156,20 +157,34 @@ async function atomicWrite(outputPath, content) {
 export function timingManifestFromProfile(profile) {
   /** @type {Record<string, number>} */
   const manifest = {}
+  const validatedManifest = validateTimingManifest(profile.timingManifest || {}, {source: "Test profile timing manifest"})
 
-  for (const filePath of Object.keys(profile.timingManifest || {}).sort()) {
-    const durationMs = profile.timingManifest[filePath]
-
-    if (typeof durationMs !== "number" || !Number.isFinite(durationMs) || durationMs < 0) {
-      throw new Error(`Invalid timing manifest duration for ${filePath}`)
-    }
-
+  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.
@@ -189,7 +204,7 @@ export async function writeTestProfileOutputs({profile, profileJsonPath, timingM
   }
 
   if (timingManifestOutputPath) {
-    await atomicWrite(timingManifestOutputPath, `${JSON.stringify(timingManifest, null, 2)}\n`)
+    await writeTimingManifest({outputPath: timingManifestOutputPath, timingManifest})
   }
 }
 

package/src/testing/test-profiler.js

@@ -4,6 +4,7 @@ import { createHash } from "node:crypto"
 import path from "node:path"
 import { registerTestProfileContextReader } from "./test-profile-context.js"
 import { validateTestActivityName } from "./test-profile-activity.js"
+import { compareTimingManifestPaths } from "./timing-manifest.js"
 
 /** @typedef {"passed" | "failed" | "interrupted" | "timed-out"} TestProfileAttemptStatus */
 /** @typedef {{user: number, system: number}} ProcessCpuUsage */
@@ -625,7 +626,7 @@ export default class TestProfiler {
         attemptsMs: roundProfileDuration(file.attemptsMs),
         totalMs: roundProfileDuration(file.totalMs)
       }))
-      .sort((fileA, fileB) => fileA.path.localeCompare(fileB.path))
+      .sort((fileA, fileB) => compareTimingManifestPaths(fileA.path, fileB.path))
     const timingManifest = Object.fromEntries(files.map((file) => [file.path, file.totalMs]))
     const attempts = this._tests.reduce((sum, test) => sum + test.attempts.length, 0)
 

package/src/testing/test-suite-splitter.js

@@ -2,6 +2,7 @@
 
 import path from "path"
 import restArgsError from "../utils/rest-args-error.js"
+import { canonicalTimingManifestPath, compareTimingManifestPaths } from "./timing-manifest.js"
 
 /**
  * SplitterFileEntry type.
@@ -95,14 +96,13 @@ export default class TestSuiteSplitter {
    * @returns {number} - Weight value.
    */
   computeWeight(filePath) {
-    const relativePath = this.normalizeRelativePath(path.relative(this._baseDirectory, filePath))
-    const projectRelativePath = this.normalizeRelativePath(path.join(path.basename(this._baseDirectory), relativePath))
-    const duration = this._timingManifest[relativePath] ?? this._timingManifest[projectRelativePath]
+    const duration = this.timingManifestDuration(filePath)
 
-    if (duration !== undefined) {
+    if (duration !== undefined && duration > 0) {
       return duration
     }
 
+    const relativePath = this.heuristicRelativePath(filePath)
     let weight = DEFAULT_WEIGHT
 
     // Extract the type directory from the relative path.
@@ -139,8 +139,12 @@ export default class TestSuiteSplitter {
     }
 
     for (const [filePath, duration] of Object.entries(timingManifest)) {
-      if (typeof duration === "number" && Number.isFinite(duration) && duration > 0) {
+      if (typeof duration !== "number" || !Number.isFinite(duration) || duration < 0) continue
+
+      try {
         normalized[this.normalizeRelativePath(filePath)] = duration
+      } catch (error) {
+        if (!(error instanceof Error)) throw error
       }
     }
 
@@ -153,11 +157,91 @@ export default class TestSuiteSplitter {
    * @returns {string} - Normalized relative test path.
    */
   normalizeRelativePath(filePath) {
-    return filePath
+    return canonicalTimingManifestPath(filePath)
+  }
+
+  /**
+   * Returns the permissive relative path used only for heuristic classification.
+   * @param {string} filePath - Absolute test file path.
+   * @returns {string} - Portable relative path which may escape the profiling base.
+   */
+  heuristicRelativePath(filePath) {
+    return path.relative(this._baseDirectory, filePath)
       .replaceAll("\\", "/")
       .replace(/^\.\//, "")
   }
 
+  /**
+   * Returns a canonical manifest key when the file is representable under the profiling base.
+   * @param {string} filePath - Absolute test file path.
+   * @returns {string | undefined} - Canonical relative path, or undefined for an external file.
+   */
+  manifestRelativePath(filePath) {
+    const relativePath = path.relative(this._baseDirectory, filePath)
+
+    if (!relativePath || path.isAbsolute(relativePath)) return
+    if (relativePath === ".." || relativePath.startsWith(`..${path.sep}`)) return
+
+    return this.normalizeRelativePath(relativePath)
+  }
+
+  /**
+   * Returns the first manifest entry matching a discovered test file.
+   * @param {string} filePath - Absolute test file path.
+   * @returns {number | undefined} - Recorded duration, including zero.
+   */
+  timingManifestDuration(filePath) {
+    for (const manifestPath of this.timingManifestPaths(filePath)) {
+      if (Object.hasOwn(this._timingManifest, manifestPath)) return this._timingManifest[manifestPath]
+    }
+
+    return undefined
+  }
+
+  /**
+   * Returns compatible manifest keys for one discovered file.
+   * @param {string} filePath - Absolute test file path.
+   * @returns {string[]} - Canonical keys in matching priority order.
+   */
+  timingManifestPaths(filePath) {
+    const relativePath = this.manifestRelativePath(filePath)
+
+    if (!relativePath) return []
+
+    const projectRelativePath = this.normalizeRelativePath(path.join(path.basename(this._baseDirectory), relativePath))
+
+    return relativePath === projectRelativePath ? [relativePath] : [relativePath, projectRelativePath]
+  }
+
+  /**
+   * Summarizes timing-history coverage for the complete discovered suite.
+   * @returns {{heuristicFiles: number, measuredFiles: number, staleEntries: number}} - Compact coverage counts.
+   */
+  getTimingManifestCoverage() {
+    const matchedManifestPaths = new Set()
+    let measuredFiles = 0
+
+    for (const filePath of this._testFiles) {
+      let matchedDuration
+
+      for (const manifestPath of this.timingManifestPaths(filePath)) {
+        if (!Object.hasOwn(this._timingManifest, manifestPath)) continue
+
+        matchedManifestPaths.add(manifestPath)
+        matchedDuration = this._timingManifest[manifestPath]
+        break
+      }
+
+      if (matchedDuration !== undefined && matchedDuration > 0) measuredFiles++
+    }
+
+    return {
+      heuristicFiles: this._testFiles.length - measuredFiles,
+      measuredFiles,
+      staleEntries: Object.keys(this._timingManifest).length - matchedManifestPaths.size
+    }
+  }
+
   /**
    * Sorts files by weight descending, then by path for determinism.
    * @param {SplitterFileEntry[]} files - Weighted files.
@@ -169,7 +253,7 @@ export default class TestSuiteSplitter {
         return b.weight - a.weight
       }
 
-      return a.filePath.localeCompare(b.filePath)
+      return compareTimingManifestPaths(a.filePath, b.filePath)
     })
   }