@vibecodeqa/cli 0.42.0 → 0.44.0

package/dist/runners/design-consistency.js

@@ -0,0 +1,125 @@
+/** Design Consistency — LLM-powered audit of visual consistency across components.
+ *
+ * Pro feature. Requires VCQA_PRO_KEY env var.
+ *
+ * Detects:
+ *   - Components that define the same visual pattern differently (accidental design system)
+ *   - Spacing/color/typography inconsistencies across files
+ *   - Missing component extraction opportunities
+ *   - Tailwind class patterns that should be @apply'd or componentized
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getProductionFiles } from "../fs-utils.js";
+import { gradeFromScore } from "../types.js";
+export async function runDesignConsistency(cwd) {
+    const start = Date.now();
+    const proKey = process.env.VCQA_PRO_KEY || "";
+    if (!proKey) {
+        return {
+            name: "design-consistency",
+            score: 0,
+            grade: "F",
+            details: {
+                premium: true,
+                comingSoon: true,
+                reason: "Set VCQA_PRO_KEY to enable design consistency analysis",
+                description: "LLM-powered audit of visual consistency — finds components with duplicate styling, inconsistent spacing scales, and missing component extraction opportunities.",
+            },
+            issues: [],
+            duration: Date.now() - start,
+        };
+    }
+    const files = getProductionFiles(cwd);
+    const componentFiles = files.filter((f) => !f.isTest && /\.(tsx|jsx|vue|svelte)$/.test(f.path));
+    if (componentFiles.length < 2) {
+        return {
+            name: "design-consistency",
+            score: 100,
+            grade: "A",
+            details: { componentsAnalyzed: componentFiles.length },
+            issues: [],
+            duration: Date.now() - start,
+        };
+    }
+    // Build hash of all component content for cache key
+    const h = createHash("sha256");
+    for (const f of componentFiles.sort((a, b) => a.path.localeCompare(b.path))) {
+        h.update(f.path);
+        h.update(f.content.slice(0, 2000));
+    }
+    const contentHash = h.digest("hex").slice(0, 16);
+    // Check cache
+    const cache = loadCache(cwd);
+    if (cache && cache.hash === contentHash) {
+        return {
+            name: "design-consistency",
+            score: cache.findings.length === 0 ? 100 : Math.max(20, 100 - cache.findings.length * 12),
+            grade: gradeFromScore(cache.findings.length === 0 ? 100 : Math.max(20, 100 - cache.findings.length * 12)),
+            details: { premium: true, componentsAnalyzed: componentFiles.length, cached: true },
+            issues: cache.findings,
+            duration: Date.now() - start,
+        };
+    }
+    // Extract styling snippets from top components (by size, most likely to have styling)
+    const candidates = componentFiles
+        .sort((a, b) => b.content.length - a.content.length)
+        .slice(0, 10);
+    const snippets = candidates.map((f) => ({
+        path: f.path,
+        content: f.content.slice(0, 2000),
+    }));
+    const issues = await analyzeDesign(snippets, proKey);
+    // Cache results
+    saveCache(cwd, { version: 1, hash: contentHash, findings: issues });
+    const score = issues.length === 0 ? 100 : Math.max(20, 100 - issues.length * 12);
+    return {
+        name: "design-consistency",
+        score,
+        grade: gradeFromScore(score),
+        details: { premium: true, componentsAnalyzed: componentFiles.length },
+        issues,
+        duration: Date.now() - start,
+    };
+}
+async function analyzeDesign(files, proKey) {
+    try {
+        const res = await fetch("https://api.vibecodeqa.online/api/pro/design-consistency", {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${proKey}`,
+            },
+            body: JSON.stringify({ files: files.map((f) => ({ path: f.path, content: f.content })) }),
+        });
+        if (!res.ok)
+            return [];
+        const data = (await res.json());
+        return data.findings || [];
+    }
+    catch {
+        return [];
+    }
+}
+function loadCache(cwd) {
+    try {
+        const cachePath = join(cwd, ".vibe-check", "design-consistency-cache.json");
+        if (existsSync(cachePath)) {
+            const data = JSON.parse(readFileSync(cachePath, "utf-8"));
+            if (data.version === 1)
+                return data;
+        }
+    }
+    catch { /* corrupt cache */ }
+    return null;
+}
+function saveCache(cwd, cache) {
+    try {
+        const dir = join(cwd, ".vibe-check");
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, "design-consistency-cache.json"), JSON.stringify(cache));
+    }
+    catch { /* write failed */ }
+}

