@sansavision/aurora 0.1.0-alpha.20260212.4

package/src/doctor.ts

@@ -0,0 +1,611 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { relative, resolve } from "node:path";
+
+import { toAiReadableDiagnostic, type AiReadableDiagnostic } from "./ai-diagnostics";
+import { type CommandContext, type CommandResult } from "./registry";
+
+type DoctorFormat = "text" | "json";
+type DoctorSeverity = "error" | "warn";
+type DoctorCategory =
+  | "boundary"
+  | "migration"
+  | "security"
+  | "performance"
+  | "a11y"
+  | "governance";
+type DoctorCode =
+  | "BOUNDARY_CLIENT_IMPORTS_SERVER"
+  | "DEPRECATED_ROUTE_API"
+  | "MIGRATION_MANUAL_ROUTES_ARRAY"
+  | "SECURITY_DYNAMIC_CODE_EXECUTION"
+  | "SECURITY_RAW_SQL_STRING"
+  | "PERF_UNBOUNDED_QUERY"
+  | "PERF_N_PLUS_ONE_LOOP_AWAIT"
+  | "A11Y_IMAGE_MISSING_ALT"
+  | "A11Y_CLICKABLE_NON_INTERACTIVE"
+  | "GOVERNANCE_MISSING_MODULE_OWNER"
+  | "GOVERNANCE_INVALID_OWNERS_EXPORT";
+
+interface DoctorOptions {
+  format: DoctorFormat;
+}
+
+interface DoctorFinding {
+  code: DoctorCode;
+  category: DoctorCategory;
+  severity: DoctorSeverity;
+  file: string;
+  line: number;
+  message: string;
+  remediation: string;
+  ai: AiReadableDiagnostic;
+}
+
+interface DoctorReport {
+  mode: "doctor";
+  projectRoot: string;
+  issues: DoctorFinding[];
+  errors: number;
+  warnings: number;
+  byCategory: Record<DoctorCategory, number>;
+}
+
+const SCANNABLE_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
+const OWNERS_HANDLE_PATTERN = /^@[A-Za-z0-9._/-]+$/;
+
+function parseDoctorOptions(args: ReadonlyArray<string>): DoctorOptions | CommandResult {
+  const options: DoctorOptions = { format: "text" };
+
+  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 doctor: --format requires 'text' or 'json'",
+        };
+      }
+
+      if (value !== "text" && value !== "json") {
+        return {
+          exitCode: 2,
+          stderr: `aurora doctor: invalid format '${value}'. Expected 'text' or 'json'`,
+        };
+      }
+
+      options.format = value;
+      i += 1;
+      continue;
+    }
+
+    return {
+      exitCode: 2,
+      stderr: `aurora doctor: unknown option '${arg}'`,
+    };
+  }
+
+  return options;
+}
+
+function isScannableFile(path: string): boolean {
+  for (const extension of SCANNABLE_EXTENSIONS) {
+    if (path.endsWith(extension)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function walkProjectFiles(root: string, directory = root): string[] {
+  const entries = readdirSync(directory, { withFileTypes: true });
+  const results: string[] = [];
+
+  for (const entry of entries) {
+    if (entry.name === ".git" || entry.name === "node_modules" || entry.name === ".aurora") {
+      continue;
+    }
+
+    const absolute = resolve(directory, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...walkProjectFiles(root, absolute));
+      continue;
+    }
+
+    if (!entry.isFile()) {
+      continue;
+    }
+
+    if (isScannableFile(absolute)) {
+      results.push(absolute);
+    }
+  }
+
+  return results;
+}
+
+function findLineNumber(source: string, index: number): number {
+  if (index <= 0) {
+    return 1;
+  }
+
+  return source.slice(0, index).split("\n").length;
+}
+
+function createFinding(input: {
+  code: DoctorCode;
+  category: DoctorCategory;
+  severity: DoctorSeverity;
+  file: string;
+  line: number;
+  message: string;
+  remediation: string;
+}): DoctorFinding {
+  return {
+    code: input.code,
+    category: input.category,
+    severity: input.severity,
+    file: input.file,
+    line: input.line,
+    message: input.message,
+    remediation: input.remediation,
+    ai: toAiReadableDiagnostic({
+      code: input.code,
+      severity: input.severity,
+      message: input.message,
+      remediation: input.remediation,
+      category: input.category,
+      file: input.file,
+      line: input.line,
+    }),
+  };
+}
+
+function scanBoundaryViolations(filePath: string, source: string, root: string): DoctorFinding[] {
+  const relativePath = relative(root, filePath);
+  const isClientFile =
+    relativePath.includes(".client.") ||
+    relativePath.endsWith(".client.ts") ||
+    relativePath.endsWith(".client.tsx");
+
+  if (!isClientFile) {
+    return [];
+  }
+
+  const findings: DoctorFinding[] = [];
+  const regex = /from\s+["'][^"']*\.server(?:\.[^"']*)?["']/g;
+  let match = regex.exec(source);
+
+  while (match) {
+    findings.push(
+      createFinding({
+        code: "BOUNDARY_CLIENT_IMPORTS_SERVER",
+        category: "boundary",
+        severity: "error",
+        file: relativePath,
+        line: findLineNumber(source, match.index),
+        message: "client module imports a server-only module",
+        remediation:
+          "Move server calls behind action/query boundaries and import only client-safe modules.",
+      }),
+    );
+    match = regex.exec(source);
+  }
+
+  return findings;
+}
+
+function scanMigrationRisks(filePath: string, source: string, root: string): DoctorFinding[] {
+  const findings: DoctorFinding[] = [];
+  const relativePath = relative(root, filePath);
+
+  const deprecatedRouteRegex = /\broute\s*\(\s*["'`]\//g;
+  let routeMatch = deprecatedRouteRegex.exec(source);
+  while (routeMatch) {
+    findings.push(
+      createFinding({
+        code: "DEPRECATED_ROUTE_API",
+        category: "migration",
+        severity: "warn",
+        file: relativePath,
+        line: findLineNumber(source, routeMatch.index),
+        message: "manual route() API is deprecated; use file-based routing conventions",
+        remediation:
+          "Replace route() registrations with file-based route modules and route metadata exports.",
+      }),
+    );
+    routeMatch = deprecatedRouteRegex.exec(source);
+  }
+
+  const manualRoutesRegex = /\broutes\s*:\s*\[/g;
+  let manualRouteMatch = manualRoutesRegex.exec(source);
+  while (manualRouteMatch) {
+    findings.push(
+      createFinding({
+        code: "MIGRATION_MANUAL_ROUTES_ARRAY",
+        category: "migration",
+        severity: "warn",
+        file: relativePath,
+        line: findLineNumber(source, manualRouteMatch.index),
+        message: "manual routes array detected",
+        remediation:
+          "Migrate to file-based routes (`page.tsx`, `<route>.client.tsx`, `<route>.server.ts`) and remove manual route arrays.",
+      }),
+    );
+    manualRouteMatch = manualRoutesRegex.exec(source);
+  }
+
+  return findings;
+}
+
+function scanSecurityRisks(filePath: string, source: string, root: string): DoctorFinding[] {
+  const findings: DoctorFinding[] = [];
+  const relativePath = relative(root, filePath);
+
+  const dynamicCodeRegex = /\beval\s*\(|\bnew\s+Function\s*\(/g;
+  let dynamicCodeMatch = dynamicCodeRegex.exec(source);
+  while (dynamicCodeMatch) {
+    findings.push(
+      createFinding({
+        code: "SECURITY_DYNAMIC_CODE_EXECUTION",
+        category: "security",
+        severity: "error",
+        file: relativePath,
+        line: findLineNumber(source, dynamicCodeMatch.index),
+        message: "dynamic code execution detected (eval/new Function)",
+        remediation:
+          "Remove dynamic code execution and use explicit parsing/dispatch logic with allow-listed operations.",
+      }),
+    );
+    dynamicCodeMatch = dynamicCodeRegex.exec(source);
+  }
+
+  const rawSqlRegex = /\b(?:query|execute)\s*\(\s*["'`]\s*(?:select|insert|update|delete)\b/gi;
+  let rawSqlMatch = rawSqlRegex.exec(source);
+  while (rawSqlMatch) {
+    findings.push(
+      createFinding({
+        code: "SECURITY_RAW_SQL_STRING",
+        category: "security",
+        severity: "warn",
+        file: relativePath,
+        line: findLineNumber(source, rawSqlMatch.index),
+        message: "raw SQL string execution detected",
+        remediation:
+          "Use parameterized queries or tagged SQL templates to avoid injection and improve auditability.",
+      }),
+    );
+    rawSqlMatch = rawSqlRegex.exec(source);
+  }
+
+  return findings;
+}
+
+function scanPerformanceRisks(filePath: string, source: string, root: string): DoctorFinding[] {
+  const findings: DoctorFinding[] = [];
+  const relativePath = relative(root, filePath);
+
+  const unboundedQueryRegex = /\.(?:findMany|list|scan)\s*\(\s*\)/g;
+  let unboundedMatch = unboundedQueryRegex.exec(source);
+  while (unboundedMatch) {
+    findings.push(
+      createFinding({
+        code: "PERF_UNBOUNDED_QUERY",
+        category: "performance",
+        severity: "warn",
+        file: relativePath,
+        line: findLineNumber(source, unboundedMatch.index),
+        message: "potential unbounded query detected",
+        remediation:
+          "Add pagination/limit parameters and stable ordering to bound query result size.",
+      }),
+    );
+    unboundedMatch = unboundedQueryRegex.exec(source);
+  }
+
+  const nPlusOneRegex = /for\s*\([^)]*\)\s*\{[\s\S]{0,220}?await\s+[A-Za-z0-9_$.]+\s*\(/g;
+  let nPlusOneMatch = nPlusOneRegex.exec(source);
+  while (nPlusOneMatch) {
+    findings.push(
+      createFinding({
+        code: "PERF_N_PLUS_ONE_LOOP_AWAIT",
+        category: "performance",
+        severity: "warn",
+        file: relativePath,
+        line: findLineNumber(source, nPlusOneMatch.index),
+        message: "serial await inside loop may cause N+1 latency",
+        remediation:
+          "Batch calls with Promise.all or prefetch in bulk outside the loop.",
+      }),
+    );
+    nPlusOneMatch = nPlusOneRegex.exec(source);
+  }
+
+  return findings;
+}
+
+function scanA11yRisks(filePath: string, source: string, root: string): DoctorFinding[] {
+  const findings: DoctorFinding[] = [];
+  const relativePath = relative(root, filePath);
+
+  const imgMissingAltRegex = /<img\b(?![^>]*\balt=)[^>]*>/gi;
+  let imgMatch = imgMissingAltRegex.exec(source);
+  while (imgMatch) {
+    findings.push(
+      createFinding({
+        code: "A11Y_IMAGE_MISSING_ALT",
+        category: "a11y",
+        severity: "warn",
+        file: relativePath,
+        line: findLineNumber(source, imgMatch.index),
+        message: "image tag missing alt text",
+        remediation:
+          "Add an `alt` attribute with meaningful text, or `alt=\"\"` for decorative images.",
+      }),
+    );
+    imgMatch = imgMissingAltRegex.exec(source);
+  }
+
+  const clickableDivRegex = /<div\b[^>]*\bonClick=/gi;
+  let clickableDivMatch = clickableDivRegex.exec(source);
+  while (clickableDivMatch) {
+    findings.push(
+      createFinding({
+        code: "A11Y_CLICKABLE_NON_INTERACTIVE",
+        category: "a11y",
+        severity: "warn",
+        file: relativePath,
+        line: findLineNumber(source, clickableDivMatch.index),
+        message: "click handler attached to non-interactive element",
+        remediation:
+          "Prefer `<button>`/`<a>` or add keyboard handlers and semantic role attributes.",
+      }),
+    );
+    clickableDivMatch = clickableDivRegex.exec(source);
+  }
+
+  return findings;
+}
+
+function scanGovernanceOwnership(root: string, files: readonly string[]): DoctorFinding[] {
+  const featureRoots = new Set<string>();
+
+  for (const filePath of files) {
+    const relativePath = relative(root, filePath).replaceAll("\\", "/");
+    const featureMatch = /^src\/features\/([^/]+)\//.exec(relativePath);
+    if (!featureMatch) {
+      continue;
+    }
+
+    featureRoots.add(`src/features/${featureMatch[1]}`);
+  }
+
+  const findings: DoctorFinding[] = [];
+
+  for (const featureRoot of [...featureRoots].sort()) {
+    const ownersFile = resolve(root, featureRoot, "OWNERS.ts");
+    let ownersSource = "";
+
+    try {
+      ownersSource = readFileSync(ownersFile, "utf8");
+    } catch {
+      findings.push(
+        createFinding({
+          code: "GOVERNANCE_MISSING_MODULE_OWNER",
+          category: "governance",
+          severity: "warn",
+          file: `${featureRoot}/OWNERS.ts`,
+          line: 1,
+          message: `feature module "${featureRoot}" is missing OWNERS.ts ownership metadata`,
+          remediation:
+            "Create OWNERS.ts and export at least one handle: `export const owners = [\"@team-name\"]`.",
+        }),
+      );
+      continue;
+    }
+
+    const ownersMatch = /export\s+const\s+owners\s*=\s*\[([\s\S]*?)\]/m.exec(ownersSource);
+    if (!ownersMatch) {
+      findings.push(
+        createFinding({
+          code: "GOVERNANCE_INVALID_OWNERS_EXPORT",
+          category: "governance",
+          severity: "warn",
+          file: `${featureRoot}/OWNERS.ts`,
+          line: 1,
+          message: "OWNERS.ts must export `owners` as an array of @handles",
+          remediation:
+            "Add `export const owners = [\"@team-name\"]` (and optional `reviewers`) to OWNERS.ts.",
+        }),
+      );
+      continue;
+    }
+
+    const ownersLine = findLineNumber(ownersSource, ownersMatch.index);
+    const handles = [...ownersMatch[1].matchAll(/["'`]([^"'`]+)["'`]/g)].map((match) =>
+      match[1].trim(),
+    );
+
+    if (handles.length === 0) {
+      findings.push(
+        createFinding({
+          code: "GOVERNANCE_INVALID_OWNERS_EXPORT",
+          category: "governance",
+          severity: "warn",
+          file: `${featureRoot}/OWNERS.ts`,
+          line: ownersLine,
+          message: "OWNERS.ts owners export must contain at least one handle",
+          remediation: "Use at least one owner handle: `export const owners = [\"@team-name\"]`.",
+        }),
+      );
+      continue;
+    }
+
+    const invalidHandles = handles.filter((handle) => !OWNERS_HANDLE_PATTERN.test(handle));
+    if (invalidHandles.length > 0) {
+      findings.push(
+        createFinding({
+          code: "GOVERNANCE_INVALID_OWNERS_EXPORT",
+          category: "governance",
+          severity: "warn",
+          file: `${featureRoot}/OWNERS.ts`,
+          line: ownersLine,
+          message:
+            "OWNERS.ts owners export contains invalid handles: " +
+            invalidHandles.map((handle) => `"${handle}"`).join(", "),
+          remediation:
+            "Use @prefixed handles with letters, numbers, '.', '-', '_', or '/'.",
+        }),
+      );
+    }
+  }
+
+  return findings;
+}
+
+function summarizeByCategory(findings: readonly DoctorFinding[]): Record<DoctorCategory, number> {
+  const counts: Record<DoctorCategory, number> = {
+    boundary: 0,
+    migration: 0,
+    security: 0,
+    performance: 0,
+    a11y: 0,
+    governance: 0,
+  };
+
+  for (const finding of findings) {
+    counts[finding.category] += 1;
+  }
+
+  return counts;
+}
+
+function runDoctorScans(context: CommandContext): DoctorReport | CommandResult {
+  const root = context.cwd;
+  let files: string[];
+
+  try {
+    const stats = statSync(root);
+    if (!stats.isDirectory()) {
+      return {
+        exitCode: 1,
+        stderr: `aurora doctor: project root is not a directory: ${root}`,
+      };
+    }
+    files = walkProjectFiles(root);
+  } catch {
+    return {
+      exitCode: 1,
+      stderr: `aurora doctor: unable to access project root: ${root}`,
+    };
+  }
+
+  const findings: DoctorFinding[] = [];
+
+  for (const filePath of files) {
+    let source = "";
+    try {
+      source = readFileSync(filePath, "utf8");
+    } catch {
+      continue;
+    }
+
+    findings.push(...scanBoundaryViolations(filePath, source, root));
+    findings.push(...scanMigrationRisks(filePath, source, root));
+    findings.push(...scanSecurityRisks(filePath, source, root));
+    findings.push(...scanPerformanceRisks(filePath, source, root));
+    findings.push(...scanA11yRisks(filePath, source, root));
+  }
+
+  findings.push(...scanGovernanceOwnership(root, files));
+
+  findings.sort((left, right) => {
+    const bySeverity = left.severity.localeCompare(right.severity);
+    if (bySeverity !== 0) {
+      return bySeverity;
+    }
+
+    const byFile = left.file.localeCompare(right.file);
+    if (byFile !== 0) {
+      return byFile;
+    }
+
+    const byLine = left.line - right.line;
+    if (byLine !== 0) {
+      return byLine;
+    }
+
+    return left.code.localeCompare(right.code);
+  });
+
+  const errors = findings.filter((finding) => finding.severity === "error").length;
+  const warnings = findings.filter((finding) => finding.severity === "warn").length;
+
+  return {
+    mode: "doctor",
+    projectRoot: root,
+    issues: findings,
+    errors,
+    warnings,
+    byCategory: summarizeByCategory(findings),
+  };
+}
+
+function renderDoctorTextReport(report: DoctorReport): string {
+  const lines = [
+    "aurora doctor report",
+    `project_root: ${report.projectRoot}`,
+    `issues: ${report.issues.length}`,
+    `errors: ${report.errors}`,
+    `warnings: ${report.warnings}`,
+    "categories:",
+    `- boundary: ${report.byCategory.boundary}`,
+    `- migration: ${report.byCategory.migration}`,
+    `- security: ${report.byCategory.security}`,
+    `- performance: ${report.byCategory.performance}`,
+    `- a11y: ${report.byCategory.a11y}`,
+    `- governance: ${report.byCategory.governance}`,
+  ];
+
+  if (report.issues.length > 0) {
+    lines.push("findings:");
+    for (const issue of report.issues) {
+      lines.push(
+        `- [${issue.severity}] [${issue.category}] ${issue.code} ${issue.file}:${issue.line} ${issue.message}`,
+      );
+      lines.push(`  fix: ${issue.remediation}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+export function runDoctorCommand(
+  args: ReadonlyArray<string>,
+  context: CommandContext,
+): CommandResult {
+  const options = parseDoctorOptions(args);
+  if ("exitCode" in options) {
+    return options;
+  }
+
+  const report = runDoctorScans(context);
+  if ("exitCode" in report) {
+    return report;
+  }
+
+  const exitCode = report.errors > 0 ? 1 : 0;
+
+  if (options.format === "json") {
+    return {
+      exitCode,
+      stdout: JSON.stringify(report, null, 2),
+    };
+  }
+
+  return {
+    exitCode,
+    stdout: renderDoctorTextReport(report),
+  };
+}