@vibecodeqa/cli 0.42.0 → 0.43.0

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;

package/dist/runners/html-quality.js

@@ -0,0 +1,203 @@
+/** 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 { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { gradeFromScore } from "../types.js";
+const SKIP_DIRS = new Set(["node_modules", ".git", ".vibe-check", "dist", "build", "coverage", ".next", ".nuxt"]);
+export function runHtmlQuality(cwd) {
+    const start = Date.now();
+    const issues = [];
+    const htmlFiles = collectHtmlFiles(cwd);
+    if (htmlFiles.length === 0) {
+        return {
+            name: "html-quality",
+            score: 0,
+            grade: "F",
+            details: { skipped: true, reason: "no HTML files found" },
+            issues: [],
+            duration: Date.now() - start,
+        };
+    }
+    const allLinks = new Set();
+    const titles = new Map();
+    for (const file of htmlFiles) {
+        const relPath = relative(cwd, file);
+        let content;
+        try {
+            content = readFileSync(file, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        // ── Meta tags ──
+        if (content.includes("<head")) {
+            if (!/<title[^>]*>/.test(content)) {
+                issues.push({ severity: "error", message: "Missing <title> tag", file: relPath, rule: "missing-title" });
+            }
+            else {
+                const titleMatch = content.match(/<title[^>]*>([^<]*)<\/title>/i);
+                if (titleMatch) {
+                    const title = titleMatch[1].trim();
+                    if (title.length < 10) {
+                        issues.push({ severity: "warning", message: `Title too short: "${title}" — aim for 30-60 characters`, file: relPath, rule: "short-title" });
+                    }
+                    const existing = titles.get(title) || [];
+                    existing.push(relPath);
+                    titles.set(title, existing);
+                }
+            }
+            if (!/<meta\s[^>]*name=["']description["']/i.test(content)) {
+                issues.push({ severity: "warning", message: "Missing meta description", file: relPath, rule: "missing-description" });
+            }
+            if (!/<meta\s[^>]*name=["']viewport["']/i.test(content)) {
+                issues.push({ severity: "error", message: "Missing viewport meta — page won't be mobile-responsive", file: relPath, rule: "missing-viewport" });
+            }
+            if (!/<meta\s[^>]*charset/i.test(content)) {
+                issues.push({ severity: "warning", message: "Missing charset declaration", file: relPath, rule: "missing-charset" });
+            }
+            if (!/<meta\s[^>]*property=["']og:title["']/i.test(content)) {
+                issues.push({ severity: "info", message: "Missing Open Graph tags (og:title, og:description) — social sharing will look plain", file: relPath, rule: "missing-og" });
+            }
+            if (!/<link\s[^>]*rel=["']canonical["']/i.test(content)) {
+                issues.push({ severity: "info", message: "Missing canonical link — may cause duplicate content issues", file: relPath, rule: "missing-canonical" });
+            }
+            if (!/<link\s[^>]*rel=["']icon["']/i.test(content) && !/<link\s[^>]*rel=["']shortcut icon["']/i.test(content)) {
+                issues.push({ severity: "info", message: "Missing favicon", file: relPath, rule: "missing-favicon" });
+            }
+        }
+        // ── HTML lang ──
+        if (/<html[\s>]/.test(content) && !/<html\s[^>]*lang=/i.test(content)) {
+            issues.push({ severity: "warning", message: "Missing lang attribute on <html> — screen readers need this", file: relPath, rule: "missing-lang" });
+        }
+        // ── Images ──
+        const imgRegex = /<img\s[^>]*>/gi;
+        let imgMatch;
+        while ((imgMatch = imgRegex.exec(content)) !== null) {
+            const tag = imgMatch[0];
+            const line = content.slice(0, imgMatch.index).split("\n").length;
+            if (!/alt\s*=/i.test(tag)) {
+                issues.push({ severity: "error", message: "Image missing alt attribute", file: relPath, line, rule: "img-no-alt" });
+            }
+            if (!/(?:width|height)\s*=/i.test(tag)) {
+                issues.push({ severity: "warning", message: "Image missing width/height — causes layout shift", file: relPath, line, rule: "img-no-dimensions" });
+            }
+            if (!/loading\s*=/i.test(tag)) {
+                issues.push({ severity: "info", message: "Image missing loading=\"lazy\" — add for below-fold images", file: relPath, line, rule: "img-no-lazy" });
+            }
+        }
+        // ── Links ──
+        const linkRegex = /<a\s[^>]*href=["']([^"']+)["'][^>]*>/gi;
+        let linkMatch;
+        while ((linkMatch = linkRegex.exec(content)) !== null) {
+            const href = linkMatch[1];
+            const tag = linkMatch[0];
+            const line = content.slice(0, linkMatch.index).split("\n").length;
+            // HTTP links on what should be HTTPS
+            if (href.startsWith("http://") && !href.includes("localhost")) {
+                issues.push({ severity: "warning", message: `HTTP link: ${href} — use HTTPS`, file: relPath, line, rule: "http-link" });
+            }
+            // External links without rel=noopener
+            if (href.startsWith("http") && /target\s*=\s*["']_blank["']/i.test(tag) && !/rel\s*=\s*["'][^"']*noopener/i.test(tag)) {
+                issues.push({ severity: "warning", message: "External link with target=\"_blank\" missing rel=\"noopener\"", file: relPath, line, rule: "missing-noopener" });
+            }
+            // Collect internal links for broken link check
+            if (!href.startsWith("http") && !href.startsWith("mailto:") && !href.startsWith("#") && !href.startsWith("javascript:")) {
+                allLinks.add(join(cwd, href.split("#")[0].split("?")[0]));
+            }
+        }
+        // ── Heading hierarchy ──
+        const headings = [];
+        const headingRegex = /<h(\d)/gi;
+        let hMatch;
+        while ((hMatch = headingRegex.exec(content)) !== null) {
+            headings.push(parseInt(hMatch[1], 10));
+        }
+        for (let i = 1; i < headings.length; i++) {
+            if (headings[i] > headings[i - 1] + 1) {
+                issues.push({
+                    severity: "warning",
+                    message: `Heading hierarchy skip: h${headings[i - 1]} → h${headings[i]} (should be h${headings[i - 1] + 1})`,
+                    file: relPath,
+                    rule: "heading-skip",
+                });
+                break;
+            }
+        }
+        // ── Performance ──
+        // Render-blocking scripts (script in head without async/defer)
+        const headContent = content.match(/<head[^>]*>([\s\S]*?)<\/head>/i)?.[1] || "";
+        const scriptInHead = /<script\s[^>]*src=["'][^"']+["'][^>]*>/gi;
+        let scriptMatch;
+        while ((scriptMatch = scriptInHead.exec(headContent)) !== null) {
+            const tag = scriptMatch[0];
+            if (!/\b(?:async|defer|type=["']module["'])\b/i.test(tag)) {
+                issues.push({ severity: "warning", message: "Render-blocking script in <head> — add async or defer", file: relPath, rule: "render-blocking" });
+            }
+        }
+        // ── Security ──
+        // Mixed content (http:// resources on a page)
+        if (/<(?:img|script|link|iframe)\s[^>]*(?:src|href)=["']http:\/\/(?!localhost)/i.test(content)) {
+            issues.push({ severity: "warning", message: "Mixed content: HTTP resource on page — use HTTPS", file: relPath, rule: "mixed-content" });
+        }
+    }
+    // ── Cross-file checks ──
+    // Broken internal links
+    for (const link of allLinks) {
+        if (!existsSync(link)) {
+            const relLink = relative(cwd, link);
+            issues.push({ severity: "warning", message: `Broken internal link: ${relLink}`, rule: "broken-link" });
+        }
+    }
+    // Duplicate titles
+    for (const [title, files] of titles) {
+        if (files.length > 1) {
+            issues.push({ severity: "warning", message: `Duplicate title "${title}" in ${files.length} files — each page should have a unique title`, rule: "duplicate-title" });
+        }
+    }
+    // SEO files
+    if (!existsSync(join(cwd, "robots.txt"))) {
+        issues.push({ severity: "info", message: "Missing robots.txt", rule: "missing-robots" });
+    }
+    if (!existsSync(join(cwd, "sitemap.xml"))) {
+        issues.push({ severity: "info", message: "Missing sitemap.xml", rule: "missing-sitemap" });
+    }
+    // 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 * 15 - warnCount * 5);
+    return {
+        name: "html-quality",
+        score,
+        grade: gradeFromScore(score),
+        details: { htmlFiles: htmlFiles.length },
+        issues,
+        duration: Date.now() - start,
+    };
+}
+function collectHtmlFiles(cwd, subdir = "") {
+    const files = [];
+    const dir = subdir ? join(cwd, subdir) : cwd;
+    try {
+        for (const entry of readdirSync(dir)) {
+            if (SKIP_DIRS.has(entry))
+                continue;
+            const full = join(dir, entry);
+            try {
+                const stat = statSync(full);
+                if (stat.isDirectory()) {
+                    files.push(...collectHtmlFiles(cwd, subdir ? join(subdir, entry) : entry));
+                }
+                else if (entry.endsWith(".html") || entry.endsWith(".htm")) {
+                    files.push(full);
+                }
+            }
+            catch { /* skip */ }
+        }
+    }
+    catch { /* skip */ }
+    return files;
+}

