@sansavision/aurora 0.1.0-alpha.20260212.4

package/src/analyze.ts

@@ -0,0 +1,669 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import {
+  evaluatePerformanceGuardrails,
+  type GuardrailIssue,
+  type PerformanceGuardrailsInput,
+} from "../../perf/guardrails/src";
+import { type CommandContext, type CommandResult } from "./registry";
+
+type AnalyzeMode = "bundle" | "cache" | "realtime" | "query" | "guardrails";
+
+interface AnalyzeOptions {
+  format: "text" | "json";
+  mode: AnalyzeMode;
+  outDir: string;
+  inputPath?: string;
+  maxDropRatio?: number;
+  maxLagP95Ms?: number;
+}
+
+interface BundleAnalyzeReport {
+  mode: "bundle";
+  projectRoot: string;
+  outDir: string;
+  manifestPath: string;
+  manifestFound: boolean;
+  routeCount: number;
+  chunkCount: number;
+  note: string;
+}
+
+interface CacheAnalyzeReport {
+  mode: "cache";
+  projectRoot: string;
+  inputPath: string;
+  entries: number;
+}
+
+interface RealtimeAnalyzeReport {
+  mode: "realtime";
+  projectRoot: string;
+  inputPath: string;
+  received: number;
+  delivered: number;
+  dropped: number;
+  lagP95Ms: number;
+}
+
+interface QueryAnalyzeReport {
+  mode: "query";
+  projectRoot: string;
+  inputPath: string;
+  samples: number;
+}
+
+interface GuardrailsAnalyzeReport {
+  mode: "guardrails";
+  projectRoot: string;
+  inputPath: string;
+  status: "ok" | "warn" | "error";
+  issues: readonly GuardrailIssue[];
+  summary: {
+    total: number;
+    warnings: number;
+    errors: number;
+  };
+}
+
+type AnalyzeReport =
+  | BundleAnalyzeReport
+  | CacheAnalyzeReport
+  | RealtimeAnalyzeReport
+  | QueryAnalyzeReport
+  | GuardrailsAnalyzeReport;
+
+function parseAnalyzeMode(value: string): AnalyzeMode | undefined {
+  if (
+    value === "bundle" ||
+    value === "cache" ||
+    value === "realtime" ||
+    value === "query" ||
+    value === "guardrails"
+  ) {
+    return value;
+  }
+
+  return undefined;
+}
+
+function parseNonNegativeNumber(raw: string | undefined, flag: string): number | CommandResult {
+  if (!raw) {
+    return {
+      exitCode: 2,
+      stderr: `aurora analyze: ${flag} requires a numeric value`,
+    };
+  }
+
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    return {
+      exitCode: 2,
+      stderr: `aurora analyze: ${flag} must be a non-negative number`,
+    };
+  }
+
+  return parsed;
+}
+
+function parseAnalyzeOptions(args: ReadonlyArray<string>): AnalyzeOptions | CommandResult {
+  const options: AnalyzeOptions = {
+    format: "text",
+    mode: "bundle",
+    outDir: ".aurora/analyze/compiler",
+  };
+
+  let explicitOutDir = false;
+  let explicitInput = false;
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--format") {
+      const value = args[i + 1];
+      if (!value) {
+        return {
+          exitCode: 2,
+          stderr: "aurora analyze: --format requires 'text' or 'json'",
+        };
+      }
+
+      if (value !== "text" && value !== "json") {
+        return {
+          exitCode: 2,
+          stderr: `aurora analyze: invalid format '${value}'. Expected 'text' or 'json'`,
+        };
+      }
+
+      options.format = value;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--mode") {
+      const value = args[i + 1];
+      if (!value) {
+        return {
+          exitCode: 2,
+          stderr:
+            "aurora analyze: --mode requires 'bundle', 'cache', 'realtime', 'query', or 'guardrails'",
+        };
+      }
+
+      const parsedMode = parseAnalyzeMode(value);
+      if (!parsedMode) {
+        return {
+          exitCode: 2,
+          stderr:
+            `aurora analyze: invalid mode '${value}'. Expected 'bundle', ` +
+            "'cache', 'realtime', 'query', or 'guardrails'",
+        };
+      }
+
+      options.mode = parsedMode;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--out-dir") {
+      const value = args[i + 1];
+      if (!value) {
+        return {
+          exitCode: 2,
+          stderr: "aurora analyze: --out-dir requires a path value",
+        };
+      }
+
+      explicitOutDir = true;
+      options.outDir = value;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--input") {
+      const value = args[i + 1];
+      if (!value) {
+        return {
+          exitCode: 2,
+          stderr: "aurora analyze: --input requires a path value",
+        };
+      }
+
+      explicitInput = true;
+      options.inputPath = value;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--max-drop-ratio") {
+      const parsed = parseNonNegativeNumber(args[i + 1], "--max-drop-ratio");
+      if (typeof parsed !== "number") {
+        return parsed;
+      }
+
+      options.maxDropRatio = parsed;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--max-lag-p95-ms") {
+      const parsed = parseNonNegativeNumber(args[i + 1], "--max-lag-p95-ms");
+      if (typeof parsed !== "number") {
+        return parsed;
+      }
+
+      options.maxLagP95Ms = parsed;
+      i += 1;
+      continue;
+    }
+
+    return {
+      exitCode: 2,
+      stderr: `aurora analyze: unknown option '${arg}'`,
+    };
+  }
+
+  if (options.mode === "bundle" && explicitInput) {
+    return {
+      exitCode: 2,
+      stderr:
+        "aurora analyze: --input is only valid when --mode is cache, realtime, query, or guardrails",
+    };
+  }
+
+  if (options.mode !== "bundle" && explicitOutDir) {
+    return {
+      exitCode: 2,
+      stderr: "aurora analyze: --out-dir is only valid when --mode is bundle",
+    };
+  }
+
+  if (options.mode !== "bundle" && !options.inputPath) {
+    return {
+      exitCode: 2,
+      stderr:
+        "aurora analyze: --input is required when --mode is cache, realtime, query, or guardrails",
+    };
+  }
+
+  if (
+    options.mode !== "realtime" &&
+    (options.maxDropRatio !== undefined || options.maxLagP95Ms !== undefined)
+  ) {
+    return {
+      exitCode: 2,
+      stderr:
+        "aurora analyze: --max-drop-ratio and --max-lag-p95-ms are only valid when --mode is realtime",
+    };
+  }
+
+  return options;
+}
+
+function toRecord(value: unknown): Record<string, unknown> | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return undefined;
+  }
+
+  return value as Record<string, unknown>;
+}
+
+function getRequiredString(source: Record<string, unknown>, fieldNames: ReadonlyArray<string>): string {
+  for (const fieldName of fieldNames) {
+    const value = source[fieldName];
+    if (typeof value === "string" && value.trim().length > 0) {
+      return value.trim();
+    }
+  }
+
+  throw new Error(`missing required string field (${fieldNames.join(" or ")})`);
+}
+
+function getRequiredNumber(source: Record<string, unknown>, fieldNames: ReadonlyArray<string>): number {
+  for (const fieldName of fieldNames) {
+    const value = source[fieldName];
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value;
+    }
+  }
+
+  throw new Error(`missing required numeric field (${fieldNames.join(" or ")})`);
+}
+
+function assertSupportedSchemaVersion(payload: unknown, mode: Exclude<AnalyzeMode, "bundle">): void {
+  const source = toRecord(payload);
+  if (!source) {
+    return;
+  }
+
+  const rawSchemaVersion = source.schemaVersion;
+  if (rawSchemaVersion === undefined) {
+    return;
+  }
+
+  if (rawSchemaVersion !== 1) {
+    throw new Error(`unsupported schemaVersion ${String(rawSchemaVersion)} for ${mode} input; expected 1`);
+  }
+}
+
+function readInputJson(inputPath: string, context: CommandContext): unknown | CommandResult {
+  const absolutePath = resolve(context.cwd, inputPath);
+  let raw = "";
+
+  try {
+    raw = readFileSync(absolutePath, "utf8");
+  } catch {
+    return {
+      exitCode: 1,
+      stderr: `aurora analyze: unable to read input at ${inputPath}`,
+    };
+  }
+
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {
+      exitCode: 1,
+      stderr: `aurora analyze: invalid json input at ${inputPath}`,
+    };
+  }
+}
+
+function normalizeCacheEntries(payload: unknown): unknown[] {
+  if (Array.isArray(payload)) {
+    return payload;
+  }
+
+  const record = toRecord(payload);
+  if (record && Array.isArray(record.entries)) {
+    return record.entries;
+  }
+
+  throw new Error("cache input must be an array or an object with entries[]");
+}
+
+function normalizeCacheStatus(rawStatus: unknown, rawHitValue: unknown): "hit" | "miss" | "stale" {
+  if (typeof rawStatus === "string") {
+    if (rawStatus === "hit" || rawStatus === "miss" || rawStatus === "stale") {
+      return rawStatus;
+    }
+  }
+
+  if (typeof rawHitValue === "boolean") {
+    return rawHitValue ? "hit" : "miss";
+  }
+
+  throw new Error("missing required cache status field (cacheStatus/cache/status or hit)");
+}
+
+function normalizeQuerySamples(payload: unknown): unknown[] {
+  if (Array.isArray(payload)) {
+    return payload;
+  }
+
+  const record = toRecord(payload);
+  if (record && Array.isArray(record.samples)) {
+    return record.samples;
+  }
+
+  throw new Error("query input must be an array or an object with samples[]");
+}
+
+function countManifestRoutes(source: Record<string, unknown>): number {
+  if (Array.isArray(source.routes)) {
+    return source.routes.length;
+  }
+
+  const routeGraph = toRecord(source.routeGraph);
+  if (routeGraph && Array.isArray(routeGraph.routes)) {
+    return routeGraph.routes.length;
+  }
+
+  return 0;
+}
+
+function countManifestChunks(source: Record<string, unknown>): number {
+  if (Array.isArray(source.chunks)) {
+    return source.chunks.length;
+  }
+
+  const bundle = toRecord(source.bundle);
+  if (bundle && Array.isArray(bundle.chunks)) {
+    return bundle.chunks.length;
+  }
+
+  return 0;
+}
+
+function runBundleAnalyze(options: AnalyzeOptions, context: CommandContext): BundleAnalyzeReport {
+  const manifestPath = resolve(context.cwd, options.outDir, "manifest.json");
+  let manifestFound = false;
+  let routeCount = 0;
+  let chunkCount = 0;
+  let note = "manifest not found; reporting configured out-dir only";
+
+  try {
+    const rawManifest = readFileSync(manifestPath, "utf8");
+    const parsed = JSON.parse(rawManifest);
+    const source = toRecord(parsed);
+    if (!source) {
+      throw new Error("manifest.json must contain a JSON object");
+    }
+
+    manifestFound = true;
+    routeCount = countManifestRoutes(source);
+    chunkCount = countManifestChunks(source);
+    note = "manifest loaded";
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const missingFile = message.includes("ENOENT");
+    if (!missingFile) {
+      throw new Error(`invalid bundle manifest at ${manifestPath}\n${message}`);
+    }
+  }
+
+  return {
+    mode: "bundle",
+    projectRoot: context.cwd,
+    outDir: options.outDir,
+    manifestPath,
+    manifestFound,
+    routeCount,
+    chunkCount,
+    note,
+  };
+}
+
+function runCacheAnalyze(options: AnalyzeOptions, payload: unknown, context: CommandContext): CacheAnalyzeReport {
+  assertSupportedSchemaVersion(payload, "cache");
+  const entries = normalizeCacheEntries(payload);
+
+  for (const entry of entries) {
+    const source = toRecord(entry);
+    if (!source) {
+      throw new Error("cache source entry must be an object");
+    }
+
+    getRequiredString(source, ["keyHash", "hash"]);
+  }
+
+  return {
+    mode: "cache",
+    projectRoot: context.cwd,
+    inputPath: options.inputPath ?? "",
+    entries: entries.length,
+  };
+}
+
+function runRealtimeAnalyze(
+  options: AnalyzeOptions,
+  payload: unknown,
+  context: CommandContext,
+): RealtimeAnalyzeReport {
+  assertSupportedSchemaVersion(payload, "realtime");
+  const source = toRecord(payload);
+  if (!source) {
+    throw new Error("realtime input must be an object");
+  }
+
+  const received = getRequiredNumber(source, ["received", "rx", "totalReceived"]);
+  const delivered = getRequiredNumber(source, ["delivered", "tx", "totalDelivered"]);
+  const dropped = getRequiredNumber(source, ["dropped", "totalDropped"]);
+  const lagP95Ms = getRequiredNumber(source, ["lagP95Ms", "p95"]);
+
+  return {
+    mode: "realtime",
+    projectRoot: context.cwd,
+    inputPath: options.inputPath ?? "",
+    received,
+    delivered,
+    dropped,
+    lagP95Ms,
+  };
+}
+
+function runQueryAnalyze(options: AnalyzeOptions, payload: unknown, context: CommandContext): QueryAnalyzeReport {
+  assertSupportedSchemaVersion(payload, "query");
+  const samples = normalizeQuerySamples(payload);
+
+  for (const sample of samples) {
+    const source = toRecord(sample);
+    if (!source) {
+      throw new Error("query sample must be an object");
+    }
+
+    getRequiredString(source, ["queryName", "name", "query"]);
+    getRequiredString(source, ["keyHash", "key", "hash"]);
+    getRequiredNumber(source, ["durationMs", "duration", "ms"]);
+    normalizeCacheStatus(source.cacheStatus ?? source.cache ?? source.status, source.hit);
+  }
+
+  return {
+    mode: "query",
+    projectRoot: context.cwd,
+    inputPath: options.inputPath ?? "",
+    samples: samples.length,
+  };
+}
+
+function runGuardrailsAnalyze(
+  options: AnalyzeOptions,
+  payload: unknown,
+  context: CommandContext,
+): GuardrailsAnalyzeReport {
+  assertSupportedSchemaVersion(payload, "guardrails");
+  const source = toRecord(payload);
+  if (!source) {
+    throw new Error("guardrails input must be an object");
+  }
+
+  const guardrails = evaluatePerformanceGuardrails(source as PerformanceGuardrailsInput);
+
+  return {
+    mode: "guardrails",
+    projectRoot: context.cwd,
+    inputPath: options.inputPath ?? "",
+    status: guardrails.status,
+    issues: guardrails.issues,
+    summary: guardrails.summary,
+  };
+}
+
+function renderAnalyzeTextReport(report: AnalyzeReport): string {
+  if (report.mode === "bundle") {
+    return [
+      "aurora analyze bundle report",
+      `project_root: ${report.projectRoot}`,
+      `out_dir: ${report.outDir}`,
+      `manifest_path: ${report.manifestPath}`,
+      `manifest_found: ${report.manifestFound}`,
+      `routes: ${report.routeCount}`,
+      `chunks: ${report.chunkCount}`,
+      `note: ${report.note}`,
+    ].join("\n");
+  }
+
+  if (report.mode === "cache") {
+    return [
+      "aurora analyze cache report",
+      `project_root: ${report.projectRoot}`,
+      `input_path: ${report.inputPath}`,
+      `entries: ${report.entries}`,
+    ].join("\n");
+  }
+
+  if (report.mode === "realtime") {
+    return [
+      "aurora analyze realtime report",
+      `project_root: ${report.projectRoot}`,
+      `input_path: ${report.inputPath}`,
+      `received: ${report.received}`,
+      `delivered: ${report.delivered}`,
+      `dropped: ${report.dropped}`,
+      `lag_p95_ms: ${report.lagP95Ms}`,
+    ].join("\n");
+  }
+
+  if (report.mode === "guardrails") {
+    const lines = [
+      "aurora analyze guardrails report",
+      `project_root: ${report.projectRoot}`,
+      `input_path: ${report.inputPath}`,
+      `status: ${report.status}`,
+      `issues: ${report.summary.total}`,
+      `warnings: ${report.summary.warnings}`,
+      `errors: ${report.summary.errors}`,
+    ];
+
+    if (report.issues.length > 0) {
+      lines.push("findings:");
+      for (const issue of report.issues) {
+        const location = issue.location?.file
+          ? `${issue.location.file}${issue.location.line ? `:${issue.location.line}` : ""}`
+          : "unknown";
+        lines.push(`- [${issue.severity}] ${issue.code} ${location} ${issue.message}`);
+        lines.push(`  fix: ${issue.remediation}`);
+      }
+    }
+
+    return lines.join("\n");
+  }
+
+  return [
+    "aurora analyze query report",
+    `project_root: ${report.projectRoot}`,
+    `input_path: ${report.inputPath}`,
+    `samples: ${report.samples}`,
+  ].join("\n");
+}
+
+function formatAnalyzeModeError(options: AnalyzeOptions, error: unknown): CommandResult {
+  const message = error instanceof Error ? error.message : String(error);
+  return {
+    exitCode: 1,
+    stderr: `aurora analyze: ${options.mode} mode failed\n${message}`,
+  };
+}
+
+function isCommandResult(value: unknown): value is CommandResult {
+  const record = toRecord(value);
+  if (!record) {
+    return false;
+  }
+
+  return (
+    typeof record.exitCode === "number" &&
+    (typeof record.stdout === "string" || typeof record.stderr === "string")
+  );
+}
+
+export function runAnalyzeCommand(args: ReadonlyArray<string>, context: CommandContext): CommandResult {
+  const options = parseAnalyzeOptions(args);
+  if ("exitCode" in options) {
+    return options;
+  }
+
+  let report: AnalyzeReport | CommandResult;
+  if (options.mode === "bundle") {
+    try {
+      report = runBundleAnalyze(options, context);
+    } catch (error) {
+      return formatAnalyzeModeError(options, error);
+    }
+  } else {
+    const payload = readInputJson(options.inputPath ?? "", context);
+    if (isCommandResult(payload)) {
+      return payload;
+    }
+
+    try {
+      if (options.mode === "cache") {
+        report = runCacheAnalyze(options, payload, context);
+      } else if (options.mode === "realtime") {
+        report = runRealtimeAnalyze(options, payload, context);
+      } else if (options.mode === "guardrails") {
+        report = runGuardrailsAnalyze(options, payload, context);
+      } else {
+        report = runQueryAnalyze(options, payload, context);
+      }
+    } catch (error) {
+      return formatAnalyzeModeError(options, error);
+    }
+  }
+
+  if (isCommandResult(report)) {
+    return report;
+  }
+
+  if (options.format === "json") {
+    return {
+      exitCode: 0,
+      stdout: JSON.stringify(report, null, 2),
+    };
+  }
+
+  return {
+    exitCode: 0,
+    stdout: renderAnalyzeTextReport(report),
+  };
+}

package/src/bin/aurora.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env bun
+
+import { runAuroraCli } from "../run";
+
+const result = runAuroraCli(process.argv.slice(2));
+
+if (result.stdout) {
+  process.stdout.write(`${result.stdout}\n`);
+}
+
+if (result.stderr) {
+  process.stderr.write(`${result.stderr}\n`);
+}
+
+process.exitCode = result.exitCode;