@vertaaux/cli 0.2.0

package/dist/ci/changed-routes.js

@@ -0,0 +1,304 @@
+/**
+ * Detect routes changed in PR for incremental auditing.
+ *
+ * Uses git diff to find changed files, then maps them to routes.
+ * This enables efficient CI by only auditing what changed.
+ *
+ * Implements CICD-07: Incremental mode audits only routes touched in PR.
+ */
+import { execSync, execFileSync } from "child_process";
+import { validateBranchName } from "../utils/sanitize.js";
+/**
+ * Default route patterns for common frameworks.
+ *
+ * These patterns identify files that typically map to routes.
+ */
+const DEFAULT_ROUTE_PATTERNS = [
+    // Next.js App Router
+    "src/app/**/page.tsx",
+    "src/app/**/page.ts",
+    "src/app/**/page.jsx",
+    "src/app/**/page.js",
+    // Next.js Pages Router
+    "src/pages/**/*.tsx",
+    "src/pages/**/*.ts",
+    "src/pages/**/*.jsx",
+    "src/pages/**/*.js",
+    "pages/**/*.tsx",
+    "pages/**/*.ts",
+    "pages/**/*.jsx",
+    "pages/**/*.js",
+    // SvelteKit
+    "src/routes/**/+page.svelte",
+    "src/routes/**/+page.ts",
+    "src/routes/**/+page.js",
+    // Remix
+    "app/routes/**/*.tsx",
+    "app/routes/**/*.ts",
+    "app/routes/**/*.jsx",
+    "app/routes/**/*.js",
+    // Nuxt
+    "pages/**/*.vue",
+    // Astro
+    "src/pages/**/*.astro",
+];
+/**
+ * Convert a file path to a route URL.
+ *
+ * Supports common framework conventions:
+ * - Next.js App Router: src/app/about/page.tsx -> /about
+ * - Next.js Pages Router: src/pages/blog/index.tsx -> /blog
+ * - SvelteKit: src/routes/blog/+page.svelte -> /blog
+ *
+ * @param filePath - The changed file path
+ * @returns The route URL or null if not a route file
+ */
+export function filePathToRoute(filePath) {
+    // Next.js App Router: src/app/about/page.tsx -> /about
+    const appRouterMatch = filePath.match(/^(?:src\/)?app\/(.*)\/page\.(tsx?|jsx?|mdx?)$/);
+    if (appRouterMatch) {
+        const route = appRouterMatch[1];
+        // Handle root route
+        if (route === "")
+            return "/";
+        // Handle dynamic segments: [id] -> :id (for display, keep as-is for audit)
+        return `/${route}`;
+    }
+    // Next.js Pages Router: src/pages/blog/index.tsx -> /blog
+    const pagesRouterMatch = filePath.match(/^(?:src\/)?pages\/(.+)\.(tsx?|jsx?|mdx?)$/);
+    if (pagesRouterMatch) {
+        let route = pagesRouterMatch[1];
+        // Remove index suffix
+        route = route.replace(/\/index$/, "");
+        route = route.replace(/^index$/, "");
+        // Handle root route
+        if (route === "")
+            return "/";
+        return `/${route}`;
+    }
+    // SvelteKit: src/routes/blog/+page.svelte -> /blog
+    const sveltekitMatch = filePath.match(/^src\/routes\/(.*)\/\+page\.(svelte|ts|js)$/);
+    if (sveltekitMatch) {
+        const route = sveltekitMatch[1];
+        if (route === "")
+            return "/";
+        return `/${route}`;
+    }
+    // Remix: app/routes/blog.tsx -> /blog
+    const remixMatch = filePath.match(/^app\/routes\/(.+)\.(tsx?|jsx?)$/);
+    if (remixMatch) {
+        let route = remixMatch[1];
+        // Remix uses . for nested routes: blog.post -> blog/post
+        route = route.replace(/\./g, "/");
+        // Handle _index (root)
+        route = route.replace(/\/_index$/, "");
+        route = route.replace(/^_index$/, "");
+        if (route === "")
+            return "/";
+        return `/${route}`;
+    }
+    // Nuxt: pages/about.vue -> /about
+    const nuxtMatch = filePath.match(/^pages\/(.+)\.vue$/);
+    if (nuxtMatch) {
+        let route = nuxtMatch[1];
+        route = route.replace(/\/index$/, "");
+        route = route.replace(/^index$/, "");
+        if (route === "")
+            return "/";
+        return `/${route}`;
+    }
+    // Astro: src/pages/about.astro -> /about
+    const astroMatch = filePath.match(/^src\/pages\/(.+)\.astro$/);
+    if (astroMatch) {
+        let route = astroMatch[1];
+        route = route.replace(/\/index$/, "");
+        route = route.replace(/^index$/, "");
+        if (route === "")
+            return "/";
+        return `/${route}`;
+    }
+    return null;
+}
+/**
+ * Check if a file path matches any of the route patterns.
+ */
+function matchesRoutePattern(filePath, patterns) {
+    for (const pattern of patterns) {
+        // Convert glob pattern to regex
+        const regexPattern = pattern
+            .replace(/\*\*/g, "DOUBLESTAR")
+            .replace(/\*/g, "[^/]*")
+            .replace(/DOUBLESTAR/g, ".*")
+            .replace(/\./g, "\\.");
+        const regex = new RegExp(`^${regexPattern}$`);
+        if (regex.test(filePath)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Get the list of files changed between branches.
+ *
+ * @param baseBranch - The base branch to compare against
+ * @returns Array of changed file paths
+ */
+function getChangedFiles(baseBranch) {
+    const validBranch = validateBranchName(baseBranch);
+    try {
+        // Try with origin/ prefix first (most common in CI)
+        const result = execFileSync("git", ["diff", "--name-only", `origin/${validBranch}...HEAD`], { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+        return result
+            .split("\n")
+            .map((line) => line.trim())
+            .filter(Boolean);
+    }
+    catch {
+        try {
+            // Fall back to without origin/ prefix (local branches)
+            const result = execFileSync("git", ["diff", "--name-only", `${validBranch}...HEAD`], { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+            return result
+                .split("\n")
+                .map((line) => line.trim())
+                .filter(Boolean);
+        }
+        catch {
+            // If git diff fails, return empty array
+            console.error(`Warning: Could not get changed files from git (base: ${validBranch})`);
+            return [];
+        }
+    }
+}
+/**
+ * Detect base branch from CI environment variables.
+ *
+ * Supports:
+ * - GitHub Actions: GITHUB_BASE_REF
+ * - GitLab CI: CI_MERGE_REQUEST_TARGET_BRANCH_NAME
+ * - Azure DevOps: SYSTEM_PULLREQUEST_TARGETBRANCH
+ * - Jenkins: CHANGE_TARGET
+ * - CircleCI: CIRCLE_BRANCH (for base, uses main as fallback)
+ *
+ * @returns Detected base branch or "main" as default
+ */
+export function detectBaseBranch() {
+    let detected;
+    // GitHub Actions
+    if (process.env.GITHUB_BASE_REF) {
+        detected = process.env.GITHUB_BASE_REF;
+    }
+    // GitLab CI
+    if (!detected && process.env.CI_MERGE_REQUEST_TARGET_BRANCH_NAME) {
+        detected = process.env.CI_MERGE_REQUEST_TARGET_BRANCH_NAME;
+    }
+    // Azure DevOps
+    if (!detected && process.env.SYSTEM_PULLREQUEST_TARGETBRANCH) {
+        // Azure uses refs/heads/main format
+        detected = process.env.SYSTEM_PULLREQUEST_TARGETBRANCH.replace(/^refs\/heads\//, "");
+    }
+    // Jenkins
+    if (!detected && process.env.CHANGE_TARGET) {
+        detected = process.env.CHANGE_TARGET;
+    }
+    // Try to detect main vs master
+    if (!detected) {
+        try {
+            execSync("git rev-parse --verify origin/main", {
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            detected = "main";
+        }
+        catch {
+            try {
+                execSync("git rev-parse --verify origin/master", {
+                    stdio: ["pipe", "pipe", "pipe"],
+                });
+                detected = "master";
+            }
+            catch {
+                // Default to main
+                detected = "main";
+            }
+        }
+    }
+    // Defense in depth: validate the detected branch name.
+    // If a CI env var contained malicious characters, fall back to "main".
+    try {
+        return validateBranchName(detected);
+    }
+    catch {
+        return "main";
+    }
+}
+/**
+ * Get list of routes affected by changed files.
+ *
+ * Uses git diff to find changed files, then maps to routes.
+ *
+ * @param options - Detection options
+ * @returns Changed routes result
+ */
+export async function getChangedRoutes(options) {
+    const { baseBranch, routePatterns = DEFAULT_ROUTE_PATTERNS, fileToRouteMap } = options;
+    // Get changed files from git
+    const changedFiles = getChangedFiles(baseBranch);
+    if (changedFiles.length === 0) {
+        return {
+            routes: [],
+            changedFiles: [],
+            hasChanges: false,
+        };
+    }
+    // Collect routes from changed files
+    const routeSet = new Set();
+    for (const filePath of changedFiles) {
+        // First, check custom mapping
+        if (fileToRouteMap) {
+            for (const [pattern, routes] of Object.entries(fileToRouteMap)) {
+                const regexPattern = pattern
+                    .replace(/\*\*/g, "DOUBLESTAR")
+                    .replace(/\*/g, "[^/]*")
+                    .replace(/DOUBLESTAR/g, ".*")
+                    .replace(/\./g, "\\.");
+                const regex = new RegExp(`^${regexPattern}$`);
+                if (regex.test(filePath)) {
+                    for (const route of routes) {
+                        routeSet.add(route);
+                    }
+                }
+            }
+        }
+        // Check if file matches route patterns
+        if (matchesRoutePattern(filePath, routePatterns)) {
+            const route = filePathToRoute(filePath);
+            if (route) {
+                routeSet.add(route);
+            }
+        }
+    }
+    const routes = Array.from(routeSet).sort();
+    return {
+        routes,
+        changedFiles,
+        hasChanges: routes.length > 0,
+    };
+}
+/**
+ * Budget modes for controlling audit scope.
+ *
+ * CICD-13: Default mode runs under sane budget; full scan is opt-in.
+ */
+export const BUDGET_MODES = {
+    /** Quick scan: 5 pages, 30s timeout, 2 concurrent */
+    quick: { maxPages: 5, maxTime: 30000, concurrency: 2 },
+    /** Standard scan: 20 pages, 2min timeout, 4 concurrent */
+    standard: { maxPages: 20, maxTime: 120000, concurrency: 4 },
+    /** Full scan: unlimited pages, 10min timeout, 8 concurrent */
+    full: { maxPages: Infinity, maxTime: 600000, concurrency: 8 },
+};
+/**
+ * Get budget configuration for a mode.
+ */
+export function getBudgetConfig(mode) {
+    return BUDGET_MODES[mode] || BUDGET_MODES.standard;
+}

package/dist/ci/github-api.d.ts

@@ -0,0 +1,68 @@
+/**
+ * GitHub API wrapper for PR comment operations.
+ *
+ * Provides utilities for posting and updating PR comments
+ * with sticky comment semantics (find existing by hidden header).
+ *
+ * Uses native fetch (Node 18+).
+ */
+/**
+ * Options for GitHub comment operations.
+ */
+export interface GitHubCommentOptions {
+    /** GitHub token (from GITHUB_TOKEN env var) */
+    token: string;
+    /** Repository owner */
+    owner: string;
+    /** Repository name */
+    repo: string;
+    /** PR number */
+    prNumber: number;
+    /** Comment body (markdown) */
+    body: string;
+    /** Header identifier for finding existing comment */
+    header: string;
+}
+/**
+ * Find existing comment by hidden header identifier.
+ *
+ * Searches PR comments for `<!-- {header} -->` pattern in body.
+ * Handles pagination for repos with many comments.
+ *
+ * @param options - Comment search options (token, owner, repo, prNumber, header)
+ * @returns Comment ID if found, null otherwise
+ */
+export declare function findExistingComment(options: Omit<GitHubCommentOptions, "body">): Promise<number | null>;
+/**
+ * Post new comment or update existing one.
+ *
+ * Uses header identifier to find existing comment for update semantics.
+ * This prevents comment spam and ensures only one VertaaUX comment per PR.
+ *
+ * @param options - Comment options (token, owner, repo, prNumber, body, header)
+ * @returns Created/updated comment with ID and URL
+ */
+export declare function postOrUpdateGitHubComment(options: GitHubCommentOptions): Promise<{
+    id: number;
+    html_url: string;
+}>;
+/**
+ * Parse repository string into owner and repo.
+ *
+ * @param repository - Repository string in "owner/repo" format
+ * @returns Parsed owner and repo, or null if invalid
+ */
+export declare function parseRepository(repository: string): {
+    owner: string;
+    repo: string;
+} | null;
+/**
+ * Extract PR number from GitHub Actions environment.
+ *
+ * Checks GITHUB_REF_NAME for PR merge ref format (e.g., "123/merge")
+ * and falls back to GITHUB_EVENT_NUMBER.
+ *
+ * @returns PR number or null if not in PR context
+ */
+export declare function extractPRNumber(): number | null;
+//# sourceMappingURL=github-api.d.ts.map

package/dist/ci/github-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-api.d.ts","sourceRoot":"","sources":["../../src/ci/github-api.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,uBAAuB;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;CAChB;AA8DD;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,IAAI,CAAC,oBAAoB,EAAE,MAAM,CAAC,GAC1C,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA4BxB;AAED;;;;;;;;GAQG;AACH,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAqB3C;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,GACjB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAIxC;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,IAAI,MAAM,GAAG,IAAI,CAqB/C"}

package/dist/ci/github-api.js

@@ -0,0 +1,138 @@
+/**
+ * GitHub API wrapper for PR comment operations.
+ *
+ * Provides utilities for posting and updating PR comments
+ * with sticky comment semantics (find existing by hidden header).
+ *
+ * Uses native fetch (Node 18+).
+ */
+const GITHUB_API_BASE = "https://api.github.com";
+/**
+ * Make an authenticated GitHub API request.
+ */
+async function githubRequest(method, url, token, body) {
+    const headers = {
+        Accept: "application/vnd.github+json",
+        Authorization: `Bearer ${token}`,
+        "X-GitHub-Api-Version": "2022-11-28",
+        "User-Agent": "VertaaUX-CLI",
+    };
+    if (body) {
+        headers["Content-Type"] = "application/json";
+    }
+    const response = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    if (!response.ok) {
+        const errorData = (await response.json().catch(() => ({})));
+        throw new Error(`GitHub API error (${response.status}): ${errorData.message || response.statusText}`);
+    }
+    // Handle no content responses
+    if (response.status === 204) {
+        return {};
+    }
+    return response.json();
+}
+/**
+ * Find existing comment by hidden header identifier.
+ *
+ * Searches PR comments for `<!-- {header} -->` pattern in body.
+ * Handles pagination for repos with many comments.
+ *
+ * @param options - Comment search options (token, owner, repo, prNumber, header)
+ * @returns Comment ID if found, null otherwise
+ */
+export async function findExistingComment(options) {
+    const { token, owner, repo, prNumber, header } = options;
+    const headerPattern = `<!-- ${header} -->`;
+    let page = 1;
+    const perPage = 100;
+    // Paginate through comments until we find one or run out
+    while (true) {
+        const url = `${GITHUB_API_BASE}/repos/${owner}/${repo}/issues/${prNumber}/comments?page=${page}&per_page=${perPage}`;
+        const comments = await githubRequest("GET", url, token);
+        for (const comment of comments) {
+            if (comment.body?.includes(headerPattern)) {
+                return comment.id;
+            }
+        }
+        // No more pages
+        if (comments.length < perPage) {
+            break;
+        }
+        page++;
+    }
+    return null;
+}
+/**
+ * Post new comment or update existing one.
+ *
+ * Uses header identifier to find existing comment for update semantics.
+ * This prevents comment spam and ensures only one VertaaUX comment per PR.
+ *
+ * @param options - Comment options (token, owner, repo, prNumber, body, header)
+ * @returns Created/updated comment with ID and URL
+ */
+export async function postOrUpdateGitHubComment(options) {
+    const { token, owner, repo, prNumber, body, header } = options;
+    // Try to find existing comment
+    const existingId = await findExistingComment({
+        token,
+        owner,
+        repo,
+        prNumber,
+        header,
+    });
+    if (existingId) {
+        // Update existing comment
+        const url = `${GITHUB_API_BASE}/repos/${owner}/${repo}/issues/comments/${existingId}`;
+        return githubRequest("PATCH", url, token, { body });
+    }
+    else {
+        // Create new comment
+        const url = `${GITHUB_API_BASE}/repos/${owner}/${repo}/issues/${prNumber}/comments`;
+        return githubRequest("POST", url, token, { body });
+    }
+}
+/**
+ * Parse repository string into owner and repo.
+ *
+ * @param repository - Repository string in "owner/repo" format
+ * @returns Parsed owner and repo, or null if invalid
+ */
+export function parseRepository(repository) {
+    const match = repository.match(/^([^/]+)\/([^/]+)$/);
+    if (!match)
+        return null;
+    return { owner: match[1], repo: match[2] };
+}
+/**
+ * Extract PR number from GitHub Actions environment.
+ *
+ * Checks GITHUB_REF_NAME for PR merge ref format (e.g., "123/merge")
+ * and falls back to GITHUB_EVENT_NUMBER.
+ *
+ * @returns PR number or null if not in PR context
+ */
+export function extractPRNumber() {
+    // From PR merge ref: refs/pull/123/merge -> GITHUB_REF_NAME = "123/merge"
+    const refName = process.env.GITHUB_REF_NAME;
+    if (refName) {
+        const match = refName.match(/^(\d+)\/merge$/);
+        if (match) {
+            return parseInt(match[1], 10);
+        }
+    }
+    // From workflow context
+    const eventNumber = process.env.GITHUB_EVENT_NUMBER;
+    if (eventNumber) {
+        const num = parseInt(eventNumber, 10);
+        if (!isNaN(num))
+            return num;
+    }
+    // From pull_request event payload (parsed from GITHUB_EVENT_PATH)
+    // This requires reading the event file, skipping for simplicity
+    return null;
+}

package/dist/ci/gitlab-api.d.ts

@@ -0,0 +1,75 @@
+/**
+ * GitLab API wrapper for MR note operations.
+ *
+ * Provides utilities for posting and updating MR notes (comments)
+ * with sticky note semantics (find existing by hidden header).
+ *
+ * Uses native fetch (Node 18+).
+ */
+/**
+ * Options for GitLab note operations.
+ */
+export interface GitLabNoteOptions {
+    /** GitLab token (from GITLAB_TOKEN or CI_JOB_TOKEN) */
+    token: string;
+    /** GitLab API URL (from CI_API_V4_URL or https://gitlab.com/api/v4) */
+    apiUrl: string;
+    /** Project ID or URL-encoded path */
+    projectId: string;
+    /** MR IID (internal ID within project) */
+    mrIid: number;
+    /** Note body (markdown) */
+    body: string;
+    /** Header identifier for finding existing note */
+    header: string;
+}
+/**
+ * URL-encode a project path for GitLab API.
+ *
+ * Project ID can be numeric or a path like "group/project".
+ * Numeric IDs pass through unchanged, paths are URL-encoded.
+ *
+ * @param projectId - Project ID or path
+ * @returns URL-safe project identifier
+ */
+export declare function encodeProjectId(projectId: string): string;
+/**
+ * Find existing note by hidden header identifier.
+ *
+ * Searches MR notes for `<!-- {header} -->` pattern in body.
+ * Handles pagination for MRs with many notes.
+ *
+ * @param options - Note search options
+ * @returns Note ID if found, null otherwise
+ */
+export declare function findExistingNote(options: Omit<GitLabNoteOptions, "body">): Promise<number | null>;
+/**
+ * Post new note or update existing one.
+ *
+ * Uses header identifier to find existing note for update semantics.
+ * This prevents note spam and ensures only one VertaaUX note per MR.
+ *
+ * @param options - Note options
+ * @returns Created/updated note with ID and web URL
+ */
+export declare function postOrUpdateGitLabNote(options: GitLabNoteOptions): Promise<{
+    id: number;
+    web_url: string;
+}>;
+/**
+ * Extract MR IID from GitLab CI environment.
+ *
+ * @returns MR IID or null if not in MR context
+ */
+export declare function extractMRIid(): number | null;
+/**
+ * Get GitLab API configuration from environment.
+ *
+ * @returns API configuration or null if not in GitLab CI
+ */
+export declare function getGitLabConfig(): {
+    token: string;
+    apiUrl: string;
+    projectId: string;
+} | null;
+//# sourceMappingURL=gitlab-api.d.ts.map

package/dist/ci/gitlab-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitlab-api.d.ts","sourceRoot":"","sources":["../../src/ci/gitlab-api.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;CAChB;AAwED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAOzD;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,GACvC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAgCxB;AAED;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CA6B1C;AAyBD;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,MAAM,GAAG,IAAI,CAO5C;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,IAAI,CAeP"}