modestbench 0.2.0 → 0.3.0

package/src/types/profiler.ts

@@ -0,0 +1,132 @@
+/**
+ * Profiler Types
+ *
+ * Type definitions for the profile command, including configuration options,
+ * profiled function data, and filtering results.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Filtered profile data ready for reporting
+ */
+export interface FilteredProfileData {
+  /** Command that was profiled */
+  command?: string;
+
+  /** Duration of profiled execution (ms) */
+  duration?: number;
+
+  /** Filtered and sorted functions */
+  functions: ProfiledFunction[];
+
+  /** Grouped by file (if requested) */
+  groupedByFile?: Map<string, ProfiledFunction[]>;
+
+  /** Profile summary */
+  summary: ProfileSummary;
+
+  /** Total functions before filtering */
+  totalFiltered: number;
+
+  /** Number of functions shown */
+  totalShown: number;
+
+  /** Total CPU ticks */
+  totalTicks: number;
+}
+
+/**
+ * Profile command configuration
+ */
+export interface ProfileConfig {
+  /** Command to profile (e.g., "npm test") */
+  command?: string;
+
+  /** Patterns to exclude */
+  exclude?: string[];
+
+  /** Explicit patterns to focus on */
+  focus?: string[];
+
+  /** Group results by file */
+  groupByFile?: boolean;
+
+  /** Path to existing *.cpuprofile file */
+  input?: string;
+
+  /** Minimum call count to show */
+  minCallCount?: number;
+
+  /** Minimum execution percentage to show (default: 0.5) */
+  minExecutionPercent?: number;
+
+  /** Output file path */
+  outputFile?: string;
+
+  /** Smart detection: only show functions from your package */
+  smartDetection?: boolean;
+
+  /** Number of top functions to show (default: 25) */
+  topN?: number;
+}
+
+/**
+ * A profiled JavaScript function
+ */
+export interface ProfiledFunction {
+  /** Function category */
+  category: 'C++' | 'GC' | 'JavaScript' | 'Unknown';
+
+  /** File path */
+  file: string;
+
+  /** Line number (if available) */
+  line: null | number;
+
+  /** Function name */
+  name: string;
+
+  /** Percentage of total execution time */
+  percentage: number;
+
+  /** CPU ticks in this function */
+  ticks: number;
+}
+
+/**
+ * Profile execution summary
+ */
+export interface ProfileSummary {
+  /** C++ ticks */
+  cppTicks: number;
+
+  /** Garbage collection ticks */
+  gcTicks: number;
+
+  /** JavaScript ticks */
+  javascriptTicks: number;
+
+  /** Shared library ticks */
+  sharedLibraryTicks: number;
+
+  /** Total CPU ticks */
+  totalTicks: number;
+}
+
+/**
+ * Raw profile data from V8 profiler
+ */
+export interface RawProfileData {
+  /** All profiled functions */
+  functions: ProfiledFunction[];
+
+  /** Path to log file */
+  logPath: string;
+
+  /** Profile summary */
+  summary: ProfileSummary;
+
+  /** Total CPU ticks */
+  totalTicks: number;
+}

package/src/types/utility.ts

@@ -281,11 +281,6 @@ export type Result<T, E = Error> =
   | { readonly data: T; readonly success: true }
   | { readonly error: E; readonly success: false };
 
-/**
- * Run identifier
- */
-export type RunId = Brand<string, 'RunId'>;
-
 /**
  * Configuration that can be serialized to JSON
  */
