@sansavision/aurora 0.1.0-alpha.20260212.4

package/src/node-shims.d.ts

@@ -0,0 +1,26 @@
+declare module "node:fs" {
+  export interface Dirent {
+    name: string;
+    isDirectory(): boolean;
+    isFile(): boolean;
+  }
+
+  export interface Stats {
+    isDirectory(): boolean;
+  }
+
+  export function readFileSync(path: string, encoding: "utf8"): string;
+  export function writeFileSync(path: string, data: string, encoding: "utf8"): void;
+  export function existsSync(path: string): boolean;
+  export function mkdirSync(path: string, options?: { recursive?: boolean }): void;
+  export function readdirSync(path: string): string[];
+  export function readdirSync(path: string, options: { withFileTypes: true }): Dirent[];
+  export function statSync(path: string): Stats;
+}
+
+declare module "node:path" {
+  export function dirname(path: string): string;
+  export function join(...paths: string[]): string;
+  export function resolve(...paths: string[]): string;
+  export function relative(from: string, to: string): string;
+}

package/src/process.d.ts

@@ -0,0 +1,11 @@
+declare const process: {
+  argv: string[];
+  cwd: () => string;
+  stdout: {
+    write: (chunk: string) => void;
+  };
+  stderr: {
+    write: (chunk: string) => void;
+  };
+  exitCode: number;
+};

package/src/query-profiler.ts

