Code Auditor

Code Auditor

The code-auditor skill ensures that the JavaScript, HTML, and CSS running your website is correct, robust, and follows best practices. While the performance-optimizer focuses on speed and file size, the code-auditor focuses on correctness: Does your code run without errors? Do your API integrations actually work? Is there proper error handling in place? Are your dependencies secure?

This skill is your "web programmer" — the person who makes sure everything runs without breaking.

---

JavaScript Audit

Console Error Detection

Scans your browser console for JavaScript errors with zero-error tolerance in production. Checks:

• Uncaught errors and exceptions
• Unhandled promise rejections (async operations that fail silently)
• TypeError, ReferenceError, SyntaxError messages
• Deprecation warnings that could break in future browser updates
• Security warnings (mixed content, unsafe operations)

Why it matters: Users see broken functionality and get frustrated. Search engines penalize sites with errors.

API Call Failures

Tests all fetch() and XMLHttpRequest calls:

• Failed requests (4xx, 5xx responses)
• Network timeout issues
• Malformed request headers or bodies
• CORS errors when calling external APIs
• Missing or invalid API keys blocking requests

Why it matters: If your contact form can't submit to Resend, or your analytics don't load, visitors won't know — they'll just see a broken site.

Memory Leaks & Event Listeners

Identifies JavaScript that keeps eating memory:

• Event listeners never removed (onclick handlers that stack up)
• Old data stored in variables but never cleaned up
• DOM nodes kept in memory after being removed from the page
• Timer intervals/timeouts that never clear

Why it matters: Your site gets slower and slower the longer users stay on it. On mobile, it can crash.

Dead Code & Unused Variables

Finds code that's not being used:

• Functions defined but never called
• Variables assigned but never read
• Imports that don't get used
• Conditional branches that will never execute

Why it matters: Dead code adds to file size and confuses future maintenance. It's clutter.

ES6+ Compatibility

Checks that your JavaScript works in your target browsers:

