@vertaaux/cli 0.2.0

package/dist/monorepo/workspace.js

@@ -0,0 +1,171 @@
+/**
+ * Workspace audit orchestration for monorepos.
+ *
+ * Handles running audits across multiple workspaces with
+ * proper isolation and result aggregation.
+ */
+/**
+ * Audit a single workspace.
+ *
+ * If URL not provided, uses the workspace's inferred URL.
+ * In future versions, this could start the dev server automatically.
+ *
+ * @param options - Workspace audit options
+ * @returns WorkspaceResult with audit outcome
+ */
+export async function auditWorkspace(options) {
+    const startTime = Date.now();
+    const { workspace, baseUrl, port } = options;
+    // Determine URL to audit
+    const url = baseUrl ||
+        (port ? `http://localhost:${port}` : workspace.url) ||
+        `http://localhost:${workspace.port || 3000}`;
+    try {
+        // Note: The actual audit execution is delegated to the main audit logic
+        // This function provides the orchestration structure
+        // The audit command will call this and provide the actual audit implementation
+        const result = {
+            workspace,
+            auditResult: {
+                url,
+                status: "pending",
+                issues: [],
+            },
+            duration: Date.now() - startTime,
+        };
+        return result;
+    }
+    catch (error) {
+        return {
+            workspace,
+            auditResult: null,
+            error: error instanceof Error ? error : new Error(String(error)),
+            duration: Date.now() - startTime,
+        };
+    }
+}
+/**
+ * Generate matrix configuration for CI parallel execution.
+ *
+ * This generates a JSON structure suitable for GitHub Actions matrix strategy
+ * or similar CI systems that support parallel job execution.
+ *
+ * @param workspaces - List of workspaces to include in matrix
+ * @returns Matrix configuration object
+ *
+ * @example
+ * ```yaml
+ * # In GitHub Actions:
+ * jobs:
+ *   detect-apps:
+ *     runs-on: ubuntu-latest
+ *     outputs:
+ *       matrix: ${{ steps.detect.outputs.matrix }}
+ *     steps:
+ *       - id: detect
+ *         run: echo "matrix=$(vertaa audit --detect-matrix --json)" >> $GITHUB_OUTPUT
+ *
+ *   audit:
+ *     needs: detect-apps
+ *     strategy:
+ *       matrix: ${{ fromJson(needs.detect-apps.outputs.matrix) }}
+ *     steps:
+ *       - run: vertaa audit --workspace ${{ matrix.name }}
+ * ```
+ */
+export function generateMatrixConfig(workspaces) {
+    return {
+        include: workspaces.map((ws) => ({
+            name: ws.name,
+            path: ws.path,
+            url: ws.url,
+            port: ws.port,
+            appType: ws.appType,
+        })),
+    };
+}
+/**
+ * Aggregate results from multiple workspace audits.
+ *
+ * @param results - Array of workspace results
+ * @returns Aggregated results summary
+ */
+export function aggregateResults(results) {
+    const aggregated = {
+        totalWorkspaces: results.length,
+        successfulAudits: 0,
+        failedAudits: 0,
+        totalIssues: 0,
+        issuesBySeverity: {
+            error: 0,
+            warning: 0,
+            info: 0,
+        },
+        workspaceResults: results,
+        totalDuration: 0,
+    };
+    for (const result of results) {
+        aggregated.totalDuration += result.duration;
+        if (result.error || !result.auditResult) {
+            aggregated.failedAudits++;
+            continue;
+        }
+        aggregated.successfulAudits++;
+        const issues = result.auditResult.issues || [];
+        aggregated.totalIssues += issues.length;
+        // Count issues by severity
+        for (const issue of issues) {
+            const severity = (issue.severity || "info").toLowerCase();
+            if (severity === "error" || severity === "critical") {
+                aggregated.issuesBySeverity.error++;
+            }
+            else if (severity === "warning" || severity === "serious") {
+                aggregated.issuesBySeverity.warning++;
+            }
+            else {
+                aggregated.issuesBySeverity.info++;
+            }
+        }
+    }
+    return aggregated;
+}
+/**
+ * Format aggregated results for display.
+ *
+ * @param aggregated - Aggregated results
+ * @returns Formatted string for console output
+ */
+export function formatAggregatedResults(aggregated) {
+    const lines = [];
+    lines.push(`Monorepo Audit Summary`);
+    lines.push(`======================`);
+    lines.push(``);
+    lines.push(`Workspaces: ${aggregated.totalWorkspaces}`);
+    lines.push(`  Successful: ${aggregated.successfulAudits}`);
+    lines.push(`  Failed: ${aggregated.failedAudits}`);
+    lines.push(``);
+    lines.push(`Total Issues: ${aggregated.totalIssues}`);
+    lines.push(`  Errors: ${aggregated.issuesBySeverity.error}`);
+    lines.push(`  Warnings: ${aggregated.issuesBySeverity.warning}`);
+    lines.push(`  Info: ${aggregated.issuesBySeverity.info}`);
+    lines.push(``);
+    lines.push(`Duration: ${(aggregated.totalDuration / 1000).toFixed(2)}s`);
+    // Per-workspace breakdown
+    lines.push(``);
+    lines.push(`Per-Workspace Results:`);
+    lines.push(`----------------------`);
+    for (const result of aggregated.workspaceResults) {
+        const issueCount = result.auditResult?.issues?.length || 0;
+        const status = result.error
+            ? "FAILED"
+            : result.cached
+                ? "CACHED"
+                : "OK";
+        const statusSymbol = result.error ? "X" : result.cached ? "~" : "+";
+        lines.push(`  [${statusSymbol}] ${result.workspace.name}: ${issueCount} issues (${status})`);
+        if (result.error) {
+            lines.push(`      Error: ${result.error.message}`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/output/envelope.d.ts

@@ -0,0 +1,21 @@
+/**
+ * JSON output envelope for CLI commands.
+ *
+ * Wraps all JSON output with metadata (version, timestamp, command, args).
+ * This satisfies the output contract requirement that JSON output includes
+ * provenance information for debugging and version tracking.
+ */
+export interface OutputMeta {
+    version: string;
+    timestamp: string;
+    command: string;
+    args: string[];
+}
+export interface OutputEnvelope<T = unknown> {
+    meta: OutputMeta;
+    data: T;
+}
+export declare function createEnvelope<T>(data: T, command: string): OutputEnvelope<T>;
+export declare function writeJsonOutput<T>(data: T, command: string): void;
+export declare function writeOutput(content: string): void;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/output/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/output/envelope.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO;IACzC,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,CAAC,CAAC;CACT;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,CAa7E;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAGjE;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEjD"}

package/dist/output/envelope.js

@@ -0,0 +1,27 @@
+/**
+ * JSON output envelope for CLI commands.
+ *
+ * Wraps all JSON output with metadata (version, timestamp, command, args).
+ * This satisfies the output contract requirement that JSON output includes
+ * provenance information for debugging and version tracking.
+ */
+import { getVersion } from "../ui/banner.js";
+export function createEnvelope(data, command) {
+    return {
+        meta: {
+            version: getVersion(),
+            timestamp: new Date().toISOString(),
+            command,
+            // Filter out any args containing API keys or tokens
+            args: process.argv.slice(2).filter(a => !a.includes("VERTAAUX_API_KEY") && !a.includes("Bearer")),
+        },
+        data,
+    };
+}
+export function writeJsonOutput(data, command) {
+    const envelope = createEnvelope(data, command);
+    process.stdout.write(JSON.stringify(envelope, null, 2) + "\n");
+}
+export function writeOutput(content) {
+    process.stdout.write(content + "\n");
+}

package/dist/output/factory.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Output formatter factory for CLI.
+ *
+ * Creates the appropriate formatter based on detected or explicit output format.
+ * Supports human, JSON, HTML, SARIF, and JUnit output with auto-detection.
+ */
+import { type FormatHumanOptions } from "./human.js";
+import { type FormatJsonOptions } from "./json.js";
+import { type FormatHtmlOptions } from "./html.js";
+import { type SarifOptions } from "./sarif.js";
+import { type JunitOptions } from "./junit.js";
+import { type OutputFormat } from "../utils/detect-env.js";
+export interface AuditResult {
+    job_id?: string;
+    status?: string;
+    url?: string;
+    mode?: string;
+    progress?: number;
+    created_at?: string;
+    started_at?: string;
+    completed_at?: string;
+    scores?: Record<string, unknown>;
+    issues?: unknown;
+    error?: string;
+}
+export interface FormatOptions {
+    /** Human output options */
+    human?: FormatHumanOptions;
+    /** JSON output options */
+    json?: FormatJsonOptions;
+    /** HTML output options */
+    html?: FormatHtmlOptions;
+    /** SARIF output options */
+    sarif?: SarifOptions;
+    /** JUnit output options */
+    junit?: JunitOptions;
+}
+/**
+ * Formatter interface for audit results.
+ */
+export interface Formatter {
+    /** The resolved output format */
+    format: OutputFormat;
+    /**
+     * Format the audit result.
+     * @param result - Audit result to format
+     * @param options - Format-specific options
+     * @returns Formatted string
+     */
+    formatResult(result: AuditResult, options?: FormatOptions): string;
+}
+/**
+ * Create a formatter for the specified or auto-detected output format.
+ *
+ * @param format - Explicit format or "auto" for auto-detection
+ * @returns A formatter instance
+ */
+export declare function createOutput(format?: OutputFormat | "auto"): Formatter;
+/**
+ * Quick format helper - formats result using auto-detected format.
+ *
+ * @param result - Audit result to format
+ * @param explicitFormat - Optional explicit format override
+ * @param options - Format-specific options
+ * @returns Formatted string
+ */
+export declare function formatOutput(result: AuditResult, explicitFormat?: string, options?: FormatOptions): string;
+export { formatAuditHuman } from "./human.js";
+export { formatAuditJson, formatJson } from "./json.js";
+export { formatAuditHtml } from "./html.js";
+export { formatSarif } from "./sarif.js";
+export { formatJunit } from "./junit.js";
+//# sourceMappingURL=factory.d.ts.map

package/dist/output/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/output/factory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAoB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAAmB,KAAK,iBAAiB,EAAE,MAAM,WAAW,CAAC;AACpE,OAAO,EAAmB,KAAK,iBAAiB,EAAE,MAAM,WAAW,CAAC;AACpE,OAAO,EAAe,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAe,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE/E,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,2BAA2B;IAC3B,KAAK,CAAC,EAAE,kBAAkB,CAAC;IAC3B,0BAA0B;IAC1B,IAAI,CAAC,EAAE,iBAAiB,CAAC;IACzB,0BAA0B;IAC1B,IAAI,CAAC,EAAE,iBAAiB,CAAC;IACzB,2BAA2B;IAC3B,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,2BAA2B;IAC3B,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,iCAAiC;IACjC,MAAM,EAAE,YAAY,CAAC;IACrB;;;;;OAKG;IACH,YAAY,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,CAAC;CACpE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,GAAE,YAAY,GAAG,MAAe,GAAG,SAAS,CA4B9E;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,WAAW,EACnB,cAAc,CAAC,EAAE,MAAM,EACvB,OAAO,CAAC,EAAE,aAAa,GACtB,MAAM,CAIR;AAGD,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}

package/dist/output/factory.js

@@ -0,0 +1,60 @@
+/**
+ * Output formatter factory for CLI.
+ *
+ * Creates the appropriate formatter based on detected or explicit output format.
+ * Supports human, JSON, HTML, SARIF, and JUnit output with auto-detection.
+ */
+import { formatAuditHuman } from "./human.js";
+import { formatAuditJson } from "./json.js";
+import { formatAuditHtml } from "./html.js";
+import { formatSarif } from "./sarif.js";
+import { formatJunit } from "./junit.js";
+import { detectOutputFormat } from "../utils/detect-env.js";
+/**
+ * Create a formatter for the specified or auto-detected output format.
+ *
+ * @param format - Explicit format or "auto" for auto-detection
+ * @returns A formatter instance
+ */
+export function createOutput(format = "auto") {
+    const resolvedFormat = format === "auto" ? detectOutputFormat() : format;
+    return {
+        format: resolvedFormat,
+        formatResult(result, options = {}) {
+            switch (resolvedFormat) {
+                case "human":
+                    return formatAuditHuman(result, options.human);
+                case "json":
+                    return formatAuditJson(result, options.json);
+                case "html":
+                    return formatAuditHtml(result, options.html);
+                case "sarif":
+                    return formatSarif(result, options.sarif);
+                case "junit":
+                    return formatJunit(result, options.junit);
+                default:
+                    // Default to JSON for unknown formats
+                    return formatAuditJson(result, options.json);
+            }
+        },
+    };
+}
+/**
+ * Quick format helper - formats result using auto-detected format.
+ *
+ * @param result - Audit result to format
+ * @param explicitFormat - Optional explicit format override
+ * @param options - Format-specific options
+ * @returns Formatted string
+ */
+export function formatOutput(result, explicitFormat, options) {
+    const format = explicitFormat || "auto";
+    const formatter = createOutput(format);
+    return formatter.formatResult(result, options);
+}
+// Re-export individual formatters for direct access
+export { formatAuditHuman } from "./human.js";
+export { formatAuditJson, formatJson } from "./json.js";
+export { formatAuditHtml } from "./html.js";
+export { formatSarif } from "./sarif.js";
+export { formatJunit } from "./junit.js";

package/dist/output/formats.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Per-command format registry for CLI output.
+ *
+ * Defines which output formats each command supports, their defaults,
+ * and validates format selection with clear error messages.
+ */
+export declare const COMMAND_FORMATS: Record<string, readonly string[]>;
+export declare const COMMAND_DEFAULT_FORMAT: Record<string, string>;
+export declare function validateFormat(command: string, format: string | undefined): string;
+export declare function resolveCommandFormat(command: string, explicitFormat: string | undefined, machineMode: boolean): string;
+//# sourceMappingURL=formats.d.ts.map

package/dist/output/formats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formats.d.ts","sourceRoot":"","sources":["../../src/output/formats.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAM7D,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAMzD,CAAC;AAEF,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAclF;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,WAAW,EAAE,OAAO,GACnB,MAAM,CAMR"}

package/dist/output/formats.js

@@ -0,0 +1,41 @@
+/**
+ * Per-command format registry for CLI output.
+ *
+ * Defines which output formats each command supports, their defaults,
+ * and validates format selection with clear error messages.
+ */
+export const COMMAND_FORMATS = {
+    audit: ["json", "sarif", "junit", "html", "human"],
+    comment: ["json", "markdown"],
+    explain: ["json", "human"],
+    "policy-show": ["json", "yaml"],
+    diff: ["json", "human"],
+};
+export const COMMAND_DEFAULT_FORMAT = {
+    audit: "human",
+    comment: "markdown",
+    explain: "human",
+    "policy-show": "yaml",
+    diff: "human",
+};
+export function validateFormat(command, format) {
+    const allowed = COMMAND_FORMATS[command];
+    if (!allowed)
+        return format || "json"; // unknown command, pass through
+    // Use default if no format specified
+    if (!format)
+        return COMMAND_DEFAULT_FORMAT[command] || allowed[0];
+    if (!allowed.includes(format)) {
+        const msg = `Error: Invalid format "${format}" for "${command}". Supported: ${allowed.join(", ")}`;
+        console.error(msg);
+        process.exit(2);
+    }
+    return format;
+}
+export function resolveCommandFormat(command, explicitFormat, machineMode) {
+    // Machine mode defaults to JSON unless explicitly overridden
+    if (machineMode && !explicitFormat) {
+        return "json";
+    }
+    return validateFormat(command, explicitFormat);
+}

package/dist/output/html.d.ts

@@ -0,0 +1,45 @@
+/**
+ * HTML output formatter for CLI.
+ *
+ * Generates standalone HTML reports with embedded CSS and JS.
+ * Reports are print-friendly and don't require external dependencies.
+ */
+export interface Issue {
+    id?: string;
+    severity?: string;
+    category?: string;
+    description?: string;
+    title?: string;
+    selector?: string;
+    wcag_reference?: string;
+    recommendation?: string;
+    recommended_fix?: string;
+}
+export interface AuditResult {
+    job_id?: string;
+    status?: string;
+    url?: string;
+    mode?: string;
+    progress?: number;
+    created_at?: string;
+    started_at?: string;
+    completed_at?: string;
+    scores?: Record<string, unknown>;
+    issues?: unknown;
+    error?: string;
+}
+export interface FormatHtmlOptions {
+    /** Report title (default: "VertaaUX Audit Report") */
+    title?: string;
+    /** Whether to include inline JavaScript for interactivity */
+    interactive?: boolean;
+}
+/**
+ * Format audit result as standalone HTML report.
+ *
+ * @param result - Audit result object
+ * @param options - Formatting options
+ * @returns Complete HTML document string
+ */
+export declare function formatAuditHtml(result: AuditResult, options?: FormatHtmlOptions): string;
+//# sourceMappingURL=html.d.ts.map

package/dist/output/html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../../src/output/html.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,KAAK;IACpB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAoiBD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,WAAW,EACnB,OAAO,GAAE,iBAAsB,GAC9B,MAAM,CA8DR"}