From f2b556a2988b056de3b98164e3cfa619627f4cd0 Mon Sep 17 00:00:00 2001 From: Benjamin DeMann Date: Tue, 17 Dec 2024 15:46:27 -0700 Subject: [PATCH] add js doc --- scripts/analyze_benchmarks/extractor.ts | 15 +++++++ scripts/analyze_benchmarks/file_finder.ts | 11 ++++++ scripts/analyze_benchmarks/index.ts | 9 +++++ scripts/analyze_benchmarks/reporter.ts | 9 +++++ scripts/analyze_benchmarks/statistics.ts | 39 +++++++++++++++++-- .../analyze_benchmarks/validate_versions.ts | 22 +++++++++++ 6 files changed, 102 insertions(+), 3 deletions(-) diff --git a/scripts/analyze_benchmarks/extractor.ts b/scripts/analyze_benchmarks/extractor.ts index caa5dfcc83..da24bbe59f 100644 --- a/scripts/analyze_benchmarks/extractor.ts +++ b/scripts/analyze_benchmarks/extractor.ts @@ -21,6 +21,11 @@ type BenchmarksJson = { [canisterName: string]: CanisterBenchmark; }; +/** + * Extracts benchmark entries from multiple files and groups them by version + * @param files Array of file paths to process + * @returns A record mapping version strings to arrays of benchmark entries + */ export async function extractBenchmarksEntriesFromFiles( files: string[] ): Promise> { @@ -32,6 +37,11 @@ export async function extractBenchmarksEntriesFromFiles( return groupEntriesByVersion(versionEntries); } +/** + * Extracts benchmark entries from a single file + * @param file Path to the benchmark file + * @returns Array of tuples containing version and benchmark entry pairs + */ async function extractBenchmarkEntries( file: string ): Promise> { @@ -60,6 +70,11 @@ async function extractBenchmarkEntries( }); } +/** + * Groups benchmark entries by their version + * @param entries Array of version and benchmark entry pairs + * @returns A record mapping version strings to arrays of benchmark entries + */ function groupEntriesByVersion( entries: Array<[string, BenchmarkEntry]> ): Record { diff --git a/scripts/analyze_benchmarks/file_finder.ts b/scripts/analyze_benchmarks/file_finder.ts index ac646f4fd6..b8992d048c 100644 --- a/scripts/analyze_benchmarks/file_finder.ts +++ b/scripts/analyze_benchmarks/file_finder.ts @@ -1,6 +1,11 @@ import { readdir, stat } from 'fs/promises'; import { join } from 'path'; +/** + * Recursively finds all benchmark.json files in a directory and its subdirectories + * @param dir Directory path to search + * @returns Array of full paths to benchmark.json files + */ export async function findBenchmarkFiles(dir: string): Promise { if (dir.includes('node_modules')) { return []; @@ -12,6 +17,12 @@ export async function findBenchmarkFiles(dir: string): Promise { return itemResults.flat(); } +/** + * Processes a single item in a directory to determine if it's a benchmark file + * @param dir Parent directory path + * @param item Name of the item to process + * @returns Array of paths to benchmark files (empty if item is not a benchmark file) + */ async function processDirectoryItem( dir: string, item: string diff --git a/scripts/analyze_benchmarks/index.ts b/scripts/analyze_benchmarks/index.ts index 9cffb78aca..7fc030a60e 100644 --- a/scripts/analyze_benchmarks/index.ts +++ b/scripts/analyze_benchmarks/index.ts @@ -7,6 +7,11 @@ import { findBenchmarkFiles } from './file_finder'; import { reportResults, StableAndExperimentalStatistics } from './reporter'; import { calculateVersionStatistics } from './statistics'; +/** + * Analyzes benchmarks for a specific version across stable and experimental examples + * @param targetVersion Version string to analyze + * @returns Statistics for both stable and experimental benchmarks + */ async function analyzeBenchmarksForVersion( targetVersion: string ): Promise { @@ -35,6 +40,10 @@ async function analyzeBenchmarksForVersion( }; } +/** + * Runs the benchmark analysis for a specified version or current version + * @param specifiedVersion Optional version to analyze. If not provided, uses current package version + */ function runBenchmarkAnalysis(specifiedVersion?: string): void { const versionToAnalyze = specifiedVersion ?? currentAzleVersion; console.info('Analyzing benchmarks...'); diff --git a/scripts/analyze_benchmarks/reporter.ts b/scripts/analyze_benchmarks/reporter.ts index 24168b67ac..4237a270bd 100644 --- a/scripts/analyze_benchmarks/reporter.ts +++ b/scripts/analyze_benchmarks/reporter.ts @@ -14,6 +14,11 @@ export type StableAndExperimentalStatistics = { const RESULTS_FILE = join(AZLE_PACKAGE_PATH, 'benchmark_stats.json'); const MARKDOWN_FILE = RESULTS_FILE.replace('.json', '.md'); +/** + * Reports benchmark results by updating JSON file and generating markdown report + * @param results Statistics for stable and experimental benchmarks + * @param version Version string for the results + */ export async function reportResults( results: StableAndExperimentalStatistics, version: string @@ -22,6 +27,10 @@ export async function reportResults( await outputMarkdownFromJson(); } +/** + * Reads the benchmark statistics from the JSON file + * @returns Record of version-keyed benchmark statistics + */ export async function readBenchmarkJsonFile(): Promise< Record> > { diff --git a/scripts/analyze_benchmarks/statistics.ts b/scripts/analyze_benchmarks/statistics.ts index 730f7fadb7..8ece2f376e 100644 --- a/scripts/analyze_benchmarks/statistics.ts +++ b/scripts/analyze_benchmarks/statistics.ts @@ -17,6 +17,11 @@ const EFFICIENCY_WEIGHTS = { mean: 0.1 } as const; +/** + * Calculates statistics for a set of benchmark entries + * @param entries Array of benchmark entries to analyze + * @returns Statistical analysis of the benchmark data + */ export function calculateVersionStatistics( entries: BenchmarkEntry[] ): Statistics { @@ -27,6 +32,12 @@ export function calculateVersionStatistics( return calculateStatistics(instructions); } +/** + * Calculates statistical measures for an array of instruction counts + * @param instructions Array of instruction counts + * @returns Statistical analysis including mean, median, standard deviation, etc. + * @throws Error if input array is empty or contains no valid instructions + */ function calculateStatistics(instructions: number[]): Statistics { if (instructions.length === 0) { throw new Error('Cannot calculate statistics for empty array'); @@ -65,20 +76,35 @@ function calculateStatistics(instructions: number[]): Statistics { }; } -function calculateMean(instructions: readonly number[]): number { +/** + * Calculates the mean of an array of numbers + * @param instructions Array of instruction counts + * @returns Arithmetic mean + */ +function calculateMean(instructions: number[]): number { return ( instructions.reduce((acc, val) => acc + val, 0) / instructions.length ); } -function calculateMedian(sorted: readonly number[]): number { +/** + * Calculates the median of a sorted array of numbers + * @param sorted Sorted array of numbers + * @returns Median value + */ +function calculateMedian(sorted: number[]): number { const mid = Math.floor(sorted.length / 2); return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid]; } -function calculateStandardDeviation(instructions: readonly number[]): number { +/** + * Calculates the standard deviation of an array of numbers + * @param instructions Array of instruction counts + * @returns Standard deviation + */ +function calculateStandardDeviation(instructions: number[]): number { const mean = calculateMean(instructions); return Math.sqrt( instructions @@ -87,6 +113,13 @@ function calculateStandardDeviation(instructions: readonly number[]): number { ); } +/** + * Calculates a weighted efficiency score based on min, median, and mean values + * @param min Minimum instruction count + * @param median Median instruction count + * @param mean Mean instruction count + * @returns Weighted efficiency score + */ function calculateBaselineWeightEfficiencyScore( min: number, median: number, diff --git a/scripts/analyze_benchmarks/validate_versions.ts b/scripts/analyze_benchmarks/validate_versions.ts index 5f906f1b5c..c4eee0e8fe 100644 --- a/scripts/analyze_benchmarks/validate_versions.ts +++ b/scripts/analyze_benchmarks/validate_versions.ts @@ -20,6 +20,14 @@ type BenchmarkEntry = { type BenchmarkData = Record; +/** + * Validates benchmark entries against expected versions + * @param filePath Path to the benchmark file + * @param entry Benchmark entry to validate + * @param expectedCurrentVersion Expected current version + * @param expectedPreviousVersion Expected previous version + * @returns Array of validation issues found + */ function validateEntry( filePath: string, entry: BenchmarkEntry, @@ -52,6 +60,13 @@ function validateEntry( ].filter(Boolean) as BenchmarkIssue[]; } +/** + * Validates versions in a benchmark file + * @param filePath Path to the benchmark file + * @param expectedCurrentVersion Expected current version + * @param expectedPreviousVersion Expected previous version + * @returns Array of validation issues found + */ async function validateFile( filePath: string, expectedCurrentVersion: string, @@ -70,6 +85,13 @@ async function validateFile( ); } +/** + * Validates versions across multiple benchmark files + * @param benchmarkFilePaths Array of paths to benchmark files + * @param expectedCurrentVersion Expected current version + * @param expectedPreviousVersion Expected previous version + * @returns Array of all validation issues found + */ async function validateBenchmarkVersions( benchmarkFilePaths: string[], expectedCurrentVersion: string,