modestbench 0.2.0 → 0.3.0

package/dist/utils/identifiers.d.cts

@@ -0,0 +1,32 @@
+/**
+ * Utility functions for creating branded identifier types
+ *
+ * @module utils/identifiers
+ */
+import type { RunId, TaskId } from "../types/budgets.cjs";
+/**
+ * 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 declare const createRunId: (id: string) => 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 declare 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 declare function createTaskId(taskId: string): TaskId;
+//# sourceMappingURL=identifiers.d.ts.map

package/dist/utils/identifiers.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identifiers.d.ts","sourceRoot":"","sources":["../../src/utils/identifiers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,6BAA4B;AAEzD;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,IAAI,MAAM,KAAG,KAAoB,CAAC;AAE9D;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,MAAM,CAAC;AAEV;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC"}

package/dist/utils/identifiers.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 declare const createRunId: (id: string) => 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 declare 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 declare function createTaskId(taskId: string): TaskId;
+//# sourceMappingURL=identifiers.d.ts.map

package/dist/utils/identifiers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identifiers.d.ts","sourceRoot":"","sources":["../../src/utils/identifiers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,4BAA4B;AAEzD;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,IAAI,MAAM,KAAG,KAAoB,CAAC;AAE9D;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,MAAM,CAAC;AAEV;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC"}

package/dist/utils/identifiers.js

@@ -0,0 +1,27 @@
+/**
+ * Utility functions for creating branded identifier types
+ *
+ * @module utils/identifiers
+ */
+/**
+ * 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) => id;
+/**
+ * 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, suiteName, taskName) {
+    if (suiteName !== undefined && taskName !== undefined) {
+        return `${filePath}/${suiteName}/${taskName}`;
+    }
+    return filePath;
+}
+//# sourceMappingURL=identifiers.js.map

package/dist/utils/identifiers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identifiers.js","sourceRoot":"","sources":["../../src/utils/identifiers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,EAAU,EAAS,EAAE,CAAC,EAAW,CAAC;AA0B9D;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAC1B,QAAgB,EAChB,SAAkB,EAClB,QAAiB;IAEjB,IAAI,SAAS,KAAK,SAAS,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QACtD,OAAO,GAAG,QAAQ,IAAI,SAAS,IAAI,QAAQ,EAAY,CAAC;IAC1D,CAAC;IACD,OAAO,QAAkB,CAAC;AAC5B,CAAC"}

package/dist/utils/package.cjs

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * Package Utilities
+ *
+ * Utilities for working with package.json files and package structure.
+ *
+ * @packageDocumentation
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findPackageRoot = void 0;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("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
+ */
+const findPackageRoot = async (startDir) => {
+    let currentDir = node_path_1.default.resolve(startDir);
+    const root = node_path_1.default.parse(currentDir).root;
+    while (currentDir !== root) {
+        try {
+            const packagePath = node_path_1.default.join(currentDir, 'package.json');
+            await (0, promises_1.readFile)(packagePath, 'utf-8');
+            return currentDir;
+        }
+        catch {
+            // package.json not found, go up one directory
+            currentDir = node_path_1.default.dirname(currentDir);
+        }
+    }
+    // No package.json found, return starting directory
+    return startDir;
+};
+exports.findPackageRoot = findPackageRoot;
+//# sourceMappingURL=package.js.map

package/dist/utils/package.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.js","sourceRoot":"","sources":["../../src/utils/package.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;;;;AAEH,+CAA4C;AAC5C,0DAA6B;AAE7B;;;;;GAKG;AACI,MAAM,eAAe,GAAG,KAAK,EAAE,QAAgB,EAAmB,EAAE;IACzE,IAAI,UAAU,GAAG,mBAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACxC,MAAM,IAAI,GAAG,mBAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC;IAEzC,OAAO,UAAU,KAAK,IAAI,EAAE,CAAC;QAC3B,IAAI,CAAC;YACH,MAAM,WAAW,GAAG,mBAAI,CAAC,IAAI,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC;YAC1D,MAAM,IAAA,mBAAQ,EAAC,WAAW,EAAE,OAAO,CAAC,CAAC;YACrC,OAAO,UAAU,CAAC;QACpB,CAAC;QAAC,MAAM,CAAC;YACP,8CAA8C;YAC9C,UAAU,GAAG,mBAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IAED,mDAAmD;IACnD,OAAO,QAAQ,CAAC;AAClB,CAAC,CAAC;AAjBW,QAAA,eAAe,mBAiB1B"}

