apex-auditor 0.1.6 → 0.2.0

package/dist/bin.js

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 import { runAuditCli } from "./cli.js";
 import { runWizardCli } from "./wizard-cli.js";
+import { runQuickstartCli } from "./quickstart-cli.js";
 function parseBinArgs(argv) {
     const rawCommand = argv[2];
     if (rawCommand === undefined || rawCommand === "help" || rawCommand === "--help" || rawCommand === "-h") {
         return { command: "help", argv };
     }
-    if (rawCommand === "audit" || rawCommand === "wizard") {
+    if (rawCommand === "audit" || rawCommand === "wizard" || rawCommand === "quickstart") {
         const commandArgv = ["node", "apex-auditor", ...argv.slice(3)];
         return { command: rawCommand, argv: commandArgv };
     }
@@ -17,13 +18,21 @@ function printHelp() {
         "ApexAuditor CLI",
         "",
         "Usage:",
+        "  apex-auditor quickstart --base-url <url> [--project-root <path>]",
         "  apex-auditor wizard [--config <path>]",
-        "  apex-auditor audit [--config <path>]",
+        "  apex-auditor audit [--config <path>] [--ci] [--no-color|--color] [--log-level <level>]",
         "",
         "Commands:",
+        "  quickstart  Detect routes and run a one-off audit with sensible defaults",
         "  wizard   Run interactive config wizard",
         "  audit    Run Lighthouse audits using apex.config.json",
         "  help     Show this help message",
+        "",
+        "Options (audit):",
+        "  --ci               Enable CI mode with budgets and non-zero exit code on failure",
+        "  --no-color         Disable ANSI colours in console output (default in CI mode)",
+        "  --color            Force ANSI colours in console output",
+        "  --log-level <lvl>  Override Lighthouse log level: silent|error|info|verbose",
     ].join("\n"));
 }
 export async function runBin(argv) {
@@ -32,6 +41,10 @@ export async function runBin(argv) {
         printHelp();
         return;
     }
+    if (parsed.command === "quickstart") {
+        await runQuickstartCli(parsed.argv);
+        return;
+    }
     if (parsed.command === "audit") {
         await runAuditCli(parsed.argv);
         return;

package/dist/cli.js

@@ -8,15 +8,37 @@ const ANSI_YELLOW = "\u001B[33m";
 const ANSI_GREEN = "\u001B[32m";
 function parseArgs(argv) {
     let configPath;
+    let ci = false;
+    let colorMode = "auto";
+    let logLevelOverride;
     for (let i = 2; i < argv.length; i += 1) {
         const arg = argv[i];
         if ((arg === "--config" || arg === "-c") && i + 1 < argv.length) {
             configPath = argv[i + 1];
             i += 1;
         }
+        else if (arg === "--ci") {
+            ci = true;
+        }
+        else if (arg === "--no-color") {
+            colorMode = "off";
+        }
+        else if (arg === "--color") {
+            colorMode = "on";
+        }
+        else if (arg === "--log-level" && i + 1 < argv.length) {
+            const value = argv[i + 1];
+            if (value === "silent" || value === "error" || value === "info" || value === "verbose") {
+                logLevelOverride = value;
+            }
+            else {
+                throw new Error(`Invalid --log-level value: ${value}`);
+            }
+            i += 1;
+        }
     }
     const finalConfigPath = configPath ?? "apex.config.json";
-    return { configPath: finalConfigPath };
+    return { configPath: finalConfigPath, ci, colorMode, logLevelOverride };
 }
 /**
  * Runs the ApexAuditor audit CLI.
@@ -26,17 +48,24 @@ function parseArgs(argv) {
 export async function runAuditCli(argv) {
     const args = parseArgs(argv);
     const { configPath, config } = await loadConfig({ configPath: args.configPath });
-    const summary = await runAuditsForConfig({ config, configPath });
+    const effectiveLogLevel = args.logLevelOverride ?? config.logLevel;
+    const effectiveConfig = {
+        ...config,
+        logLevel: effectiveLogLevel,
+    };
+    const summary = await runAuditsForConfig({ config: effectiveConfig, configPath });
     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);
     await writeFile(resolve(outputDir, "summary.md"), markdown, "utf8");
     // Also echo a compact, colourised table to stdout for quick viewing.
-    const consoleTable = buildConsoleTable(summary.results);
+    const useColor = shouldUseColor(args.ci, args.colorMode);
+    const consoleTable = buildConsoleTable(summary.results, useColor);
     // eslint-disable-next-line no-console
     console.log(consoleTable);
     printRedIssues(summary.results);
+    printCiSummary(args, summary.results, effectiveConfig.budgets);
 }
 function buildMarkdown(results) {
     const header = [
@@ -46,12 +75,12 @@ function buildMarkdown(results) {
     const lines = results.map((result) => buildRow(result));
     return `${header}\n${lines.join("\n")}`;
 }
-function buildConsoleTable(results) {
+function buildConsoleTable(results, useColor) {
     const header = [
         "| Label | Path | Device | P | A | BP | SEO | LCP (s) | FCP (s) | TBT (ms) | CLS | Error | Top issues |",
         "|-------|------|--------|---|---|----|-----|---------|---------|----------|-----|-------|-----------|",
     ].join("\n");
-    const lines = results.map((result) => buildConsoleRow(result));
+    const lines = results.map((result) => buildConsoleRow(result, useColor));
     return `${header}\n${lines.join("\n")}`;
 }
 function buildRow(result) {
@@ -65,7 +94,7 @@ function buildRow(result) {
     const error = result.runtimeErrorCode ?? (result.runtimeErrorMessage !== undefined ? result.runtimeErrorMessage : "");
     return `| ${result.label} | ${result.path} | ${result.device} | ${scores.performance ?? "-"} | ${scores.accessibility ?? "-"} | ${scores.bestPractices ?? "-"} | ${scores.seo ?? "-"} | ${lcpSeconds} | ${fcpSeconds} | ${tbtMs} | ${cls} | ${error} | ${issues} |`;
 }
-function buildConsoleRow(result) {
+function buildConsoleRow(result, useColor) {
     const scores = result.scores;
     const metrics = result.metrics;
     const lcpSeconds = metrics.lcpMs !== undefined ? (metrics.lcpMs / 1000).toFixed(1) : "-";
@@ -74,10 +103,10 @@ function buildConsoleRow(result) {
     const cls = metrics.cls !== undefined ? metrics.cls.toFixed(3) : "-";
     const issues = formatTopIssues(result.opportunities);
     const error = result.runtimeErrorCode ?? (result.runtimeErrorMessage !== undefined ? result.runtimeErrorMessage : "");
-    const performanceText = colourScore(scores.performance);
-    const accessibilityText = colourScore(scores.accessibility);
-    const bestPracticesText = colourScore(scores.bestPractices);
-    const seoText = colourScore(scores.seo);
+    const performanceText = colourScore(scores.performance, useColor);
+    const accessibilityText = colourScore(scores.accessibility, useColor);
+    const bestPracticesText = colourScore(scores.bestPractices, useColor);
+    const seoText = colourScore(scores.seo, useColor);
     return `| ${result.label} | ${result.path} | ${result.device} | ${performanceText} | ${accessibilityText} | ${bestPracticesText} | ${seoText} | ${lcpSeconds} | ${fcpSeconds} | ${tbtMs} | ${cls} | ${error} | ${issues} |`;
 }
 function formatTopIssues(opportunities) {
@@ -93,12 +122,15 @@ function formatTopIssues(opportunities) {
     });
     return items.join("; ");
 }
-function colourScore(score) {
+function colourScore(score, useColor) {
     if (score === undefined) {
         return "-";
     }
     const value = score;
     const text = value.toString();
+    if (!useColor) {
+        return text;
+    }
     let colour;
     if (value < 50) {
         colour = ANSI_RED;
@@ -147,3 +179,98 @@ function printRedIssues(results) {
         console.log(`- ${result.label} ${result.path} [${result.device}] – ${badParts.join(", ")} – ${issues}`);
     }
 }
+function shouldUseColor(ci, colorMode) {
+    if (colorMode === "on") {
+        return true;
+    }
+    if (colorMode === "off") {
+        return false;
+    }
+    if (ci) {
+        return false;
+    }
+    return typeof process !== "undefined" && Boolean(process.stdout && process.stdout.isTTY);
+}
+function printCiSummary(args, results, budgets) {
+    if (!args.ci) {
+        return;
+    }
+    if (!budgets) {
+        // eslint-disable-next-line no-console
+        console.log("\nCI mode: no budgets configured. Skipping threshold checks.");
+        return;
+    }
+    const violations = collectBudgetViolations(results, budgets);
+    if (violations.length === 0) {
+        // eslint-disable-next-line no-console
+        console.log("\nCI budgets PASSED.");
+        return;
+    }
+    // eslint-disable-next-line no-console
+    console.log(`\nCI budgets FAILED (${violations.length} violations):`);
+    for (const violation of violations) {
+        // eslint-disable-next-line no-console
+        console.log(`- ${violation.pageLabel} ${violation.path} [${violation.device}] – ${violation.kind} ${violation.id}: ${violation.value} vs limit ${violation.limit}`);
+    }
+    process.exitCode = 1;
+}
+function collectBudgetViolations(results, budgets) {
+    const violations = [];
+    for (const result of results) {
+        if (budgets.categories) {
+            collectCategoryViolations(result, budgets.categories, violations);
+        }
+        if (budgets.metrics) {
+            collectMetricViolations(result, budgets.metrics, violations);
+        }
+    }
+    return violations;
+}
+function collectCategoryViolations(result, categories, allViolations) {
+    const scores = result.scores;
+    addCategoryViolation("performance", scores.performance, categories.performance, result, allViolations);
+    addCategoryViolation("accessibility", scores.accessibility, categories.accessibility, result, allViolations);
+    addCategoryViolation("bestPractices", scores.bestPractices, categories.bestPractices, result, allViolations);
+    addCategoryViolation("seo", scores.seo, categories.seo, result, allViolations);
+}
+function addCategoryViolation(id, actual, limit, result, allViolations) {
+    if (limit === undefined || actual === undefined) {
+        return;
+    }
+    if (actual >= limit) {
+        return;
+    }
+    allViolations.push({
+        pageLabel: result.label,
+        path: result.path,
+        device: result.device,
+        kind: "category",
+        id,
+        value: actual,
+        limit,
+    });
+}
+function collectMetricViolations(result, metricsBudgets, allViolations) {
+    const metrics = result.metrics;
+    addMetricViolation("lcpMs", metrics.lcpMs, metricsBudgets.lcpMs, result, allViolations);
+    addMetricViolation("fcpMs", metrics.fcpMs, metricsBudgets.fcpMs, result, allViolations);
+    addMetricViolation("tbtMs", metrics.tbtMs, metricsBudgets.tbtMs, result, allViolations);
+    addMetricViolation("cls", metrics.cls, metricsBudgets.cls, result, allViolations);
+}
+function addMetricViolation(id, actual, limit, result, allViolations) {
+    if (limit === undefined || actual === undefined) {
+        return;
+    }
+    if (actual <= limit) {
+        return;
+    }
+    allViolations.push({
+        pageLabel: result.label,
+        path: result.path,
+        device: result.device,
+        kind: "metric",
+        id,
+        value: actual,
+        limit,
+    });
+}

package/dist/config.js

@@ -31,6 +31,7 @@ function normaliseConfig(input, absolutePath) {
     const logLevel = rawLogLevel === "silent" || rawLogLevel === "error" || rawLogLevel === "info" || rawLogLevel === "verbose"
         ? rawLogLevel
         : undefined;
+    const budgets = normaliseBudgets(maybeConfig.budgets, absolutePath);
     return {
         baseUrl,
         query,
@@ -38,6 +39,7 @@ function normaliseConfig(input, absolutePath) {
         runs,
         logLevel,
         pages,
+        budgets,
     };
 }
 function normalisePage(page, index, absolutePath) {
@@ -66,3 +68,86 @@ function normalisePage(page, index, absolutePath) {
         devices,
     };
 }
+function normaliseBudgets(input, absolutePath) {
+    if (input === undefined) {
+        return undefined;
+    }
+    if (!input || typeof input !== "object") {
+        throw new Error(`Invalid budgets in ${absolutePath}: expected object`);
+    }
+    const maybeBudgets = input;
+    const categories = normaliseCategoryBudgets(maybeBudgets.categories, absolutePath);
+    const metrics = normaliseMetricBudgets(maybeBudgets.metrics, absolutePath);
+    if (!categories && !metrics) {
+        return undefined;
+    }
+    return {
+        categories,
+        metrics,
+    };
+}
+function normaliseCategoryBudgets(input, absolutePath) {
+    if (input === undefined) {
+        return undefined;
+    }
+    if (!input || typeof input !== "object") {
+        throw new Error(`Invalid budgets.categories in ${absolutePath}: expected object`);
+    }
+    const maybeCategories = input;
+    const performance = normaliseScoreBudget(maybeCategories.performance, "performance", absolutePath);
+    const accessibility = normaliseScoreBudget(maybeCategories.accessibility, "accessibility", absolutePath);
+    const bestPractices = normaliseScoreBudget(maybeCategories.bestPractices, "bestPractices", absolutePath);
+    const seo = normaliseScoreBudget(maybeCategories.seo, "seo", absolutePath);
+    if (performance === undefined &&
+        accessibility === undefined &&
+        bestPractices === undefined &&
+        seo === undefined) {
+        return undefined;
+    }
+    return {
+        performance,
+        accessibility,
+        bestPractices,
+        seo,
+    };
+}
+function normaliseMetricBudgets(input, absolutePath) {
+    if (input === undefined) {
+        return undefined;
+    }
+    if (!input || typeof input !== "object") {
+        throw new Error(`Invalid budgets.metrics in ${absolutePath}: expected object`);
+    }
+    const maybeMetrics = input;
+    const lcpMs = normaliseMetricBudget(maybeMetrics.lcpMs, "lcpMs", absolutePath);
+    const fcpMs = normaliseMetricBudget(maybeMetrics.fcpMs, "fcpMs", absolutePath);
+    const tbtMs = normaliseMetricBudget(maybeMetrics.tbtMs, "tbtMs", absolutePath);
+    const cls = normaliseMetricBudget(maybeMetrics.cls, "cls", absolutePath);
+    if (lcpMs === undefined && fcpMs === undefined && tbtMs === undefined && cls === undefined) {
+        return undefined;
+    }
+    return {
+        lcpMs,
+        fcpMs,
+        tbtMs,
+        cls,
+    };
+}
+function normaliseScoreBudget(value, key, absolutePath) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "number" || value < 0 || value > 100) {
+        throw new Error(`Invalid budgets.categories.${key} in ${absolutePath}: expected number between 0 and 100`);
+    }
+    return value;
+}
+function normaliseMetricBudget(value, key, absolutePath) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "number" || value < 0) {
+        throw new Error(`Invalid budgets.metrics.${key} in ${absolutePath}: expected non-negative number`);
+    }
+    return value;
+}

package/dist/quickstart-cli.js

@@ -0,0 +1,118 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import prompts from "prompts";
+import { detectRoutes } from "./route-detectors.js";
+import { pathExists } from "./fs-utils.js";
+import { runAuditCli } from "./cli.js";
+const DEFAULT_BASE_URL = "http://localhost:3000";
+const DEFAULT_RUNS = 1;
+const DEFAULT_DEVICES = ["mobile", "desktop"];
+const DEFAULT_ROUTE_LIMIT = 5;
+const QUICKSTART_CONFIG_NAME = "quickstart.config.json";
+const PROMPT_OPTIONS = { onCancel: handleCancel };
+const baseUrlQuestion = {
+    type: "text",
+    name: "baseUrl",
+    message: "Base URL of the running app",
+    initial: DEFAULT_BASE_URL,
+    validate: (value) => (value.startsWith("http") ? true : "Enter a full http(s) URL."),
+};
+function handleCancel() {
+    // eslint-disable-next-line no-console
+    console.log("Quickstart cancelled. No audits run.");
+    process.exit(1);
+    return true;
+}
+async function ask(question) {
+    const answers = await prompts(question, PROMPT_OPTIONS);
+    return answers;
+}
+function parseQuickstartArgs(argv) {
+    let baseUrl;
+    let projectRoot = ".";
+    for (let index = 2; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if ((arg === "--base-url" || arg === "-b") && index + 1 < argv.length) {
+            baseUrl = argv[index + 1];
+            index += 1;
+        }
+        else if ((arg === "--project-root" || arg === "-p") && index + 1 < argv.length) {
+            projectRoot = argv[index + 1];
+            index += 1;
+        }
+    }
+    return { baseUrl, projectRoot };
+}
+async function resolveBaseUrl(cliBaseUrl) {
+    if (cliBaseUrl && cliBaseUrl.length > 0) {
+        return cliBaseUrl;
+    }
+    // eslint-disable-next-line no-console
+    console.error("Quickstart requires --base-url <url>. No base URL was provided.");
+    process.exit(1);
+    return DEFAULT_BASE_URL;
+}
+async function resolveProjectRoot(rawProjectRoot) {
+    const absolutePath = resolve(rawProjectRoot);
+    if (await pathExists(absolutePath)) {
+        return absolutePath;
+    }
+    // eslint-disable-next-line no-console
+    console.log(`Project root ${absolutePath} does not exist. Falling back to current directory.`);
+    return process.cwd();
+}
+async function detectQuickstartPages(projectRoot) {
+    const routes = await detectRoutes({ projectRoot, limit: DEFAULT_ROUTE_LIMIT });
+    if (routes.length === 0) {
+        return buildFallbackPages();
+    }
+    return routes.map((route) => convertRouteToPage(route));
+}
+function buildFallbackPages() {
+    return [
+        {
+            path: "/",
+            label: "home",
+            devices: DEFAULT_DEVICES,
+        },
+    ];
+}
+function convertRouteToPage(route) {
+    return {
+        path: route.path,
+        label: route.label,
+        devices: DEFAULT_DEVICES,
+    };
+}
+async function writeQuickstartConfig(config) {
+    const outputDir = resolve(".apex-auditor");
+    await mkdir(outputDir, { recursive: true });
+    const configPath = join(outputDir, QUICKSTART_CONFIG_NAME);
+    await writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+    return configPath;
+}
+async function buildQuickstartConfig(args) {
+    const baseUrl = await resolveBaseUrl(args.baseUrl);
+    const projectRoot = await resolveProjectRoot(args.projectRoot);
+    const pages = await detectQuickstartPages(projectRoot);
+    const config = {
+        baseUrl,
+        pages,
+        runs: DEFAULT_RUNS,
+    };
+    return writeQuickstartConfig(config);
+}
+/**
+ * Run the ApexAuditor quickstart flow.
+ *
+ * This command discovers common routes from the current project, asks for a base URL
+ * if needed, writes a temporary config file, and then delegates to the audit CLI.
+ *
+ * @param argv - The process arguments array.
+ */
+export async function runQuickstartCli(argv) {
+    const args = parseQuickstartArgs(argv);
+    const configPath = await buildQuickstartConfig(args);
+    const auditArgv = ["node", "apex-auditor", "--config", configPath];
+    await runAuditCli(auditArgv);
+}

package/package.json

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