• Arrow functions, destructuring, spread operator — all modern syntax
• Compatibility with older browsers (if that's your audience)
• Polyfill requirements for unsupported features
• Async/await vs Promise support

Why it matters: If your site breaks in Safari or older Chrome versions, you've lost those users.

Strict Mode & Variable Scoping

Validates proper JavaScript rigor:

• 'use strict' enforcement
• Global variable pollution
• Properly scoped let and const (not var)
• Undeclared variables (implicit globals)

Why it matters: Sloppy variable scoping causes hard-to-debug bugs and conflicts.

---

HTML Validation

W3C HTML5 Standards

Runs your HTML through validation against official standards:

• Proper DOCTYPE declaration
• Required meta tags (charset, viewport)
• Valid nesting of elements
• Deprecated HTML attributes (old code patterns)
• Duplicate IDs on the page

Why it matters: Invalid HTML can break in unexpected ways across browsers. Search engines prefer clean HTML.

Semantic Structure

Checks for proper use of meaningful HTML elements:

• `, , , , , , `
• Proper heading hierarchy (h1 → h2 → h3, not skipping levels)
• ` and ` for form structure
• `` for actual tabular data (not layout)

Why it matters: Semantic HTML helps screen readers, search engines, and makes your code readable.

Meta Tag Completeness

Ensures all important metadata is present:

• Viewport meta tag (mobile responsiveness)
• Character encoding declaration
• Open Graph tags for social sharing
• Canonical URL to prevent duplicate content issues

Why it matters: Missing meta tags mean broken mobile experience and poor social sharing.

---

CSS Audit

Invalid & Unused Selectors

Identifies CSS that doesn't work:

• Selectors with typos that never match any element
• Vendor prefixes that are outdated or missing where needed
• CSS that overrides itself (conflicting rules)
• Unused class/ID selectors (dead CSS)

Why it matters: Broken CSS rules add file size without any benefit.

Browser Compatibility

Checks for CSS features not supported in your target browsers:

• Missing vendor prefixes (-webkit-, -moz-, etc.)
• CSS Grid, Flexbox support in older browsers
• Custom properties (CSS variables) with no fallbacks
• Gradient, transform, and animation syntax compatibility

Why it matters: Your site looks perfect in Chrome but broken in Safari = lost users.

Specificity & !important Abuse

Analyzes CSS specificity issues:

• Excessive use of !important (forces CSS wars)
• Over-nested selectors (creates high specificity)
• Specificity conflicts preventing overrides
• Inline styles that fight with stylesheets

Why it matters: High specificity CSS is rigid and hard to change. It slows down redesigns.

Animation Performance

Checks which CSS properties are being animated:

• Layout-triggering animations (width, height, margin, padding)
• Paint-heavy animations (box-shadow, filter)
• Performant animations using transform and opacity
• GPU acceleration with will-change (when appropriate)

Why it matters: Bad animations cause jank (stuttering) and drain battery on mobile.

Media Query Organization

Reviews responsive design implementation:

• Consistent breakpoints (not scattered random widths)
• Mobile-first vs desktop-first strategy
• Missing breakpoints for awkward screen sizes
• Redundant media queries

Why it matters: Well-organized breakpoints make the code maintainable.

---

API Integration Testing

Resend Email Delivery

Tests email sending functionality:

• API endpoint exists and responds
• API key is valid and has permission to send
• Email validation (proper sender, recipient format)
• Error responses (what happens when email is invalid?)
• Rate limits and quota issues

What we check: Does clicking "Send" actually deliver the email, or silently fail?

Beehiiv Embed

Validates newsletter signup integration:

• Embed script loads without errors
• Form displays and is responsive
• Submissions go to Beehiiv (not stuck in your form)
• No JavaScript errors in the embed code
• No CORS blocking the embed

What we check: Can visitors actually sign up, or is the form silently broken?

Analytics (Google Analytics / Fathom)

Ensures tracking is working:

• Tracking code fires on page load
• Events are tracked (button clicks, form submissions)
• Not blocked by browser privacy settings or ad blockers
• Data appears in your analytics dashboard
• No script errors from the analytics library

What we check: Do you actually know how many visitors you have and what they do?

Vercel Serverless Functions

Audits backend function health:

• Function responds within timeout (30 seconds default)
• Cold start time (first request is slower)
• Error handling (what happens on failure?)
• Environment variables are set correctly
• Database connections work (no timeouts)
• Proper HTTP status codes returned

What we check: Can your backend handle requests, or do they time out?

---

Dependency Audit

Security Vulnerabilities

Runs npm audit to find known security issues:

• Outdated packages with published vulnerabilities
• Dependency chains that expose you to risk
• Major vs minor security issues (prioritize major)

Why it matters: Hackers actively exploit known vulnerabilities. Keeping dependencies updated is critical.

Outdated Packages

Identifies packages that have newer versions:

• Major version bumps (breaking changes)
• Minor version bumps (new features, backward compatible)
• Patch versions (bug fixes, usually safe to update)
• Package maintenance status (abandoned projects)

Why it matters: New versions often have performance fixes and bug fixes.

Unused Dependencies

Finds packages you're not actually using:

• Imported but never used
• Installed as transitive dependency (installed because something else needs it)
• Replaced by built-in browser APIs

Why it matters: Every dependency adds to your bundle size and increases attack surface.

Bundle Impact

Measures how much each dependency adds to your file size:

• Uncompressed vs compressed size
• Tree-shaking effectiveness (can dead code be removed?)
• Duplicate packages in node_modules

Why it matters: Large dependencies slow down page load.

---

Error Handling Review

Graceful Degradation

Tests what happens when things fail:

Network down? Does your site still show cached content or at least a helpful message?

API key expired? Do users see a helpful "something went wrong" message, or a JavaScript error dump?

JavaScript disabled? Can visitors still read your content and submit forms?

Third-party service down? Does your site still work if Beehiiv or analytics is slow/broken?

Why it matters: Real users encounter failures. Sites that handle failure gracefully seem more professional.

Try/Catch Around Async

Checks that async operations are wrapped in error handling:

• Fetch calls have .catch() handlers
• Async/await uses try/catch blocks
• Promise chains don't have unhandled rejections
• Error messages are user-friendly (not stack traces)

Why it matters: Without error handling, a failed API call crashes your page silently.

Form Fallbacks

Verifies forms work even if JavaScript fails:

• Form has action attribute (submits to server as fallback)
• Form has proper method (GET or POST)
• Progressive enhancement (basic functionality works, JS adds polish)

Why it matters: If your form relies 100% on JavaScript, it's broken for JavaScript-disabled users.

---

Build Pipeline Review

Vite Configuration

Audits your build setup:

• Entry points are correct (usually index.html)
• Output directory is set (usually dist/)
• Environment variables are configured
• Plugin order is correct (plugins can interact)
• Build optimization settings (minification, source maps)

Why it matters: Wrong build config means your site ships broken or bloated.

Tree-Shaking Effectiveness

Checks if unused code is actually removed from the bundle:

• Exports are export default or named exports (tree-shakeable)
• Dependencies use ES6 modules (not CommonJS)
• Side effects are marked correctly in package.json
• Dead code elimination is working

Why it matters: Without tree-shaking, your bundle includes code you don't use.

Chunk Splitting Strategy

Reviews how code is split across files:

• Vendor dependencies in separate chunks (cached longer)
• Route-based code splitting (load code only when needed)
• Chunk sizes are reasonable (not one giant file)
• Shared code between routes is deduplicated

Why it matters: Good chunking means faster page loads and better caching.

Source Maps

Checks debugging configuration:

• Source maps are enabled during development
• Source maps are disabled in production (they expose your source code)
• Error reporting still works (using error tracking service)

Why it matters: Production source maps are a security risk.

Environment Variables

Validates configuration management:

• Variables are loaded from .env files
• Secrets are never committed to git
• Production vs development configs are different
• Variables are used correctly in code (not string literals)

Why it matters: Hardcoded API keys or passwords in code get stolen.

---

Progressive Enhancement Check

Content Without JavaScript

Tests core functionality with JS disabled:

• Page displays readable content (not blank)
• Text and images load (not hidden behind JS)
• Critical links and navigation work
• Forms can be submitted

Why it matters: Users with old browsers, slow connections, or JS errors still get value.

HTML-First Architecture

Checks if content is in HTML (not JavaScript-rendered):

• Content is in semantic HTML tags (not empty divs)
• Navigation links are in `` tags (not divs with click handlers)
• Form fields exist in HTML (not generated by JavaScript)
• Text content isn't hidden in JavaScript strings

Why it matters: Search engines and screen readers see what's in the HTML. If content is only in JavaScript, they miss it.

---

Code Quality Metrics

Linting Results

Runs ESLint (or equivalent) to catch code style issues:

• Unused variables
• Missing semicolons (if your style requires them)
• Inconsistent naming conventions (camelCase vs snake_case)
• Problematic patterns (var vs let/const)

Why it matters: Consistent code is easier to read and less error-prone.

Code Complexity

Measures how complex your functions are:

• Functions doing too many things (should be smaller)
• Nested conditionals creating hard-to-follow logic
• Long parameter lists
• Functions with too many return paths

Why it matters: Simple code is less buggy and easier to maintain.

File Organization

Reviews directory structure and file sizes:

• Related code grouped together (not scattered)
• Files aren't too large (single responsibility)
• No circular dependencies (file A imports B imports A)
• Clear naming conventions (components/, utils/, pages/, etc.)

Why it matters: Good organization makes features easier to find and modify.

Naming Conventions

Checks that names are consistent and clear:

• Variables/functions use camelCase (or your chosen convention)
• Classes use PascalCase
• Constants use UPPERSNAKECASE
• Names are descriptive (not x, temp, data)

Why it matters: Clear names make code self-documenting.

---

Audit Report Format

When the code-auditor runs, you'll receive a structured report with:

Error Summary

Severity Breakdown:
- Critical (blocks functionality): 3 issues
- High (breaks features): 2 issues  
- Medium (poor UX): 5 issues
- Low (code quality): 8 issues

Organized by Category

• JavaScript Errors (file:line reference)
• HTML Issues (validation failures)
• CSS Problems (browser compatibility)
• API Integration (Resend, Beehiiv, Analytics status)
• Dependencies (vulnerabilities, outdated packages)
• Build Pipeline (Vite configuration issues)

For Each Issue

1. What's wrong (plain English explanation)
2. Why it matters (impact on users/performance)
3. Where it is (file path and line number)
4. How to fix it (specific steps)
5. Priority (Critical > High > Medium > Low)

Prioritization

Issues are ordered by impact:

1. Critical: Site doesn't work (API failures, JavaScript crashes)
2. High: Features are broken (form submission fails, analytics don't load)
3. Medium: Poor user experience (slow animations, confusing errors)
4. Low: Code quality and maintenance (unused code, naming conventions)

---

How to Use This Skill

Trigger the code-auditor skill when you notice:

• Error messages in the browser console
• Forms or buttons that don't work
• Third-party integrations (email, newsletters, analytics) that seem broken
• You want a general code quality review
• You're getting a JavaScript error that's hard to track down
• You need to know if your dependencies have security issues
• You're refactoring and want to ensure nothing breaks

The skill will:

1. Test your site in a browser environment
2. Run automated checks against your code
3. Test API integrations with real calls
4. Check dependencies for vulnerabilities
5. Produce a prioritized report of what needs fixing

Result: A clear list of what's broken, why it matters, and exactly how to fix it.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mrhinkle
• Source: mrhinkle/VibeCoding-a-Website
• License: MIT

Install and usage instructions live in the source repository linked above.