package/dist/utils/package.d.cts

@@ -0,0 +1,15 @@
+/**
+ * Package Utilities
+ *
+ * Utilities for working with package.json files and package structure.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Find the nearest package.json and return its directory
+ *
+ * @param startDir - Directory to start searching from
+ * @returns Path to directory containing package.json
+ */
+export declare const findPackageRoot: (startDir: string) => Promise<string>;
+//# sourceMappingURL=package.d.ts.map

package/dist/utils/package.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.d.ts","sourceRoot":"","sources":["../../src/utils/package.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAU,UAAU,MAAM,KAAG,OAAO,CAAC,MAAM,CAiBtE,CAAC"}

package/dist/utils/package.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Package Utilities
+ *
+ * Utilities for working with package.json files and package structure.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Find the nearest package.json and return its directory
+ *
+ * @param startDir - Directory to start searching from
+ * @returns Path to directory containing package.json
+ */
+export declare const findPackageRoot: (startDir: string) => Promise<string>;
+//# sourceMappingURL=package.d.ts.map

package/dist/utils/package.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.d.ts","sourceRoot":"","sources":["../../src/utils/package.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAU,UAAU,MAAM,KAAG,OAAO,CAAC,MAAM,CAiBtE,CAAC"}

package/dist/utils/package.js

@@ -0,0 +1,33 @@
+/**
+ * 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) => {
+    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;
+};
+//# sourceMappingURL=package.js.map

package/dist/utils/package.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.js","sourceRoot":"","sources":["../../src/utils/package.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,EAAE,QAAgB,EAAmB,EAAE;IACzE,IAAI,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACxC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC;IAEzC,OAAO,UAAU,KAAK,IAAI,EAAE,CAAC;QAC3B,IAAI,CAAC;YACH,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC;YAC1D,MAAM,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;YACrC,OAAO,UAAU,CAAC;QACpB,CAAC;QAAC,MAAM,CAAC;YACP,8CAA8C;YAC9C,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IAED,mDAAmD;IACnD,OAAO,QAAQ,CAAC;AAClB,CAAC,CAAC"}

package/dist/utils/type-guards.cjs

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * Type Guard Utilities
+ *
+ * Reusable type guard functions for runtime type checking and narrowing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasErrorCode = exports.isError = void 0;
+/**
+ * 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) => {
+    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
+ */
+const isError = (value) => {
+    return value instanceof Error;
+};
+exports.isError = isError;
+/**
+ * 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 = (value, property) => {
+    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
+ */
+const hasErrorCode = (error) => {
+    return (0, exports.isError)(error) && hasProperty(error, 'code');
+};
+exports.hasErrorCode = hasErrorCode;
+//# sourceMappingURL=type-guards.js.map

package/dist/utils/type-guards.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-guards.js","sourceRoot":"","sources":["../../src/utils/type-guards.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAEH;;;;;GAKG;AACH,MAAM,QAAQ,GAAG,CAAC,KAAc,EAAoC,EAAE;IACpE,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC,CAAC;AAEF;;;;;GAKG;AACI,MAAM,OAAO,GAAG,CAAC,KAAc,EAAkB,EAAE;IACxD,OAAO,KAAK,YAAY,KAAK,CAAC;AAChC,CAAC,CAAC;AAFW,QAAA,OAAO,WAElB;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,GAAG,CAClB,KAAc,EACd,QAAW,EACkB,EAAE;IAC/B,OAAO,QAAQ,CAAC,KAAK,CAAC,IAAI,QAAQ,IAAI,KAAK,CAAC;AAC9C,CAAC,CAAC;AAEF;;;;;GAKG;AACI,MAAM,YAAY,GAAG,CAC1B,KAAc,EACqB,EAAE;IACrC,OAAO,IAAA,eAAO,EAAC,KAAK,CAAC,IAAI,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;AACtD,CAAC,CAAC;AAJW,QAAA,YAAY,gBAIvB"}

