@auraindustry/aurajs 0.0.6 → 0.1.0

package/src/runtime-hotspot-audit.mjs

@@ -0,0 +1,707 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const SCHEMA_VERSION = 'aurajs.runtime-hotspot-audit.v1';
+export const DEFAULT_HOTSPOT_BUDGETS = Object.freeze([
+  Object.freeze({
+    path: 'src/rust-host/src/renderer.rs',
+    owner: 'renderer-facade',
+    maxLines: 1200,
+    reason: 'top-level renderer should stay a thin facade over draw2d/draw3d/support modules and split test owners',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/bindings.rs',
+    owner: 'bindings-installer-facade',
+    maxLines: 1500,
+    reason: 'bindings facade should stay a dispatcher over install, callback, support, and split test owner modules',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/main.rs',
+    owner: 'entrypoint-crash-boundary',
+    maxLines: 1400,
+    reason: 'main.rs should stay focused on entrypoint and crash-boundary concerns',
+  }),
+  Object.freeze({
+    path: 'src/cli/test/conformance.test.mjs',
+    owner: 'conformance-aggregate-coordinator',
+    maxLines: 80,
+    reason: 'aggregate conformance coordinator should stay a pure importer over owned suites',
+  }),
+  Object.freeze({
+    path: 'src/cli/src/cli.mjs',
+    owner: 'cli-router-facade',
+    maxLines: 6500,
+    reason: 'cli.mjs should stay a thin dispatcher over command-family modules and shared argument parsing',
+  }),
+  Object.freeze({
+    path: 'src/cli/src/conformance.mjs',
+    owner: 'conformance-coordinator',
+    maxLines: 3400,
+    reason: 'conformance.mjs should stay focused on runner orchestration and defer large case catalogs to owned suites',
+  }),
+  Object.freeze({
+    path: 'src/cli/src/conformance/cases/app-and-ui-runtime-cases.mjs',
+    owner: 'conformance-app-and-ui-runtime-family',
+    maxLines: 3400,
+    reason: 'app and UI runtime conformance cases should stay isolated from other case families instead of regrowing the aggregate runner',
+  }),
+  Object.freeze({
+    path: 'src/cli/src/conformance/cases/core-runtime-cases.mjs',
+    owner: 'conformance-core-runtime-family',
+    maxLines: 1600,
+    reason: 'core runtime cases should stay in the owned core family instead of leaking back into the aggregate runner',
+  }),
+  Object.freeze({
+    path: 'src/cli/src/conformance/cases/scene3d-and-media-cases.mjs',
+    owner: 'conformance-scene3d-and-media-family',
+    maxLines: 2100,
+    reason: 'scene3d and media conformance cases should stay in their owned family catalog',
+  }),
+  Object.freeze({
+    path: 'src/cli/src/conformance/cases/systems-and-gameplay-cases.mjs',
+    owner: 'conformance-systems-and-gameplay-family',
+    maxLines: 1900,
+    reason: 'systems and gameplay conformance cases should stay in their owned family catalog',
+  }),
+  Object.freeze({
+    path: 'src/cli/src/headless-test.mjs',
+    owner: 'headless-runtime-entry',
+    maxLines: 1200,
+    reason: 'headless-test.mjs should stay a thin entry over owned runtime coordinator and helper modules',
+  }),
+  Object.freeze({
+    path: 'src/cli/src/headless-test/runtime-coordinator.mjs',
+    owner: 'headless-runtime-coordinator',
+    maxLines: 1700,
+    reason: 'runtime-coordinator should stay the only broad headless orchestration file instead of absorbing unrelated namespace factories again',
+  }),
+  Object.freeze({
+    path: 'src/cli/src/scaffold.mjs',
+    owner: 'scaffold-entry',
+    maxLines: 250,
+    reason: 'scaffold.mjs should stay a thin entry over owned scaffold config, layout, fs, and project-docs families',
+  }),
+  Object.freeze({
+    path: 'src/cli/src/build-contract.mjs',
+    owner: 'build-contract-entry',
+    maxLines: 250,
+    reason: 'build-contract.mjs should stay a thin entry over owned build-contract helper modules',
+  }),
+  Object.freeze({
+    path: 'src/cli/src/build-contract/web-templates.mjs',
+    owner: 'build-contract-web-template-family',
+    maxLines: 4300,
+    reason: 'web build templates are now the large owned contract family and should stay isolated from the build-contract entry facade',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/bindings/tests_core.rs',
+    owner: 'bindings-test-corpus-dispatcher',
+    maxLines: 5000,
+    reason: 'bindings/tests_core.rs should stay a dispatcher over the owned bindings regression families instead of regrowing into the previous monolith',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/gltf_import.rs',
+    owner: 'gltf-import-entry',
+    maxLines: 3400,
+    reason: 'gltf_import.rs should stay focused on entry and owned helper delegation instead of reabsorbing schema and buffer helpers',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/mesh.rs',
+    owner: 'mesh-runtime-entry',
+    maxLines: 1900,
+    reason: 'mesh.rs should stay focused on mesh runtime ownership instead of reabsorbing import and generator helper families',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/bindings_navmesh.rs',
+    owner: 'navmesh-binding-family',
+    maxLines: 1700,
+    reason: 'bindings_navmesh.rs should stay bounded now that parse, result, and follow helpers can live in sibling families',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/audio.rs',
+    owner: 'audio-runtime-family',
+    maxLines: 1850,
+    reason: 'audio.rs should stay focused on audio runtime control after the observer and media helper split',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/bindings_video.rs',
+    owner: 'video-binding-entry',
+    maxLines: 900,
+    reason: 'bindings_video.rs should stay a thin entry over the dedicated media presentation helper bootstrap',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/bindings/install/ui.rs',
+    owner: 'ui-installer-entry',
+    maxLines: 80,
+    reason: 'bindings/install/ui.rs should stay a thin installer entry over the retained UI bootstrap family',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/bindings/install/ui/bootstrap.rs',
+    owner: 'ui-retained-bootstrap-family',
+    maxLines: 3300,
+    reason: 'the retained UI bootstrap surface is now the large owned family and should not leak back into the installer entry',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/renderer/draw2d.rs',
+    owner: 'draw2d-renderer-entry',
+    maxLines: 2800,
+    reason: 'renderer/draw2d.rs should stay focused on draw2d orchestration after pipeline extraction',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/bindings/draw2d.rs',
+    owner: 'draw2d-binding-entry',
+    maxLines: 3600,
+    reason: 'bindings/draw2d.rs should stay focused on draw2d binding orchestration after runtime and compositor extraction',
+  }),
+]);
+export const DEFAULT_REQUIRED_FILES = Object.freeze([
+  Object.freeze({
+    path: 'src/rust-host/src/renderer/draw2d.rs',
+    role: 'draw2d_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/renderer/draw3d.rs',
+    role: 'draw3d_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/bindings/draw3d.rs',
+    role: 'draw3d_binding_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/bindings/install.rs',
+    role: 'bindings_install_facade',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/bindings/install/core.rs',
+    role: 'bindings_install_core_family',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/bindings/install/ui.rs',
+    role: 'bindings_install_ui_family',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/bindings/install/scene.rs',
+    role: 'bindings_install_scene_family',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/bindings/value_support.rs',
+    role: 'bindings_value_support_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/bindings/callback_runtime_support.rs',
+    role: 'bindings_callback_runtime_support_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/bindings/test_support.rs',
+    role: 'bindings_test_support_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/bindings/input_support.rs',
+    role: 'bindings_input_window_support_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/bindings/window_input.rs',
+    role: 'bindings_window_input_bridge_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/bindings/audio_assets.rs',
+    role: 'bindings_audio_assets_bridge_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/bindings/physics_support.rs',
+    role: 'bindings_physics_support_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/bindings/utility_surface_support.rs',
+    role: 'bindings_utility_surface_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/host_runtime.rs',
+    role: 'host_bootstrap_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/host_runtime_callbacks.rs',
+    role: 'host_runtime_callback_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/runtime_bootstrap.rs',
+    role: 'runtime_bootstrap_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/runtime_launch_target.rs',
+    role: 'runtime_launch_target_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/runtime_host_commands.rs',
+    role: 'runtime_host_command_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/console_runtime.rs',
+    role: 'console_runtime_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/renderer/core.rs',
+    role: 'renderer_core_helper_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/renderer/debug_draw.rs',
+    role: 'renderer_debug_draw_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/renderer/math.rs',
+    role: 'renderer_math_helper_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/renderer/facade_support.rs',
+    role: 'renderer_facade_support_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/renderer/test_support.rs',
+    role: 'renderer_test_support_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/renderer/tests_core.rs',
+    role: 'renderer_core_test_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/renderer/tests_draw2d.rs',
+    role: 'renderer_draw2d_test_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/renderer/tests_scene_runtime.rs',
+    role: 'renderer_scene_runtime_test_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/renderer/tests_materials.rs',
+    role: 'renderer_material_test_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/renderer/draw2d_geometry.rs',
+    role: 'renderer_draw2d_geometry_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/renderer/passes.rs',
+    role: 'renderer_passes_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/renderer/passes/postfx.rs',
+    role: 'renderer_postfx_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/renderer/scene_submit.rs',
+    role: 'renderer_scene_submit_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/renderer/sprite_support.rs',
+    role: 'renderer_sprite_support_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/tests/main_runtime_surface_tests/mod.rs',
+    role: 'main_runtime_surface_test_owner',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/tests/main_launch_target_tests/mod.rs',
+    role: 'main_launch_target_test_owner',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/bindings/tests_core.rs',
+    role: 'bindings_core_test_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/bindings/tests_ui_layout.rs',
+    role: 'bindings_ui_layout_test_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/bindings/tests_ui_retained.rs',
+    role: 'bindings_ui_retained_test_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/bindings/tests_ui_widgets.rs',
+    role: 'bindings_ui_widgets_test_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/bindings/tests_draw2d.rs',
+    role: 'bindings_draw2d_test_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/bindings/tests_optional_modules.rs',
+    role: 'bindings_optional_module_test_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/tests/conformance_3d_internal/renderer_command_seam_tests.rs',
+    role: 'renderer_seam_proof',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/tests/conformance_3d_internal/bindings_bridge_seam_tests.rs',
+    role: 'bindings_seam_proof',
+  }),
+  Object.freeze({
+    path: 'src/cli/test/conformance-bootstrap-seams.test.mjs',
+    role: 'bootstrap_seam_proof',
+  }),
+  Object.freeze({
+    path: 'src/cli/test/conformance-bindings-seams.test.mjs',
+    role: 'bindings_seam_metadata_proof',
+  }),
+  Object.freeze({
+    path: 'src/cli/test/conformance-renderer-seams.test.mjs',
+    role: 'renderer_seam_metadata_proof',
+  }),
+  Object.freeze({
+    path: 'src/cli/test/conformance-aggregate-defaults.test.mjs',
+    role: 'conformance_aggregate_defaults_owner_suite',
+  }),
+  Object.freeze({
+    path: 'src/cli/test/conformance-animation-runtime.test.mjs',
+    role: 'animation_conformance_family_suite',
+  }),
+  Object.freeze({
+    path: 'src/cli/test/conformance-scene-runtime.test.mjs',
+    role: 'scene_conformance_family_suite',
+  }),
+  Object.freeze({
+    path: 'src/cli/test/conformance-reporting.test.mjs',
+    role: 'reporting_conformance_family_suite',
+  }),
+  Object.freeze({
+    path: 'src/cli/src/scene-composition/index.mjs',
+    role: 'scene_composition_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/cli/src/scene-composition/runtime.mjs',
+    role: 'scene_composition_runtime_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/cli/src/prefabs/index.mjs',
+    role: 'prefab_authoring_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/cli/src/prefabs/scene-serialization.mjs',
+    role: 'prefab_scene_serialization_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/cli/test/scene-composition.test.mjs',
+    role: 'scene_composition_owner_suite',
+  }),
+  Object.freeze({
+    path: 'src/cli/test/prefab-serialization.test.mjs',
+    role: 'prefab_scene_serialization_owner_suite',
+  }),
+  Object.freeze({
+    path: 'src/cli/src/commands/project-authoring.mjs',
+    role: 'cli_project_authoring_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/cli/src/conformance/cases/index.mjs',
+    role: 'conformance_case_catalog_index',
+  }),
+  Object.freeze({
+    path: 'src/cli/src/conformance/cases/app-and-ui-runtime-cases.mjs',
+    role: 'conformance_app_and_ui_runtime_owner_suite',
+  }),
+  Object.freeze({
+    path: 'src/cli/src/conformance/cases/core-runtime-cases.mjs',
+    role: 'conformance_core_runtime_owner_suite',
+  }),
+  Object.freeze({
+    path: 'src/cli/src/conformance/cases/scene3d-and-media-cases.mjs',
+    role: 'conformance_scene3d_and_media_owner_suite',
+  }),
+  Object.freeze({
+    path: 'src/cli/src/conformance/cases/systems-and-gameplay-cases.mjs',
+    role: 'conformance_systems_and_gameplay_owner_suite',
+  }),
+  Object.freeze({
+    path: 'src/cli/src/conformance/shared.mjs',
+    role: 'conformance_shared_helper_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/cli/src/headless-test/runtime-coordinator.mjs',
+    role: 'headless_runtime_coordinator_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/cli/src/headless-test/runtime-primitives.mjs',
+    role: 'headless_runtime_primitives_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/cli/src/headless-test/runtime-world.mjs',
+    role: 'headless_runtime_world_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/cli/src/headless-test/runtime-animation.mjs',
+    role: 'headless_runtime_animation_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/cli/src/scaffold/project-docs.mjs',
+    role: 'scaffold_project_docs_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/cli/src/build-contract/assets.mjs',
+    role: 'build_contract_assets_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/cli/src/build-contract/capabilities.mjs',
+    role: 'build_contract_capabilities_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/cli/src/build-contract/web-templates.mjs',
+    role: 'build_contract_web_templates_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/gltf_import/schema.rs',
+    role: 'gltf_import_schema_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/gltf_import/buffer.rs',
+    role: 'gltf_import_buffer_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/renderer/draw2d/pipelines.rs',
+    role: 'renderer_draw2d_pipeline_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/bindings/draw2d/runtime.rs',
+    role: 'bindings_draw2d_runtime_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/bindings/draw2d/compositor.rs',
+    role: 'bindings_draw2d_compositor_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/bindings/install/ui/bootstrap.rs',
+    role: 'bindings_install_ui_bootstrap_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/terrain_bindings/parsing.rs',
+    role: 'terrain_bindings_parse_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/terrain_splat/runtime.rs',
+    role: 'terrain_splat_runtime_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/terrain_vegetation/manager.rs',
+    role: 'terrain_vegetation_manager_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/bindings/multiplayer_events.rs',
+    role: 'bindings_multiplayer_event_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/bindings/multiplayer_v8.rs',
+    role: 'bindings_multiplayer_v8_owner_module',
+  }),
+  Object.freeze({
+    path: 'src/rust-host/src/bindings_video_presentation.rs',
+    role: 'bindings_video_presentation_owner_module',
+  }),
+]);
+
+const DEFAULTS = Object.freeze({
+  projectRoot: '.',
+  reportPath: null,
+  markdownPath: null,
+  check: false,
+  json: false,
+});
+
+function countLines(text) {
+  if (!text) return 0;
+  return String(text).split(/\r?\n/).length;
+}
+
+export function parseArgs(argv = process.argv.slice(2)) {
+  const parsed = { ...DEFAULTS };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token === '--project-root') {
+      parsed.projectRoot = argv[i + 1] || parsed.projectRoot;
+      i += 1;
+      continue;
+    }
+    if (token === '--report-path') {
+      parsed.reportPath = argv[i + 1] || parsed.reportPath;
+      i += 1;
+      continue;
+    }
+    if (token === '--markdown-path') {
+      parsed.markdownPath = argv[i + 1] || parsed.markdownPath;
+      i += 1;
+      continue;
+    }
+    if (token === '--check') {
+      parsed.check = true;
+      continue;
+    }
+    if (token === '--json') {
+      parsed.json = true;
+      continue;
+    }
+    throw new Error(`Unknown option: ${token}`);
+  }
+
+  return parsed;
+}
+
+export function evaluateRuntimeHotspotAudit({
+  projectRoot = '.',
+  hotspotBudgets = DEFAULT_HOTSPOT_BUDGETS,
+  requiredFiles = DEFAULT_REQUIRED_FILES,
+} = {}) {
+  const auditedProjectRoot = resolve(projectRoot);
+
+  const hotspotFiles = hotspotBudgets.map((budget) => {
+    const absolutePath = resolve(auditedProjectRoot, budget.path);
+    const exists = existsSync(absolutePath);
+    const lineCount = exists ? countLines(readFileSync(absolutePath, 'utf8')) : null;
+    const withinBudget = exists && Number.isFinite(lineCount) && lineCount <= budget.maxLines;
+    return {
+      ...budget,
+      absolutePath,
+      exists,
+      lineCount,
+      deltaLines: Number.isFinite(lineCount) ? budget.maxLines - lineCount : null,
+      status: withinBudget ? 'pass' : 'fail',
+      reasonCode: !exists
+        ? 'hotspot_file_missing'
+        : (lineCount > budget.maxLines ? 'hotspot_budget_exceeded' : 'hotspot_within_budget'),
+    };
+  });
+
+  const seamFiles = requiredFiles.map((entry) => {
+    const absolutePath = resolve(auditedProjectRoot, entry.path);
+    const exists = existsSync(absolutePath);
+    return {
+      ...entry,
+      absolutePath,
+      exists,
+      status: exists ? 'pass' : 'fail',
+      reasonCode: exists ? 'required_owner_file_present' : 'required_owner_file_missing',
+    };
+  });
+
+  const failures = [];
+  for (const hotspot of hotspotFiles) {
+    if (hotspot.status === 'fail') {
+      failures.push({
+        code: hotspot.reasonCode,
+        path: hotspot.path,
+        owner: hotspot.owner,
+        maxLines: hotspot.maxLines,
+        lineCount: hotspot.lineCount,
+      });
+    }
+  }
+  for (const seamFile of seamFiles) {
+    if (seamFile.status === 'fail') {
+      failures.push({
+        code: seamFile.reasonCode,
+        path: seamFile.path,
+        role: seamFile.role,
+      });
+    }
+  }
+
+  const pass = failures.length === 0;
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    reportType: 'runtime-hotspot-audit',
+    auditedProjectRoot,
+    pass,
+    fail: !pass,
+    status: pass ? 'pass' : 'fail',
+    reasonCode: pass ? 'runtime_hotspot_audit_pass' : (failures[0]?.code || 'runtime_hotspot_audit_failed'),
+    summary: {
+      budgetedHotspots: hotspotFiles.length,
+      hotspotsWithinBudget: hotspotFiles.filter((entry) => entry.status === 'pass').length,
+      requiredFiles: seamFiles.length,
+      requiredFilesPresent: seamFiles.filter((entry) => entry.status === 'pass').length,
+      failedHotspotPaths: hotspotFiles.filter((entry) => entry.status === 'fail').map((entry) => entry.path),
+      missingRequiredFiles: seamFiles.filter((entry) => entry.status === 'fail').map((entry) => entry.path),
+    },
+    hotspotFiles,
+    requiredFiles: seamFiles,
+    failures,
+  };
+}
+
+export function buildRuntimeHotspotAuditMarkdown(report) {
+  const lines = [
+    '# AuraJS Runtime Hotspot Audit',
+    '',
+    `- Schema: ${report.schemaVersion}`,
+    `- Status: ${report.status}`,
+    `- Reason code: ${report.reasonCode}`,
+    `- Audited project root: ${report.auditedProjectRoot}`,
+    '',
+    '## Hotspot budgets',
+  ];
+
+  for (const hotspot of report.hotspotFiles) {
+    lines.push(
+      `- ${hotspot.path}: ${hotspot.status.toUpperCase()} (${hotspot.lineCount ?? 'missing'} / ${hotspot.maxLines} lines, owner=${hotspot.owner})`,
+      `  - reason: ${hotspot.reason}`,
+    );
+  }
+
+  lines.push('', '## Required owner and seam files');
+  for (const seamFile of report.requiredFiles) {
+    lines.push(`- ${seamFile.path}: ${seamFile.status.toUpperCase()} (${seamFile.role})`);
+  }
+
+  lines.push('', `## Failures (${report.failures.length})`);
+  if (report.failures.length === 0) {
+    lines.push('- None');
+  } else {
+    for (const failure of report.failures) {
+      lines.push(`- ${failure.code}: ${failure.path}`);
+    }
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+export function runRuntimeHotspotAudit(options = {}) {
+  const report = evaluateRuntimeHotspotAudit(options);
+
+  if (options.reportPath) {
+    const reportPath = resolve(options.projectRoot || '.', options.reportPath);
+    mkdirSync(dirname(reportPath), { recursive: true });
+    writeFileSync(reportPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+  }
+
+  if (options.markdownPath) {
+    const markdownPath = resolve(options.projectRoot || '.', options.markdownPath);
+    mkdirSync(dirname(markdownPath), { recursive: true });
+    writeFileSync(markdownPath, buildRuntimeHotspotAuditMarkdown(report), 'utf8');
+  }
+
+  return report;
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+  const report = runRuntimeHotspotAudit(args);
+
+  if (!args.reportPath && !args.markdownPath) {
+    const output = args.json ? `${JSON.stringify(report, null, 2)}\n` : buildRuntimeHotspotAuditMarkdown(report);
+    process.stdout.write(output);
+  }
+
+  if (args.check && !report.pass) {
+    process.exitCode = 1;
+  }
+}
+
+const entryPath = process.argv[1] ? resolve(process.argv[1]) : null;
+const currentPath = fileURLToPath(import.meta.url);
+if (entryPath && currentPath === entryPath) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}