@sansavision/aurora 0.1.0-alpha.20260212.4

package/README.md

@@ -0,0 +1,4 @@
+# @sansavision/aurora
+
+Private alpha Aurora package.
+

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@sansavision/aurora",
+  "version": "0.1.0-alpha.20260212.4",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "aurora": "./src/bin/aurora.ts"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "bunx --bun tsc --noEmit",
+    "aurora": "bun run ./src/bin/aurora.ts"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  }
+}

package/src/ai-diagnostics.ts

@@ -0,0 +1,156 @@
+export type AiDiagnosticSeverity = "error" | "warning" | "info";
+
+export interface AiDiagnosticLocation {
+  file?: string;
+  line?: number;
+}
+
+export interface AiDiagnosticInput {
+  code: string;
+  severity: "error" | "warn" | "warning" | "info";
+  message: string;
+  remediation?: string;
+  category?: string;
+  file?: string;
+  line?: number;
+}
+
+export interface AiReadableDiagnostic {
+  code: string;
+  severity: AiDiagnosticSeverity;
+  whatWentWrong: string;
+  why: string;
+  howToFix: string;
+  docs: string;
+  category?: string;
+  location?: AiDiagnosticLocation;
+}
+
+interface DiagnosticTemplate {
+  why: string;
+  docs: string;
+}
+
+const DIAGNOSTIC_TEMPLATES: Record<string, DiagnosticTemplate> = {
+  BOUNDARY_CLIENT_IMPORTS_SERVER: {
+    why:
+      "Client bundles cannot safely execute server-only modules and may leak secrets or break hydration semantics.",
+    docs: "https://aurora.dev/docs/concepts/module-boundaries",
+  },
+  DEPRECATED_ROUTE_API: {
+    why:
+      "Manual route registration bypasses Aurora's file-convention inference and future metadata/type guarantees.",
+    docs: "https://aurora.dev/docs/routing/file-conventions",
+  },
+  MIGRATION_MANUAL_ROUTES_ARRAY: {
+    why:
+      "Manual route arrays are a migration risk and can drift from inferred runtime behavior.",
+    docs: "https://aurora.dev/docs/migrations/manual-routes",
+  },
+  SECURITY_DYNAMIC_CODE_EXECUTION: {
+    why:
+      "Dynamic code execution prevents static verification and can enable injection vulnerabilities.",
+    docs: "https://aurora.dev/docs/security/dynamic-code",
+  },
+  SECURITY_RAW_SQL_STRING: {
+    why:
+      "Raw SQL strings are difficult to audit and increase SQL injection risk when interpolation slips in.",
+    docs: "https://aurora.dev/docs/security/raw-sql",
+  },
+  PERF_UNBOUNDED_QUERY: {
+    why:
+      "Unbounded queries can cause high memory/latency spikes and unstable response times under growth.",
+    docs: "https://aurora.dev/docs/performance/query-bounds",
+  },
+  PERF_N_PLUS_ONE_LOOP_AWAIT: {
+    why:
+      "Serial awaits in loops create avoidable N+1 latency and lower throughput.",
+    docs: "https://aurora.dev/docs/performance/n-plus-one",
+  },
+  A11Y_IMAGE_MISSING_ALT: {
+    why:
+      "Images without alt text are not announced correctly by assistive technology.",
+    docs: "https://aurora.dev/docs/accessibility/images",
+  },
+  A11Y_CLICKABLE_NON_INTERACTIVE: {
+    why:
+      "Non-semantic clickable elements often miss keyboard and screen-reader affordances.",
+    docs: "https://aurora.dev/docs/accessibility/interactive-elements",
+  },
+  GOVERNANCE_MISSING_MODULE_OWNER: {
+    why:
+      "Without declared ownership, review routing and escalation paths become ambiguous in team-scale delivery.",
+    docs: "https://aurora.dev/docs/governance/module-ownership",
+  },
+  GOVERNANCE_INVALID_OWNERS_EXPORT: {
+    why:
+      "Invalid ownership metadata breaks automation and review policy enforcement.",
+    docs: "https://aurora.dev/docs/governance/module-ownership",
+  },
+  AI_PROMPT_UNDERSPECIFIED: {
+    why:
+      "The prompt omitted key product/domain details, reducing scaffold relevance and confidence.",
+    docs: "https://aurora.dev/docs/ai/prompting-guide",
+  },
+  AI_SCAFFOLD_FAILED: {
+    why:
+      "AI intent inference succeeded, but scaffold generation could not be applied safely in the current workspace.",
+    docs: "https://aurora.dev/docs/ai/troubleshooting",
+  },
+};
+
+export function toAiReadableDiagnostic(
+  input: AiDiagnosticInput,
+): AiReadableDiagnostic {
+  const template = DIAGNOSTIC_TEMPLATES[input.code];
+
+  return {
+    code: input.code,
+    severity: normalizeSeverity(input.severity),
+    whatWentWrong:
+      normalizeMessage(input.message) ?? "Aurora reported a diagnostic event.",
+    why:
+      template?.why ??
+      "Aurora detected behavior that may violate framework safety, correctness, or maintainability rules.",
+    howToFix:
+      normalizeMessage(input.remediation) ??
+      "Apply the remediation hint and rerun the command to confirm the issue is resolved.",
+    docs:
+      template?.docs ??
+      `https://aurora.dev/docs/diagnostics#${input.code.toLowerCase()}`,
+    category: normalizeMessage(input.category),
+    location:
+      input.file || typeof input.line === "number"
+        ? {
+            file: normalizeMessage(input.file),
+            line:
+              typeof input.line === "number" && Number.isFinite(input.line)
+                ? Math.max(1, Math.trunc(input.line))
+                : undefined,
+          }
+        : undefined,
+  };
+}
+
+function normalizeSeverity(
+  value: AiDiagnosticInput["severity"],
+): AiDiagnosticSeverity {
+  if (value === "error") {
+    return "error";
+  }
+
+  if (value === "warn" || value === "warning") {
+    return "warning";
+  }
+
+  return "info";
+}
+
+function normalizeMessage(value: string | undefined): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+
+  const normalized = value.trim().replace(/\s+/g, " ");
+  return normalized.length > 0 ? normalized : undefined;
+}