@tryinget/runtime-trace-insights 0.1.0

package/src/runtime_trace_bundle/runtime_trace_bundle_flow.mjs

@@ -0,0 +1,168 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { runRuntimeRecordFlow } from "../runtime_record/index.mjs";
+import {
+  RUNTIME_TRACE_BUNDLE_NON_AUTHORITY_NOTE,
+  RUNTIME_TRACE_BUNDLE_PROFILES,
+  RUNTIME_TRACE_BUNDLE_SCHEMA_VERSION,
+  RUNTIME_TRACE_REOBSERVATION_NON_AUTHORITY_NOTE,
+  RUNTIME_TRACE_REOBSERVATION_SCHEMA_VERSION,
+  buildRuntimeTraceBundle,
+  normalizeDiagnosticList,
+} from "./runtime_trace_bundle_builder.mjs";
+
+export {
+  RUNTIME_TRACE_BUNDLE_NON_AUTHORITY_NOTE,
+  RUNTIME_TRACE_BUNDLE_SCHEMA_VERSION,
+  RUNTIME_TRACE_REOBSERVATION_NON_AUTHORITY_NOTE,
+  RUNTIME_TRACE_REOBSERVATION_SCHEMA_VERSION,
+};
+export const DEFAULT_RUNTIME_TRACE_BUNDLE_PATH = "out/runtime-trace-insights/runtime-trace-bundle.json";
+
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function asNonEmptyString(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : null;
+}
+
+function toRelativePath(basePath, targetPath) {
+  const relative = path.relative(basePath, targetPath);
+  return (relative.length > 0 ? relative : ".").replaceAll("\\", "/");
+}
+
+function createDiagnostic({ code, level = "warning", message, details }) {
+  const diagnostic = { code, level, source: "runtimeTraceBundle", message };
+  if (details !== undefined) {
+    diagnostic.details = details;
+  }
+  return diagnostic;
+}
+
+function hasErrorDiagnostic(entries) {
+  return asArray(entries)
+    .some((entry) => String(entry?.level ?? "").toLowerCase() === "error");
+}
+
+function createFailureResult({ cwd, generatedAt, diagnostics, code, message }) {
+  return {
+    ok: false,
+    cwd,
+    generatedAt,
+    bundle: null,
+    bundlePath: null,
+    recordResult: null,
+    diagnostics: [
+      createDiagnostic({ code, level: "error", message }),
+      ...normalizeDiagnosticList(diagnostics, "runtimeTraceBundle"),
+    ],
+  };
+}
+
+export function runRuntimeTraceBundleFlow(options = {}) {
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const generatedAt = asNonEmptyString(options.traceTimestamp) ?? new Date().toISOString();
+  const diagnostics = [];
+
+  // The record flow's own dep-diet record artifacts (bundle + dep-viz handoff) are not part of this
+  // command; the bundle is built below with this command's profile and written to --out.
+  const recordResult = runRuntimeRecordFlow({
+    ...options,
+    cwd,
+    traceTimestamp: generatedAt,
+    emitRecordHandoffArtifacts: false,
+  });
+
+  diagnostics.push(...normalizeDiagnosticList(recordResult?.diagnostics, "runtimeRecord"));
+
+  if (!recordResult || recordResult.ok !== true) {
+    return createFailureResult({
+      cwd,
+      generatedAt,
+      diagnostics,
+      code: "runtimeTraceBundle.recordFailed",
+      message: "Runtime trace bundle creation aborted because the observed command record failed.",
+    });
+  }
+
+  const projectPathInput = asNonEmptyString(recordResult.command?.projectPath) ?? asNonEmptyString(options.projectPath);
+  const projectPathAbsolute = path.resolve(cwd, projectPathInput ?? ".");
+  const bundleAbsolutePath = path.resolve(cwd, asNonEmptyString(options.bundlePath) ?? DEFAULT_RUNTIME_TRACE_BUNDLE_PATH);
+  const runDirectory = asNonEmptyString(recordResult.artifacts?.runDirectory);
+
+  const bundle = buildRuntimeTraceBundle({
+    profile: RUNTIME_TRACE_BUNDLE_PROFILES.bundleCommand,
+    diagnostics,
+    options,
+    generatedAt,
+    runId: recordResult.runId,
+    bundleId: options.bundleId,
+    projectPathInput,
+    projectPathAbsolute,
+    observedCommand: recordResult.command?.observedCommand ?? [],
+    commandLine: asNonEmptyString(recordResult.trace?.commandLine)
+      ?? asArray(recordResult.command?.observedCommand).join(" "),
+    exitCode: recordResult.trace?.exitCode ?? null,
+    durationMs: recordResult.trace?.durationMs ?? null,
+    packageAutodiscovery: recordResult.trace?.packageAutodiscovery,
+    artifactPaths: {
+      runDirectoryAbsolute: runDirectory ? path.resolve(cwd, runDirectory) : null,
+      runtimeTraceManifestAbsolutePath: asNonEmptyString(recordResult.artifacts?.runtimeTraceManifest?.absolutePath),
+      bundleAbsolutePath,
+    },
+    references: [
+      { kind: "runtime-trace", path: recordResult.artifacts?.runtimeTrace?.path },
+      { kind: "setup-guidance", path: recordResult.artifacts?.setupGuidance?.path },
+      { kind: "package-autodiscovery-log", path: recordResult.artifacts?.packageAutodiscovery?.logPath },
+    ],
+  });
+
+  try {
+    fs.mkdirSync(path.dirname(bundleAbsolutePath), { recursive: true });
+    fs.writeFileSync(bundleAbsolutePath, `${JSON.stringify(bundle, null, 2)}\n`, "utf8");
+  } catch (error) {
+    return createFailureResult({
+      cwd,
+      generatedAt,
+      diagnostics: [
+        ...diagnostics,
+        createDiagnostic({
+          code: "runtimeTraceBundle.writeFailed",
+          level: "error",
+          message: "Failed to write runtime trace bundle artifact.",
+          details: {
+            bundleAbsolutePath,
+            error: error instanceof Error ? error.message : String(error),
+          },
+        }),
+      ],
+      code: "runtimeTraceBundle.writeFailed",
+      message: "Runtime trace bundle creation failed while writing the bundle artifact.",
+    });
+  }
+
+  const normalizedDiagnostics = normalizeDiagnosticList(diagnostics, "runtimeTraceBundle");
+
+  return {
+    ok: !hasErrorDiagnostic(normalizedDiagnostics),
+    cwd,
+    generatedAt,
+    bundle,
+    bundlePath: toRelativePath(cwd, bundleAbsolutePath),
+    bundlePathAbsolute: bundleAbsolutePath,
+    recordResult,
+    summary: {
+      observedPackageCount: bundle.observedPackages.length,
+      commandExitCode: recordResult.trace?.exitCode ?? null,
+      commandDurationMs: recordResult.trace?.durationMs ?? null,
+    },
+    diagnostics: normalizedDiagnostics,
+  };
+}