@vertaaux/cli 0.3.3 → 0.5.0

package/dist/utils/formatters.js

@@ -0,0 +1,277 @@
+/**
+ * Output formatting utilities for the VertaaUX CLI legacy commands.
+ * Provides markdown and JSON formatting functions for audit/fix/verify results.
+ */
+import { scoreColor, boldColor } from "@vertaaux/tui";
+import { writeOutput } from "../output/envelope.js";
+// ============================================================================
+// Data normalization
+// ============================================================================
+export function normalizeIssues(issues) {
+    if (Array.isArray(issues))
+        return issues;
+    if (issues && typeof issues === "object") {
+        const values = Object.values(issues);
+        return values.flatMap((value) => (Array.isArray(value) ? value : []));
+    }
+    return [];
+}
+export function toNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    return null;
+}
+export function getOverallScore(scores) {
+    if (!scores)
+        return null;
+    const s = scores;
+    const direct = toNumber(s.overall ?? s.ux ?? s.total);
+    if (direct !== null)
+        return direct;
+    const numeric = Object.values(s)
+        .map((value) => toNumber(value))
+        .filter((value) => value !== null);
+    if (numeric.length === 0)
+        return null;
+    const avg = numeric.reduce((sum, value) => sum + value, 0) / numeric.length;
+    return Math.round(avg);
+}
+export function getCategoryScore(scores, key) {
+    if (!scores)
+        return null;
+    return toNumber(scores[key]);
+}
+// ============================================================================
+// Markdown formatters
+// ============================================================================
+export function formatScoresTable(scores) {
+    if (!scores)
+        return "No scores available.";
+    const entries = Object.entries(scores).filter(([, value]) => typeof value === "number");
+    if (entries.length === 0)
+        return "No scores available.";
+    const lines = ["| Category | Score |", "| --- | --- |"];
+    for (const [key, value] of entries) {
+        lines.push(`| ${key} | ${value} |`);
+    }
+    return lines.join("\n");
+}
+export function formatIssuesList(issues, limit = 5) {
+    if (!issues.length)
+        return "No issues.";
+    const lines = issues.slice(0, limit).map((issue, index) => {
+        const label = issue.title || issue.id || "Issue";
+        const severity = issue.severity ? issue.severity.toUpperCase() : "INFO";
+        return `${index + 1}. [${severity}] ${label}`;
+    });
+    if (issues.length > limit) {
+        lines.push(`...and ${issues.length - limit} more`);
+    }
+    return lines.join("\n");
+}
+export function formatAuditMarkdown(result) {
+    const status = result.status || "unknown";
+    const lines = [`## Audit Results`, `- Status: ${status}`];
+    if (result.job_id)
+        lines.push(`- Job ID: ${result.job_id}`);
+    if (result.url)
+        lines.push(`- URL: ${result.url}`);
+    if (result.mode)
+        lines.push(`- Mode: ${result.mode}`);
+    if (typeof result.progress === "number" && status !== "completed") {
+        lines.push(`- Progress: ${result.progress}%`);
+    }
+    if (status !== "completed")
+        return lines.join("\n");
+    const overall = getOverallScore(result.scores);
+    if (overall !== null)
+        lines.push(`- Overall score: ${boldColor(String(overall), scoreColor(overall))}`);
+    lines.push("\n### Scores");
+    lines.push(formatScoresTable(result.scores));
+    const issues = normalizeIssues(result.issues);
+    lines.push("\n### Issues");
+    lines.push(`Total issues: ${issues.length}`);
+    lines.push(formatIssuesList(issues));
+    return lines.join("\n");
+}
+export function formatA11yMarkdown(result) {
+    const lines = [`## Accessibility Audit`, `- Status: ${result.status || "unknown"}`];
+    if (result.url)
+        lines.push(`- URL: ${result.url}`);
+    if (result.mode)
+        lines.push(`- Mode: ${result.mode}`);
+    if (result.status !== "completed")
+        return lines.join("\n");
+    const a11yScore = getCategoryScore(result.scores, "accessibility");
+    if (a11yScore !== null)
+        lines.push(`- Accessibility score: ${boldColor(String(a11yScore), scoreColor(a11yScore))}`);
+    const issues = normalizeIssues(result.issues).filter((issue) => {
+        const category = (issue.category || "").toLowerCase();
+        return (category.includes("accessibility") ||
+            category.includes("a11y") ||
+            category.includes("wcag"));
+    });
+    lines.push("\n### Accessibility Issues");
+    lines.push(`Total accessibility issues: ${issues.length}`);
+    lines.push(formatIssuesList(issues));
+    return lines.join("\n");
+}
+export function formatCompareMarkdown(compare) {
+    const lines = ["## Audit Comparison"];
+    lines.push(`- URL A: ${compare.urlA}`);
+    lines.push(`- URL B: ${compare.urlB}`);
+    lines.push(`- Job A: ${compare.jobA}`);
+    lines.push(`- Job B: ${compare.jobB}`);
+    lines.push("\n### Overall Scores");
+    lines.push("| Site | Score | Delta |");
+    lines.push("| --- | --- | --- |");
+    lines.push(`| A | ${compare.overallA !== null ? boldColor(String(compare.overallA), scoreColor(compare.overallA)) : "n/a"} | ${compare.delta ?? "n/a"} |`);
+    lines.push(`| B | ${compare.overallB !== null ? boldColor(String(compare.overallB), scoreColor(compare.overallB)) : "n/a"} | ${compare.delta ?? "n/a"} |`);
+    lines.push("\n### Category Scores");
+    lines.push("| Category | A | B | Delta |");
+    lines.push("| --- | --- | --- | --- |");
+    for (const [key, values] of Object.entries(compare.categoryDeltas)) {
+        lines.push(`| ${key} | ${values.a ?? "n/a"} | ${values.b ?? "n/a"} | ${values.delta ?? "n/a"} |`);
+    }
+    lines.push("\n### Issue Counts");
+    lines.push(`- A: ${compare.issuesA}`);
+    lines.push(`- B: ${compare.issuesB}`);
+    return lines.join("\n");
+}
+export function formatExplainMarkdown(issue) {
+    const lines = ["## Issue Explanation"];
+    if (issue.id)
+        lines.push(`- ID: ${issue.id}`);
+    if (issue.severity)
+        lines.push(`- Severity: ${issue.severity}`);
+    if (issue.category)
+        lines.push(`- Category: ${issue.category}`);
+    if (issue.selector)
+        lines.push(`- Selector: ${issue.selector}`);
+    if (issue.description) {
+        lines.push("\n### Description");
+        lines.push(issue.description);
+    }
+    const recommendation = issue.recommendation || issue.recommended_fix;
+    if (recommendation) {
+        lines.push("\n### Recommendation");
+        lines.push(recommendation);
+    }
+    if (issue.wcag_reference) {
+        lines.push("\n### WCAG Reference");
+        lines.push(issue.wcag_reference);
+    }
+    return lines.join("\n");
+}
+export function formatPatchMarkdown(patch) {
+    if (!patch)
+        return "No patch generated.";
+    const lines = [
+        "## Patch Generated",
+        "",
+        `**Confidence:** ${patch.confidence.label} (${patch.confidence.percentage}%)`,
+        `**Classification:** ${patch.classification}`,
+        "",
+        "### Explanation",
+        patch.explanation,
+        "",
+        "### Search",
+        "```",
+        patch.search,
+        "```",
+        "",
+        "### Replace",
+        "```",
+        patch.replace,
+        "```",
+    ];
+    return lines.join("\n");
+}
+export function formatVerifyMarkdown(result) {
+    if (!result.success || !result.verification) {
+        return `## Verification Failed\n\n${result.error?.message || "Unknown error"}`;
+    }
+    const v = result.verification;
+    const deltaSign = v.score_delta.delta >= 0 ? "+" : "";
+    const lines = [
+        "## Verification Result",
+        "",
+        `**Issue Fixed:** ${v.issue_fixed ? "Yes" : "No"}`,
+        `**Score Delta:** ${boldColor(String(v.score_delta.before), scoreColor(v.score_delta.before))} -> ${boldColor(String(v.score_delta.after), scoreColor(v.score_delta.after))} (${deltaSign}${v.score_delta.delta})`,
+        `**Component:** ${v.component_audited}`,
+        `**Duration:** ${v.duration_ms}ms`,
+    ];
+    if (v.regressions.length > 0) {
+        lines.push("", "### Regressions");
+        for (const r of v.regressions) {
+            lines.push(`- [${r.impact.toUpperCase()}] ${r.rule_id}: ${r.description}`);
+        }
+    }
+    else {
+        lines.push("", "### Regressions", "None");
+    }
+    if (v.error) {
+        lines.push("", `**Warning:** ${v.error}`);
+    }
+    return lines.join("\n");
+}
+// Auto-fixable issue types (from lib/patch/classifier.ts)
+const AUTO_FIXABLE_TYPES = new Set([
+    "label",
+    "input-missing-label",
+    "form-field-label",
+    "button-name",
+    "missing-button-name",
+    "link-name",
+    "html-has-lang",
+    "missing-lang-attribute",
+    "html-lang-valid",
+    "document-title",
+    "bypass",
+    "region",
+    "landmark-one-main",
+    "color-contrast",
+    "autocomplete-valid",
+    "aria-required-attr",
+    "aria-valid-attr",
+    "aria-valid-attr-value",
+]);
+export function isAutoFixable(issueType) {
+    const normalized = issueType.toLowerCase().replace(/^(axe|wcag)-/, "");
+    return AUTO_FIXABLE_TYPES.has(normalized);
+}
+export function formatBatchMarkdown(results) {
+    const lines = [
+        "## Batch Patch Results",
+        "",
+        `**Total Requested:** ${results.totalRequested}`,
+        `**Succeeded:** ${results.successes.length}`,
+        `**Failed:** ${results.failures.length}`,
+        `**Skipped:** ${results.totalSkipped}`,
+    ];
+    if (results.successes.length > 0) {
+        lines.push("", "### Successful Patches");
+        for (const s of results.successes) {
+            const conf = s.patch?.confidence;
+            const cls = s.patch?.classification || "unknown";
+            const confStr = conf ? `${conf.label} (${conf.percentage}%)` : "n/a";
+            lines.push(`- ${s.issueId}: ${confStr} [${cls}]`);
+        }
+    }
+    if (results.failures.length > 0) {
+        lines.push("", "### Failed");
+        for (const f of results.failures) {
+            const details = f.details ? ` - ${f.details}` : "";
+            lines.push(`- ${f.issueId}: ${f.reason}${details}`);
+        }
+    }
+    return lines.join("\n");
+}
+export function printOutput(format, data, markdown) {
+    if (format === "json") {
+        process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+        return;
+    }
+    // Route through writeOutput so interactive mode can buffer the output
+    writeOutput(markdown || "");
+}