package/dist/utils/type-guards.d.cts

@@ -0,0 +1,22 @@
+/**
+ * Type Guard Utilities
+ *
+ * Reusable type guard functions for runtime type checking and narrowing.
+ */
+/**
+ * Type guard to check if a value is an Error instance
+ *
+ * @param value - Value to check
+ * @returns True if value is an Error
+ */
+export declare const isError: (value: unknown) => value is Error;
+/**
+ * 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 declare const hasErrorCode: (error: unknown) => error is Error & {
+    code: string;
+};
+//# sourceMappingURL=type-guards.d.ts.map

package/dist/utils/type-guards.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-guards.d.ts","sourceRoot":"","sources":["../../src/utils/type-guards.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAYH;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,KAEjD,CAAC;AAgBF;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GACvB,OAAO,OAAO,KACb,KAAK,IAAI,KAAK,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAEjC,CAAC"}

package/dist/utils/type-guards.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Type Guard Utilities
+ *
+ * Reusable type guard functions for runtime type checking and narrowing.
+ */
+/**
+ * Type guard to check if a value is an Error instance
+ *
+ * @param value - Value to check
+ * @returns True if value is an Error
+ */
+export declare const isError: (value: unknown) => value is Error;
+/**
+ * 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 declare const hasErrorCode: (error: unknown) => error is Error & {
+    code: string;
+};
+//# sourceMappingURL=type-guards.d.ts.map

package/dist/utils/type-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-guards.d.ts","sourceRoot":"","sources":["../../src/utils/type-guards.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAYH;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,KAEjD,CAAC;AAgBF;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GACvB,OAAO,OAAO,KACb,KAAK,IAAI,KAAK,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAEjC,CAAC"}

package/dist/utils/type-guards.js

@@ -0,0 +1,43 @@
+/**
+ * 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) => {
+    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) => {
+    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 = (value, property) => {
+    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) => {
+    return isError(error) && hasProperty(error, 'code');
+};
+//# sourceMappingURL=type-guards.js.map

package/dist/utils/type-guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-guards.js","sourceRoot":"","sources":["../../src/utils/type-guards.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AACH,MAAM,QAAQ,GAAG,CAAC,KAAc,EAAoC,EAAE;IACpE,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,KAAc,EAAkB,EAAE;IACxD,OAAO,KAAK,YAAY,KAAK,CAAC;AAChC,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,GAAG,CAClB,KAAc,EACd,QAAW,EACkB,EAAE;IAC/B,OAAO,QAAQ,CAAC,KAAK,CAAC,IAAI,QAAQ,IAAI,KAAK,CAAC;AAC9C,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,KAAc,EACqB,EAAE;IACrC,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;AACtD,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modestbench",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "A full-ass benchmarking framework for Node.js",
   "repository": {
@@ -16,9 +16,7 @@
   "engines": {
     "node": ">=20.0.0"
   },
-  "bin": {
-    "modestbench": "dist/cli/index.js"
-  },
+  "bin": "./dist/cli/index.cjs",
   "main": "./dist/index.cjs",
   "types": "./dist/index.d.cts",
   "module": "./dist/index.js",
@@ -72,14 +70,14 @@
     "docs:preview": "astro preview --config astro.config.js",
     "fix": "run-s -sl fix:*",
     "fix:eslint": "eslint --fix .",
-    "fix:format": "prettier --write . && markdownlint-cli2 --fix \"**/*.md\"",
     "fix:pkg": "npm pkg fix",
+    "fix:prettier": "prettier --write . && markdownlint-cli2 --fix \"**/*.md\"",
     "lint": "run-p -sl --aggregate-output lint:*",
     "lint-staged": "lint-staged",
     "lint:eslint": "eslint .",
-    "lint:format": "prettier --check .",
     "lint:knip": "knip",
     "lint:markdown": "markdownlint-cli2 \"**/*.md\"",
+    "lint:prettier": "prettier --check .",
     "lint:spelling": "cspell .",
     "lint:types": "tsc --noEmit",
     "prepack": "run-s -s clean build",
@@ -99,7 +97,8 @@
     "cosmiconfig": "9.0.0",
     "cosmiconfig-typescript-loader": "6.2.0",
     "glob": "11.0.3",