@@ -0,0 +1,520 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { type CommandContext, type CommandResult } from "./registry";
+
+type QueryProfilerFormat = "text" | "json";
+type QueryProfilerStatus = "ok" | "warn";
+type QueryCacheStatus = "hit" | "miss" | "stale";
+
+interface QueryProfilerOptions {
+  inputPath: string;
+  format: QueryProfilerFormat;
+  maxP95Ms: number;
+  minCacheHitRatio: number;
+  limit: number;
+}
+
+interface QuerySample {
+  queryName: string;
+  keyHash: string;
+  durationMs: number;
+  cacheStatus: QueryCacheStatus;
+}
+
+interface QueryProfilerIssue {
+  code: "QUERY_P95_EXCEEDED" | "CACHE_HIT_RATIO_BELOW_MIN";
+  message: string;
+}
+
+interface SlowQueryEntry {
+  queryName: string;
+  samples: number;
+  avgMs: number;
+  p95Ms: number;
+  cacheHitRatio: number;
+}
+
+interface QueryProfilerReport {
+  mode: "query-profiler";
+  projectRoot: string;
+  inputPath: string;
+  status: QueryProfilerStatus;
+  samples: number;
+  avgMs: number;
+  p95Ms: number;
+  cacheHits: number;
+  cacheMisses: number;
+  cacheStale: number;
+  cacheHitRatio: number;
+  thresholds: {
+    maxP95Ms: number;
+    minCacheHitRatio: number;
+  };
+  issues: QueryProfilerIssue[];
+  slowQueries: SlowQueryEntry[];
+}
+
+const DEFAULT_MAX_P95_MS = 80;
+const DEFAULT_MIN_CACHE_HIT_RATIO = 0.6;
+const DEFAULT_LIMIT = 10;
+const MAX_LIMIT = 200;
+
+function parseNonNegativeNumber(raw: string | undefined, flag: string): number | CommandResult {
+  if (!raw) {
+    return {
+      exitCode: 2,
+      stderr: `aurora profile-query: ${flag} requires a numeric value`,
+    };
+  }
+
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    return {
+      exitCode: 2,
+      stderr: `aurora profile-query: ${flag} must be a non-negative number`,
+    };
+  }
+
+  return parsed;
+}
+
+function parseRatio(raw: string | undefined, flag: string): number | CommandResult {
+  const parsed = parseNonNegativeNumber(raw, flag);
+  if (typeof parsed !== "number") {
+    return parsed;
+  }
+
+  if (parsed > 1) {
+    return {
+      exitCode: 2,
+      stderr: `aurora profile-query: ${flag} must be between 0 and 1`,
+    };
+  }
+
+  return parsed;
+}
+
+function parseLimit(raw: string | undefined): number | CommandResult {
+  if (!raw) {
+    return {
+      exitCode: 2,
+      stderr: "aurora profile-query: --limit requires an integer value",
+    };
+  }
+
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed < 1 || parsed > MAX_LIMIT) {
+    return {
+      exitCode: 2,
+      stderr: `aurora profile-query: --limit must be an integer between 1 and ${MAX_LIMIT}`,
+    };
+  }
+
+  return parsed;
+}
+
+function parseQueryProfilerOptions(args: ReadonlyArray<string>): QueryProfilerOptions | CommandResult {
+  const options: QueryProfilerOptions = {
+    inputPath: "",
+    format: "text",
+    maxP95Ms: DEFAULT_MAX_P95_MS,
+    minCacheHitRatio: DEFAULT_MIN_CACHE_HIT_RATIO,
+    limit: DEFAULT_LIMIT,
+  };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--input") {
+      const value = args[i + 1];
+      if (!value) {
+        return {
+          exitCode: 2,
+          stderr: "aurora profile-query: --input requires a path value",
+        };
+      }
+
+      options.inputPath = value;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--format") {
+      const value = args[i + 1];
+      if (!value) {
+        return {
+          exitCode: 2,
+          stderr: "aurora profile-query: --format requires 'text' or 'json'",
+        };
+      }
+
+      if (value !== "text" && value !== "json") {
+        return {
+          exitCode: 2,
+          stderr: `aurora profile-query: invalid format '${value}'. Expected 'text' or 'json'`,
+        };
+      }
+
+      options.format = value;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--max-p95-ms") {
+      const parsed = parseNonNegativeNumber(args[i + 1], "--max-p95-ms");
+      if (typeof parsed !== "number") {
+        return parsed;
+      }
+
+      options.maxP95Ms = parsed;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--min-cache-hit-ratio") {
+      const parsed = parseRatio(args[i + 1], "--min-cache-hit-ratio");
+      if (typeof parsed !== "number") {
+        return parsed;
+      }
+
+      options.minCacheHitRatio = parsed;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--limit") {
+      const parsed = parseLimit(args[i + 1]);
+      if (typeof parsed !== "number") {
+        return parsed;
+      }
+
+      options.limit = parsed;
+      i += 1;
+      continue;
+    }
+
+    return {
+      exitCode: 2,
+      stderr: `aurora profile-query: unknown option '${arg}'`,
+    };
+  }
+
+  if (!options.inputPath) {
+    return {
+      exitCode: 2,
+      stderr: "aurora profile-query: --input is required",
+    };
+  }
+
+  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 isCommandResult(value: unknown): value is CommandResult {
+  const source = toRecord(value);
+  return Boolean(source && typeof source.exitCode === "number");
+}
+
+function getRequiredString(source: Record<string, unknown>, fields: ReadonlyArray<string>): string {
+  for (const field of fields) {
+    const value = source[field];
+    if (typeof value === "string" && value.trim().length > 0) {
+      return value.trim();
+    }
+  }
+
+  throw new Error(`missing required string field (${fields.join(" or ")})`);
+}
+
+function getRequiredNumber(source: Record<string, unknown>, fields: ReadonlyArray<string>): number {
+  for (const field of fields) {
+    const value = source[field];
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value;
+    }
+  }
+
+  throw new Error(`missing required numeric field (${fields.join(" or ")})`);
+}
+
+function normalizeCacheStatus(rawStatus: unknown, rawHitValue: unknown): QueryCacheStatus {
+  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 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 profile-query: unable to read input at ${inputPath}`,
+    };
+  }
+
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {
+      exitCode: 1,
+      stderr: `aurora profile-query: invalid json input at ${inputPath}`,
+    };
+  }
+}
+
+function assertSupportedSchemaVersion(payload: unknown): 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 query input; expected 1`);
+  }
+}
+
+function normalizeSamples(payload: unknown): unknown[] {
+  if (Array.isArray(payload)) {
+    return payload;
+  }
+
+  const source = toRecord(payload);
+  if (source && Array.isArray(source.samples)) {
+    return source.samples;
+  }
+
+  throw new Error("query profiler input must be an array or an object with samples[]");
+}
+
+function percentile(values: ReadonlyArray<number>, ratio: number): number {
+  if (values.length === 0) {
+    return 0;
+  }
+
+  const sorted = [...values].sort((left, right) => left - right);
+  const index = Math.ceil(sorted.length * ratio) - 1;
+  const bounded = Math.min(Math.max(index, 0), sorted.length - 1);
+  return sorted[bounded] ?? 0;
+}
+
+function average(values: ReadonlyArray<number>): number {
+  if (values.length === 0) {
+    return 0;
+  }
+
+  const sum = values.reduce((total, value) => total + value, 0);
+  return sum / values.length;
+}
+
+function buildQueryProfilerReport(
+  options: QueryProfilerOptions,
+  context: CommandContext,
+): QueryProfilerReport | CommandResult {
+  const payload = readInputJson(options.inputPath, context);
+  if (isCommandResult(payload)) {
+    return payload;
+  }
+
+  let normalizedSamples: QuerySample[] = [];
+  try {
+    assertSupportedSchemaVersion(payload);
+    const rawSamples = normalizeSamples(payload);
+    normalizedSamples = rawSamples.map((sample) => {
+      const source = toRecord(sample);
+      if (!source) {
+        throw new Error("query sample must be an object");
+      }
+
+      return {
+        queryName: getRequiredString(source, ["queryName", "name", "query"]),
+        keyHash: getRequiredString(source, ["keyHash", "key", "hash"]),
+        durationMs: getRequiredNumber(source, ["durationMs", "duration", "ms"]),
+        cacheStatus: normalizeCacheStatus(source.cacheStatus ?? source.cache ?? source.status, source.hit),
+      };
+    });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return {
+      exitCode: 1,
+      stderr: `aurora profile-query: ${reason}`,
+    };
+  }
+
+  const durations = normalizedSamples.map((sample) => sample.durationMs);
+  const p95Ms = percentile(durations, 0.95);
+  const avgMs = average(durations);
+  const cacheHits = normalizedSamples.filter((sample) => sample.cacheStatus === "hit").length;
+  const cacheMisses = normalizedSamples.filter((sample) => sample.cacheStatus === "miss").length;
+  const cacheStale = normalizedSamples.filter((sample) => sample.cacheStatus === "stale").length;
+  const cacheHitRatio = normalizedSamples.length === 0 ? 1 : cacheHits / normalizedSamples.length;
+
+  const perQuery = new Map<
+    string,
+    {
+      durations: number[];
+      hits: number;
+      samples: number;
+    }
+  >();
+
+  for (const sample of normalizedSamples) {
+    const current = perQuery.get(sample.queryName) ?? {
+      durations: [],
+      hits: 0,
+      samples: 0,
+    };
+    current.durations.push(sample.durationMs);
+    current.samples += 1;
+    if (sample.cacheStatus === "hit") {
+      current.hits += 1;
+    }
+    perQuery.set(sample.queryName, current);
+  }
+
+  const slowQueries: SlowQueryEntry[] = [...perQuery.entries()]
+    .map(([queryName, summary]) => ({
+      queryName,
+      samples: summary.samples,
+      avgMs: average(summary.durations),
+      p95Ms: percentile(summary.durations, 0.95),
+      cacheHitRatio: summary.samples === 0 ? 1 : summary.hits / summary.samples,
+    }))
+    .sort((left, right) => {
+      if (right.p95Ms !== left.p95Ms) {
+        return right.p95Ms - left.p95Ms;
+      }
+      if (right.avgMs !== left.avgMs) {
+        return right.avgMs - left.avgMs;
+      }
+      return left.queryName.localeCompare(right.queryName);
+    })
+    .slice(0, options.limit);
+
+  const issues: QueryProfilerIssue[] = [];
+  if (p95Ms > options.maxP95Ms) {
+    issues.push({
+      code: "QUERY_P95_EXCEEDED",
+      message: `p95 ${p95Ms.toFixed(2)}ms exceeds threshold ${options.maxP95Ms.toFixed(2)}ms`,
+    });
+  }
+
+  if (cacheHitRatio < options.minCacheHitRatio) {
+    issues.push({
+      code: "CACHE_HIT_RATIO_BELOW_MIN",
+      message:
+        `cache hit ratio ${cacheHitRatio.toFixed(4)} is below threshold ` +
+        `${options.minCacheHitRatio.toFixed(4)}`,
+    });
+  }
+
+  const status: QueryProfilerStatus = issues.length > 0 ? "warn" : "ok";
+
+  return {
+    mode: "query-profiler",
+    projectRoot: context.cwd,
+    inputPath: options.inputPath,
+    status,
+    samples: normalizedSamples.length,
+    avgMs,
+    p95Ms,
+    cacheHits,
+    cacheMisses,
+    cacheStale,
+    cacheHitRatio,
+    thresholds: {
+      maxP95Ms: options.maxP95Ms,
+      minCacheHitRatio: options.minCacheHitRatio,
+    },
+    issues,
+    slowQueries,
+  };
+}
+
+function renderQueryProfilerText(report: QueryProfilerReport): string {
+  const lines = [
+    "aurora query profiler report",
+    `project_root: ${report.projectRoot}`,
+    `input_path: ${report.inputPath}`,
+    `status: ${report.status}`,
+    `samples: ${report.samples}`,
+    `avg_ms: ${report.avgMs.toFixed(2)}`,
+    `p95_ms: ${report.p95Ms.toFixed(2)}`,
+    `cache_hit_ratio: ${report.cacheHitRatio.toFixed(4)}`,
+    `cache_hits: ${report.cacheHits}`,
+    `cache_misses: ${report.cacheMisses}`,
+    `cache_stale: ${report.cacheStale}`,
+    `max_p95_ms: ${report.thresholds.maxP95Ms.toFixed(2)}`,
+    `min_cache_hit_ratio: ${report.thresholds.minCacheHitRatio.toFixed(4)}`,
+  ];
+
+  if (report.issues.length > 0) {
+    lines.push("issues:");
+    for (const issue of report.issues) {
+      lines.push(`- [${issue.code}] ${issue.message}`);
+    }
+  }
+
+  if (report.slowQueries.length > 0) {
+    lines.push("slow_queries:");
+    for (const entry of report.slowQueries) {
+      lines.push(
+        `- ${entry.queryName} samples=${entry.samples} avg_ms=${entry.avgMs.toFixed(2)} ` +
+          `p95_ms=${entry.p95Ms.toFixed(2)} cache_hit_ratio=${entry.cacheHitRatio.toFixed(4)}`,
+      );
+    }
+  }
+
+  return lines.join("\n");
+}
+
+export function runQueryProfilerCommand(
+  args: ReadonlyArray<string>,
+  context: CommandContext,
+): CommandResult {
+  const options = parseQueryProfilerOptions(args);
+  if ("exitCode" in options) {
+    return options;
+  }
+
+  const report = buildQueryProfilerReport(options, context);
+  if ("exitCode" in report) {
+    return report;
+  }
+
+  const exitCode = report.status === "warn" ? 1 : 0;
+  if (options.format === "json") {
+    return {
+      exitCode,
+      stdout: JSON.stringify(report, null, 2),
+    };
+  }
+
+  return {
+    exitCode,
+    stdout: renderQueryProfilerText(report),
+  };
+}