package/dist/utils/local-capture.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Local page capture for localhost/private URL auditing.
+ *
+ * Fetches HTML content from a local URL using Node's native fetch,
+ * so the CLI can send pre-captured content to the cloud API for analysis.
+ */
+export interface CapturedPage {
+    html: string;
+    url: string;
+    statusCode: number;
+    headers: Record<string, string>;
+    fetchTimeMs: number;
+}
+/**
+ * Fetch a local/private URL and capture its rendered HTML.
+ *
+ * @param url - The local URL to capture (e.g., http://localhost:3000/)
+ * @param options - Optional configuration
+ * @returns Captured page content and metadata
+ * @throws Error with user-friendly message on connection failures
+ */
+export declare function captureLocalPage(url: string, options?: {
+    timeoutMs?: number;
+}): Promise<CapturedPage>;
+//# sourceMappingURL=local-capture.d.ts.map

package/dist/utils/local-capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-capture.d.ts","sourceRoot":"","sources":["../../src/utils/local-capture.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/B,OAAO,CAAC,YAAY,CAAC,CAmDvB"}

package/dist/utils/local-capture.js

@@ -0,0 +1,57 @@
+/**
+ * Local page capture for localhost/private URL auditing.
+ *
+ * Fetches HTML content from a local URL using Node's native fetch,
+ * so the CLI can send pre-captured content to the cloud API for analysis.
+ */
+/**
+ * Fetch a local/private URL and capture its rendered HTML.
+ *
+ * @param url - The local URL to capture (e.g., http://localhost:3000/)
+ * @param options - Optional configuration
+ * @returns Captured page content and metadata
+ * @throws Error with user-friendly message on connection failures
+ */
+export async function captureLocalPage(url, options) {
+    const timeoutMs = options?.timeoutMs ?? 15_000;
+    const start = Date.now();
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, {
+            signal: controller.signal,
+            headers: {
+                "User-Agent": "VertaaUX-CLI (local-capture)",
+                Accept: "text/html,application/xhtml+xml,*/*",
+            },
+            redirect: "follow",
+        });
+        const html = await response.text();
+        const headers = {};
+        response.headers.forEach((value, key) => {
+            headers[key] = value;
+        });
+        return {
+            html,
+            url,
+            statusCode: response.status,
+            headers,
+            fetchTimeMs: Date.now() - start,
+        };
+    }
+    catch (err) {
+        if (err instanceof DOMException && err.name === "AbortError") {
+            throw new Error(`Timed out after ${timeoutMs}ms trying to reach ${url}. ` +
+                "Ensure your local server is running and responsive.");
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes("ECONNREFUSED")) {
+            throw new Error(`Connection refused at ${url}. ` +
+                "Ensure your local development server is running.");
+        }
+        throw new Error(`Failed to capture local page at ${url}: ${message}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/utils/url-classify.d.ts

@@ -0,0 +1,18 @@
+/**
+ * URL classification for local vs. public URLs.
+ *
+ * Mirrors the SSRF guard logic from lib/ssrf.ts on the client side
+ * to determine routing strategy (cloud API vs local capture).
+ */
+export type UrlKind = "public" | "localhost" | "private";
+/**
+ * Classify a URL as public, localhost, or private-network.
+ * Used to decide whether the CLI should capture the page locally.
+ */
+export declare function classifyUrl(urlString: string): UrlKind;
+/**
+ * Check if a URL points to a local or private address
+ * (unreachable from the cloud API).
+ */
+export declare function isLocalUrl(urlString: string): boolean;
+//# sourceMappingURL=url-classify.d.ts.map

package/dist/utils/url-classify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-classify.d.ts","sourceRoot":"","sources":["../../src/utils/url-classify.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAC;AAEzD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CA8BtD;AAgED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAGrD"}

package/dist/utils/url-classify.js

@@ -0,0 +1,106 @@
+/**
+ * URL classification for local vs. public URLs.
+ *
+ * Mirrors the SSRF guard logic from lib/ssrf.ts on the client side
+ * to determine routing strategy (cloud API vs local capture).
+ */
+import net from "net";
+/**
+ * Classify a URL as public, localhost, or private-network.
+ * Used to decide whether the CLI should capture the page locally.
+ */
+export function classifyUrl(urlString) {
+    let parsed;
+    try {
+        parsed = new URL(urlString);
+    }
+    catch {
+        return "public"; // Let the API decide for malformed URLs
+    }
+    const hostname = parsed.hostname.toLowerCase();
+    // Localhost variants (URL parser keeps brackets on IPv6)
+    if (hostname === "localhost" ||
+        hostname === "::1" ||
+        hostname === "[::1]" ||
+        hostname.endsWith(".localhost")) {
+        return "localhost";
+    }
+    // IP literal check — strip brackets from IPv6 literals
+    const ip = hostname.startsWith("[") && hostname.endsWith("]")
+        ? hostname.slice(1, -1)
+        : hostname;
+    if (net.isIP(ip)) {
+        if (isPrivateIp(ip))
+            return "private";
+        return "public";
+    }
+    return "public";
+}
+/**
+ * Check common private/reserved IPv4 ranges.
+ */
+function isPrivateIp(address) {
+    const version = net.isIP(address);
+    if (version === 6) {
+        const lower = address.toLowerCase();
+        // IPv4-mapped IPv6 — extract and check as IPv4
+        // Handles both dotted form (::ffff:127.0.0.1) and hex form (::ffff:7f00:1)
+        if (lower.startsWith("::ffff:")) {
+            const mapped = lower.slice(7); // strip "::ffff:"
+            if (net.isIPv4(mapped)) {
+                return isPrivateIp(mapped);
+            }
+            // Hex form: two 16-bit groups (e.g. "7f00:1" = 127.0.0.1)
+            const hexParts = mapped.split(":");
+            if (hexParts.length === 2) {
+                const hi = parseInt(hexParts[0], 16);
+                const lo = parseInt(hexParts[1], 16);
+                if (!isNaN(hi) && !isNaN(lo) && hi <= 0xffff && lo <= 0xffff) {
+                    const ipv4 = `${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`;
+                    return isPrivateIp(ipv4);
+                }
+            }
+        }
+        return (lower === "::" ||
+            lower === "::1" ||
+            lower.startsWith("fc") ||
+            lower.startsWith("fd") ||
+            lower.startsWith("fe8") ||
+            lower.startsWith("fe9") ||
+            lower.startsWith("fea") ||
+            lower.startsWith("feb"));
+    }
+    if (version !== 4)
+        return false;
+    const parts = address.split(".").map(Number);
+    if (parts.length !== 4 || parts.some((n) => !Number.isFinite(n)))
+        return false;
+    const [a, b] = parts;
+    // 127.0.0.0/8 — loopback
+    if (a === 127)
+        return true;
+    // 10.0.0.0/8
+    if (a === 10)
+        return true;
+    // 172.16.0.0/12
+    if (a === 172 && b >= 16 && b <= 31)
+        return true;
+    // 192.168.0.0/16
+    if (a === 192 && b === 168)
+        return true;
+    // 169.254.0.0/16 — link-local
+    if (a === 169 && b === 254)
+        return true;
+    // 0.0.0.0/8
+    if (a === 0)
+        return true;
+    return false;
+}
+/**
+ * Check if a URL points to a local or private address
+ * (unreachable from the cloud API).
+ */
+export function isLocalUrl(urlString) {
+    const kind = classifyUrl(urlString);
+    return kind === "localhost" || kind === "private";
+}