@@ -324,11 +319,6 @@ export interface Stream<T> extends AsyncIterable<T> {
  */
 export type SuiteId = Brand<string, 'SuiteId'>;
 
-/**
- * Task identifier
- */
-export type TaskId = Brand<string, 'TaskId'>;
-
 /**
  * Timing information
  */

package/src/utils/identifiers.ts

@@ -0,0 +1,58 @@
+/**
+ * Utility functions for creating branded identifier types
+ *
+ * @module utils/identifiers
+ */
+
+import type { RunId, TaskId } from '../types/budgets.js';
+
+/**
+ * Create a RunId from a string (validation should happen elsewhere)
+ *
+ * @param id - The run identifier string (typically 7 alphanumeric characters)
+ * @returns A branded RunId
+ */
+export const createRunId = (id: string): RunId => id as RunId;
+
+/**
+ * Create a TaskId from file, suite, and task names
+ *
+ * @param filePath - Path to the benchmark file
+ * @param suiteName - Name of the test suite
+ * @param taskName - Name of the benchmark task
+ * @returns A branded TaskId in the format `{filePath}/{suiteName}/{taskName}`
+ */
+export function createTaskId(
+  filePath: string,
+  suiteName: string,
+  taskName: string,
+): TaskId;
+
+/**
+ * Create a TaskId from a single string
+ *
+ * @param filePath - Path to the benchmark file
+ * @param suiteName - Name of the test suite
+ * @param taskName - Name of the benchmark task
+ * @returns A branded TaskId in the format `{filePath}/{suiteName}/{taskName}`
+ */
+export function createTaskId(taskId: string): TaskId;
+
+/**
+ * Create a TaskId from file, suite, and task names
+ *
+ * @param filePath - Path to the benchmark file
+ * @param suiteName - Name of the test suite
+ * @param taskName - Name of the benchmark task
+ * @returns A branded TaskId in the format `{filePath}/{suiteName}/{taskName}`
+ */
+export function createTaskId(
+  filePath: string,
+  suiteName?: string,
+  taskName?: string,
+): TaskId {
+  if (suiteName !== undefined && taskName !== undefined) {
+    return `${filePath}/${suiteName}/${taskName}` as TaskId;
+  }
+  return filePath as TaskId;
+}

package/src/utils/package.ts

@@ -0,0 +1,35 @@
+/**
+ * Package Utilities
+ *
+ * Utilities for working with package.json files and package structure.
+ *
+ * @packageDocumentation
+ */
+
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * Find the nearest package.json and return its directory
+ *
+ * @param startDir - Directory to start searching from
+ * @returns Path to directory containing package.json
+ */
+export const findPackageRoot = async (startDir: string): Promise<string> => {
+  let currentDir = path.resolve(startDir);
+  const root = path.parse(currentDir).root;
+
+  while (currentDir !== root) {
+    try {
+      const packagePath = path.join(currentDir, 'package.json');
+      await readFile(packagePath, 'utf-8');
+      return currentDir;
+    } catch {
+      // package.json not found, go up one directory
+      currentDir = path.dirname(currentDir);
+    }
+  }
+
+  // No package.json found, return starting directory
+  return startDir;
+};

package/src/utils/type-guards.ts

@@ -0,0 +1,51 @@
+/**
+ * Type Guard Utilities
+ *
+ * Reusable type guard functions for runtime type checking and narrowing.
+ */
+
+/**
+ * Type guard to check if a value is an object (not null or array)
+ *
+ * @param value - Value to check
+ * @returns True if value is a non-null object
+ */
+const isObject = (value: unknown): value is Record<string, unknown> => {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+};
+
+/**
+ * Type guard to check if a value is an Error instance
+ *
+ * @param value - Value to check
+ * @returns True if value is an Error
+ */
+export const isError = (value: unknown): value is Error => {
+  return value instanceof Error;
+};
+
+/**
+ * Type guard to check if a value has a specific property
+ *
+ * @param value - Value to check
+ * @param property - Property name to check for
+ * @returns True if value is an object with the specified property
+ */
+const hasProperty = <K extends string>(
+  value: unknown,
+  property: K,
+): value is Record<K, unknown> => {
+  return isObject(value) && property in value;
+};
+
+/**
+ * Type guard to check if an error has a code property
+ *
+ * @param error - Error to check
+ * @returns True if error has a code property
+ */
+export const hasErrorCode = (
+  error: unknown,
+): error is Error & { code: string } => {
+  return isError(error) && hasProperty(error, 'code');
+};