velocious 1.0.430 → 1.0.431

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

@@ -0,0 +1,177 @@
+// @ts-check
+
+import path from "path"
+import restArgsError from "../utils/rest-args-error.js"
+
+/**
+ * SplitterFileEntry type.
+ * @typedef {object} SplitterFileEntry
+ * @property {string} filePath - Absolute file path.
+ * @property {number} weight - Computed weight for load balancing.
+ */
+
+/**
+ * GroupBucket type.
+ * @typedef {object} GroupBucket
+ * @property {number} totalWeight - Accumulated weight.
+ * @property {string[]} files - Files assigned to this group.
+ */
+
+/** Default weight for a regular test file. */
+const DEFAULT_WEIGHT = 1
+
+/**
+ * Weight multipliers by spec directory name.
+ * Heavier test types get higher weights so greedy distribution balances wall-clock time.
+ * @type {Record<string, number>}
+ */
+const DIRECTORY_WEIGHTS = {
+  system: 20,
+  "frontend-models": 10,
+  controller: 3
+}
+
+/** Extra multiplier applied to browser spec files on top of directory weight. */
+const BROWSER_SPEC_MULTIPLIER = 2
+
+/**
+ * Splits a list of test files into balanced groups using a greedy load-balancing algorithm.
+ * Modeled after test_suite_splitter for RSpec.
+ */
+export default class TestSuiteSplitter {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options.
+   * @param {number} args.groups - Total number of groups.
+   * @param {number} args.groupNumber - Which group to return (1-indexed).
+   * @param {string[]} args.testFiles - All discovered test file paths.
+   * @param {string} [args.baseDirectory] - Base directory for relative path computation.
+   */
+  constructor({groups, groupNumber, testFiles, baseDirectory, ...restArgs}) {
+    restArgsError(restArgs)
+
+    if (!Number.isInteger(groups) || groups < 1) {
+      throw new Error(`--groups must be a positive integer, got: ${groups}`)
+    }
+
+    if (!Number.isInteger(groupNumber) || groupNumber < 1 || groupNumber > groups) {
+      throw new Error(`--group-number must be between 1 and ${groups}, got: ${groupNumber}`)
+    }
+
+    this._groups = groups
+    this._groupNumber = groupNumber
+    this._testFiles = testFiles
+    this._baseDirectory = baseDirectory || process.cwd()
+  }
+
+  /**
+   * Returns the test files assigned to this group.
+   * @returns {string[]} - File paths for the requested group.
+   */
+  getGroupFiles() {
+    const weighted = this.computeWeightedFiles()
+    const sorted = this.sortByWeightDescending(weighted)
+    const buckets = this.distributeGreedily(sorted)
+
+    return buckets[this._groupNumber - 1].files
+  }
+
+  /**
+   * Computes weight for each test file based on directory type and file suffix.
+   * @returns {SplitterFileEntry[]} - Weighted file entries.
+   */
+  computeWeightedFiles() {
+    return this._testFiles.map((filePath) => ({
+      filePath,
+      weight: this.computeWeight(filePath)
+    }))
+  }
+
+  /**
+   * Computes the weight for a single file.
+   * @param {string} filePath - Absolute file path.
+   * @returns {number} - Weight value.
+   */
+  computeWeight(filePath) {
+    const relativePath = path.relative(this._baseDirectory, filePath).split(path.sep).join("/")
+    let weight = DEFAULT_WEIGHT
+
+    // Extract the type directory from the relative path.
+    // Matches both "spec/system/..." (base is project root) and "system/..." (base is spec/ itself).
+    const specDirMatch = relativePath.match(/^(?:(?:spec|__tests__|tests)\/)?([^/]+)\//)
+
+    if (specDirMatch) {
+      const dirName = specDirMatch[1]
+
+      if (DIRECTORY_WEIGHTS[dirName] !== undefined) {
+        weight = DIRECTORY_WEIGHTS[dirName]
+      }
+    }
+
+    // Browser spec files are heavier
+    if (filePath.endsWith(".browser-spec.js") || filePath.endsWith(".browser-spec.mjs")) {
+      weight *= BROWSER_SPEC_MULTIPLIER
+    }
+
+    return weight
+  }
+
+  /**
+   * Sorts files by weight descending, then by path for determinism.
+   * @param {SplitterFileEntry[]} files - Weighted files.
+   * @returns {SplitterFileEntry[]} - Sorted files.
+   */
+  sortByWeightDescending(files) {
+    return [...files].sort((a, b) => {
+      if (b.weight !== a.weight) {
+        return b.weight - a.weight
+      }
+
+      return a.filePath.localeCompare(b.filePath)
+    })
+  }
+
+  /**
+   * Distributes files greedily into N balanced groups.
+   * Each file is assigned to the group with the least accumulated weight.
+   * @param {SplitterFileEntry[]} sortedFiles - Files sorted by weight descending.
+   * @returns {GroupBucket[]} - Array of group buckets.
+   */
+  distributeGreedily(sortedFiles) {
+    /**
+     * Buckets.
+      @type {GroupBucket[]} */
+    const buckets = []
+
+    for (let i = 0; i < this._groups; i++) {
+      buckets.push({totalWeight: 0, files: []})
+    }
+
+    for (const entry of sortedFiles) {
+      const lightest = this.findLightestBucket(buckets)
+
+      lightest.files.push(entry.filePath)
+      lightest.totalWeight += entry.weight
+    }
+
+    return buckets
+  }
+
+  /**
+   * Finds the bucket with the least accumulated weight.
+   * Ties are broken by bucket index (earlier bucket wins) for determinism.
+   * @param {GroupBucket[]} buckets - Group buckets.
+   * @returns {GroupBucket} - The lightest bucket.
+   */
+  findLightestBucket(buckets) {
+    let lightest = buckets[0]
+
+    for (let i = 1; i < buckets.length; i++) {
+      if (buckets[i].totalWeight < lightest.totalWeight) {
+        lightest = buckets[i]
+      }
+    }
+
+    return lightest
+  }
+}

package/src/testing/test.js

@@ -0,0 +1,370 @@
+// @ts-check
+
+import path from "path"
+import {fileURLToPath} from "url"
+import EventEmitter from "../utils/event-emitter.js"
+import Expect from "./expect.js"
+import {arrayContaining, objectContaining} from "./expect-utils.js"
+
+/**
+ * Tests.
+  @type {import("./test-runner.js").TestsArgument} */
+const tests = {
+  /**
+   * Narrows the runtime value to the documented type.
+    @type {import("./test-runner.js").AfterBeforeEachCallbackObjectType[]} */
+  afterEaches: [],
+  /**
+   * Narrows the runtime value to the documented type.
+    @type {import("./test-runner.js").BeforeAfterAllCallbackObjectType[]} */
+  afterAlls: [],
+  args: {},
+
+  /**
+   * Narrows the runtime value to the documented type.
+    @type {import("./test-runner.js").BeforeAfterAllCallbackObjectType[]} */
+  beforeAlls: [],
+  /**
+   * Narrows the runtime value to the documented type.
+    @type {import("./test-runner.js").AfterBeforeEachCallbackObjectType[]} */
+  beforeEaches: [],
+  filePath: undefined,
+  line: undefined,
+  subs: {},
+  tests: {}
+}
+
+const testEvents = new EventEmitter()
+
+let currentPath = [tests]
+
+/**
+ * Runs capture location.
+ * @returns {{filePath?: string, line?: number}} - Location.
+ */
+function captureLocation() {
+  const error = new Error()
+  const stack = typeof error.stack === "string" ? error.stack.split("\n") : []
+
+  for (const line of stack) {
+    const trimmed = line.trim()
+
+    if (!trimmed.includes("at")) continue
+    if (trimmed.includes("/src/testing/test.js")) continue
+
+    const match = trimmed.match(/(?:\(|\s)(file:\/\/.*?|\/.*?):(\d+):(\d+)\)?$/)
+
+    if (!match) continue
+
+    const rawPath = match[1]
+    const lineNumber = Number(match[2])
+    const filePath = rawPath.startsWith("file://")
+      ? fileURLToPath(rawPath)
+      : rawPath
+
+    return {
+      filePath: path.resolve(filePath),
+      line: Number.isFinite(lineNumber) ? lineNumber : undefined
+    }
+  }
+
+  return {}
+}
+
+/**
+ * Runs normalize tags.
+ * @param {string[] | string | undefined} tags - Tags.
+ * @returns {string[]} - Normalized tags.
+ */
+function normalizeTags(tags) {
+  if (!tags) return []
+
+  const values = []
+  const rawTags = Array.isArray(tags) ? tags : [tags]
+
+  for (const rawTag of rawTags) {
+    if (rawTag === undefined || rawTag === null) continue
+
+    const parts = String(rawTag).split(",")
+
+    for (const part of parts) {
+      const trimmed = part.trim()
+
+      if (trimmed) values.push(trimmed)
+    }
+  }
+
+  return Array.from(new Set(values))
+}
+
+/**
+ * Test config.
+  @type {VelociousTestConfig} */
+const testConfig = {
+  consoleOutput: "failure",
+  failedConsoleOutputMaxLines: 200,
+  excludeTags: [],
+  defaultTimeoutSeconds: 60
+}
+
+/**
+ * Runs configure tests.
+ * @param {object} args - Options.
+ * @param {"failure" | "live"} [args.consoleOutput] - Console output mode.
+ * @param {string[] | string} [args.excludeTags] - Tags to exclude.
+ * @param {number} [args.defaultTimeoutSeconds] - Default timeout in seconds.
+ * @param {number} [args.failedConsoleOutputMaxLines] - Maximum failed console lines to print inline.
+ * @returns {void}
+ */
+function configureTests({consoleOutput, excludeTags, defaultTimeoutSeconds, failedConsoleOutputMaxLines} = {}) {
+  if (excludeTags !== undefined) {
+    testConfig.excludeTags = normalizeTags(excludeTags)
+  }
+
+  if (consoleOutput !== undefined) {
+    if (consoleOutput !== "failure" && consoleOutput !== "live") {
+      throw new Error(`Invalid consoleOutput config: ${consoleOutput}`)
+    }
+
+    testConfig.consoleOutput = consoleOutput
+  }
+
+  if (typeof defaultTimeoutSeconds === "number") {
+    testConfig.defaultTimeoutSeconds = defaultTimeoutSeconds
+  }
+
+  if (typeof failedConsoleOutputMaxLines === "number") {
+    testConfig.failedConsoleOutputMaxLines = failedConsoleOutputMaxLines
+  }
+}
+
+/**
+ * Runs merge test args.
+ * @param {Record<string, ?>} baseArgs - Base args.
+ * @param {Record<string, ?>} extraArgs - Extra args.
+ * @returns {Record<string, ?>} - Merged args.
+ */
+function mergeTestArgs(baseArgs, extraArgs) {
+  const merged = Object.assign({}, baseArgs, extraArgs)
+  const mergedTags = [...normalizeTags(baseArgs?.tags), ...normalizeTags(extraArgs?.tags)]
+
+  if (mergedTags.length > 0) {
+    merged.tags = Array.from(new Set(mergedTags))
+  } else if ("tags" in merged) {
+    delete merged.tags
+  }
+
+  return merged
+}
+
+/**
+ * Runs before each.
+ * @param {import("./test-runner.js").AfterBeforeEachCallbackType} callback - Callback function.
+ * @returns {void} - No return value.
+ */
+function beforeEach(callback) {
+  const currentTest = currentPath[currentPath.length - 1]
+
+  currentTest.beforeEaches.push({callback})
+}
+
+/**
+ * Runs before all.
+ * @param {import("./test-runner.js").BeforeAfterAllCallbackType} callback - Callback function.
+ * @returns {void} - No return value.
+ */
+function beforeAll(callback) {
+  const currentTest = currentPath[currentPath.length - 1]
+
+  currentTest.beforeAlls.push({callback})
+}
+
+/**
+ * Runs after each.
+ * @param {import("./test-runner.js").AfterBeforeEachCallbackType} callback - Callback function.
+ * @returns {void} - No return value.
+ */
+function afterEach(callback) {
+  const currentTest = currentPath[currentPath.length - 1]
+
+  currentTest.afterEaches.push({callback})
+}
+
+/**
+ * Runs after all.
+ * @param {import("./test-runner.js").BeforeAfterAllCallbackType} callback - Callback function.
+ * @returns {void} - No return value.
+ */
+function afterAll(callback) {
+  const currentTest = currentPath[currentPath.length - 1]
+
+  currentTest.afterAlls.push({callback})
+}
+
+
+/**
+ * Runs describe.
+ * @param {string} description - Description.
+ * @param {object|(() => (void|Promise<void>))} arg1 - Arg1.
+ * @param {undefined|(() => (void|Promise<void>))} [arg2] - Arg2.
+ * @returns {Promise<void>} - Resolves when complete.
+ */
+async function describe(description, arg1, arg2) {
+  /**
+   * Defines testArgs.
+    @type {Record<string, ?>} */
+  let testArgs, testFunction
+
+  if (typeof arg2 == "function") {
+    testFunction = arg2
+    testArgs = arg1
+  } else if (typeof arg1 == "function") {
+    testFunction = arg1
+    testArgs = {}
+  } else {
+    throw new Error(`Invalid arguments for describe: ${arg1}, ${arg2}`)
+  }
+
+  const currentTest = currentPath[currentPath.length - 1]
+  const newTestArgs = mergeTestArgs(currentTest.args, testArgs)
+
+  if (description in currentTest.subs) {
+    throw new Error(`Duplicate test description: ${description}`)
+  }
+
+  const location = captureLocation()
+  const newTestData = {
+    afterEaches: [],
+    afterAlls: [],
+    args: newTestArgs,
+    beforeAlls: [],
+    beforeEaches: [],
+    filePath: location.filePath,
+    line: location.line,
+    subs: {},
+    tests: {}
+  }
+
+  currentTest.subs[description] = newTestData
+  currentPath.push(newTestData)
+
+  try {
+    await testFunction()
+  } finally {
+    currentPath.pop()
+  }
+}
+
+/**
+ * Runs expect.
+ * @param {?} arg - Arg.
+ * @returns {Expect} - The expect.
+ */
+function expect(arg) {
+  return new Expect(arg)
+}
+
+expect.objectContaining = objectContaining
+expect.arrayContaining = arrayContaining
+
+/**
+ * Runs it.
+ * @param {string} description - Description.
+ * @param {object|(() => (void|Promise<void>))} arg1 - Arg1.
+ * @param {undefined|(() => (void|Promise<void>))} [arg2] - Arg2.
+ * @returns {void} - No return value.
+ */
+function it(description, arg1, arg2) {
+  const currentTest = currentPath[currentPath.length - 1]
+  /**
+   * Defines testArgs.
+    @type {Record<string, ?>} */
+  let testArgs
+
+  /**
+   * Defines testFunction.
+    @type {() => (void|Promise<void>)} */
+  let testFunction
+
+  if (typeof arg1 == "function") {
+    testFunction = /**
+                    * Narrows the runtime value to the documented type.
+                     @type {() => (void|Promise<void>)} */ (arg1)
+    testArgs = {}
+  } else if (typeof arg2 == "function") {
+    testFunction = /**
+                    * Narrows the runtime value to the documented type.
+                     @type {() => (void|Promise<void>)} */ (arg2)
+    testArgs = arg1
+  } else {
+    throw new Error(`Invalid arguments for it: ${description}, ${arg1}`)
+  }
+
+  const newTestArgs = mergeTestArgs(currentTest.args, testArgs)
+
+  const location = captureLocation()
+
+  currentTest.tests[description] = {
+    args: newTestArgs,
+    function: testFunction,
+    filePath: location.filePath,
+    line: location.line
+  }
+}
+
+/**
+ * Runs fit.
+ * @param {string} description - Description.
+ * @param {object|(() => (void|Promise<void>))} arg1 - Arg1.
+ * @param {undefined|(() => (void|Promise<void>))} [arg2] - Arg2.
+ * @returns {void} - No return value.
+ */
+function fit(description, arg1, arg2) {
+  /**
+   * Defines testArgs.
+    @type {Record<string, ?>} */
+  let testArgs
+
+  /**
+   * Defines testFunction.
+    @type {() => (void|Promise<void>)} */
+  let testFunction
+
+  if (typeof arg1 == "function") {
+    testFunction = /**
+                    * Narrows the runtime value to the documented type.
+                     @type {() => (void|Promise<void>)} */ (arg1)
+    testArgs = {focus: true}
+  } else if (typeof arg2 == "function") {
+    testFunction = /**
+                    * Narrows the runtime value to the documented type.
+                     @type {() => (void|Promise<void>)} */ (arg2)
+    testArgs = Object.assign({focus: true}, arg1)
+  } else {
+    throw new Error(`Invalid arguments for it: ${description}, ${arg1}`)
+  }
+
+  return it(description, testArgs, testFunction)
+}
+
+// Make the methods global so they can be used in test files
+globalThis.afterEach = afterEach
+globalThis.afterAll = afterAll
+globalThis.beforeEach = beforeEach
+globalThis.beforeAll = beforeAll
+globalThis.describe = describe
+globalThis.expect = expect
+globalThis.it = it
+globalThis.fit = fit
+globalThis.testEvents = testEvents
+globalThis.configureTests = configureTests
+
+export {afterAll, afterEach, beforeAll, beforeEach, configureTests, describe, expect, fit, it, arrayContaining, objectContaining, testConfig, testEvents, tests}
+/**
+ * VelociousTestConfig type.
+ * @typedef {object} VelociousTestConfig
+ * @property {"failure" | "live"} consoleOutput - Console output mode.
+ * @property {string[]} excludeTags - Tags excluded by default.
+ * @property {number} defaultTimeoutSeconds - Default timeout in seconds.
+ * @property {number} failedConsoleOutputMaxLines - Maximum failed console lines to print inline.
+ */

package/src/types/external-modules.d.ts

@@ -0,0 +1,57 @@
+declare module "incorporator" {
+  export function incorporate<T extends object, U extends object>(target: T, source: U): T & U
+}
+
+declare module "sql-escape-string" {
+  export default function escapeString(value: string, quoteCharacter?: string | null): string
+}
+
+declare module "sql.js" {
+  export interface QueryExecResult {
+    columns: string[]
+    values: unknown[][]
+  }
+
+  export class Database {
+    constructor(data?: Uint8Array | ArrayLike<number> | null)
+    close(): void
+    exec(sql: string): QueryExecResult[]
+    export(): Uint8Array
+  }
+
+  export interface SqlJsStatic {
+    Database: typeof Database
+  }
+
+  export default function initSqlJs(options?: {locateFile?: (file: string) => string}): Promise<SqlJsStatic>
+}
+
+declare module "smtp-connection" {
+  import {EventEmitter} from "node:events"
+
+  export interface SMTPConnectionAuth {
+    [key: string]: unknown
+  }
+
+  export interface SMTPConnectionOptions {
+    auth?: SMTPConnectionAuth
+    [key: string]: unknown
+  }
+
+  export default class SMTPConnection extends EventEmitter {
+    constructor(options?: SMTPConnectionOptions)
+    close(): void
+    connect(callback: () => void): void
+    login(authData: SMTPConnectionAuth, callback: (error?: Error | null) => void): void
+    send(envelope: unknown, message: unknown, callback: (error?: Error | null, info?: unknown) => void): void
+    quit(): void
+  }
+}
+
+declare module "is-plain-object" {
+  export function isPlainObject(value: unknown): value is Record<string, unknown>
+}
+
+declare module "escape-string-regexp" {
+  export default function escapeStringRegexp(value: string): string
+}

package/src/utils/backtrace-cleaner-node.js

@@ -0,0 +1,87 @@
+// @ts-check
+
+import BacktraceCleaner from "./backtrace-cleaner.js"
+
+/**
+ * Runs normalize path.
+ * @param {string | undefined} value - Path or file URL.
+ * @returns {string | undefined} - Normalized path.
+ */
+function normalizePath(value) {
+  if (!value) return undefined
+
+  let normalized = value
+
+  if (normalized.startsWith("file://")) {
+    try {
+      normalized = new URL(normalized).pathname
+    } catch {
+      // Keep original value when URL parsing fails.
+    }
+  }
+
+  try {
+    normalized = decodeURIComponent(normalized)
+  } catch {
+    // Keep encoded value when decoding fails.
+  }
+
+  return normalized.replace(/\\/g, "/")
+}
+
+/**
+ * Runs framework source directory.
+ * @returns {string | undefined} - The Velocious source directory for Node runtimes.
+ */
+function frameworkSourceDirectory() {
+  try {
+    const sourceUrl = new URL("../", import.meta.url)
+
+    if (sourceUrl.protocol !== "file:") return undefined
+
+    return normalizePath(sourceUrl.pathname)
+  } catch {
+    return undefined
+  }
+}
+
+export const FRAMEWORK_SOURCE_DIRECTORY = frameworkSourceDirectory()
+
+export default class NodeBacktraceCleaner extends BacktraceCleaner {
+  /**
+   * Runs get cleaned stack.
+   * @param {Error} error - Error instance.
+   * @param {object} [args] - Options object.
+   * @param {string | undefined} [args.frameworkSourceDirectory] - Directory for Velocious internals to skip.
+   * @param {boolean} [args.includeErrorHeader] - Whether to include the `Error: ...` header line.
+   * @returns {string | undefined} - The cleaned stack.
+   */
+  static getCleanedStack(error, args) {
+    return new NodeBacktraceCleaner(error, args).getCleanedStack(args)
+  }
+
+  /**
+   * Runs get application source line.
+   * @param {Error} error - Error instance.
+   * @param {object} args - Options object.
+   * @param {string} args.applicationDirectory - Application directory.
+   * @param {string | undefined} [args.frameworkSourceDirectory] - Directory for Velocious internals to skip.
+   * @returns {string | undefined} - Source line for the first application frame.
+   */
+  static getApplicationSourceLine(error, args) {
+    return new NodeBacktraceCleaner(error, args).getApplicationSourceLine(args)
+  }
+
+  /**
+   * Runs constructor.
+   * @param {Error} error - Error instance.
+   * @param {object} [args] - Options object.
+   * @param {string | undefined} [args.frameworkSourceDirectory] - Directory for Velocious internals to skip.
+   */
+  constructor(error, args = {}) {
+    super(error, {
+      ...args,
+      frameworkSourceDirectory: args.frameworkSourceDirectory || FRAMEWORK_SOURCE_DIRECTORY
+    })
+  }
+}