package/dist/runners/react.js

@@ -201,6 +201,7 @@ export function runReact(cwd, stack) {
             inlineHandlers,
             effectNoDeps,
             domManipulation,
+            suggestion: !hasHooksPlugin ? "Install eslint-plugin-react-hooks for deeper React analysis: pnpm add -D eslint-plugin-react-hooks" : undefined,
         },
         issues,
         duration: Date.now() - start,

package/dist/runners/secrets.js

@@ -122,8 +122,9 @@ export async function runSecrets(cwd) {
     // Try gitleaks first (industry standard, 800+ patterns)
     const gitleaksResult = tryGitleaks(cwd, issues);
     const tool = gitleaksResult ? "gitleaks" : "secretlint";
-    if (!gitleaksResult)
+    if (!gitleaksResult) {
         issues.push(...(await scanFallback(cwd)));
+    }
     // ── .env file audit ──
     const envFiles = [".env", ".env.local", ".env.production", ".env.development"];
     const gitignore = existsSync(join(cwd, ".gitignore")) ? readFileSync(join(cwd, ".gitignore"), "utf-8") : "";
@@ -185,7 +186,11 @@ export async function runSecrets(cwd) {
         name: "secrets",
         score,
         grade: gradeFromScore(score),
-        details: { secretsFound: issues.length, tool },
+        details: {
+            secretsFound: issues.length,
+            tool,
+            suggestion: !gitleaksResult ? "Install gitleaks for deeper secret detection (800+ patterns): brew install gitleaks" : undefined,
+        },
         issues,
         duration: Date.now() - start,
     };

package/dist/runners/security.js

@@ -301,11 +301,17 @@ export function runSecurity(cwd) {
             if (trimmed.startsWith("//") || trimmed.startsWith("*"))
                 continue;
             // Skip pattern/config definition lines and string-heavy metadata (prevents false positives on own code)
-            if (/\bpattern\s*:|name:\s*["']|message:\s*["']|description:\s*["']|risk:\s*["']|recommendation:\s*["']/.test(trimmed))
+            if (/\bpattern\s*:|name:\s*["']|message:\s*["'`]|description:\s*["']|risk:\s*["']|recommendation:\s*["']|rule:\s*["']|severity:\s*["']/.test(trimmed))
                 continue;
             // Skip lines that are primarily string content (check-meta descriptions, etc.)
             if (/^\s*["'`].*["'`][,;]?\s*$/.test(line))
                 continue;
+            // Skip return statements returning string literals (e.g., fix suggestions mentioning patterns)
+            if (/\breturn\s+["'`]/.test(trimmed))
+                continue;
+            // Skip rule-matching conditionals (e.g., if (rule === "secret-detected") ...)
+            if (/\brule\s*===?\s*["']/.test(trimmed) || /\bcheck\s*===?\s*["']/.test(trimmed))
+                continue;
             for (const p of PATTERNS) {
                 if (p.pattern.test(line)) {
                     issues.push({