@sansavision/aurora 0.1.0-alpha.20260212.4

package/src/explain.ts

@@ -0,0 +1,855 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import {
+  createInlineHintsFromExplainReport,
+  type AuroraInlineHint,
+} from "./lsp-inline-hints";
+import { type CommandContext, type CommandResult } from "./registry";
+
+type ExplainFormat = "text" | "json";
+export type ExplainSource = "explicit" | "inferred" | "inherited" | "default" | "none";
+type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | readonly JsonValue[] | { readonly [key: string]: JsonValue };
+
+export interface ExplainField<TValue> {
+  value: TValue;
+  source: ExplainSource;
+  note?: string;
+}
+
+interface ExplainCacheValue {
+  staleTime?: string;
+  gcTime?: string;
+}
+
+export interface ExplainQueryEntry {
+  kind: "query";
+  name: string;
+  key: ExplainField<readonly JsonValue[] | string>;
+  tags: ExplainField<readonly string[]>;
+  cache?: ExplainField<ExplainCacheValue | string>;
+  realtime?: ExplainField<string>;
+  auth?: ExplainField<string>;
+  mask?: ExplainField<string>;
+  estimatedPayloadBytes?: number;
+  suggestions: readonly string[];
+}
+
+export interface ExplainActionEntry {
+  kind: "action";
+  name: string;
+  invalidates: ExplainField<readonly string[]>;
+  publishes?: ExplainField<readonly string[]>;
+  auth?: ExplainField<string>;
+  rateLimit?: ExplainField<string>;
+  input?: ExplainField<string>;
+  errors?: ExplainField<readonly string[]>;
+  suggestions: readonly string[];
+}
+
+export interface ExplainModuleReportV1 {
+  schemaVersion: 1;
+  module: string;
+  queries: readonly ExplainQueryEntry[];
+  actions: readonly ExplainActionEntry[];
+  warnings: readonly string[];
+}
+
+interface ExplainCommandReport extends ExplainModuleReportV1 {
+  mode: "explain";
+  projectRoot: string;
+  requestedModule: string;
+  inputPath: string;
+  inlineHints: readonly AuroraInlineHint[];
+}
+
+interface ExplainOptions {
+  modulePath: string;
+  inputPath: string;
+  format: ExplainFormat;
+}
+
+const VALID_SOURCES: readonly ExplainSource[] = [
+  "explicit",
+  "inferred",
+  "inherited",
+  "default",
+  "none",
+];
+
+function parseExplainOptions(args: ReadonlyArray<string>): ExplainOptions | CommandResult {
+  let modulePath: string | undefined;
+  let inputPath: string | undefined;
+  let format: ExplainFormat = "text";
+
+  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 explain: --input requires a path value",
+        };
+      }
+
+      inputPath = value;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--format") {
+      const value = args[i + 1];
+      if (!value) {
+        return {
+          exitCode: 2,
+          stderr: "aurora explain: --format requires 'text' or 'json'",
+        };
+      }
+
+      if (value !== "text" && value !== "json") {
+        return {
+          exitCode: 2,
+          stderr: `aurora explain: invalid format '${value}'. Expected 'text' or 'json'`,
+        };
+      }
+
+      format = value;
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--")) {
+      return {
+        exitCode: 2,
+        stderr: `aurora explain: unknown option '${arg}'`,
+      };
+    }
+
+    if (!modulePath) {
+      modulePath = arg;
+      continue;
+    }
+
+    return {
+      exitCode: 2,
+      stderr: `aurora explain: unexpected positional argument '${arg}'`,
+    };
+  }
+
+  if (!modulePath || modulePath.trim().length === 0) {
+    return {
+      exitCode: 2,
+      stderr: "aurora explain: module path is required (usage: aurora explain <module-path>)",
+    };
+  }
+
+  const normalizedModulePath = normalizeModulePath(modulePath);
+  return {
+    modulePath: normalizedModulePath,
+    inputPath: inputPath ?? defaultExplainSnapshotPath(normalizedModulePath),
+    format,
+  };
+}
+
+function defaultExplainSnapshotPath(modulePath: string): string {
+  const normalized = normalizeModulePath(modulePath)
+    .replace(/^\.{1,2}\//, "")
+    .replace(/[^a-zA-Z0-9._-]+/g, "__");
+
+  return `.aurora/explain/${normalized}.explain.v1.json`;
+}
+
+function normalizeModulePath(modulePath: string): string {
+  return modulePath.replace(/\\+/g, "/").trim();
+}
+
+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 explain: unable to read input at ${inputPath}\n` +
+        "Run the compiler explain export first, or provide --input <path>.",
+    };
+  }
+
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {
+      exitCode: 1,
+      stderr: `aurora explain: invalid json input at ${inputPath}`,
+    };
+  }
+}
+
+function readModuleSourceIfExists(modulePath: string, context: CommandContext): string | undefined {
+  const absolutePath = resolve(context.cwd, modulePath);
+  try {
+    return readFileSync(absolutePath, "utf8");
+  } catch {
+    return undefined;
+  }
+}
+
+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 parseExplainReport(
+  payload: unknown,
+  requestedModule: string,
+): ExplainModuleReportV1 {
+  const root = toRecord(payload);
+  if (!root) {
+    throw new Error("explain input must be an object");
+  }
+
+  const schemaVersion = root.schemaVersion;
+  if (schemaVersion !== 1) {
+    throw new Error(`unsupported schemaVersion ${String(schemaVersion)}; expected 1`);
+  }
+
+  const moduleFromPayload = getOptionalString(root, ["module", "modulePath"]);
+  const modulePath = moduleFromPayload ?? requestedModule;
+  const queries = parseQueryEntries(root.queries ?? []);
+  const actions = parseActionEntries(root.actions ?? []);
+  const warnings = dedupePreservingOrder([
+    ...parseStringArray(root.warnings ?? [], "warnings", { allowEmpty: true }),
+  ]);
+
+  if (normalizeModulePath(modulePath) !== normalizeModulePath(requestedModule)) {
+    warnings.push(
+      `snapshot module '${modulePath}' does not match requested module '${requestedModule}'`,
+    );
+  }
+
+  return {
+    schemaVersion: 1,
+    module: modulePath,
+    queries,
+    actions,
+    warnings,
+  };
+}
+
+function parseQueryEntries(raw: unknown): readonly ExplainQueryEntry[] {
+  if (!Array.isArray(raw)) {
+    throw new Error("queries must be an array");
+  }
+
+  return raw.map((entry, index) => parseQueryEntry(entry, index));
+}
+
+function parseActionEntries(raw: unknown): readonly ExplainActionEntry[] {
+  if (!Array.isArray(raw)) {
+    throw new Error("actions must be an array");
+  }
+
+  return raw.map((entry, index) => parseActionEntry(entry, index));
+}
+
+function parseQueryEntry(raw: unknown, index: number): ExplainQueryEntry {
+  const source = toRecord(raw);
+  if (!source) {
+    throw new Error(`queries[${index}] must be an object`);
+  }
+
+  const label = `queries[${index}]`;
+
+  const name = getRequiredString(source, ["name", "queryName"], `${label}.name`);
+  const key = parseExplainField(
+    source.key,
+    `${label}.key`,
+    (value, valueLabel) => parseKey(value, valueLabel),
+    "inferred",
+  );
+  const tags = parseExplainField(
+    source.tags,
+    `${label}.tags`,
+    (value, valueLabel) => parseStringArray(value, valueLabel, { allowEmpty: false }),
+    "inferred",
+  );
+
+  const cache =
+    source.cache === undefined
+      ? undefined
+      : parseExplainField(
+          source.cache,
+          `${label}.cache`,
+          (value, valueLabel) => parseCacheValue(value, valueLabel),
+          "default",
+        );
+
+  const realtime =
+    source.realtime === undefined
+      ? undefined
+      : parseExplainField(
+          source.realtime,
+          `${label}.realtime`,
+          (value, valueLabel) => parseNonEmptyString(value, valueLabel),
+          "inferred",
+        );
+
+  const auth =
+    source.auth === undefined
+      ? undefined
+      : parseExplainField(
+          source.auth,
+          `${label}.auth`,
+          (value, valueLabel) => parseNonEmptyString(value, valueLabel),
+          "inherited",
+        );
+
+  const mask =
+    source.mask === undefined
+      ? undefined
+      : parseExplainField(
+          source.mask,
+          `${label}.mask`,
+          (value, valueLabel) => parseNonEmptyString(value, valueLabel),
+          "none",
+        );
+
+  const estimatedPayloadBytes =
+    source.estimatedPayloadBytes === undefined
+      ? undefined
+      : parseNonNegativeNumber(source.estimatedPayloadBytes, `${label}.estimatedPayloadBytes`);
+
+  const suggestions = parseStringArray(source.suggestions ?? [], `${label}.suggestions`, {
+    allowEmpty: true,
+  });
+
+  return {
+    kind: "query",
+    name,
+    key,
+    tags,
+    cache,
+    realtime,
+    auth,
+    mask,
+    estimatedPayloadBytes,
+    suggestions,
+  };
+}
+
+function parseActionEntry(raw: unknown, index: number): ExplainActionEntry {
+  const source = toRecord(raw);
+  if (!source) {
+    throw new Error(`actions[${index}] must be an object`);
+  }
+
+  const label = `actions[${index}]`;
+
+  const name = getRequiredString(source, ["name", "actionName"], `${label}.name`);
+
+  const invalidates = parseExplainField(
+    source.invalidates,
+    `${label}.invalidates`,
+    (value, valueLabel) => parseStringArray(value, valueLabel, { allowEmpty: false }),
+    "inferred",
+  );
+
+  const publishes =
+    source.publishes === undefined
+      ? undefined
+      : parseExplainField(
+          source.publishes,
+          `${label}.publishes`,
+          (value, valueLabel) => parseStringArray(value, valueLabel, { allowEmpty: true }),
+          "explicit",
+        );
+
+  const auth =
+    source.auth === undefined
+      ? undefined
+      : parseExplainField(
+          source.auth,
+          `${label}.auth`,
+          (value, valueLabel) => parseNonEmptyString(value, valueLabel),
+          "explicit",
+        );
+
+  const rateLimit =
+    source.rateLimit === undefined
+      ? undefined
+      : parseExplainField(
+          source.rateLimit,
+          `${label}.rateLimit`,
+          (value, valueLabel) => parseNonEmptyString(value, valueLabel),
+          "none",
+        );
+
+  const input =
+    source.input === undefined
+      ? undefined
+      : parseExplainField(
+          source.input,
+          `${label}.input`,
+          (value, valueLabel) => parseNonEmptyString(value, valueLabel),
+          "explicit",
+        );
+
+  const errors =
+    source.errors === undefined
+      ? undefined
+      : parseExplainField(
+          source.errors,
+          `${label}.errors`,
+          (value, valueLabel) => parseStringArray(value, valueLabel, { allowEmpty: true }),
+          "none",
+        );
+
+  const suggestions = parseStringArray(source.suggestions ?? [], `${label}.suggestions`, {
+    allowEmpty: true,
+  });
+
+  return {
+    kind: "action",
+    name,
+    invalidates,
+    publishes,
+    auth,
+    rateLimit,
+    input,
+    errors,
+    suggestions,
+  };
+}
+
+function parseExplainField<TValue>(
+  raw: unknown,
+  label: string,
+  parseValue: (rawValue: unknown, valueLabel: string) => TValue,
+  defaultSource: ExplainSource,
+): ExplainField<TValue> {
+  const sourceRecord = toRecord(raw);
+  if (sourceRecord && Object.prototype.hasOwnProperty.call(sourceRecord, "value")) {
+    const value = parseValue(sourceRecord.value, `${label}.value`);
+    const source = parseSource(sourceRecord.source, defaultSource, `${label}.source`);
+    const note = getOptionalString(sourceRecord, ["note", "reason"]);
+
+    return note
+      ? {
+          value,
+          source,
+          note,
+        }
+      : {
+          value,
+          source,
+        };
+  }
+
+  return {
+    value: parseValue(raw, label),
+    source: defaultSource,
+  };
+}
+
+function parseSource(raw: unknown, fallback: ExplainSource, label: string): ExplainSource {
+  if (raw === undefined) {
+    return fallback;
+  }
+
+  if (typeof raw !== "string") {
+    throw new Error(`${label} must be one of: ${VALID_SOURCES.join(", ")}`);
+  }
+
+  if (!VALID_SOURCES.includes(raw as ExplainSource)) {
+    throw new Error(`${label} must be one of: ${VALID_SOURCES.join(", ")}`);
+  }
+
+  return raw as ExplainSource;
+}
+
+function parseKey(raw: unknown, label: string): readonly JsonValue[] | string {
+  if (typeof raw === "string" && raw.trim().length > 0) {
+    return raw.trim();
+  }
+
+  if (!Array.isArray(raw)) {
+    throw new Error(`${label} must be a string or an array`);
+  }
+
+  for (let index = 0; index < raw.length; index += 1) {
+    if (!isJsonValue(raw[index])) {
+      throw new Error(`${label}[${index}] must be JSON-serializable`);
+    }
+  }
+
+  return raw as readonly JsonValue[];
+}
+
+function parseCacheValue(raw: unknown, label: string): ExplainCacheValue | string {
+  if (typeof raw === "string") {
+    const normalized = raw.trim();
+    if (normalized.length > 0) {
+      return normalized;
+    }
+  }
+
+  const source = toRecord(raw);
+  if (!source) {
+    throw new Error(`${label} must be a string or an object`);
+  }
+
+  const staleTime = getOptionalString(source, ["staleTime", "staleTimeMs"]);
+  const gcTime = getOptionalString(source, ["gcTime", "gcTimeMs"]);
+
+  if (!staleTime && !gcTime) {
+    throw new Error(`${label} must define staleTime or gcTime when using object form`);
+  }
+
+  return {
+    staleTime,
+    gcTime,
+  };
+}
+
+function parseStringArray(
+  raw: unknown,
+  label: string,
+  options: { allowEmpty: boolean },
+): readonly string[] {
+  const values =
+    typeof raw === "string"
+      ? [raw]
+      : Array.isArray(raw)
+        ? raw
+        : (() => {
+            throw new Error(`${label} must be a string or an array of strings`);
+          })();
+
+  const normalized: string[] = [];
+  for (let index = 0; index < values.length; index += 1) {
+    const value = values[index];
+    if (typeof value !== "string") {
+      throw new Error(`${label}[${index}] must be a string`);
+    }
+
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+      continue;
+    }
+
+    normalized.push(trimmed);
+  }
+
+  const deduped = dedupePreservingOrder(normalized);
+  if (!options.allowEmpty && deduped.length === 0) {
+    throw new Error(`${label} must include at least one non-empty string`);
+  }
+
+  return deduped;
+}
+
+function dedupePreservingOrder(values: readonly string[]): string[] {
+  const seen = new Set<string>();
+  const output: string[] = [];
+
+  for (const value of values) {
+    if (seen.has(value)) {
+      continue;
+    }
+
+    seen.add(value);
+    output.push(value);
+  }
+
+  return output;
+}
+
+function parseNonNegativeNumber(raw: unknown, label: string): number {
+  if (typeof raw !== "number" || !Number.isFinite(raw) || raw < 0) {
+    throw new Error(`${label} must be a non-negative number`);
+  }
+
+  return raw;
+}
+
+function parseNonEmptyString(raw: unknown, label: string): string {
+  if (typeof raw !== "string") {
+    throw new Error(`${label} must be a string`);
+  }
+
+  const normalized = raw.trim();
+  if (normalized.length === 0) {
+    throw new Error(`${label} must be a non-empty string`);
+  }
+
+  return normalized;
+}
+
+function getRequiredString(
+  source: Record<string, unknown>,
+  fields: ReadonlyArray<string>,
+  label: string,
+): string {
+  const value = getOptionalString(source, fields);
+  if (value) {
+    return value;
+  }
+
+  throw new Error(`missing required string field (${label})`);
+}
+
+function getOptionalString(
+  source: Record<string, unknown>,
+  fields: ReadonlyArray<string>,
+): string | undefined {
+  for (const field of fields) {
+    const value = source[field];
+    if (typeof value === "string") {
+      const normalized = value.trim();
+      if (normalized.length > 0) {
+        return normalized;
+      }
+    }
+  }
+
+  return undefined;
+}
+
+function isJsonValue(value: unknown): value is JsonValue {
+  if (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "boolean"
+  ) {
+    return true;
+  }
+
+  if (typeof value === "number") {
+    return Number.isFinite(value);
+  }
+
+  if (Array.isArray(value)) {
+    return value.every((entry) => isJsonValue(entry));
+  }
+
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+
+  return Object.values(value).every((entry) => isJsonValue(entry));
+}
+
+function renderExplainText(report: ExplainCommandReport): string {
+  const lines: string[] = [
+    "aurora explain report",
+    `module: ${report.module}`,
+    `requested_module: ${report.requestedModule}`,
+    `input: ${report.inputPath}`,
+    `schema_version: ${report.schemaVersion}`,
+  ];
+
+  if (report.queries.length === 0 && report.actions.length === 0) {
+    lines.push("", "no explain entries found");
+  }
+
+  for (const query of report.queries) {
+    lines.push("", `query: ${query.name}`);
+    lines.push(formatFieldLine("key", formatKey(query.key.value), query.key));
+    lines.push(formatFieldLine("tags", formatStringList(query.tags.value), query.tags));
+
+    if (query.cache) {
+      lines.push(formatFieldLine("cache", formatCacheValue(query.cache.value), query.cache));
+    }
+
+    if (query.realtime) {
+      lines.push(formatFieldLine("realtime", query.realtime.value, query.realtime));
+    }
+
+    if (query.auth) {
+      lines.push(formatFieldLine("auth", query.auth.value, query.auth));
+    }
+
+    if (query.mask) {
+      lines.push(formatFieldLine("mask", query.mask.value, query.mask));
+    }
+
+    if (query.estimatedPayloadBytes !== undefined) {
+      lines.push(`  estimated_payload: ${formatBytes(query.estimatedPayloadBytes)}`);
+    }
+
+    for (const suggestion of query.suggestions) {
+      lines.push(`  suggestion: ${suggestion}`);
+    }
+  }
+
+  for (const action of report.actions) {
+    lines.push("", `action: ${action.name}`);
+    lines.push(
+      formatFieldLine("invalidates", formatStringList(action.invalidates.value), action.invalidates),
+    );
+
+    if (action.publishes) {
+      lines.push(formatFieldLine("publishes", formatStringList(action.publishes.value), action.publishes));
+    }
+
+    if (action.auth) {
+      lines.push(formatFieldLine("auth", action.auth.value, action.auth));
+    }
+
+    if (action.rateLimit) {
+      lines.push(formatFieldLine("rate_limit", action.rateLimit.value, action.rateLimit));
+    }
+
+    if (action.input) {
+      lines.push(formatFieldLine("input", action.input.value, action.input));
+    }
+
+    if (action.errors) {
+      lines.push(formatFieldLine("errors", formatStringList(action.errors.value), action.errors));
+    }
+
+    for (const suggestion of action.suggestions) {
+      lines.push(`  suggestion: ${suggestion}`);
+    }
+  }
+
+  if (report.warnings.length > 0) {
+    lines.push("", "warnings:");
+    for (const warning of report.warnings) {
+      lines.push(`- ${warning}`);
+    }
+  }
+
+  if (report.inlineHints.length > 0) {
+    lines.push("", `inline_hints: ${report.inlineHints.length}`);
+    for (const hint of report.inlineHints) {
+      lines.push(
+        `- [${hint.kind}] ${hint.symbol} @${hint.position.line + 1}:${hint.position.character + 1} ${hint.label}`,
+      );
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function formatFieldLine(
+  label: string,
+  formattedValue: string,
+  field: ExplainField<unknown>,
+): string {
+  const note = field.note ? `; ${field.note}` : "";
+  return `  ${label}: ${formattedValue} (${field.source}${note})`;
+}
+
+function formatKey(value: readonly JsonValue[] | string): string {
+  if (typeof value === "string") {
+    return value;
+  }
+
+  return JSON.stringify(value);
+}
+
+function formatStringList(values: readonly string[]): string {
+  if (values.length === 0) {
+    return "[]";
+  }
+
+  return `[${values.join(", ")}]`;
+}
+
+function formatCacheValue(value: ExplainCacheValue | string): string {
+  if (typeof value === "string") {
+    return value;
+  }
+
+  const parts: string[] = [];
+  if (value.staleTime) {
+    parts.push(`staleTime=${value.staleTime}`);
+  }
+
+  if (value.gcTime) {
+    parts.push(`gcTime=${value.gcTime}`);
+  }
+
+  return parts.join(", ");
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) {
+    return `${Math.trunc(bytes)}B`;
+  }
+
+  if (bytes < 1024 * 1024) {
+    return `~${(bytes / 1024).toFixed(1)}KB`;
+  }
+
+  return `~${(bytes / (1024 * 1024)).toFixed(2)}MB`;
+}
+
+export function runExplainCommand(
+  args: ReadonlyArray<string>,
+  context: CommandContext,
+): CommandResult {
+  const options = parseExplainOptions(args);
+  if (isCommandResult(options)) {
+    return options;
+  }
+
+  const payload = readInputJson(options.inputPath, context);
+  if (isCommandResult(payload)) {
+    return payload;
+  }
+
+  let parsed: ExplainModuleReportV1;
+  try {
+    parsed = parseExplainReport(payload, options.modulePath);
+  } catch (error) {
+    return {
+      exitCode: 1,
+      stderr:
+        `aurora explain: failed to parse explain report at ${options.inputPath}: ` +
+        (error instanceof Error ? error.message : "unknown error"),
+    };
+  }
+
+  const moduleSource = readModuleSourceIfExists(options.modulePath, context);
+  const inlineHints =
+    moduleSource !== undefined
+      ? createInlineHintsFromExplainReport(moduleSource, parsed)
+      : [];
+
+  const report: ExplainCommandReport = {
+    mode: "explain",
+    projectRoot: context.cwd,
+    requestedModule: options.modulePath,
+    inputPath: options.inputPath,
+    inlineHints,
+    ...parsed,
+  };
+
+  if (options.format === "json") {
+    return {
+      exitCode: 0,
+      stdout: JSON.stringify(report, null, 2),
+    };
+  }
+
+  return {
+    exitCode: 0,
+    stdout: renderExplainText(report),
+  };
+}