-    "tinybench": "5.0.1",
+    "minimatch": "10.0.3",
+    "tinybench": "5.1.0",
     "yargs": "18.0.0",
     "zod": "4.1.12"
   },
@@ -112,17 +111,17 @@
     "@stylistic/eslint-plugin": "5.5.0",
     "@types/node": "24.9.1",
     "@types/wallabyjs": "0.0.15",
-    "@types/yargs": "17.0.33",
+    "@types/yargs": "17.0.34",
     "asciinema-player": "3.12.1",
     "astro": "5.15.1",
-    "bupkis": "0.11.1",
+    "bupkis": "0.12.0",
     "cspell": "9.2.2",
     "eslint": "9.38.0",
     "eslint-plugin-jsonc": "2.21.0",
     "eslint-plugin-perfectionist": "4.15.1",
     "globals": "16.4.0",
     "husky": "9.1.7",
-    "knip": "5.66.2",
+    "knip": "5.66.3",
     "lint-staged": "16.2.6",
     "markdownlint-cli2": "0.18.1",
     "markdownlint-cli2-formatter-pretty": "0.0.8",
@@ -207,6 +206,7 @@
     "tsdoc": true
   },
   "zshy": {
+    "bin": "./src/cli/index.ts",
     "exports": {
       ".": "./src/index.ts",
       "./cli": "./src/cli/index.ts",

package/src/cli/commands/analyze.ts

@@ -0,0 +1,101 @@
+/**
+ * Analyze Command
+ *
+ * CLI command for analyzing code execution and identifying benchmark
+ * candidates. Uses Node.js V8 profiler to capture function execution data.
+ *
+ * @packageDocumentation
+ */
+
+import type { ProfileConfig } from '../../types/profiler.js';
+import type { CliContext } from '../index.js';
+
+import { ProfileHumanReporter } from '../../reporters/profile-human.js';
+import { filterProfile } from '../../services/profiler/profile-filter.js';
+import { parseProfile } from '../../services/profiler/profile-parser.js';
+import { runWithProfiling } from '../../services/profiler/profile-runner.js';
+import { findPackageRoot } from '../../utils/package.js';
+
+/**
+ * Analyze command options interface
+ */
+export interface AnalyzeOptions {
+  /** Enable color output */
+  color?: boolean | undefined;
+
+  /** Command to analyze */
+  command?: string | undefined;
+
+  /** Working directory */
+  cwd: string;
+
+  /** Filter by file pattern */
+  filterFile?: string | undefined;
+
+  /** Group by file */
+  groupByFile?: boolean | undefined;
+
+  /** Input profile file */
+  input?: string | undefined;
+
+  /** Minimum execution percentage */
+  minPercent?: number | undefined;
+
+  /** Number of top functions to show */
+  top?: number | undefined;
+}
+
+/**
+ * Handle analyze command
+ */
+export const handleAnalyzeCommand = async (
+  _context: CliContext,
+  options: AnalyzeOptions,
+): Promise<number> => {
+  try {
+    const startTime = Date.now();
+
+    // Run profiling or load existing profile
+    const logPath = options.input
+      ? options.input
+      : await runWithProfiling(options.command!, {
+          cwd: options.cwd,
+        });
+
+    const duration = Date.now() - startTime;
+
+    // Parse profile data
+    const profileData = await parseProfile(logPath);
+
+    // Find package root for smart detection
+    const packageRoot = await findPackageRoot(options.cwd);
+
+    // Apply filtering
+    const config: ProfileConfig = {
+      focus: options.filterFile ? [options.filterFile] : undefined,
+      groupByFile: options.groupByFile,
+      minExecutionPercent: options.minPercent,
+      smartDetection: true,
+      topN: options.top,
+    };
+
+    const filtered = filterProfile(profileData, config, packageRoot);
+
+    // Add command and duration to filtered data
+    filtered.command = options.command;
+    filtered.duration = duration;
+
+    // Report results
+    const reporter = new ProfileHumanReporter({
+      color: options.color,
+      groupByFile: options.groupByFile,
+    });
+
+    reporter.report(filtered);
+
+    return 0;
+  } catch (error) {
+    console.error('Analyze command failed:', error);
+    return 1;
+  }
+};