@reicek/neataptic-ts 0.1.24 → 0.1.26

package/scripts/generate-bench-tables.ts

@@ -14,46 +14,336 @@
  *  - Gracefully degrades when fields missing (older artifact schema).
  *  - Extend later for variance/regression annotation summaries.
  */
-import fs from 'fs';
-import path from 'path';
+import fs from 'node:fs';
+import path from 'node:path';
 
+/** Canonical benchmark artifact consumed by the table generator. */
+const BENCHMARK_ARTIFACT_PATH = path.resolve(
+  'test/benchmarks/benchmark.results.json',
+);
+
+/** Metrics shown in the variant delta table. */
+const DELTA_METRICS = ['buildMs', 'fwdAvgMs', 'bytesPerConn'] as const;
+
+/** Metrics shown in the heap and resident-set table. */
+const HEAP_METRICS = ['heapUsed', 'rss'] as const;
+
+/** Full metric set recognized across both current and legacy artifact schemas. */
+const AGGREGATED_METRICS = [...DELTA_METRICS, ...HEAP_METRICS] as const;
+
+/** Benchmark variant identifiers emitted by the build-variant suite. */
+type BenchmarkMode = 'src' | 'dist';
+
+/** Metric names that participate in src-vs-dist regression comparison. */
+type DeltaMetricName = (typeof DELTA_METRICS)[number];
+
+/** Metric names that participate in the heap summary table. */
+type HeapMetricName = (typeof HEAP_METRICS)[number];
+
+/** All metric names recognized by the script. */
+type BenchmarkMetricName = (typeof AGGREGATED_METRICS)[number];
+
+/** Legacy flat-artifact key names such as `buildMsMean`. */
+type LegacyMeanMetricKey = `${BenchmarkMetricName}Mean`;
+
+/**
+ * Aggregate statistics for one benchmark metric.
+ *
+ * The current table generator only consumes `mean`, but the wider schema can
+ * also carry percentile and spread values that may be used by later reports.
+ */
 interface AggregatedMetric {
-  mean: number;
-  p50: number;
-  p95: number;
-  std: number;
+  mean?: number;
+  p50?: number;
+  p95?: number;
+  std?: number;
 }
 
