@sansavision/aurora 0.1.0-alpha.20260212.4

package/src/inspect-cache.ts

@@ -0,0 +1,464 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { type CommandContext, type CommandResult } from "./registry";
+
+type InspectorFormat = "text" | "json";
+
+interface InspectorOptions {
+  inputPath: string;
+  format: InspectorFormat;
+  limit: number;
+  tagFilter?: string;
+}
+
+interface InspectableEntry {
+  key: string;
+  tags: string[];
+  sizeBytes: number;
+  stale: boolean;
+  expiresAt?: number;
+}
+
+interface TagCount {
+  tag: string;
+  entries: number;
+}
+
+interface CacheInspectorLargestEntry {
+  key: string;
+  tags: string[];
+  sizeBytes: number;
+  stale: boolean;
+  expiresAt?: number;
+}
+
+interface CacheInspectorReport {
+  mode: "cache-inspector";
+  projectRoot: string;
+  inputPath: string;
+  entries: number;
+  filteredEntries: number;
+  staleEntries: number;
+  totalSizeBytes: number;
+  uniqueTags: number;
+  topTags: TagCount[];
+  largestEntries: CacheInspectorLargestEntry[];
+}
+
+const MAX_LIMIT = 500;
+const DEFAULT_LIMIT = 20;
+
+function parsePositiveLimit(raw: string | undefined): number | CommandResult {
+  if (!raw) {
+    return {
+      exitCode: 2,
+      stderr: "aurora inspect-cache: --limit requires an integer value",
+    };
+  }
+
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed < 1 || parsed > MAX_LIMIT) {
+    return {
+      exitCode: 2,
+      stderr: `aurora inspect-cache: --limit must be an integer between 1 and ${MAX_LIMIT}`,
+    };
+  }
+
+  return parsed;
+}
+
+function parseInspectorOptions(args: ReadonlyArray<string>): InspectorOptions | CommandResult {
+  const options: InspectorOptions = {
+    inputPath: "",
+    format: "text",
+    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 inspect-cache: --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 inspect-cache: --format requires 'text' or 'json'",
+        };
+      }
+
+      if (value !== "text" && value !== "json") {
+        return {
+          exitCode: 2,
+          stderr: `aurora inspect-cache: invalid format '${value}'. Expected 'text' or 'json'`,
+        };
+      }
+
+      options.format = value;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--tag") {
+      const value = args[i + 1];
+      if (!value || value.trim().length === 0) {
+        return {
+          exitCode: 2,
+          stderr: "aurora inspect-cache: --tag requires a non-empty tag value",
+        };
+      }
+
+      options.tagFilter = value.trim();
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--limit") {
+      const parsed = parsePositiveLimit(args[i + 1]);
+      if (typeof parsed !== "number") {
+        return parsed;
+      }
+
+      options.limit = parsed;
+      i += 1;
+      continue;
+    }
+
+    return {
+      exitCode: 2,
+      stderr: `aurora inspect-cache: unknown option '${arg}'`,
+    };
+  }
+
+  if (!options.inputPath) {
+    return {
+      exitCode: 2,
+      stderr: "aurora inspect-cache: --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 getOptionalNumber(
+  source: Record<string, unknown>,
+  fields: ReadonlyArray<string>,
+): number | undefined {
+  for (const field of fields) {
+    const value = source[field];
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value;
+    }
+  }
+
+  return undefined;
+}
+
+function getOptionalBoolean(
+  source: Record<string, unknown>,
+  fields: ReadonlyArray<string>,
+): boolean | undefined {
+  for (const field of fields) {
+    const value = source[field];
+    if (typeof value === "boolean") {
+      return value;
+    }
+  }
+
+  return undefined;
+}
+
+function normalizeTags(raw: unknown): string[] {
+  const source =
+    typeof raw === "string"
+      ? [raw]
+      : Array.isArray(raw)
+        ? raw.filter((item): item is string => typeof item === "string")
+        : [];
+
+  const unique = new Set(
+    source
+      .map((tag) => tag.trim())
+      .filter((tag) => tag.length > 0),
+  );
+
+  return [...unique].sort();
+}
+
+function getRequiredKey(source: Record<string, unknown>, entryIndex: number): string {
+  const fields = ["key", "hash", "cacheKey"];
+  for (const field of fields) {
+    const value = source[field];
+    if (typeof value === "string" && value.trim().length > 0) {
+      return value.trim();
+    }
+  }
+
+  throw new Error(`entry ${entryIndex}: missing key field (key/hash/cacheKey)`);
+}
+
+function getEntrySizeBytes(source: Record<string, unknown>): number {
+  const rawSize = source.sizeBytes;
+  if (typeof rawSize === "number" && Number.isFinite(rawSize) && rawSize >= 0) {
+    return Math.trunc(rawSize);
+  }
+
+  try {
+    const serialized = JSON.stringify(source.value);
+    if (typeof serialized === "string") {
+      return serialized.length;
+    }
+  } catch {
+    // Fall through to default.
+  }
+
+  return 0;
+}
+
+function readJsonPayload(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 inspect-cache: unable to read input at ${inputPath}`,
+    };
+  }
+
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {
+      exitCode: 1,
+      stderr: `aurora inspect-cache: invalid json input at ${inputPath}`,
+    };
+  }
+}
+
+function assertSupportedInputVersion(payload: unknown): void {
+  const source = toRecord(payload);
+  if (!source) {
+    return;
+  }
+
+  const version = source.version;
+  if (version !== undefined && version !== 1) {
+    throw new Error(`unsupported cache snapshot version ${String(version)}; expected 1`);
+  }
+
+  const schemaVersion = source.schemaVersion;
+  if (schemaVersion !== undefined && schemaVersion !== 1) {
+    throw new Error(`unsupported schemaVersion ${String(schemaVersion)}; expected 1`);
+  }
+}
+
+function normalizePayloadEntries(payload: unknown): unknown[] {
+  if (Array.isArray(payload)) {
+    return payload;
+  }
+
+  const source = toRecord(payload);
+  if (source && Array.isArray(source.entries)) {
+    return source.entries;
+  }
+
+  throw new Error("cache inspector input must be an array or an object with entries[]");
+}
+
+function normalizeEntry(raw: unknown, entryIndex: number, now: number): InspectableEntry {
+  const source = toRecord(raw);
+  if (!source) {
+    throw new Error(`entry ${entryIndex}: expected an object`);
+  }
+
+  const key = getRequiredKey(source, entryIndex);
+  const tags = normalizeTags(source.tags ?? source.labels ?? source.tag);
+  const sizeBytes = getEntrySizeBytes(source);
+  const expiresAt = getOptionalNumber(source, ["expiresAt", "expires_at"]);
+  const staleExplicit = getOptionalBoolean(source, ["stale", "isStale"]);
+  const stale = staleExplicit ?? (expiresAt !== undefined && expiresAt <= now);
+
+  return {
+    key,
+    tags,
+    sizeBytes,
+    stale,
+    expiresAt,
+  };
+}
+
+function compareLargestEntries(left: InspectableEntry, right: InspectableEntry): number {
+  if (right.sizeBytes !== left.sizeBytes) {
+    return right.sizeBytes - left.sizeBytes;
+  }
+
+  return left.key.localeCompare(right.key);
+}
+
+function buildReport(
+  options: InspectorOptions,
+  context: CommandContext,
+): CacheInspectorReport | CommandResult {
+  const payload = readJsonPayload(options.inputPath, context);
+  if (isCommandResult(payload)) {
+    return payload;
+  }
+
+  let normalized: InspectableEntry[];
+  try {
+    assertSupportedInputVersion(payload);
+    const entries = normalizePayloadEntries(payload);
+    const now = Date.now();
+    normalized = entries.map((entry, index) => normalizeEntry(entry, index, now));
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return {
+      exitCode: 1,
+      stderr: `aurora inspect-cache: ${reason}`,
+    };
+  }
+
+  const tagFilter = options.tagFilter;
+  const filtered =
+    tagFilter !== undefined
+      ? normalized.filter((entry) => entry.tags.includes(tagFilter))
+      : normalized;
+
+  const tagCounts = new Map<string, number>();
+  for (const entry of filtered) {
+    for (const tag of entry.tags) {
+      tagCounts.set(tag, (tagCounts.get(tag) ?? 0) + 1);
+    }
+  }
+
+  const topTags: TagCount[] = [...tagCounts.entries()]
+    .map(([tag, entries]) => ({ tag, entries }))
+    .sort((left, right) => {
+      if (right.entries !== left.entries) {
+        return right.entries - left.entries;
+      }
+      return left.tag.localeCompare(right.tag);
+    })
+    .slice(0, 10);
+
+  const largestEntries = [...filtered]
+    .sort(compareLargestEntries)
+    .slice(0, options.limit)
+    .map((entry) => ({
+      key: entry.key,
+      tags: entry.tags,
+      sizeBytes: entry.sizeBytes,
+      stale: entry.stale,
+      expiresAt: entry.expiresAt,
+    }));
+
+  const totalSizeBytes = filtered.reduce((sum, entry) => sum + entry.sizeBytes, 0);
+  const staleEntries = filtered.filter((entry) => entry.stale).length;
+
+  return {
+    mode: "cache-inspector",
+    projectRoot: context.cwd,
+    inputPath: options.inputPath,
+    entries: normalized.length,
+    filteredEntries: filtered.length,
+    staleEntries,
+    totalSizeBytes,
+    uniqueTags: tagCounts.size,
+    topTags,
+    largestEntries,
+  };
+}
+
+function renderTextReport(report: CacheInspectorReport, options: InspectorOptions): string {
+  const lines = [
+    "aurora cache inspector report",
+    `project_root: ${report.projectRoot}`,
+    `input_path: ${report.inputPath}`,
+    `entries_total: ${report.entries}`,
+    `entries_filtered: ${report.filteredEntries}`,
+    `stale_entries: ${report.staleEntries}`,
+    `total_size_bytes: ${report.totalSizeBytes}`,
+    `unique_tags: ${report.uniqueTags}`,
+  ];
+
+  if (options.tagFilter) {
+    lines.push(`filter_tag: ${options.tagFilter}`);
+  }
+
+  if (report.topTags.length > 0) {
+    lines.push("top_tags:");
+    for (const tag of report.topTags) {
+      lines.push(`- ${tag.tag}: ${tag.entries}`);
+    }
+  }
+
+  if (report.largestEntries.length > 0) {
+    lines.push("largest_entries:");
+    for (const entry of report.largestEntries) {
+      const tags = entry.tags.length > 0 ? entry.tags.join(",") : "-";
+      const expiresAt =
+        entry.expiresAt !== undefined ? ` expires_at=${entry.expiresAt}` : "";
+      lines.push(
+        `- ${entry.key} size_bytes=${entry.sizeBytes} stale=${entry.stale} tags=${tags}${expiresAt}`,
+      );
+    }
+  }
+
+  return lines.join("\n");
+}
+
+export function runInspectCacheCommand(
+  args: ReadonlyArray<string>,
+  context: CommandContext,
+): CommandResult {
+  const options = parseInspectorOptions(args);
+  if ("exitCode" in options) {
+    return options;
+  }
+
+  const report = buildReport(options, context);
+  if ("exitCode" in report) {
+    return report;
+  }
+
+  if (options.format === "json") {
+    return {
+      exitCode: 0,
+      stdout: JSON.stringify(report, null, 2),
+    };
+  }
+
+  return {
+    exitCode: 0,
+    stdout: renderTextReport(report, options),
+  };
+}

package/src/lsp-inline-hints.ts

@@ -0,0 +1,254 @@
+import type {
+  ExplainModuleReportV1,
+  ExplainQueryEntry,
+  ExplainSource,
+  JsonValue,
+} from "./explain";
+
+export type AuroraInlineHintKind =
+  | "key"
+  | "tags"
+  | "invalidation"
+  | "auth"
+  | "runtime";
+
+export interface AuroraInlineHint {
+  kind: AuroraInlineHintKind;
+  symbol: string;
+  label: string;
+  source: ExplainSource;
+  position: {
+    line: number;
+    character: number;
+  };
+  paddingLeft: boolean;
+}
+
+export function createInlineHintsFromExplainReport(
+  sourceText: string,
+  report: Pick<ExplainModuleReportV1, "queries" | "actions">,
+): readonly AuroraInlineHint[] {
+  const lines = sourceText.split(/\r?\n/);
+  const hints: AuroraInlineHint[] = [];
+
+  for (const query of report.queries) {
+    const line = findSymbolLine(lines, query.name);
+    if (line === undefined) {
+      continue;
+    }
+
+    const character = lines[line]?.length ?? 0;
+    hints.push(buildQueryHint("key", query, line, character));
+    hints.push(buildQueryHint("tags", query, line, character));
+
+    if (query.auth) {
+      hints.push({
+        kind: "auth",
+        symbol: query.name,
+        label: `auth: ${query.auth.value}`,
+        source: query.auth.source,
+        position: { line, character },
+        paddingLeft: true,
+      });
+    }
+  }
+
+  for (const action of report.actions) {
+    const line = findSymbolLine(lines, action.name);
+    if (line === undefined) {
+      continue;
+    }
+
+    const character = lines[line]?.length ?? 0;
+    hints.push({
+      kind: "invalidation",
+      symbol: action.name,
+      label: `invalidates: ${formatStringList(action.invalidates.value)}`,
+      source: action.invalidates.source,
+      position: { line, character },
+      paddingLeft: true,
+    });
+
+    if (action.auth) {
+      hints.push({
+        kind: "auth",
+        symbol: action.name,
+        label: `auth: ${action.auth.value}`,
+        source: action.auth.source,
+        position: { line, character },
+        paddingLeft: true,
+      });
+    }
+  }
+
+  const runtimeExport = findMetadataExport(lines, "runtime");
+  if (runtimeExport) {
+    hints.push({
+      kind: "runtime",
+      symbol: "module",
+      label: `runtime: ${runtimeExport.value}`,
+      source: "explicit",
+      position: {
+        line: runtimeExport.line,
+        character: lines[runtimeExport.line]?.length ?? 0,
+      },
+      paddingLeft: true,
+    });
+  }
+
+  const authExport = findMetadataExport(lines, "auth");
+  if (authExport) {
+    hints.push({
+      kind: "auth",
+      symbol: "module",
+      label: `auth: ${authExport.value}`,
+      source: "explicit",
+      position: {
+        line: authExport.line,
+        character: lines[authExport.line]?.length ?? 0,
+      },
+      paddingLeft: true,
+    });
+  }
+
+  hints.sort((left, right) => {
+    const byLine = left.position.line - right.position.line;
+    if (byLine !== 0) {
+      return byLine;
+    }
+
+    const byCharacter = left.position.character - right.position.character;
+    if (byCharacter !== 0) {
+      return byCharacter;
+    }
+
+    const bySymbol = left.symbol.localeCompare(right.symbol);
+    if (bySymbol !== 0) {
+      return bySymbol;
+    }
+
+    const byKind = left.kind.localeCompare(right.kind);
+    if (byKind !== 0) {
+      return byKind;
+    }
+
+    return left.label.localeCompare(right.label);
+  });
+
+  return dedupeHints(hints);
+}
+
+function buildQueryHint(
+  kind: "key" | "tags",
+  query: ExplainQueryEntry,
+  line: number,
+  character: number,
+): AuroraInlineHint {
+  if (kind === "key") {
+    return {
+      kind,
+      symbol: query.name,
+      label: `key: ${formatKey(query.key.value)}`,
+      source: query.key.source,
+      position: { line, character },
+      paddingLeft: true,
+    };
+  }
+
+  return {
+    kind,
+    symbol: query.name,
+    label: `tags: ${formatStringList(query.tags.value)}`,
+    source: query.tags.source,
+    position: { line, character },
+    paddingLeft: true,
+  };
+}
+
+function formatKey(value: readonly JsonValue[] | string): string {
+  if (typeof value === "string") {
+    return value;
+  }
+
+  return JSON.stringify(value);
+}
+
+function formatStringList(values: readonly string[]): string {
+  return values.length === 0 ? "[]" : `[${values.join(", ")}]`;
+}
+
+function findSymbolLine(lines: readonly string[], symbol: string): number | undefined {
+  const escaped = escapeRegExp(symbol);
+  const exportConstPattern = new RegExp(`\\bexport\\s+const\\s+${escaped}\\b`);
+  const exportFunctionPattern = new RegExp(`\\bexport\\s+function\\s+${escaped}\\b`);
+
+  for (let lineIndex = 0; lineIndex < lines.length; lineIndex += 1) {
+    const line = lines[lineIndex] ?? "";
+    if (exportConstPattern.test(line) || exportFunctionPattern.test(line)) {
+      return lineIndex;
+    }
+  }
+
+  const symbolPattern = new RegExp(`\\b${escaped}\\b`);
+  for (let lineIndex = 0; lineIndex < lines.length; lineIndex += 1) {
+    const line = lines[lineIndex] ?? "";
+    if (symbolPattern.test(line)) {
+      return lineIndex;
+    }
+  }
+
+  return undefined;
+}
+
+function findMetadataExport(
+  lines: readonly string[],
+  exportName: "runtime" | "auth",
+): { line: number; value: string } | undefined {
+  const pattern = new RegExp(
+    `^\\s*export\\s+const\\s+${exportName}\\s*=\\s*[\"']([^\"']+)[\"']`,
+  );
+
+  for (let lineIndex = 0; lineIndex < lines.length; lineIndex += 1) {
+    const line = lines[lineIndex] ?? "";
+    const match = pattern.exec(line);
+    if (!match?.[1]) {
+      continue;
+    }
+
+    return {
+      line: lineIndex,
+      value: match[1],
+    };
+  }
+
+  return undefined;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function dedupeHints(hints: readonly AuroraInlineHint[]): readonly AuroraInlineHint[] {
+  const seen = new Set<string>();
+  const result: AuroraInlineHint[] = [];
+
+  for (const hint of hints) {
+    const key = [
+      hint.kind,
+      hint.symbol,
+      hint.label,
+      String(hint.source),
+      String(hint.position.line),
+      String(hint.position.character),
+    ].join("|");
+
+    if (seen.has(key)) {
+      continue;
+    }
+
+    seen.add(key);
+    result.push(hint);
+  }
+
+  return result;
+}