uiaudit.js 1.0.0

package/src/parser/index.ts

@@ -0,0 +1,106 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as parser from '@babel/parser';
+import type { File } from '@babel/types';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface ParsedFile {
+  filePath: string;
+  ast: File;
+  source: string;
+}
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+const SUPPORTED_EXT = new Set(['.tsx', '.ts', '.jsx', '.js']);
+
+// Directories we never descend into
+const IGNORED_DIRS = new Set([
+  'node_modules', '.next', 'dist', 'build', '.git',
+  '.cache', 'coverage', 'out', '.turbo', 'storybook-static',
+]);
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Parse a single file with Babel.
+ * Returns null for unsupported extensions or parse errors (we never crash on
+ * a single bad file — we just skip it and continue).
+ */
+export function parseFile(filePath: string): ParsedFile | null {
+  if (!SUPPORTED_EXT.has(path.extname(filePath))) return null;
+
+  try {
+    const source = fs.readFileSync(filePath, 'utf-8');
+    const ast = parser.parse(source, {
+      sourceType: 'module',
+      // Enable all syntax that appears in real React/Next.js projects
+      plugins: [
+        'jsx',
+        'typescript',
+        'decorators-legacy',
+        'classProperties',
+        'classStaticBlock',
+        'optionalChaining',
+        'nullishCoalescingOperator',
+        'importAssertions',
+      ],
+    });
+    return { filePath, ast, source };
+  } catch {
+    // Silently skip files that fail to parse.
+    // This happens with binary files, unusual encodings, or unsupported syntax.
+    return null;
+  }
+}
+
+/**
+ * Recursively collect all supported source files under a target path.
+ * Target can be either a single file or a directory.
+ */
+export function collectFiles(target: string): string[] {
+  const absTarget = path.resolve(target);
+
+  let stat: fs.Stats;
+  try {
+    stat = fs.statSync(absTarget);
+  } catch {
+    throw new Error(`Path not found: ${absTarget}`);
+  }
+
+  if (stat.isFile()) {
+    return SUPPORTED_EXT.has(path.extname(absTarget)) ? [absTarget] : [];
+  }
+
+  if (stat.isDirectory()) {
+    return walkDir(absTarget);
+  }
+
+  return [];
+}
+
+// ─── Private helpers ─────────────────────────────────────────────────────────
+
+function walkDir(dir: string): string[] {
+  const results: string[] = [];
+
+  for (const entry of fs.readdirSync(dir)) {
+    if (IGNORED_DIRS.has(entry)) continue;
+
+    const fullPath = path.join(dir, entry);
+
+    try {
+      const entryStat = fs.statSync(fullPath);
+      if (entryStat.isDirectory()) {
+        results.push(...walkDir(fullPath));
+      } else if (SUPPORTED_EXT.has(path.extname(entry))) {
+        results.push(fullPath);
+      }
+    } catch {
+      // Skip files we can't stat (permission issues, broken symlinks, etc.)
+    }
+  }
+
+  return results;
+}

package/src/parser/traverse.ts

@@ -0,0 +1,14 @@
+/**
+ * @babel/traverse has a well-known CommonJS interop quirk.
+ * Depending on the Node version and moduleResolution settings,
+ * the default export may land on `.default` or on the module itself.
+ * This file normalises that into a single reliable `traverse` export.
+ *
+ * All auditors import traverse from HERE, not directly from @babel/traverse.
+ */
+
+import _traverse from '@babel/traverse';
+
+export const traverse = ((typeof (_traverse as any).default === 'function'
+  ? (_traverse as any).default
+  : _traverse) as any) as (ast: any, visitors: any) => any;

package/src/reporter/terminal.ts