-/** Pad / truncate value to fixed width for monospace block. */
-function cell(v: any, w: number): string {
+/**
+ * Scenario-level metrics under one size bucket.
+ *
+ * The script currently reads the `all` scenario, but the normalized shape keeps
+ * the scenario layer so future reporting can distinguish specialized runs.
+ */
+type AggregatedScenarioBucket = Partial<
+  Record<BenchmarkMetricName, AggregatedMetric>
+>;
+
+/**
+ * Size bucket keyed by scenario name.
+ *
+ * Example: `1024 -> all -> buildMs -> { mean: ... }`.
+ */
+type AggregatedSizeBucket = Record<
+  string,
+  AggregatedScenarioBucket | undefined
+> & {
+  all?: AggregatedScenarioBucket;
+};
+
+/** Aggregated metrics keyed by benchmark size. */
+type AggregatedModeBucket = Record<string, AggregatedSizeBucket>;
+
+/** Fully normalized aggregated results keyed by build variant. */
+interface NormalizedAggregatedResults {
+  src: AggregatedModeBucket;
+  dist: AggregatedModeBucket;
+}
+
+/** Minimal artifact contract needed by this script. */
+interface BenchmarkArtifact {
+  aggregated?: unknown;
+}
+
+/**
+ * Legacy array-based aggregated entry shape.
+ *
+ * Older benchmark artifacts stored one flat record per `(mode, size)` pair
+ * using `fooMean` properties instead of the nested scenario bucket structure.
+ */
+interface LegacyAggregatedEntry extends Partial<
+  Record<LegacyMeanMetricKey, number>
+> {
+  mode: BenchmarkMode;
+  size: number | string;
+}
+
+/**
+ * Pads or truncates a value to fixed width for the fenced monospace tables.
+ *
+ * @param v - Cell value to render.
+ * @param w - Target cell width.
+ * @returns Fixed-width cell content.
+ */
+function cell(v: string | number | undefined | null, w: number): string {
   const s = String(v ?? '');
   return s.length >= w ? s.slice(0, w) : s + ' '.repeat(w - s.length);
 }
 
-/** Format number with trimmed trailing zeros. */
-function fmtNum(n: any, digits = 4): string {
-  if (typeof n !== 'number' || !isFinite(n)) return '';
+/**
+ * Formats a numeric value with trimmed trailing zeros.
+ *
+ * This keeps markdown tables compact without losing the ability to request
+ * higher precision for smaller benchmark values.
+ *
+ * @param n - Candidate numeric value.
+ * @param digits - Maximum fixed decimal precision.
+ * @returns Formatted number or an empty string when the input is not finite.
+ */
+function fmtNum(n: number | undefined, digits = 4): string {
+  if (typeof n !== 'number' || !Number.isFinite(n)) return '';
   return n.toFixed(digits).replace(/0+$/, '').replace(/\.$/, '');
 }
 
-function loadArtifact(): any | null {
-  const file = path.resolve('test/benchmarks/benchmark.results.json');
-  if (!fs.existsSync(file)) {
-    console.error('[bench:tables] Artifact not found:', file);
+/**
+ * Loads the benchmark artifact from disk.
+ *
+ * @returns Parsed artifact when present and readable, otherwise `null`.
+ */
+function loadArtifact(): BenchmarkArtifact | null {
+  if (!fs.existsSync(BENCHMARK_ARTIFACT_PATH)) {
+    console.error(
+      '[bench:tables] Artifact not found:',
+      BENCHMARK_ARTIFACT_PATH,
+    );
     return null;
   }
+
   try {
-    return JSON.parse(fs.readFileSync(file, 'utf8'));
-  } catch (e) {
-    console.error('[bench:tables] Parse error', e);
+    return JSON.parse(
+      fs.readFileSync(BENCHMARK_ARTIFACT_PATH, 'utf8'),
+    ) as BenchmarkArtifact;
+  } catch (error) {
+    console.error('[bench:tables] Parse error', error);
     return null;
   }
 }
 
-function buildVariantDeltaTable(artifact: any): string {
-  const agg = artifact.aggregated || {};
-  const sizes = new Set<string>(Object.keys(agg.src || {}));
-  const ordered = Array.from(sizes).sort((a, b) => parseInt(a) - parseInt(b));
+/**
+ * Normalizes the artifact's aggregated payload into one stable nested shape.
+ *
+ * The benchmark pipeline has emitted both nested and legacy flat array schemas.
+ * Folding both into the same mode/size/scenario/metric structure keeps the
+ * table builders simple and resilient.
+ *
+ * @param artifact - Parsed benchmark artifact.
+ * @returns Normalized aggregated result buckets.
+ */
+function normalizeAggregated(
+  artifact: BenchmarkArtifact,
+): NormalizedAggregatedResults {
+  if (Array.isArray(artifact.aggregated)) {
+    return normalizeLegacyAggregated(artifact.aggregated);
+  }
+
+  if (!isRecord(artifact.aggregated)) {
+    return createEmptyAggregatedResults();
+  }
+
+  return {
+    src: normalizeModeBucket(artifact.aggregated.src),
+    dist: normalizeModeBucket(artifact.aggregated.dist),
+  };
+}
+
+/**
+ * Converts the older flat array schema into the normalized nested shape.
+ *
+ * @param rawEntries - Legacy aggregated entries.
+ * @returns Normalized aggregated result buckets.
+ */
+function normalizeLegacyAggregated(
+  rawEntries: readonly unknown[],
+): NormalizedAggregatedResults {
+  const aggregatedResults = createEmptyAggregatedResults();
+
+  for (const rawEntry of rawEntries) {
+    if (!isLegacyAggregatedEntry(rawEntry)) {
+      continue;
+    }
+
+    const sizeKey = String(rawEntry.size);
+    const scenarioBucket = ensureAllScenarioBucket(
+      aggregatedResults[rawEntry.mode],
+      sizeKey,
+    );
+
+    for (const metricName of AGGREGATED_METRICS) {
+      const meanKey = `${metricName}Mean` as const;
+      const meanValue = rawEntry[meanKey];
+      if (typeof meanValue === 'number' && Number.isFinite(meanValue)) {
+        scenarioBucket[metricName] = { mean: meanValue };
+      }
+    }
+  }
+
+  return aggregatedResults;
+}
+
+/**
+ * Normalizes one top-level mode bucket such as `src` or `dist`.
+ *
+ * @param rawModeBucket - Unknown raw mode payload.
+ * @returns Normalized size buckets.
+ */
+function normalizeModeBucket(rawModeBucket: unknown): AggregatedModeBucket {
+  if (!isRecord(rawModeBucket)) {
+    return {};
+  }
+
+  return Object.fromEntries(
+    Object.entries(rawModeBucket).map(([sizeKey, rawSizeBucket]) => [
+      sizeKey,
+      normalizeSizeBucket(rawSizeBucket),
+    ]),
+  );
+}
+
+/**
+ * Normalizes one size bucket keyed by scenario names.
+ *
+ * @param rawSizeBucket - Unknown raw size payload.
+ * @returns Normalized scenario buckets.
+ */
+function normalizeSizeBucket(rawSizeBucket: unknown): AggregatedSizeBucket {
+  if (!isRecord(rawSizeBucket)) {
+    return {};
+  }
+
+  return Object.fromEntries(
+    Object.entries(rawSizeBucket).map(([scenarioName, rawScenarioBucket]) => [
+      scenarioName,
+      normalizeScenarioBucket(rawScenarioBucket),
+    ]),
+  ) as AggregatedSizeBucket;
+}
+
+/**
+ * Normalizes one scenario bucket keyed by metric name.
+ *
+ * Invalid or incomplete metric objects are dropped rather than guessed.
+ *
+ * @param rawScenarioBucket - Unknown raw scenario payload.
+ * @returns Normalized metric bucket.
+ */
+function normalizeScenarioBucket(
+  rawScenarioBucket: unknown,
+): AggregatedScenarioBucket {
+  if (!isRecord(rawScenarioBucket)) {
+    return {};
+  }
+
+  const normalizedEntries = AGGREGATED_METRICS.flatMap((metricName) => {
+    const rawMetric = rawScenarioBucket[metricName];
+    if (!isRecord(rawMetric)) {
+      return [];
+    }
+
+    const meanValue = rawMetric.mean;
+    if (typeof meanValue !== 'number' || !Number.isFinite(meanValue)) {
+      return [];
+    }
+
+    return [[metricName, { mean: meanValue }] as const];
+  });
+
+  return Object.fromEntries(normalizedEntries) as AggregatedScenarioBucket;
+}
+
+/**
+ * Ensures the `all` scenario exists for one `(mode, size)` pair.
+ *
+ * @param modeBucket - Normalized mode bucket.
+ * @param sizeKey - Size identifier.
+ * @returns Mutable `all` scenario bucket.
+ */
+function ensureAllScenarioBucket(
+  modeBucket: AggregatedModeBucket,
+  sizeKey: string,
+): AggregatedScenarioBucket {
+  modeBucket[sizeKey] ??= {};
+  modeBucket[sizeKey].all ??= {};
+  return modeBucket[sizeKey].all!;
+}
+
+/**
+ * Creates an empty normalized results shell.
+ *
+ * @returns Empty `src` and `dist` mode buckets.
+ */
+function createEmptyAggregatedResults(): NormalizedAggregatedResults {
+  return {
+    src: {},
+    dist: {},
+  };
+}
+
+/**
+ * Resolves size keys in ascending numeric order.
+ *
+ * @param aggregatedResults - Normalized aggregated result buckets.
+ * @returns Ordered size keys.
+ */
+function resolveOrderedSizes(
+  aggregatedResults: NormalizedAggregatedResults,
+): string[] {
+  return [...new Set(Object.keys(aggregatedResults.src))].toSorted(
+    compareNumericSizeKeys,
+  );
+}
+
+/**
+ * Builds the variant delta table comparing `src` and `dist` means.
+ *
+ * The result is tuned for markdown fenced blocks rather than GFM pipe tables,
+ * which keeps wide benchmark rows easier to scan in docs and pull requests.
+ *
+ * @param artifact - Parsed benchmark artifact.
+ * @returns Monospace markdown table body.
+ */
+function buildVariantDeltaTable(artifact: BenchmarkArtifact): string {
+  const aggregatedResults = normalizeAggregated(artifact);
+  const orderedSizes = resolveOrderedSizes(aggregatedResults);
   const rows: string[] = [];
   rows.push(
     'Size    Metric            Src Mean      Dist Mean     Δ Abs         Δ %        Flag          Result',
@@ -61,13 +351,10 @@ function buildVariantDeltaTable(artifact: any): string {
   rows.push(
     '------  ----------------- ------------- ------------- ------------- ---------- ------------- ------------------------------------------------------------',
   );
-  const metrics = ['buildMs', 'fwdAvgMs', 'bytesPerConn'];
-  for (const size of ordered) {
-    for (const metric of metrics) {
-      const srcAgg: AggregatedMetric | undefined =
-        agg.src?.[size]?.all?.[metric];
-      const distAgg: AggregatedMetric | undefined =
-        agg.dist?.[size]?.all?.[metric];
+  for (const size of orderedSizes) {
+    for (const metric of DELTA_METRICS) {
+      const srcAgg = aggregatedResults.src[size]?.all?.[metric];
+      const distAgg = aggregatedResults.dist[size]?.all?.[metric];
       const sMean = srcAgg?.mean;
       const dMean = distAgg?.mean;
       let dAbs: number | undefined;
@@ -123,10 +410,15 @@ function buildVariantDeltaTable(artifact: any): string {
   return rows.join('\n');
 }
 
-function buildHeapTable(artifact: any): string {
-  const agg = artifact.aggregated || {};
-  const sizes = new Set<string>(Object.keys(agg.src || {}));
-  const ordered = Array.from(sizes).sort((a, b) => parseInt(a) - parseInt(b));
+/**
+ * Builds the heap and RSS comparison table.
+ *
+ * @param artifact - Parsed benchmark artifact.
+ * @returns Monospace markdown table body.
+ */
+function buildHeapTable(artifact: BenchmarkArtifact): string {
+  const aggregatedResults = normalizeAggregated(artifact);
+  const orderedSizes = resolveOrderedSizes(aggregatedResults);
   const rows: string[] = [];
   rows.push(
     'Size    Metric         Src Bytes    Dist Bytes    Src MB    Dist MB   Δ Bytes      Δ %     Note',
@@ -134,10 +426,10 @@ function buildHeapTable(artifact: any): string {
   rows.push(
     '------  -------------- ------------ ------------ --------- --------- ----------- ------- -------------------------------------------------',
   );
-  for (const size of ordered) {
-    for (const metric of ['heapUsed', 'rss']) {
-      const s = agg.src?.[size]?.all?.[metric]?.mean;
-      const d = agg.dist?.[size]?.all?.[metric]?.mean;
+  for (const size of orderedSizes) {
+    for (const metric of HEAP_METRICS) {
+      const s = aggregatedResults.src[size]?.all?.[metric]?.mean;
+      const d = aggregatedResults.dist[size]?.all?.[metric]?.mean;
       if (typeof s !== 'number' || typeof d !== 'number') continue;
       const dBytes = d - s;
       const dPct = s === 0 ? 0 : (dBytes / s) * 100;
@@ -165,6 +457,55 @@ function buildHeapTable(artifact: any): string {
   return rows.join('\n');
 }
 
+/**
+ * Compares size keys numerically, falling back to lexical comparison.
+ *
+ * @param left - Left size key.
+ * @param right - Right size key.
+ * @returns Standard comparator delta.
+ */
+function compareNumericSizeKeys(left: string, right: string): number {
+  const leftValue = Number.parseInt(left, 10);
+  const rightValue = Number.parseInt(right, 10);
+
+  if (Number.isNaN(leftValue) || Number.isNaN(rightValue)) {
+    return left.localeCompare(right);
+  }
+
+  return leftValue - rightValue || left.localeCompare(right);
+}
+
+/**
+ * Narrows an unknown value to the legacy flat aggregated entry shape.
+ *
+ * @param value - Candidate legacy entry.
+ * @returns `true` when the value matches the legacy schema.
+ */
+function isLegacyAggregatedEntry(
+  value: unknown,
+): value is LegacyAggregatedEntry {
+  return (
+    isRecord(value) &&
+    (value.mode === 'src' || value.mode === 'dist') &&
+    (typeof value.size === 'number' || typeof value.size === 'string')
+  );
+}
+
+/**
+ * Narrows an unknown value to a plain object record.
+ *
+ * @param value - Candidate value.
+ * @returns `true` when the value is a non-array object.
+ */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Runs the artifact load and emits both markdown tables to standard output.
+ *
+ * @returns Nothing.
+ */
 function main() {
   const artifact = loadArtifact();
   if (!artifact) process.exit(1);

package/scripts/generate-docs/generate-docs.constants.ts

@@ -0,0 +1,107 @@
+/*
+ * Centralizes stable docs-generator constants and target definitions.
+ *
+ * Keeping these values in one file makes it easier to audit what the generator
+ * considers a target, a published output root, or an ordering-control file
+ * without mixing that policy into traversal or rendering code.
+ */
+
+import * as path from 'path';
+
+import type { DocsTargetConfig } from './generate-docs.types.js';
+
+/** Root docs output directory mirrored into the published docs site. */
+export const DOCS_DIR = path.resolve('docs');
+
+/** Default docs target when no CLI or environment override is supplied. */
+export const DEFAULT_DOCS_TARGET = 'src';
+
+/** Synthetic symbol name used to store file-level summary content. */
+export const FILE_SUMMARY_SYMBOL_NAME = '__file_summary__';
+
+/** Source-file glob used to discover docs-generator inputs. */
+export const SOURCE_FILE_GLOBS = ['**/*.ts'];
+
+/** Ignore rules for files that should never become generated docs sources. */
+export const SOURCE_FILE_IGNORE_GLOBS = ['**/*.d.ts'];
+
+/** Generated docs landing page file name for the folder index. */
+export const FOLDER_INDEX_FILE_NAME = 'FOLDERS.md';
+
+/** Per-directory ordering config file name. */
+export const DOCS_ORDER_CONFIG_FILE_NAME = 'docs.order.json';
+
+/** Supported keys accepted inside `docs.order.json`. */
+export const DOCS_ORDER_SUPPORTED_KEYS = [
+  'introFile',
+  'fileOrder',
+  'symbolOrder',
+  'folderOrder',
+  'hiddenFiles',
+  'hiddenSymbols',
+] as const;
+
+/** Workspace root used to rewrite absolute ts-morph type paths into repo paths. */
+export const WORKSPACE_ROOT_DIR = path.resolve('.');
+
+/**
+ * Docs targets supported by the folder README generator.
+ *
+ * Each target maps one source tree into one published docs tree while keeping
+ * any target-specific root README mirroring rules local to the target.
+ */
+export const DOCS_TARGETS: Record<string, DocsTargetConfig> = {
+  src: {
+    name: 'src',
+    sourceDir: path.resolve('src'),
+    docsDir: DOCS_DIR,
+    rootDocsDir: path.join(DOCS_DIR, 'src'),
+    rootReadmeSource: path.resolve('README.md'),
+    rootReadmeDestination: path.join(DOCS_DIR, 'README.md'),
+    includeFolderIndex: true,
+  },
+  asciiMaze: {
+    name: 'asciiMaze',
+    sourceDir: path.resolve('test', 'examples', 'asciiMaze'),
+    docsDir: path.join(DOCS_DIR, 'examples', 'asciiMaze', 'docs'),
+    rootDocsDir: path.join(DOCS_DIR, 'examples', 'asciiMaze', 'docs'),
+    rootReadmeSource: path.resolve(
+      'test',
+      'examples',
+      'asciiMaze',
+      'README.md',
+    ),
+    rootReadmeDestination: path.join(
+      DOCS_DIR,
+      'examples',
+      'asciiMaze',
+      'docs',
+      'README.md',
+    ),
+    excludeRootSourceFiles: true,
+    publishedRootDir: path.join(DOCS_DIR, 'examples', 'asciiMaze'),
+    preservePublishedEntries: ['index.html'],
+  },
+  'flappy-bird': {
+    name: 'flappy-bird',
+    sourceDir: path.resolve('test', 'examples', 'flappy_bird'),
+    docsDir: path.join(DOCS_DIR, 'examples', 'flappy_bird', 'docs'),
+    rootDocsDir: path.join(DOCS_DIR, 'examples', 'flappy_bird', 'docs'),
+    rootReadmeSource: path.resolve(
+      'test',
+      'examples',
+      'flappy_bird',
+      'README.md',
+    ),
+    rootReadmeDestination: path.join(
+      DOCS_DIR,
+      'examples',
+      'flappy_bird',
+      'docs',
+      'README.md',
+    ),
+    excludeRootSourceFiles: true,
+    publishedRootDir: path.join(DOCS_DIR, 'examples', 'flappy_bird'),
+    preservePublishedEntries: ['index.html'],
+  },
+};