apex-auditor 0.2.9 → 0.3.0

package/README.md

@@ -87,6 +87,7 @@ apex-auditor audit --config apex.config.json
 | `--warm-up` | Perform warm-up requests before auditing |
 | `--open` | Auto-open HTML report in browser after audit |
 | `--json` | Output JSON to stdout (for piping) |
+| `--show-parallel` | Print the resolved parallel worker count before running |
 | `--mobile-only` | Only audit mobile device configurations |
 | `--desktop-only` | Only audit desktop device configurations |
 
@@ -97,8 +98,8 @@ apex-auditor audit --config apex.config.json
 After each audit, results are saved to `.apex-auditor/`:
 
 - `summary.json` – structured JSON results
-- `summary.md` – Markdown table
-- `report.html` – visual HTML report with score circles and metrics
+- `summary.md` – Markdown table plus a structured meta section (parallel, timings, throttling)
+- `report.html` – visual HTML report with score circles, metrics, and a meta grid (resolved parallel, elapsed, avg/step)
 
 ---
 

package/dist/bin.js

@@ -35,6 +35,8 @@ function printHelp() {
         "  --log-level <lvl>  Override Lighthouse log level: silent|error|info|verbose",
         "  --mobile-only      Run audits only for 'mobile' devices defined in the config",
         "  --desktop-only     Run audits only for 'desktop' devices defined in the config",
+        "  --parallel <n>     Override parallel workers (1-10). Default auto-tunes from CPU/memory.",
+        "  --show-parallel    Print the resolved parallel workers before running.",
     ].join("\n"));
 }
 export async function runBin(argv) {

package/dist/cli.js

@@ -31,6 +31,7 @@ function parseArgs(argv) {
     let openReport = false;
     let warmUp = false;
     let jsonOutput = false;
+    let showParallel = false;
     for (let i = 2; i < argv.length; i += 1) {
         const arg = argv[i];
         if ((arg === "--config" || arg === "-c") && i + 1 < argv.length) {
@@ -103,9 +104,12 @@ function parseArgs(argv) {
         else if (arg === "--json") {
             jsonOutput = true;
         }
+        else if (arg === "--show-parallel") {
+            showParallel = true;
+        }
     }
     const finalConfigPath = configPath ?? "apex.config.json";
-    return { configPath: finalConfigPath, ci, colorMode, logLevelOverride, deviceFilter, throttlingMethodOverride, cpuSlowdownOverride, parallelOverride, openReport, warmUp, jsonOutput };
+    return { configPath: finalConfigPath, ci, colorMode, logLevelOverride, deviceFilter, throttlingMethodOverride, cpuSlowdownOverride, parallelOverride, openReport, warmUp, jsonOutput, showParallel };
 }
 /**
  * Runs the ApexAuditor audit CLI.
@@ -136,13 +140,13 @@ export async function runAuditCli(argv) {
         process.exitCode = 1;
         return;
     }
-    const summary = await runAuditsForConfig({ config: filteredConfig, configPath });
+    const summary = await runAuditsForConfig({ config: filteredConfig, configPath, showParallel: args.showParallel });
     const outputDir = resolve(".apex-auditor");
     await mkdir(outputDir, { recursive: true });
     await writeFile(resolve(outputDir, "summary.json"), JSON.stringify(summary, null, 2), "utf8");
-    const markdown = buildMarkdown(summary.results);
+    const markdown = buildMarkdown(summary);
     await writeFile(resolve(outputDir, "summary.md"), markdown, "utf8");
-    const html = buildHtmlReport(summary.results, summary.configPath);
+    const html = buildHtmlReport(summary);
     const reportPath = resolve(outputDir, "report.html");
     await writeFile(reportPath, html, "utf8");
     // Open HTML report in browser if requested
@@ -160,6 +164,7 @@ export async function runAuditCli(argv) {
     const consoleTable = buildConsoleTable(summary.results, useColor);
     // eslint-disable-next-line no-console
     console.log(consoleTable);
+    printRunMeta(summary.meta, useColor);
     printSummaryStats(summary.results, useColor);
     printRedIssues(summary.results);
     printCiSummary(args, summary.results, effectiveConfig.budgets);
@@ -195,15 +200,34 @@ function filterPageDevices(page, deviceFilter) {
         devices,
     };
 }
-function buildMarkdown(results) {
+function buildMarkdown(summary) {
+    const meta = summary.meta;
+    const metaTable = [
+        "| Field | Value |",
+        "|-------|-------|",
+        `| Config | ${meta.configPath} |`,
+        `| Resolved parallel | ${meta.resolvedParallel} |`,
+        `| Warm-up | ${meta.warmUp ? "yes" : "no"} |`,
+        `| Throttling | ${meta.throttlingMethod} |`,
+        `| CPU slowdown | ${meta.cpuSlowdownMultiplier} |`,
+        `| Combos | ${meta.comboCount} |`,
+        `| Runs per combo | ${meta.runsPerCombo} |`,
+        `| Total steps | ${meta.totalSteps} |`,
+        `| Started | ${meta.startedAt} |`,
+        `| Completed | ${meta.completedAt} |`,
+        `| Elapsed | ${formatElapsedTime(meta.elapsedMs)} |`,
+        `| Avg per step | ${formatElapsedTime(meta.averageStepMs)} |`,
+    ].join("\n");
     const header = [
         "| Label | Path | Device | P | A | BP | SEO | LCP (s) | FCP (s) | TBT (ms) | CLS | INP (ms) | Error | Top issues |",
         "|-------|------|--------|---|---|----|-----|---------|---------|----------|-----|----------|-------|-----------|",
     ].join("\n");
-    const lines = results.map((result) => buildRow(result));
-    return `${header}\n${lines.join("\n")}`;
+    const lines = summary.results.map((result) => buildRow(result));
+    return `${metaTable}\n\n${header}\n${lines.join("\n")}`;
 }
-function buildHtmlReport(results, configPath) {
+function buildHtmlReport(summary) {
+    const results = summary.results;
+    const meta = summary.meta;
     const timestamp = new Date().toISOString();
     const rows = results.map((result) => buildHtmlRow(result)).join("\n");
     return `<!DOCTYPE html>
@@ -218,6 +242,10 @@ function buildHtmlReport(results, configPath) {
     body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: var(--bg); color: var(--text); padding: 2rem; }
     h1 { margin-bottom: 0.5rem; }
     .meta { color: #888; margin-bottom: 2rem; font-size: 0.9rem; }
+    .meta-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); gap: 1rem; margin-bottom: 2rem; }
+    .meta-card { background: #16213e; border-radius: 10px; padding: 1rem; border: 1px solid #23304f; }
+    .meta-label { font-size: 0.8rem; color: #9ca3af; text-transform: uppercase; letter-spacing: 0.04em; }
+    .meta-value { font-size: 1rem; font-weight: 600; color: #e5e7eb; }
     .cards { display: grid; gap: 1.5rem; }
     .card { background: var(--card); border-radius: 12px; padding: 1.5rem; }
     .card-header { display: flex; justify-content: space-between; align-items: center; margin-bottom: 1rem; border-bottom: 1px solid #333; padding-bottom: 1rem; }
@@ -246,7 +274,21 @@ function buildHtmlReport(results, configPath) {
 </head>
 <body>
   <h1>ApexAuditor Report</h1>
-  <p class="meta">Generated: ${timestamp} | Config: ${escapeHtml(configPath)}</p>
+  <p class="meta">Generated: ${timestamp}</p>
+  <div class="meta-grid">
+    ${buildMetaCard("Config", escapeHtml(meta.configPath))}
+    ${buildMetaCard("Resolved parallel", meta.resolvedParallel.toString())}
+    ${buildMetaCard("Warm-up", meta.warmUp ? "Yes" : "No")}
+    ${buildMetaCard("Throttling", meta.throttlingMethod)}
+    ${buildMetaCard("CPU slowdown", meta.cpuSlowdownMultiplier.toString())}
+    ${buildMetaCard("Combos", meta.comboCount.toString())}
+    ${buildMetaCard("Runs per combo", meta.runsPerCombo.toString())}
+    ${buildMetaCard("Total steps", meta.totalSteps.toString())}
+    ${buildMetaCard("Elapsed", formatElapsedTime(meta.elapsedMs))}
+    ${buildMetaCard("Avg / step", formatElapsedTime(meta.averageStepMs))}
+    ${buildMetaCard("Started", meta.startedAt)}
+    ${buildMetaCard("Completed", meta.completedAt)}
+  </div>
   <div class="cards">
 ${rows}
   </div>
@@ -291,6 +333,30 @@ function buildScoreCircle(label, score) {
 function buildMetricBox(label, value, colorClass) {
     return `<div class="metric"><div class="metric-value ${colorClass}">${value}</div><div class="metric-label">${label}</div></div>`;
 }
+function buildMetaCard(label, value) {
+    return `<div class="meta-card"><div class="meta-label">${escapeHtml(label)}</div><div class="meta-value">${escapeHtml(value)}</div></div>`;
+}
+function printRunMeta(meta, useColor) {
+    const rows = [
+        { label: "Resolved parallel", value: meta.resolvedParallel.toString() },
+        { label: "Warm-up", value: meta.warmUp ? "Yes" : "No" },
+        { label: "Throttling", value: meta.throttlingMethod },
+        { label: "CPU slowdown", value: meta.cpuSlowdownMultiplier.toString() },
+        { label: "Combos", value: meta.comboCount.toString() },
+        { label: "Runs per combo", value: meta.runsPerCombo.toString() },
+        { label: "Total steps", value: meta.totalSteps.toString() },
+        { label: "Elapsed", value: formatElapsedTime(meta.elapsedMs) },
+        { label: "Avg / step", value: formatElapsedTime(meta.averageStepMs) },
+    ];
+    const padLabel = (label) => label.padEnd(16, " ");
+    // eslint-disable-next-line no-console
+    console.log("\nMeta:");
+    for (const row of rows) {
+        const value = useColor ? `${ANSI_CYAN}${row.value}${ANSI_RESET}` : row.value;
+        // eslint-disable-next-line no-console
+        console.log(`  ${padLabel(row.label)} ${value}`);
+    }
+}
 function getMetricClass(value, good, warn) {
     if (value === undefined)
         return "";

package/dist/lighthouse-runner.js

@@ -1,5 +1,6 @@
 import { request as httpRequest } from "node:http";
 import { request as httpsRequest } from "node:https";
+import { cpus, freemem } from "node:os";
 import lighthouse from "lighthouse";
 import { launch as launchChrome } from "chrome-launcher";
 async function createChromeSession(chromePort) {
@@ -112,9 +113,8 @@ async function fetchUrl(url) {
 /**
  * Run audits for all pages defined in the config and return a structured summary.
  */
-export async function runAuditsForConfig({ config, configPath, }) {
+export async function runAuditsForConfig({ config, configPath, showParallel, }) {
     const runs = config.runs ?? 1;
-    const parallelCount = config.parallel ?? 1;
     const firstPage = config.pages[0];
     const healthCheckUrl = buildUrl({ baseUrl: config.baseUrl, path: firstPage.path, query: config.query });
     await ensureUrlReachable(healthCheckUrl);
@@ -142,13 +142,20 @@ export async function runAuditsForConfig({ config, configPath, }) {
             });
         }
     }
+    const startedAtMs = Date.now();
+    const parallelCount = resolveParallelCount({ requested: config.parallel, chromePort: config.chromePort, taskCount: tasks.length });
+    if (showParallel === true) {
+        // eslint-disable-next-line no-console
+        console.log(`Resolved parallel workers: ${parallelCount}`);
+    }
     const totalSteps = tasks.length * runs;
     let completedSteps = 0;
     const progressLock = { count: 0 };
     const updateProgress = (path, device) => {
         progressLock.count += 1;
         completedSteps = progressLock.count;
-        logProgress({ completed: completedSteps, total: totalSteps, path, device });
+        const etaMs = computeEtaMs({ startedAtMs, completed: completedSteps, total: totalSteps });
+        logProgress({ completed: completedSteps, total: totalSteps, path, device, etaMs });
     };
     let results;
     if (parallelCount <= 1 || config.chromePort !== undefined) {
@@ -159,7 +166,26 @@ export async function runAuditsForConfig({ config, configPath, }) {
         // Parallel execution with multiple Chrome instances
         results = await runParallel(tasks, parallelCount, updateProgress);
     }
-    return { configPath, results };
+    const completedAtMs = Date.now();
+    const elapsedMs = completedAtMs - startedAtMs;
+    const averageStepMs = totalSteps > 0 ? elapsedMs / totalSteps : 0;
+    return {
+        meta: {
+            configPath,
+            resolvedParallel: parallelCount,
+            totalSteps,
+            comboCount: tasks.length,
+            runsPerCombo: runs,
+            warmUp: config.warmUp === true,
+            throttlingMethod,
+            cpuSlowdownMultiplier,
+            startedAt: new Date(startedAtMs).toISOString(),
+            completedAt: new Date(completedAtMs).toISOString(),
+            elapsedMs,
+            averageStepMs,
+        },
+        results,
+    };
 }
 async function runSequential(tasks, chromePort, updateProgress) {
     const results = [];
@@ -242,9 +268,10 @@ function buildUrl({ baseUrl, path, query }) {
     const queryPart = query && query.length > 0 ? query : "";
     return `${cleanBase}${cleanPath}${queryPart}`;
 }
-function logProgress({ completed, total, path, device, }) {
+function logProgress({ completed, total, path, device, etaMs, }) {
     const percentage = total > 0 ? Math.round((completed / total) * 100) : 0;
-    const message = `Running audits ${completed}/${total} (${percentage}%) – ${path} [${device}]`;
+    const etaText = etaMs !== undefined ? ` | ETA ${formatEta(etaMs)}` : "";
+    const message = `Running audits ${completed}/${total} (${percentage}%) – ${path} [${device}]${etaText}`;
     if (typeof process !== "undefined" && process.stdout && typeof process.stdout.write === "function" && process.stdout.isTTY) {
         const padded = message.padEnd(80, " ");
         process.stdout.write(`\r${padded}`);
@@ -395,3 +422,32 @@ function averageOf(values) {
     const total = defined.reduce((sum, value) => sum + value, 0);
     return total / defined.length;
 }
+function resolveParallelCount({ requested, chromePort, taskCount, }) {
+    if (chromePort !== undefined) {
+        return 1;
+    }
+    if (requested !== undefined) {
+        return requested;
+    }
+    const cpuBased = Math.max(1, Math.min(6, Math.floor(cpus().length / 2)));
+    const memoryBased = Math.max(1, Math.min(6, Math.floor(freemem() / 1_500_000_000)));
+    const suggested = Math.max(1, Math.min(cpuBased, memoryBased));
+    return Math.max(1, Math.min(10, Math.min(taskCount, suggested || 1)));
+}
+function computeEtaMs({ startedAtMs, completed, total, }) {
+    if (completed === 0 || total === 0 || completed > total) {
+        return undefined;
+    }
+    const elapsedMs = Date.now() - startedAtMs;
+    const averagePerStep = elapsedMs / completed;
+    const remainingSteps = total - completed;
+    return Math.max(0, Math.round(averagePerStep * remainingSteps));
+}
+function formatEta(etaMs) {
+    const totalSeconds = Math.ceil(etaMs / 1000);
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    const minutesPart = minutes > 0 ? `${minutes}m ` : "";
+    const secondsPart = `${seconds}s`;
+    return `${minutesPart}${secondsPart}`.trim();
+}

package/dist/wizard-cli.js

@@ -278,6 +278,7 @@ function convertRouteToPage(route) {
 async function buildConfig() {
     const profileAnswer = await ask(profileQuestion);
     const baseAnswers = await collectBaseAnswers();
+    console.log("Tip: parallel workers auto-tune from CPU/memory. Override later with --parallel <n> or inspect with --show-parallel.");
     const detectedPages = await maybeDetectPages(profileAnswer.profile);
     const pages = await collectPages(detectedPages);
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apex-auditor",
-  "version": "0.2.9",
+  "version": "0.3.0",
   "private": false,
   "description": "CLI to run structured Lighthouse audits (Performance, Accessibility, Best Practices, SEO) across routes.",
   "type": "module",