@@ -0,0 +1,247 @@
+import chalk from 'chalk';
+import type { AuditReport, AuditResult, Issue, IssueImpact } from '../types.js';
+
+// ─── Impact colour map ────────────────────────────────────────────────────────
+
+const IMPACT_BADGE: Record<IssueImpact, string> = {
+  critical: chalk.bgRed.white.bold(' CRITICAL '),
+  major:    chalk.bgYellow.black.bold('  MAJOR   '),
+  minor:    chalk.bgGray.white(     '  MINOR   '),
+};
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+export function renderTerminal(report: AuditReport): void {
+  console.log('');
+  printHeader(report);
+  printScoreSummary(report);
+
+  const { results } = report;
+  if (results.performance)   printCategorySection(results.performance);
+  if (results.seo)           printCategorySection(results.seo);
+  if (results.accessibility) printCategorySection(results.accessibility);
+
+  printCriticalSummary(report);
+  printFooter(report);
+}
+
+// ─── Header ──────────────────────────────────────────────────────────────────
+
+function printHeader(report: AuditReport): void {
+  const W = 66;
+  const rule = '─'.repeat(W);
+
+  const centre = (text: string) => {
+    const pad = Math.max(0, Math.floor((W - text.length) / 2));
+    return ' '.repeat(pad) + text + ' '.repeat(Math.max(0, W - pad - text.length));
+  };
+
+  console.log(chalk.cyan(`┌${rule}┐`));
+  console.log(chalk.cyan('│') + chalk.bold(centre('🔍  UIAudit')) + chalk.cyan('│'));
+  console.log(chalk.cyan('│') + chalk.cyan(centre(truncate(report.target, W - 2))) + chalk.cyan('│'));
+  console.log(chalk.cyan('│') + chalk.dim(centre(new Date(report.timestamp).toLocaleString())) + chalk.cyan('│'));
+  console.log(chalk.cyan(`└${rule}┘`));
+  console.log('');
+}
+
+// ─── Score summary table ──────────────────────────────────────────────────────
+
+function printScoreSummary(report: AuditReport): void {
+  const { overallScore, totalFiles, results } = report;
+
+  console.log(
+    `${chalk.bold('Overall Score:')}  ${colorScore(overallScore)(`${overallScore}/100`)}  ${scoreLabel(overallScore)}` +
+    chalk.dim(`   (${totalFiles} file${totalFiles !== 1 ? 's' : ''} scanned)\n`)
+  );
+
+  const rows: [string, AuditResult | undefined][] = [
+    ['Performance',   results.performance],
+    ['SEO',           results.seo],
+    ['Accessibility', results.accessibility],
+  ];
+
+  for (const [label, result] of rows) {
+    if (!result) continue;
+    const { score, counts } = result;
+
+    const bar      = scoreBar(score);
+    const scoreStr = colorScore(score)(`${score}/100`.padEnd(8));
+    const summary  =
+      counts.total === 0
+        ? chalk.green('No issues ✓')
+        : [
+            counts.critical ? chalk.red.bold(`${counts.critical} critical`) : '',
+            counts.major    ? chalk.yellow(`${counts.major} major`)         : '',
+            counts.minor    ? chalk.gray(`${counts.minor} minor`)           : '',
+          ]
+            .filter(Boolean)
+            .join(chalk.dim('  '));
+
+    console.log(`  ${chalk.bold(label.padEnd(15))} ${scoreStr} ${bar}  ${summary}`);
+  }
+
+  console.log('');
+}
+
+// ─── Category section ─────────────────────────────────────────────────────────
+
+function printCategorySection(result: AuditResult): void {
+  const CATEGORY_COLORS: Record<string, chalk.ChalkFunction> = {
+    performance:   chalk.blue.bold,
+    seo:           chalk.green.bold,
+    accessibility: chalk.magenta.bold,
+  };
+
+  const color = CATEGORY_COLORS[result.category] ?? chalk.bold;
+  const title = result.category.toUpperCase();
+
+  console.log(color('═'.repeat(62)));
+  console.log(
+    color(`  ${title}`) +
+    color('  ·  ') +
+    colorScore(result.score)(`${result.score}/100`)
+  );
+  console.log(color('═'.repeat(62)));
+  console.log('');
+
+  if (result.issues.length === 0) {
+    console.log(`  ${chalk.green('✅')}  No issues found.\n`);
+    return;
+  }
+
+  // Print issues grouped by impact level (critical → major → minor)
+  const groups: IssueImpact[] = ['critical', 'major', 'minor'];
+  for (const impact of groups) {
+    const group = result.issues.filter((i) => i.impact === impact);
+    if (group.length === 0) continue;
+
+    for (const issue of group) {
+      printIssue(issue);
+    }
+  }
+
+  console.log('');
+}
+
+// ─── Single issue block ───────────────────────────────────────────────────────
+
+function printIssue(issue: Issue): void {
+  const statusIcon = issue.status === 'fail' ? '❌' : '⚠️ ';
+  const badge      = IMPACT_BADGE[issue.impact];
+
+  // Location string (file:line)
+  const location = issue.file && issue.line
+    ? chalk.dim(`  ${shortPath(issue.file)}:${issue.line}`)
+    : '';
+
+  console.log(`  ${statusIcon}  ${badge}  ${chalk.bold(issue.title)}${location}`);
+  console.log(`       ${chalk.dim(issue.description)}`);
+  console.log('');
+
+  // Code snippet (what's wrong)
+  if (issue.codeSnippet) {
+    console.log(`       ${chalk.red.dim('✗')}  ${chalk.red.dim(issue.codeSnippet)}`);
+  }
+
+  // Fix snippet (what to write instead)
+  if (issue.fixSnippet) {
+    console.log(`       ${chalk.green.dim('✓')}  ${chalk.green(issue.fixSnippet)}`);
+  }
+
+  // Multi-line suggestion
+  console.log('');
+  const suggestionLines = issue.suggestion.split('\n');
+  console.log(`       ${chalk.cyan('💡 Fix:')} ${suggestionLines[0]}`);
+  for (const line of suggestionLines.slice(1)) {
+    console.log(`              ${chalk.dim(line)}`);
+  }
+
+  console.log('');
+  console.log('       ' + chalk.dim('─'.repeat(54)));
+  console.log('');
+}
+
+// ─── Critical summary (always shown at the end if any critical exist) ─────────
+
+function printCriticalSummary(report: AuditReport): void {
+  const criticals: Issue[] = [];
+
+  for (const result of Object.values(report.results)) {
+    if (!result) continue;
+    criticals.push(...result.issues.filter((i) => i.impact === 'critical'));
+  }
+
+  if (criticals.length === 0) return;
+
+  console.log(chalk.red.bold(`┌─ 🚨 Fix These First (${criticals.length} critical issue${criticals.length !== 1 ? 's' : ''}) ${'─'.repeat(25)}┐`));
+  console.log('');
+
+  criticals.slice(0, 6).forEach((issue, idx) => {
+    const cat = issue.category.padEnd(13);
+    console.log(
+      `  ${chalk.red.bold(String(idx + 1) + '.')}  ` +
+      chalk.dim(`[${cat}]`) + '  ' +
+      chalk.bold(issue.title)
+    );
+    if (issue.file) {
+      console.log(`        ${chalk.dim(shortPath(issue.file))}${issue.line ? chalk.dim(`:${issue.line}`) : ''}`);
+    }
+    console.log('');
+  });
+
+  console.log(chalk.red.bold('└' + '─'.repeat(58) + '┘'));
+  console.log('');
+}
+
+// ─── Footer ───────────────────────────────────────────────────────────────────
+
+function printFooter(report: AuditReport): void {
+  const totalIssues = Object.values(report.results)
+    .filter(Boolean)
+    .reduce((sum, r) => sum + r!.counts.total, 0);
+
+  if (totalIssues === 0) {
+    console.log(chalk.green.bold('  ✅  All checks passed. Your code looks good!\n'));
+  } else {
+    console.log(
+      chalk.dim(
+        `  Found ${totalIssues} issue${totalIssues !== 1 ? 's' : ''} across ` +
+        `${report.totalFiles} file${report.totalFiles !== 1 ? 's' : ''}. ` +
+        `Run with --output json to export the full report.\n`
+      )
+    );
+  }
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function scoreBar(score: number): string {
+  const filled = Math.round(score / 10);
+  const empty  = 10 - filled;
+  const color  = score >= 90 ? chalk.green : score >= 70 ? chalk.yellow : chalk.red;
+  return color('█'.repeat(filled)) + chalk.gray('░'.repeat(empty));
+}
+
+function colorScore(score: number): chalk.ChalkFunction {
+  if (score >= 90) return chalk.green.bold;
+  if (score >= 70) return chalk.yellow.bold;
+  if (score >= 50) return chalk.yellow;
+  return chalk.red.bold;
+}
+
+function scoreLabel(score: number): string {
+  if (score >= 90) return chalk.green('Excellent ✓');
+  if (score >= 70) return chalk.yellow('Good');
+  if (score >= 50) return chalk.yellow('Needs work');
+  return chalk.red.bold('Critical issues found');
+}
+
+/** Show only the last 3 path segments to keep output readable. */
+function shortPath(filePath: string): string {
+  const parts = filePath.replace(/\\/g, '/').split('/');
+  return (parts.length > 3 ? '…/' : '') + parts.slice(-3).join('/');
+}
+
+function truncate(str: string, maxLen: number): string {
+  return str.length > maxLen ? '…' + str.slice(-(maxLen - 1)) : str;
+}

package/src/types.ts

@@ -0,0 +1,51 @@
+// ─── Audit Categories ────────────────────────────────────────────────────────
+
+export type AuditCategory = 'performance' | 'seo' | 'accessibility';
+export type IssueImpact = 'critical' | 'major' | 'minor';
+export type IssueStatus = 'fail' | 'warning';
+
+// ─── A single issue found in a file ─────────────────────────────────────────
+
+export interface Issue {
+  id: string;
+  category: AuditCategory;
+  title: string;
+  description: string;
+  impact: IssueImpact;
+  status: IssueStatus;
+  suggestion: string;       // Plain-text fix explanation
+  codeSnippet?: string;     // The problematic pattern
+  fixSnippet?: string;      // The corrected version
+  file?: string;            // Absolute path
+  line?: number;            // Line number in the source file
+}
+
+// ─── Result for a single audit category ─────────────────────────────────────
+
+export interface AuditResult {
+  category: AuditCategory;
+  score: number;            // 0–100
+  issues: Issue[];
+  counts: {
+    critical: number;
+    major: number;
+    minor: number;
+    total: number;
+  };
+}
+
+// ─── The full report returned by runAudit() ──────────────────────────────────
+
+export interface AuditReport {
+  target: string;           // The path that was audited
+  timestamp: string;        // ISO 8601
+  overallScore: number;     // Weighted average of category scores
+  totalFiles: number;       // How many .tsx/.ts/.jsx/.js files were scanned
+  results: Partial<Record<AuditCategory, AuditResult>>;
+}
+
+// ─── Options passed in from CLI or programmatic API ─────────────────────────
+
+export interface AuditOptions {
+  types: AuditCategory[];
+}

package/tsconfig.json

@@ -0,0 +1,47 @@
+{
+  // Visit https://aka.ms/tsconfig to read more about this file
+  "compilerOptions": {
+    // File Layout
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "esModuleInterop": true,
+    // Environment Settings
+    // See also https://aka.ms/tsconfig/module
+
+    "module": "Node16",
+    "moduleResolution": "node16",
+    "target": "es2020",
+    "types": ["node"],
+    // For nodejs:
+    // "lib": ["esnext"],
+    // "types": ["node"],
+    // and npm install -D @types/node
+
+    // Other Outputs
+    "sourceMap": true,
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": false,
+
+    // Stricter Typechecking Options
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+
+    // Style Options
+    // "noImplicitReturns": true,
+    // "noImplicitOverride": true,
+    // "noUnusedLocals": true,
+    // "noUnusedParameters": true,
+    // "noFallthroughCasesInSwitch": true,
+    // "noPropertyAccessFromIndexSignature": true,
+
+    // Recommended Options
+    "strict": true,
+    "jsx": "react-jsx",
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "noUncheckedSideEffectImports": true,
+    "moduleDetection": "force",
+    "skipLibCheck": true,
+  }
+}