uiaudit.js 1.0.0

package/src/auditors/performance.ts

@@ -0,0 +1,212 @@
+import { traverse } from '../parser/traverse.js';
+import type { ParsedFile } from '../parser/index.js';
+import type { Issue } from '../types.js';
+
+/**
+ * Audits parsed files for React performance anti-patterns.
+ * All checks are purely static — no browser, no runtime needed.
+ */
+export function auditPerformance(parsedFiles: ParsedFile[]): Issue[] {
+  const issues: Issue[] = [];
+
+  for (const { ast, filePath } of parsedFiles) {
+    traverse(ast, {
+
+      /**
+       * All CallExpression checks are merged into ONE visitor.
+       * Babel traverse does NOT support duplicate visitor keys —
+       * the last one silently wins. Always merge.
+       */
+      CallExpression(path: any) {
+        const node = path.node;
+
+        // ── Check 1: .map() returning JSX without a key prop ─────────────
+        //
+        // Why this matters: React uses keys to identify which items in a
+        // list changed. Without keys, React re-renders the entire list on
+        // every state change — O(n) DOM mutations instead of O(1).
+        if (
+          node.callee.type === 'MemberExpression' &&
+          node.callee.property.type === 'Identifier' &&
+          node.callee.property.name === 'map' &&
+          node.arguments.length > 0
+        ) {
+          const callback = node.arguments[0];
+          if (
+            callback.type === 'ArrowFunctionExpression' ||
+            callback.type === 'FunctionExpression'
+          ) {
+            const body = callback.body;
+            let jsxEl: any = null;
+
+            // Arrow fn with implicit return: items.map(item => <div />)
+            if (body.type === 'JSXElement' || body.type === 'JSXFragment') {
+              jsxEl = body;
+            }
+
+            // Arrow fn with block body: items.map(item => { return <div /> })
+            if (body.type === 'BlockStatement') {
+              const ret = body.body.find(
+                (s: any) =>
+                  s.type === 'ReturnStatement' &&
+                  (s as any).argument?.type === 'JSXElement'
+              ) as any;
+              jsxEl = ret?.argument ?? null;
+            }
+
+            if (jsxEl?.type === 'JSXElement') {
+              const attrs = jsxEl.openingElement.attributes as any[];
+              const hasKey = attrs.some(
+                (a) =>
+                  a.type === 'JSXAttribute' &&
+                  a.name?.type === 'JSXIdentifier' &&
+                  a.name.name === 'key'
+              );
+
+              if (!hasKey) {
+                issues.push({
+                  id: 'missing-key-prop',
+                  category: 'performance',
+                  title: 'Missing key prop in list render',
+                  description:
+                    'React uses keys to identify which items changed, were added, or removed. Without a key, React re-renders the whole list on every state update — even when nothing changed.',
+                  impact: 'major',
+                  status: 'fail',
+                  suggestion:
+                    'Add a unique, stable key to the root element inside .map(). Use a real ID from your data — never the array index (index shifts when items are added/removed).',
+                  codeSnippet: 'items.map(item => <Card>{item.name}</Card>)',
+                  fixSnippet:  'items.map(item => <Card key={item.id}>{item.name}</Card>)',
+                  file: filePath,
+                  line: node.loc?.start.line,
+                });
+              }
+            }
+          }
+        }
+
+        // ── Check 2: useEffect with no dependency array ───────────────────
+        //
+        // Why this matters: No second argument = runs after EVERY render.
+        // This is almost always a bug — it creates fetch loops, causes
+        // infinite re-renders, and kills performance.
+        if (
+          node.callee.type === 'Identifier' &&
+          node.callee.name === 'useEffect' &&
+          node.arguments.length === 1   // 2nd arg (dep array) is absent
+        ) {
+          issues.push({
+            id: 'useeffect-no-deps',
+            category: 'performance',
+            title: 'useEffect is missing a dependency array',
+            description:
+              'A useEffect with no second argument runs after every single render, including renders triggered by unrelated state changes. This almost always causes performance problems or infinite loops.',
+            impact: 'major',
+            status: 'fail',
+            suggestion:
+              'Add a dependency array as the second argument.\n  [] — run once on mount (equivalent to componentDidMount)\n  [value] — run whenever `value` changes\n  [id, token] — run when either changes',
+            codeSnippet: 'useEffect(() => { fetchUser(id); })',
+            fixSnippet:  'useEffect(() => { fetchUser(id); }, [id])',
+            file: filePath,
+            line: node.loc?.start.line,
+          });
+        }
+
+        // ── Check 3: console.log/debug/info in component files ────────────
+        //
+        // Why this matters: Console calls shipped to production leak
+        // internal data to any user who opens DevTools, and they
+        // accumulate into thousands of log entries in long sessions.
+        if (
+          node.callee.type === 'MemberExpression' &&
+          node.callee.object.type === 'Identifier' &&
+          node.callee.object.name === 'console' &&
+          node.callee.property.type === 'Identifier' &&
+          ['log', 'debug', 'info'].includes(node.callee.property.name)
+        ) {
+          const method = (node.callee.property as any).name as string;
+          issues.push({
+            id: 'console-in-component',
+            category: 'performance',
+            title: `console.${method}() left in component`,
+            description:
+              `console.${method} calls shipped to production expose internal data to end users and clutter the browser DevTools console.`,
+            impact: 'minor',
+            status: 'warning',
+            suggestion:
+              'Remove before shipping. For intentional debug logging, gate it:\nif (process.env.NODE_ENV !== "production") console.log(...)',
+            file: filePath,
+            line: node.loc?.start.line,
+          });
+        }
+      }, // end CallExpression
+
+      // ── Check 4: Complex inline function in event handler props ──────────
+      //
+      // Why this matters: () => { ... } inside JSX creates a NEW function
+      // object on every render. Any child component that receives this prop
+      // will always fail React.memo's shallow equality check and re-render.
+      JSXAttribute(path: any) {
+        const node = path.node;
+        const EVENT_HANDLERS = [
+          'onClick', 'onChange', 'onSubmit', 'onBlur', 'onFocus', 'onKeyDown',
+        ];
+
+        if (
+          node.name.type !== 'JSXIdentifier' ||
+          !EVENT_HANDLERS.includes(node.name.name)
+        ) return;
+
+        if (node.value?.type !== 'JSXExpressionContainer') return;
+
+        const expr = node.value.expression;
+        if (
+          expr.type !== 'ArrowFunctionExpression' &&
+          expr.type !== 'FunctionExpression'
+        ) return;
+
+        // Only flag truly inline logic — 2+ statements in the function body.
+        // A simple pass-through like onClick={() => onClick(item)} is fine.
+        const body = (expr as any).body;
+        const isComplex =
+          body?.type === 'BlockStatement' && body.body.length >= 2;
+
+        if (isComplex) {
+          const propName = node.name.name;
+          const handlerName = `handle${propName.slice(2)}`; // onClick → handleClick
+
+          issues.push({
+            id: 'inline-handler-in-jsx',
+            category: 'performance',
+            title: `Complex inline function in ${propName} prop`,
+            description:
+              `This creates a new function reference on every render. Any child receiving this prop via React.memo or PureComponent will always re-render because the prop value is never referentially equal.`,
+            impact: 'minor',
+            status: 'warning',
+            suggestion:
+              `Extract into a useCallback at the top of your component:\n\nconst ${handlerName} = useCallback(() => {\n  // your logic here\n}, [/* list dependencies */]);\n\n// Then use:\n<Component ${propName}={${handlerName}} />`,
+            codeSnippet: `<Button ${propName}={() => { doA(); doB(); }}>`,
+            fixSnippet:  `const ${handlerName} = useCallback(() => { doA(); doB(); }, []);\n<Button ${propName}={${handlerName}}>`,
+            file: filePath,
+            line: node.loc?.start.line,
+          });
+        }
+      }, // end JSXAttribute
+
+    }); // end traverse
+  }
+
+  return deduplicate(issues);
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/** Drop exact duplicate issues (same rule, file, and line). */
+function deduplicate(issues: Issue[]): Issue[] {
+  const seen = new Set<string>();
+  return issues.filter((issue) => {
+    const key = `${issue.id}::${issue.file}::${issue.line}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}

package/src/auditors/seo.ts

@@ -0,0 +1,212 @@
+import { traverse } from '../parser/traverse.js';
+import type { ParsedFile } from '../parser/index.js';
+import type { Issue } from '../types.js';
+
+/**
+ * Audits parsed files for SEO issues detectable via static AST analysis.
+ * Focus: things that directly cost you search ranking or crawlability.
+ */
+export function auditSEO(parsedFiles: ParsedFile[]): Issue[] {
+  const issues: Issue[] = [];
+
+  for (const { ast, filePath } of parsedFiles) {
+    // Per-file state — we collect import info first, then use it in checks
+    const fileState = {
+      importsNextImage: false,
+      imgTagLines: [] as number[],
+    };
+
+    traverse(ast, {
+
+      // ── Track which packages this file imports ────────────────────────────
+      ImportDeclaration(path: any) {
+        if (path.node.source.value === 'next/image') {
+          fileState.importsNextImage = true;
+        }
+      },
+
+      // ── All JSXOpeningElement checks ──────────────────────────────────────
+      JSXOpeningElement(path: any) {
+        const node = path.node;
+        if (node.name.type !== 'JSXIdentifier') return;
+
+        const tagName = node.name.name;
+
+        // Helper: check if an attribute exists on this element
+        const hasAttr = (name: string): boolean =>
+          node.attributes.some(
+            (a: any) =>
+              a.type === 'JSXAttribute' &&
+              a.name.type === 'JSXIdentifier' &&
+              a.name.name === name
+          );
+
+        // Helper: get an attribute's string value (returns null if dynamic/absent)
+        const getStringAttr = (name: string): string | null => {
+          const attr = node.attributes.find(
+            (a: any) =>
+              a.type === 'JSXAttribute' &&
+              a.name.type === 'JSXIdentifier' &&
+              a.name.name === name
+          ) as any;
+          return attr?.value?.type === 'StringLiteral'
+            ? attr.value.value
+            : null;
+        };
+
+        // ── Check 1: <img> without alt attribute ─────────────────────────
+        //
+        // Why this matters: Google uses alt text to understand image content
+        // for image search ranking. Missing alt = invisible to search engines.
+        if (tagName === 'img') {
+          fileState.imgTagLines.push(node.loc?.start.line ?? 0);
+
+          if (!hasAttr('alt')) {
+            issues.push({
+              id: 'img-missing-alt',
+              category: 'seo',
+              title: '<img> is missing an alt attribute',
+              description:
+                'Search engines use alt text to index image content. Missing alt attributes also break Google Image Search rankings and violate WCAG 1.1.1.',
+              impact: 'major',
+              status: 'fail',
+              suggestion:
+                'Add an alt attribute describing what the image shows.\nFor decorative images (pure visual flair, no meaning): alt=""\nFor meaningful images: alt="Two developers reviewing code on a laptop"',
+              codeSnippet: '<img src={hero} />',
+              fixSnippet:  '<img src={hero} alt="Hero banner showing the product dashboard" />',
+              file: filePath,
+              line: node.loc?.start.line,
+            });
+          }
+        }
+
+        // ── Check 2: Self-closing <a> with no content or aria-label ──────
+        //
+        // Why this matters: Google uses anchor text to understand what the
+        // linked page is about. An empty link gives it nothing to rank on.
+        if (tagName === 'a' && node.selfClosing) {
+          const hasAriaLabel = hasAttr('aria-label');
+          const hasTitle = hasAttr('title');
+
+          if (!hasAriaLabel && !hasTitle) {
+            issues.push({
+              id: 'anchor-no-content',
+              category: 'seo',
+              title: '<a> tag has no content or accessible label',
+              description:
+                'Empty anchor tags give search engines no anchor text to rank with, and give screen readers nothing to announce. Both hurt you — one in rankings, one in accessibility.',
+              impact: 'major',
+              status: 'fail',
+              suggestion:
+                'Add descriptive text between <a> and </a>, or add aria-label if the link contains only an icon:\n<a href="/about">About us</a>\n// Icon-only link:\n<a href="/about" aria-label="About us"><Icon /></a>',
+              codeSnippet: '<a href="/about" />',
+              fixSnippet:  '<a href="/about">About us</a>',
+              file: filePath,
+              line: node.loc?.start.line,
+            });
+          }
+        }
+
+        // ── Check 3: <div> used where a semantic HTML tag belongs ────────
+        //
+        // Why this matters: Semantic HTML is a direct ranking signal.
+        // Google's crawlers assign structural meaning to <nav>, <main>,
+        // <article>, etc. A <div> with className="nav" tells them nothing.
+        if (tagName === 'div') {
+          // Look at className and id for hints about intended semantics
+          const className = getStringAttr('className') ?? '';
+          const idVal     = getStringAttr('id') ?? '';
+          const combined  = `${className} ${idVal}`.toLowerCase();
+
+          const SEMANTIC_MAP: Record<string, string> = {
+            nav:         'nav',
+            navigation:  'nav',
+            header:      'header',
+            footer:      'footer',
+            main:        'main',
+            sidebar:     'aside',
+            aside:       'aside',
+            article:     'article',
+            section:     'section',
+          };
+
+          // Check each word in className/id against our semantic map
+          const words = combined.split(/[\s\-_/]+/);
+          const match = words.find((w) => SEMANTIC_MAP[w]);
+
+          if (match) {
+            const replacement = SEMANTIC_MAP[match];
+            issues.push({
+              id: 'non-semantic-html',
+              category: 'seo',
+              title: `Use <${replacement}> instead of <div className="${className || idVal}">`,
+              description:
+                `Search engines assign structural roles to semantic HTML elements. <${replacement}> signals its purpose to Google's crawler and improves your document outline. A <div> is invisible to that system.`,
+              impact: 'minor',
+              status: 'warning',
+              suggestion:
+                `Replace <div> with <${replacement}>. You can keep the existing className — the element name is what changes.\n<${replacement} className="${className || idVal}">...</${replacement}>`,
+              codeSnippet: `<div className="${className || idVal}">...</div>`,
+              fixSnippet:  `<${replacement} className="${className || idVal}">...</${replacement}>`,
+              file: filePath,
+              line: node.loc?.start.line,
+            });
+          }
+        }
+
+      }, // end JSXOpeningElement
+
+    }); // end traverse
+
+    // ── Post-traverse: Check for raw <img> in Next.js component files ────────
+    //
+    // This runs AFTER traverse because we need to know both:
+    //   (a) whether 'next/image' was imported (set in ImportDeclaration)
+    //   (b) whether any <img> tags were used (set in JSXOpeningElement)
+    //
+    // Why this matters: next/image gives you automatic WebP, lazy-loading,
+    // responsive sizes, and CLS prevention — all Core Web Vitals wins.
+    // A raw <img> tag bypasses ALL of that.
+
+    const isComponentFile =
+      filePath.endsWith('.tsx') || filePath.endsWith('.jsx');
+
+    if (
+      isComponentFile &&
+      fileState.imgTagLines.length > 0 &&
+      !fileState.importsNextImage
+    ) {
+      for (const line of fileState.imgTagLines) {
+        issues.push({
+          id: 'use-next-image',
+          category: 'seo',
+          title: 'Use Next.js <Image> instead of <img>',
+          description:
+            'Next.js <Image> automatically converts to WebP, lazy-loads below-the-fold images, prevents layout shift (CLS), and serves correctly-sized images per viewport. Raw <img> gets none of this.',
+          impact: 'major',
+          status: 'warning',
+          suggestion:
+            "Import and use the Next.js Image component:\nimport Image from 'next/image';\n\n// Replace:\n<img src={src} alt={alt} width={500} height={300} />",
+          codeSnippet: `import Image from 'next/image';`,
+          fixSnippet:  `<Image src={src} alt="description" width={500} height={300} />`,
+          file: filePath,
+          line,
+        });
+      }
+    }
+  }
+
+  return deduplicate(issues);
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function deduplicate(issues: Issue[]): Issue[] {
+  const seen = new Set<string>();
+  return issues.filter((i) => {
+    const key = `${i.id}::${i.file}::${i.line}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}

package/src/cli.ts

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+/**
+ * UIAudit CLI entry point.
+ * This file is what runs when someone types `uiaudit` in their terminal.
+ *
+ * The bin field in package.json points to `dist/cli.js` (compiled version).
+ * During development: `npx ts-node src/cli.ts audit ./src`
+ */
+
+import { Command } from 'commander';
+import ora         from 'ora';
+import chalk       from 'chalk';
+import * as fs     from 'fs';
+import * as path   from 'path';
+
+import { runAudit }        from './auditor.js';
+import { renderTerminal }  from './reporter/terminal.js';
+import type { AuditCategory } from './types.js';
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+const ALL_CATEGORIES: AuditCategory[] = ['performance', 'seo', 'accessibility'];
+const VERSION = '1.0.0';
+
+// ─── CLI setup ────────────────────────────────────────────────────────────────
+
+const program = new Command();
+
+program
+  .name('uiaudit')
+  .description('Audit React/Next.js components for performance, SEO, and accessibility issues')
+  .version(VERSION);
+
+// ─── Main command: uiaudit audit <target> ────────────────────────────────────
+
+program
+  .command('audit <target>')
+  .description('Audit a file or directory of React/Next.js components')
+  .option(
+    '-t, --type <types>',
+    'Comma-separated audit categories to run: performance, seo, accessibility',
+    'performance,seo,accessibility'
+  )
+  .option(
+    '-o, --output <format>',
+    'Output format: terminal (default) or json',
+    'terminal'
+  )
+  .option(
+    '-f, --file <path>',
+    'Save JSON report to a file (also prints to terminal by default)'
+  )
+  .action((target: string, opts: { type: string; output: string; file?: string }) => {
+    const types = parseTypes(opts.type);
+    if (!types) process.exit(1);
+
+    runAuditCommand(target, types, opts.output, opts.file);
+  });
+
+// ─── Shorthand commands ───────────────────────────────────────────────────────
+// These exist so developers can type `uiaudit perf ./src` instead of the
+// full `uiaudit audit ./src --type performance`. Less typing = more usage.
+
+program
+  .command('perf <target>')
+  .description('Shorthand: run performance audit only')
+  .option('-o, --output <format>', 'Output format: terminal or json', 'terminal')
+  .option('-f, --file <path>', 'Save JSON report to a file')
+  .action((target: string, opts: { output: string; file?: string }) => {
+    runAuditCommand(target, ['performance'], opts.output, opts.file);
+  });
+
+program
+  .command('seo <target>')
+  .description('Shorthand: run SEO audit only')
+  .option('-o, --output <format>', 'Output format: terminal or json', 'terminal')
+  .option('-f, --file <path>', 'Save JSON report to a file')
+  .action((target: string, opts: { output: string; file?: string }) => {
+    runAuditCommand(target, ['seo'], opts.output, opts.file);
+  });
+
+program
+  .command('a11y <target>')
+  .description('Shorthand: run accessibility audit only')
+  .option('-o, --output <format>', 'Output format: terminal or json', 'terminal')
+  .option('-f, --file <path>', 'Save JSON report to a file')
+  .action((target: string, opts: { output: string; file?: string }) => {
+    runAuditCommand(target, ['accessibility'], opts.output, opts.file);
+  });
+
+program.parse(process.argv);
+
+// ─── Shared action handler ────────────────────────────────────────────────────
+
+function runAuditCommand(
+  target: string,
+  types: AuditCategory[],
+  output: string,
+  outputFile?: string
+): void {
+  const spinner = ora({
+    text: `Scanning ${chalk.cyan(target)}...`,
+    color: 'cyan',
+  }).start();
+
+  try {
+    const report = runAudit(target, { types });
+
+    spinner.succeed(
+      chalk.green(
+        `Scanned ${report.totalFiles} file${report.totalFiles !== 1 ? 's' : ''}`
+      )
+    );
+
+    // Save JSON report to file if requested
+    if (outputFile) {
+      const resolvedPath = path.resolve(outputFile);
+      fs.writeFileSync(resolvedPath, JSON.stringify(report, null, 2), 'utf-8');
+      console.log(chalk.green(`\n  ✓ Report saved → ${resolvedPath}\n`));
+    }
+
+    // Render output
+    if (output === 'json') {
+      console.log(JSON.stringify(report, null, 2));
+    } else {
+      renderTerminal(report);
+    }
+
+    // Exit code 1 if any critical issues — makes this useful in CI pipelines.
+    // Example: `uiaudit audit ./src && git push` will block the push if crits exist.
+    const hasCritical = Object.values(report.results).some(
+      (r) => r && r.counts.critical > 0
+    );
+    process.exit(hasCritical ? 1 : 0);
+
+  } catch (err: unknown) {
+    spinner.fail(chalk.red(`Audit failed: ${(err as Error).message}`));
+    if (process.env.DEBUG) {
+      console.error('\n', err);
+    } else {
+      console.error(chalk.dim('  Run with DEBUG=1 for stack trace.'));
+    }
+    process.exit(1);
+  }
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function parseTypes(raw: string): AuditCategory[] | null {
+  const parts = raw.split(',').map((t) => t.trim().toLowerCase()) as AuditCategory[];
+  const invalid = parts.filter((p) => !ALL_CATEGORIES.includes(p));
+
+  if (invalid.length > 0) {
+    console.error(
+      chalk.red(`\n  Unknown category: "${invalid.join('", "')}"\n`) +
+      chalk.dim(`  Valid options: ${ALL_CATEGORIES.join(', ')}\n`)
+    );
+    return null;
+  }
+
+  return parts;
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+/**
+ * UIAudit — Public programmatic API
+ *
+ * This is what the VS Code extension (and any other programmatic consumer)
+ * will import. The CLI (src/cli.ts) uses this same API under the hood.
+ *
+ * Usage:
+ *   import { runAudit } from 'uiaudit';
+ *   const report = runAudit('./src/components', { types: ['accessibility', 'performance'] });
+ */
+
+export { runAudit } from './auditor.js';
+
+export type {
+  AuditReport,
+  AuditResult,
+  AuditOptions,
+  AuditCategory,
+  Issue,
+  IssueImpact,
+  IssueStatus,
+} from './types.js';