package/dist/runners/error-handling.js

@@ -25,12 +25,22 @@ export function runErrorHandling(cwd, stack) {
             const line = lines[i].trim();
             if (line.startsWith("//") || line.startsWith("*"))
                 continue;
-            // Skip string-only lines and metadata definitions
+            // Skip suppressed lines (// ok, // intentional, eslint-disable, biome-ignore)
+            if (/\/\/\s*(?:ok|intentional|eslint-disable|biome-ignore)/.test(line))
+                continue;
+            // Skip string-only lines, metadata definitions, and return statements with string literals
             if (/^\s*["'`].*["'`][,;]?\s*$/.test(lines[i]))
                 continue;
             if (/\b(?:message|description|risk|recommendation|name)\s*:\s*["']/.test(line))
                 continue;
+            if (/\breturn\s+["'`]/.test(line))
+                continue;
+            if (/\brule\s*===?\s*["']/.test(line))
+                continue;
             if (/catch\s*\([^)]*\)\s*\{\s*\}/.test(line) || /catch\s*\{\s*\}/.test(line)) {
+                // Skip intentional one-liner try-catch for optional browser APIs
+                if (/try\s*\{.*(?:localStorage|sessionStorage|document\.).*\}\s*catch/.test(line))
+                    continue;
                 emptyCatch++;
                 issues.push({ severity: "error", message: "Empty catch block", file: f.path, line: i + 1, rule: "empty-catch" });
             }
@@ -83,8 +93,14 @@ export function runErrorHandling(cwd, stack) {
             const line = lines[i].trim();
             if (line.startsWith("//") || line.startsWith("*"))
                 continue;
+            if (/\/\/\s*(?:ok|intentional|eslint-disable|biome-ignore)/.test(line))
+                continue;
+            if (/^\s*["'`].*["'`][,;]?\s*$/.test(lines[i]))
+                continue;
             if (/\b(?:message|description|risk|recommendation|name)\s*:\s*["']/.test(line))
                 continue;
+            if (/\breturn\s+["'`]/.test(line))
+                continue;
             // JSON.parse of external input without try-catch
             if (/\bJSON\.parse\s*\(/.test(line)) {
                 // Only flag if parsing user/network input (not internal known-safe files)
@@ -141,7 +157,7 @@ export function runErrorHandling(cwd, stack) {
                 }
             }
             // process.exit() in non-CLI files (library code shouldn't exit)
-            if (/\bprocess\.exit\s*\(/.test(line) && !f.path.includes("cli") && !f.path.includes("bin/")) {
+            if (/\bprocess\.exit\s*\(/.test(line) && !f.path.includes("cli") && !f.path.includes("bin/") && !f.path.includes("commands/") && !f.path.includes("monitor")) {
                 processExit++;
                 issues.push({
                     severity: "warning",

package/dist/runners/file-cohesion.d.ts

@@ -0,0 +1,17 @@
+/** File Cohesion — detects files with multiple responsibilities.
+ *
+ * Pro feature. Requires VCQA_PRO_KEY env var.
+ *
+ * Two-phase analysis:
+ *   1. Local heuristics (always run with Pro key):
+ *      - Files with exports spanning multiple domains (auth + email + db)
+ *      - Mixed concern signals: HTTP handlers + business logic + data access
+ *      - High export count relative to file purpose
+ *
+ *   2. LLM-powered analysis (via api.vibecodeqa.online):
+ *      - Labels each file's responsibility clusters
+ *      - Suggests concrete split points
+ *      - "This file handles auth, session, AND email — split into 3 modules"
+ */
+import type { CheckResult } from "../types.js";
+export declare function runFileCohesion(cwd: string): Promise<CheckResult>;

package/dist/runners/file-cohesion.js

@@ -0,0 +1,177 @@
+/** File Cohesion — detects files with multiple responsibilities.
+ *
+ * Pro feature. Requires VCQA_PRO_KEY env var.
+ *
+ * Two-phase analysis:
+ *   1. Local heuristics (always run with Pro key):
+ *      - Files with exports spanning multiple domains (auth + email + db)
+ *      - Mixed concern signals: HTTP handlers + business logic + data access
+ *      - High export count relative to file purpose
+ *
+ *   2. LLM-powered analysis (via api.vibecodeqa.online):
+ *      - Labels each file's responsibility clusters
+ *      - Suggests concrete split points
+ *      - "This file handles auth, session, AND email — split into 3 modules"
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getProductionFiles } from "../fs-utils.js";
+import { gradeFromScore } from "../types.js";
+const CONCERN_PATTERNS = [
+    { name: "HTTP/routing", patterns: [/\b(app|router|server)\.(get|post|put|delete|patch|use)\b/, /\bRequest\b.*\bResponse\b/, /\breq\s*,\s*res\b/, /\bfastify\b|\bhono\b|\bexpress\b/] },
+    { name: "database", patterns: [/\b(prisma|sequelize|typeorm|knex|drizzle)\b/, /\bSELECT\b.*\bFROM\b/i, /\.query\s*\(/, /\bcreateClient\b.*\bsupabase\b/i] },
+    { name: "auth", patterns: [/\b(jwt|token|session|cookie|passport|oauth|login|signup|signIn|signUp)\b/i, /\bverify(Token|Session|Auth)\b/, /\bbcrypt|argon2|scrypt\b/] },
+    { name: "email", patterns: [/\bsendMail|sendEmail|transporter|nodemailer|resend|postmark\b/i, /\bsmtp\b/i] },
+    { name: "file I/O", patterns: [/\breadFileSync|writeFileSync|createReadStream|createWriteStream\b/, /\bfs\.(read|write|mkdir|unlink|stat)\b/] },
+    { name: "validation", patterns: [/\bz\.(string|number|object|array)\b/, /\bJoi\.(string|number|object)\b/, /\byup\.(string|number|object)\b/, /\bvalidate\w*Schema\b/] },
+    { name: "UI rendering", patterns: [/\bJSX\b|\breturn\s*\(?\s*</, /\buseState|useEffect|useRef|useMemo\b/, /\brender\(\)/, /\bcomponent\b/i] },
+    { name: "state management", patterns: [/\bcreateStore|useStore|createSlice|createReducer\b/, /\bdispatch\(|getState\(\)/, /\buseSelector|useDispatch\b/] },
+    { name: "testing", patterns: [/\bdescribe\s*\(|it\s*\(|test\s*\(|expect\s*\(/, /\bbeforeEach|afterEach|beforeAll\b/, /\bjest\.|vitest\./] },
+    { name: "CLI", patterns: [/\bprocess\.argv\b/, /\bcommander|yargs|meow|cac\b/, /\bparse(Args|Options)\b/] },
+];
+export async function runFileCohesion(cwd) {
+    const start = Date.now();
+    const proKey = process.env.VCQA_PRO_KEY || "";
+    if (!proKey) {
+        return {
+            name: "file-cohesion",
+            score: 0,
+            grade: "F",
+            details: {
+                premium: true,
+                comingSoon: true,
+                reason: "Set VCQA_PRO_KEY to enable file cohesion analysis",
+                description: "Detects files with multiple responsibilities — the #1 code smell in AI-generated code. Labels each file's concern clusters and suggests concrete split points.",
+            },
+            issues: [],
+            duration: Date.now() - start,
+        };
+    }
+    const files = getProductionFiles(cwd);
+    const issues = [];
+    const cache = loadCache(cwd);
+    let cacheHits = 0;
+    // Phase 1: local heuristics — detect multi-concern files
+    const candidates = [];
+    for (const f of files) {
+        if (f.isTest)
+            continue;
+        const lines = f.content.split("\n").length;
+        if (lines < 100)
+            continue; // small files rarely have cohesion problems
+        const detectedConcerns = [];
+        for (const concern of CONCERN_PATTERNS) {
+            if (concern.patterns.some((p) => p.test(f.content))) {
+                detectedConcerns.push(concern.name);
+            }
+        }
+        if (detectedConcerns.length >= 2) {
+            candidates.push({ path: f.path, content: f.content, concerns: detectedConcerns, lines });
+            // Local issue for 2+ concerns
+            issues.push({
+                severity: detectedConcerns.length >= 3 ? "error" : "warning",
+                message: `${detectedConcerns.length} concerns detected: ${detectedConcerns.join(", ")} — consider splitting`,
+                file: f.path,
+                rule: "multi-concern",
+            });
+        }
+    }
+    // Phase 2: LLM analysis for top candidates (by line count, most likely to benefit from splitting)
+    const topCandidates = candidates
+        .sort((a, b) => b.lines - a.lines)
+        .slice(0, 5);
+    for (const candidate of topCandidates) {
+        const hash = createHash("sha256").update(candidate.content).digest("hex").slice(0, 16);
+        // Check cache
+        const cached = cache.files[candidate.path];
+        if (cached && cached.hash === hash) {
+            cacheHits++;
+            if (cached.suggestion) {
+                issues.push({
+                    severity: "warning",
+                    message: cached.suggestion,
+                    file: candidate.path,
+                    rule: "split-suggestion",
+                });
+            }
+            continue;
+        }
+        // Call LLM for concrete split suggestions
+        const analysis = await analyzeCohesion(candidate.path, candidate.content, proKey);
+        if (analysis) {
+            cache.files[candidate.path] = { hash, concerns: analysis.concerns, suggestion: analysis.suggestion };
+            if (analysis.suggestion) {
+                issues.push({
+                    severity: "warning",
+                    message: analysis.suggestion,
+                    file: candidate.path,
+                    rule: "split-suggestion",
+                });
+            }
+        }
+    }
+    saveCache(cwd, cache);
+    const totalFiles = files.filter((f) => !f.isTest).length;
+    const multiConcernFiles = candidates.length;
+    const ratio = totalFiles > 0 ? multiConcernFiles / totalFiles : 0;
+    const score = Math.round(Math.max(0, 100 - ratio * 300));
+    return {
+        name: "file-cohesion",
+        score,
+        grade: gradeFromScore(score),
+        details: {
+            premium: true,
+            totalFiles,
+            multiConcernFiles,
+            cacheHits,
+            candidates: candidates.map((c) => ({ path: c.path, concerns: c.concerns, lines: c.lines })),
+        },
+        issues,
+        duration: Date.now() - start,
+    };
+}
+async function analyzeCohesion(filePath, content, proKey) {
+    const truncated = content.slice(0, 4000);
+    try {
+        const res = await fetch("https://api.vibecodeqa.online/api/pro/file-cohesion", {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${proKey}`,
+            },
+            body: JSON.stringify({ file: filePath, content: truncated }),
+        });
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        return {
+            concerns: data.concerns || [],
+            suggestion: data.suggestion || "",
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function loadCache(cwd) {
+    try {
+        const cachePath = join(cwd, ".vibe-check", "file-cohesion-cache.json");
+        if (existsSync(cachePath)) {
+            const data = JSON.parse(readFileSync(cachePath, "utf-8"));
+            if (data.version === 1)
+                return data;
+        }
+    }
+    catch { /* corrupt cache */ }
+    return { version: 1, files: {} };
+}
+function saveCache(cwd, cache) {
+    try {
+        const dir = join(cwd, ".vibe-check");
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, "file-cohesion-cache.json"), JSON.stringify(cache));
+    }
+    catch { /* write failed */ }
+}

package/dist/runners/frontend-health.d.ts

@@ -0,0 +1,14 @@
+/** Frontend health — detects HTML/framework antipatterns in component code.
+ *
+ * Checks:
+ *   1. Conflicting UI frameworks (MUI + Tailwind, Chakra + Tailwind, etc.)
+ *   2. Large/unoptimized images (no width/height, no next/image, large src)
+ *   3. Inconsistent icon systems (mixing lucide + heroicons + fontawesome)
+ *   4. Bundle-heavy imports (entire libraries instead of specific components)
+ *   5. Missing loading states (async data without suspense/skeleton)
+ *   6. Hardcoded strings (potential i18n issues)
+ *   7. Missing meta tags / head management
+ *   8. DOM nesting violations (div in p, button in a)
+ */
+import type { CheckResult } from "../types.js";
+export declare function runFrontendHealth(cwd: string): CheckResult;

package/dist/runners/frontend-health.js

@@ -0,0 +1,206 @@
+/** Frontend health — detects HTML/framework antipatterns in component code.
+ *
+ * Checks:
+ *   1. Conflicting UI frameworks (MUI + Tailwind, Chakra + Tailwind, etc.)
+ *   2. Large/unoptimized images (no width/height, no next/image, large src)
+ *   3. Inconsistent icon systems (mixing lucide + heroicons + fontawesome)
+ *   4. Bundle-heavy imports (entire libraries instead of specific components)
+ *   5. Missing loading states (async data without suspense/skeleton)
+ *   6. Hardcoded strings (potential i18n issues)
+ *   7. Missing meta tags / head management
+ *   8. DOM nesting violations (div in p, button in a)
+ */
+import { getProductionFiles, readDeps } from "../fs-utils.js";
+import { gradeFromScore } from "../types.js";
+// UI framework conflicts
+const UI_FRAMEWORKS = [
+    { name: "MUI", deps: ["@mui/material", "@mui/system", "@material-ui/core"] },
+    { name: "Tailwind", deps: ["tailwindcss"] },
+    { name: "Chakra", deps: ["@chakra-ui/react"] },
+    { name: "Ant Design", deps: ["antd"] },
+    { name: "Bootstrap", deps: ["react-bootstrap", "bootstrap"] },
+    { name: "Mantine", deps: ["@mantine/core"] },
+    { name: "Radix", deps: ["@radix-ui/react-dialog", "@radix-ui/react-dropdown-menu", "@radix-ui/themes"] },
+    { name: "shadcn/ui", deps: ["cmdk", "vaul"] }, // shadcn uses these + Tailwind
+    { name: "DaisyUI", deps: ["daisyui"] },
+];
+// Icon library conflicts
+const ICON_LIBS = [
+    { name: "lucide", patterns: [/from\s+["']lucide-react["']/, /from\s+["']lucide-vue-next["']/] },
+    { name: "heroicons", patterns: [/from\s+["']@heroicons\/react/, /from\s+["']@heroicons\/vue/] },
+    { name: "fontawesome", patterns: [/from\s+["']@fortawesome/, /fa-\w+/] },
+    { name: "phosphor", patterns: [/from\s+["']@phosphor-icons/] },
+    { name: "tabler", patterns: [/from\s+["']@tabler\/icons/] },
+    { name: "react-icons", patterns: [/from\s+["']react-icons\//] },
+    { name: "material-icons", patterns: [/from\s+["']@mui\/icons-material/] },
+    { name: "ionicons", patterns: [/from\s+["']ionicons/, /ion-icon/] },
+];
+// Heavy full-library imports
+const HEAVY_IMPORTS = [
+    { pattern: /import\s+\*\s+as\s+\w+\s+from\s+["']lodash["']/, message: "Import entire lodash — use lodash/specific or lodash-es" },
+    { pattern: /from\s+["']@mui\/icons-material["'](?!\/)/, message: "Import all MUI icons — import specific: @mui/icons-material/Add" },
+    { pattern: /from\s+["']react-icons["'](?!\/)/, message: "Import all react-icons — import specific: react-icons/fi" },
+    { pattern: /from\s+["']antd["']\s*;\s*$/, message: "Import all of antd — destructure: import { Button } from 'antd'" },
+    { pattern: /import\s+(?:moment|dayjs)\s+from/, message: "Date library imported fully — consider tree-shakeable alternative" },
+];
+// DOM nesting violations
+const NESTING_VIOLATIONS = [
+    { parent: "<p", child: "<div", message: "div inside p — invalid HTML nesting" },
+    { parent: "<p", child: "<p", message: "p inside p — invalid HTML nesting" },
+    { parent: "<a", child: "<a", message: "a inside a — nested links are invalid" },
+    { parent: "<button", child: "<button", message: "button inside button — invalid nesting" },
+    { parent: "<a", child: "<button", message: "button inside a — use one or the other" },
+];
+export function runFrontendHealth(cwd) {
+    const start = Date.now();
+    const issues = [];
+    const files = getProductionFiles(cwd);
+    const deps = readDeps(cwd);
+    const componentFiles = files.filter((f) => !f.isTest && /\.(tsx|jsx|vue|svelte)$/.test(f.path));
+    if (componentFiles.length === 0) {
+        return {
+            name: "frontend-health",
+            score: 0,
+            grade: "F",
+            details: { skipped: true, reason: "no component files found" },
+            issues: [],
+            duration: Date.now() - start,
+        };
+    }
+    // 1. Conflicting UI frameworks
+    const activeFrameworks = [];
+    for (const fw of UI_FRAMEWORKS) {
+        if (fw.deps.some((d) => d in deps)) {
+            activeFrameworks.push(fw.name);
+        }
+    }
+    // Tailwind + Radix/shadcn is intentional (shadcn uses Tailwind)
+    const conflicts = activeFrameworks.filter((f) => f !== "Radix" && f !== "shadcn/ui" && f !== "DaisyUI");
+    if (conflicts.length > 1 && !(conflicts.length === 2 && conflicts.includes("Tailwind") && conflicts.includes("shadcn/ui"))) {
+        issues.push({
+            severity: "error",
+            message: `Conflicting UI frameworks: ${conflicts.join(" + ")} — pick one`,
+            rule: "framework-conflict",
+        });
+    }
+    // 2-8. Scan component files
+    const iconLibsUsed = new Set();
+    let unoptimizedImages = 0;
+    let missingLoadingStates = 0;
+    for (const f of componentFiles) {
+        const lines = f.content.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            const trimmed = line.trim();
+            // Icon libraries used
+            for (const lib of ICON_LIBS) {
+                if (lib.patterns.some((p) => p.test(line))) {
+                    iconLibsUsed.add(lib.name);
+                }
+            }
+            // Heavy imports
+            for (const heavy of HEAVY_IMPORTS) {
+                if (heavy.pattern.test(line)) {
+                    issues.push({
+                        severity: "warning",
+                        message: heavy.message,
+                        file: f.path,
+                        line: i + 1,
+                        rule: "heavy-import",
+                    });
+                }
+            }
+            // Unoptimized images
+            if (/<img\s/.test(trimmed) && !trimmed.includes("next/image") && !trimmed.includes("Image")) {
+                if (!trimmed.includes("width") || !trimmed.includes("height")) {
+                    unoptimizedImages++;
+                    if (unoptimizedImages <= 3) {
+                        issues.push({
+                            severity: "warning",
+                            message: "img without width/height — causes layout shift (use next/image or set dimensions)",
+                            file: f.path,
+                            line: i + 1,
+                            rule: "unoptimized-image",
+                        });
+                    }
+                }
+            }
+            // Large image sources (base64 data URLs in JSX)
+            if (/src\s*=\s*["']data:image\/[^"']{10000}/.test(line)) {
+                issues.push({
+                    severity: "error",
+                    message: "Large base64 image inline — move to a file and import",
+                    file: f.path,
+                    line: i + 1,
+                    rule: "inline-image",
+                });
+            }
+            // DOM nesting violations (heuristic — not a full parser)
+            for (const v of NESTING_VIOLATIONS) {
+                if (trimmed.includes(v.child) && i > 0) {
+                    // Check previous 5 lines for unclosed parent
+                    const context = lines.slice(Math.max(0, i - 5), i).join(" ");
+                    const parentOpens = (context.match(new RegExp(v.parent.replace("<", "<"), "g")) || []).length;
+                    const parentCloses = (context.match(new RegExp(v.parent.replace("<", "</"), "g")) || []).length;
+                    if (parentOpens > parentCloses) {
+                        issues.push({
+                            severity: "warning",
+                            message: v.message,
+                            file: f.path,
+                            line: i + 1,
+                            rule: "dom-nesting",
+                        });
+                        break;
+                    }
+                }
+            }
+        }
+        // Missing loading states (has fetch/useQuery but no loading/skeleton/suspense)
+        if (/\b(fetch|useQuery|useSWR|useEffect.*fetch)\b/.test(f.content)) {
+            if (!/\b(loading|isLoading|Skeleton|Spinner|Suspense|fallback)\b/.test(f.content)) {
+                missingLoadingStates++;
+                if (missingLoadingStates <= 3) {
+                    issues.push({
+                        severity: "info",
+                        message: "Async data fetch without visible loading state",
+                        file: f.path,
+                        rule: "no-loading-state",
+                    });
+                }
+            }
+        }
+    }
+    // Icon system conflicts
+    if (iconLibsUsed.size > 1) {
+        issues.push({
+            severity: "warning",
+            message: `Mixed icon libraries: ${[...iconLibsUsed].join(", ")} — pick one for consistency`,
+            rule: "mixed-icons",
+        });
+    }
+    // Summary issues
+    if (unoptimizedImages > 3) {
+        issues.push({
+            severity: "warning",
+            message: `${unoptimizedImages} images without dimensions — all cause layout shift`,
+            rule: "unoptimized-image",
+        });
+    }
+    // Score
+    const errorCount = issues.filter((i) => i.severity === "error").length;
+    const warnCount = issues.filter((i) => i.severity === "warning").length;
+    const score = Math.max(0, 100 - errorCount * 25 - warnCount * 10);
+    return {
+        name: "frontend-health",
+        score,
+        grade: gradeFromScore(score),
+        details: {
+            componentFiles: componentFiles.length,
+            activeFrameworks,
+            iconLibsUsed: [...iconLibsUsed],
+            unoptimizedImages,
+        },
+        issues,
+        duration: Date.now() - start,
+    };
+}

package/dist/runners/html-quality.d.ts

@@ -0,0 +1,8 @@
+/** HTML quality — checks static HTML sites for meta tags, images, links, a11y, performance, SEO, security.
+ *
+ * Activates when the project has .html files. Works alongside framework checks —
+ * catches issues in static sites, landing pages, and docs that framework-specific
+ * checks miss entirely.
+ */
+import type { CheckResult } from "../types.js";
+export declare function runHtmlQuality(cwd: string): CheckResult;