vortix-cli 0.1.0

package/dist/commands/check.d.ts

@@ -0,0 +1,5 @@
+interface CheckOptions {
+    url?: string;
+}
+export declare function checkCommand(options?: CheckOptions): Promise<void>;
+export {};

package/dist/commands/ci.d.ts

@@ -0,0 +1,5 @@
+interface CiOptions {
+    url?: string;
+}
+export declare function ciCommand(options?: CiOptions): Promise<void>;
+export {};

package/dist/commands/config.d.ts

@@ -0,0 +1 @@
+export declare function configCommand(): Promise<void>;

package/dist/commands/detail-ui.d.ts

@@ -0,0 +1,2 @@
+import type { RunResult } from "@core/runner.js";
+export declare function runInteractiveReport(result: RunResult): Promise<void>;

package/dist/commands/init.d.ts

@@ -0,0 +1,3 @@
+import type { VortixConfig } from "@core/types.js";
+export declare function initCommand(): Promise<void>;
+export declare function runPrompts(cwd: string, existing: VortixConfig | null): Promise<VortixConfig | undefined>;

package/dist/commands/progress-ui.d.ts

@@ -0,0 +1,3 @@
+import type { Writable } from "node:stream";
+import type { OnProgress } from "@core/runner.js";
+export declare function createProgressHandler(output?: Writable): OnProgress;

package/dist/core/config.d.ts

@@ -0,0 +1,6 @@
+import type { ResolvedConfig, VortixConfig } from "./types.js";
+export declare const CONFIG_DIR = ".vortix";
+export declare const CONFIG_FILE = "config.json";
+export declare function defineConfig(config: VortixConfig): VortixConfig;
+export declare function getConfigPath(cwd: string): string;
+export declare function loadConfig(cwd: string): ResolvedConfig;

package/dist/core/define-check.d.ts

@@ -0,0 +1,2 @@
+import type { CheckDefinition } from "./types.js";
+export declare function defineCheck(def: CheckDefinition): CheckDefinition;

package/dist/core/detail.d.ts

@@ -0,0 +1,2 @@
+import type { CheckDefinition, CheckDetail, DetailInput } from "./types.js";
+export declare function createDetailFactory(check: CheckDefinition, push: (detail: CheckDetail) => void): (input: DetailInput) => void;

package/dist/core/finding.d.ts

@@ -0,0 +1,2 @@
+import type { CheckDefinition, Finding, FindingInput, Severity } from "./types.js";
+export declare function createFindingFactory(check: CheckDefinition, configuredSeverity: Severity | undefined): (input: FindingInput) => Finding;

package/dist/core/load-checks.d.ts

@@ -0,0 +1,10 @@
+import type { CheckDefinition, ResolvedConfig } from "./types.js";
+export interface LoadChecksResult {
+    checks: CheckDefinition[];
+    /** Custom check modules that failed to load. Surfaced as run-level findings, never as a crash. */
+    loadErrors: {
+        specifier: string;
+        message: string;
+    }[];
+}
+export declare function loadChecks(config: ResolvedConfig): Promise<LoadChecksResult>;

package/dist/core/messages.d.ts

@@ -0,0 +1,3 @@
+type Params = Record<string, string | number>;
+export declare function t(key: string, params?: Params): string;
+export {};

package/dist/core/report.d.ts

@@ -0,0 +1,15 @@
+import type { RunResult } from "./runner.js";
+import type { CheckDetail, CheckSummary, Finding } from "./types.js";
+export declare function printReport(result: RunResult): void;
+/**
+ * Renders the score summary as a bordered box with a block-letter grade badge. Printed as soon
+ * as the checks finish, rather than behind the interactive "Done" step.
+ */
+export declare function buildScoreCard(result: RunResult, color?: boolean): string;
+export declare function checkOptionLabel(check: CheckSummary, findings: Finding[], skipReason?: string): {
+    label: string;
+    hint: string;
+};
+export declare function buildFullReport(result: RunResult): string;
+export declare function buildHeader(result: RunResult): string;
+export declare function buildCheckDetail(check: CheckSummary, findings: Finding[], details: CheckDetail[], skipReason?: string): string;

package/dist/core/runner.d.ts

@@ -0,0 +1,64 @@
+import type { CheckDetail, CheckSummary, Finding, PageInfo, ResolvedConfig } from "./types.js";
+export interface RunResult {
+    findings: Finding[];
+    details: CheckDetail[];
+    checks: CheckSummary[];
+    skipped: Record<string, string>;
+    adapterName: string;
+    outputDir: string;
+    pagesChecked: number;
+    totalPages: number;
+    liveUrl?: string;
+    exitCode: number;
+    /** Custom check modules from config.checks[] that failed to load. Never fatal to the run. */
+    configErrors: string[];
+}
+export type ProgressEvent = {
+    type: "build-start";
+} | {
+    type: "build-done";
+} | {
+    type: "static-start";
+    index: number;
+    total: number;
+} | {
+    type: "static-check";
+    check: CheckSummary;
+    index: number;
+    total: number;
+} | {
+    type: "static-done";
+    total: number;
+} | {
+    type: "dynamic-start";
+    index: number;
+    total: number;
+} | {
+    type: "dynamic-page-start";
+    pageInfo: PageInfo;
+    index: number;
+    total: number;
+} | {
+    type: "dynamic-page-done";
+    pageInfo: PageInfo;
+    index: number;
+    total: number;
+} | {
+    type: "dynamic-done";
+    total: number;
+} | {
+    type: "live-start";
+    url: string;
+    index: number;
+    total: number;
+} | {
+    type: "live-check";
+    check: CheckSummary;
+    index: number;
+    total: number;
+} | {
+    type: "live-done";
+    total: number;
+};
+export type OnProgress = (event: ProgressEvent) => void;
+export declare function runVortix(config: ResolvedConfig, onProgress?: OnProgress, liveUrl?: string): Promise<RunResult>;

package/dist/core/score.d.ts

@@ -0,0 +1,9 @@
+import type { CheckSummary, Finding, Severity } from "./types.js";
+export type Grade = "A" | "B" | "C" | "D" | "F";
+export interface Score {
+    value: number;
+    grade: Grade;
+    cappedByError: boolean;
+}
+export declare const SEVERITY_RANK: Record<Severity, number>;
+export declare function computeScore(checks: CheckSummary[], findings: Finding[], skippedCheckIds?: ReadonlySet<string>): Score;

package/dist/core/types.d.ts

@@ -0,0 +1,162 @@
+import type { Page } from "playwright";
+export type Category = "performance" | "security" | "accessibility" | "bugs" | "seo" | "maintainability" | "privacy";
+export declare const CATEGORIES: Category[];
+export type Severity = "error" | "warn" | "info";
+export interface Finding {
+    checkId: string;
+    category: Category;
+    severity: Severity;
+    message: string;
+    file?: string;
+    url?: string;
+}
+export interface FindingInput {
+    message: string;
+    file?: string;
+    url?: string;
+    severity?: Severity;
+}
+export type CheckMode = "static" | "dynamic" | "live";
+export interface DetailInput {
+    label: string;
+    value: string;
+    url?: string;
+}
+export interface CheckDetail extends DetailInput {
+    checkId: string;
+    category: Category;
+}
+export interface PageInfo {
+    file: string;
+    relativeFile: string;
+    urlPath: string;
+}
+export interface CapturedConsoleMessage {
+    type: string;
+    text: string;
+}
+export interface CapturedNetworkRequest {
+    url: string;
+    status: number;
+    contentType: string | null;
+    bodySize: number;
+    isMainFrame: boolean;
+    resourceType: string;
+}
+export interface LiveCheckContext {
+    url: string;
+    parsedUrl: URL;
+    headers: Record<string, string>;
+    setCookieHeaders: string[];
+    status: number;
+    redirected: boolean;
+    finalUrl: string;
+    isHttps: boolean;
+    html: string;
+    config: ResolvedConfig;
+    finding(input: FindingInput): Finding;
+    detail(input: DetailInput): void;
+    skip(reason: string): never;
+}
+export interface VortixConfig {
+    target?: {
+        adapter?: string;
+        outputDir?: string;
+        buildCommand?: string;
+    };
+    build?: boolean;
+    categories?: Partial<Record<Category, boolean>>;
+    checks?: string[];
+    disabledChecks?: string[];
+    severity?: Record<string, Severity>;
+    failOn?: Severity;
+    performance?: {
+        budgets?: {
+            lcpMs?: number;
+            cls?: number;
+            maxPageWeightKb?: number;
+            maxImageKb?: number;
+        };
+    };
+    privacy?: {
+        trackerDomains?: string[];
+    };
+}
+export interface ResolvedConfig {
+    cwd: string;
+    build: boolean;
+    failOn: Severity;
+    target: NonNullable<VortixConfig["target"]>;
+    categories: Record<Category, boolean>;
+    checks: string[];
+    disabledChecks: string[];
+    severity: Record<string, Severity>;
+    performance: {
+        budgets: {
+            lcpMs: number;
+            cls: number;
+            maxPageWeightKb: number;
+            maxImageKb: number;
+        };
+    };
+    privacy: {
+        trackerDomains: string[];
+    };
+}
+export interface BaseCheckContext {
+    siteRoot: string;
+    outputDir: string;
+    config: ResolvedConfig;
+    exec(command: string): Promise<string>;
+    glob(pattern: string, options?: {
+        cwd?: string;
+    }): Promise<string[]>;
+    readFile(filePath: string): string;
+    fileExists(filePath: string): boolean;
+    finding(input: FindingInput): Finding;
+    detail(input: DetailInput): void;
+    skip(reason: string): never;
+}
+export interface StaticCheckContext extends BaseCheckContext {
+    mode: "static";
+    pages: PageInfo[];
+}
+export interface DynamicCheckContext extends BaseCheckContext {
+    mode: "dynamic";
+    page: Page;
+    pageInfo: PageInfo;
+    consoleMessages: CapturedConsoleMessage[];
+    networkRequests: CapturedNetworkRequest[];
+}
+export type CheckDefinition = {
+    id: string;
+    name?: string;
+    category: Category;
+    mode: "static";
+    severity?: Severity;
+    description?: string;
+    run(ctx: StaticCheckContext): Promise<Finding[] | undefined> | Finding[] | undefined;
+} | {
+    id: string;
+    name?: string;
+    category: Category;
+    mode: "dynamic";
+    severity?: Severity;
+    description?: string;
+    run(ctx: DynamicCheckContext): Promise<Finding[] | undefined> | Finding[] | undefined;
+} | {
+    id: string;
+    name?: string;
+    category: Category;
+    mode: "live";
+    severity?: Severity;
+    description?: string;
+    run(ctx: LiveCheckContext): Promise<Finding[] | undefined> | Finding[] | undefined;
+};
+export interface CheckSummary {
+    id: string;
+    name: string;
+    category: Category;
+    mode: CheckMode;
+    description?: string;
+}

package/dist/dynamic/serve.d.ts

@@ -0,0 +1,5 @@
+export interface StaticServer {
+    url: string;
+    close(): Promise<void>;
+}
+export declare function startStaticServer(root: string): Promise<StaticServer>;

package/dist/dynamic/session.d.ts

@@ -0,0 +1,8 @@
+import type { CapturedConsoleMessage, CapturedNetworkRequest } from "@core/types.js";
+import type { Page } from "playwright";
+export interface Capture {
+    consoleMessages: CapturedConsoleMessage[];
+    networkRequests: CapturedNetworkRequest[];
+    detach(): void;
+}
+export declare function attachCapture(page: Page): Capture;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { defineConfig } from "./core/config.js";
+export { defineCheck } from "./core/define-check.js";
+export type { Category, CheckDefinition, CheckMode, DynamicCheckContext, Finding, FindingInput, LiveCheckContext, PageInfo, Severity, StaticCheckContext, VortixConfig, } from "./core/types.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+import {
+  defineCheck,
+  defineConfig
+} from "./chunk-KNVCFVGJ.js";
+export {
+  defineCheck,
+  defineConfig
+};

package/dist/utils/box.d.ts

@@ -0,0 +1,19 @@
+export declare function visibleLength(str: string): number;
+/** Right-pads pre-formatted (possibly ANSI-colored) text with spaces to a minimum visible width, for aligning grid columns. */
+export declare function padVisible(str: string, width: number): string;
+/** Word-wraps plain, uncolored text to a maximum visible width. Callers color the result. */
+export declare function wrapPlainText(text: string, maxWidth: number): string[];
+/**
+ * Packs pre-formatted, indivisible chunks (e.g. a colored "✔ category" badge) onto as few
+ * lines as fit within `maxWidth`, never splitting a chunk's own text across lines.
+ */
+export declare function packChunks(chunks: string[], maxWidth: number, separator?: string): string[];
+export interface RenderBoxOptions {
+    title?: string;
+    padding?: number;
+    minWidth?: number;
+}
+/** Draws a box-drawing border around pre-formatted, possibly ANSI-colored, lines. */
+export declare function renderBox(lines: string[], options?: RenderBoxOptions): string;
+/** Renders a horizontal rule for sectioning long text, such as a check's detail view. */
+export declare function divider(width?: number): string;

package/dist/utils/budget.d.ts

@@ -0,0 +1,2 @@
+import type { Severity } from "@core/types.js";
+export declare function severityForOverage(actual: number, budget: number): Severity;

package/dist/utils/clipboard.d.ts

@@ -0,0 +1 @@
+export declare function copyToClipboard(text: string): boolean;

package/dist/utils/exec.d.ts

@@ -0,0 +1,18 @@
+export interface ExecOptions {
+    cwd: string;
+    /** Kill the process and reject if it runs longer than this. Default: 5 minutes. */
+    timeoutMs?: number;
+    /**
+     * Some CLIs (npm audit, npm outdated, jscpd) use a non-zero exit code to report "found
+     * something" rather than "crashed". When enabled, such an exit resolves with stdout or
+     * stderr instead of rejecting. Disabled by default so that genuine failures, such as a
+     * site's build command, surface as errors instead of being silently swallowed.
+     */
+    allowNonZeroExit?: boolean;
+}
+export interface ExecError extends Error {
+    stdout: string;
+    stderr: string;
+    code: number | string | null;
+}
+export declare function exec(command: string, options: ExecOptions): Promise<string>;

package/dist/utils/github-workflow.d.ts

@@ -0,0 +1,9 @@
+import type { PackageManager } from "./package-manager.js";
+export declare const GITHUB_WORKFLOW_PATH = ".github/workflows/vortix.yml";
+export declare function getGithubWorkflowPath(cwd: string): string;
+/**
+ * Builds a GitHub Actions workflow that installs dependencies with the given package manager and
+ * runs `vortix ci` on every push and pull request. `vortix ci` builds the site itself (per the
+ * project's `.vortix/config.json`), so no separate build step is needed here.
+ */
+export declare function buildGithubWorkflowYaml(pm: PackageManager): string;

package/dist/utils/glob.d.ts

@@ -0,0 +1,3 @@
+export declare function globFiles(pattern: string, options: {
+    cwd: string;
+}): Promise<string[]>;

package/dist/utils/html.d.ts

@@ -0,0 +1,2 @@
+import { type HTMLElement } from "node-html-parser";
+export declare function parseHtmlFile(filePath: string): HTMLElement;

package/dist/utils/humanize.d.ts

@@ -0,0 +1 @@
+export declare function humanizeCheckId(id: string): string;

package/dist/utils/package-manager.d.ts

@@ -0,0 +1,3 @@
+export type PackageManager = "npm" | "yarn" | "pnpm" | "bun";
+/** Infers the package manager in use from lockfiles present at `cwd`. Defaults to npm when none is found. */
+export declare function detectPackageManager(cwd: string): PackageManager;

package/dist/utils/pages.d.ts

@@ -0,0 +1,2 @@
+import type { PageInfo } from "@core/types.js";
+export declare function collectPages(outputDir: string): Promise<PageInfo[]>;

package/dist/utils/resolve-bin.d.ts

@@ -0,0 +1 @@
+export declare function resolvePackageBin(pkgName: string, binRelativePath: string): string;

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "vortix-cli",
+  "version": "0.1.0",
+  "description": "Vortix — Swiss-army-knife CLI for static site quality checks — performance, security, accessibility, bugs, maintainability & privacy.",
+  "keywords": [
+    "cli",
+    "static-site",
+    "performance",
+    "accessibility",
+    "a11y",
+    "seo",
+    "security",
+    "lighthouse",
+    "audit",
+    "quality",
+    "ci"
+  ],
+  "homepage": "https://github.com/jannikmenzel/vortix-cli#readme",
+  "bugs": {
+    "url": "https://github.com/jannikmenzel/vortix-cli/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jannikmenzel/vortix-cli.git"
+  },
+  "author": "Jannik Menzel",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "vortix": "dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup && tsc --emitDeclarationOnly --declaration --outDir dist",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "biome lint .",
+    "lint:fix": "biome lint --write .",
+    "format": "biome format .",
+    "format:fix": "biome format --write .",
+    "check": "biome check .",
+    "check:fix": "biome check --write .",
+    "prepare": "husky",
+    "prepublishOnly": "npm run check && npm run typecheck && npm run test && npm run build"
+  },
+  "lint-staged": {
+    "*.{ts,tsx,js,jsx,mjs,cjs,json}": [
+      "biome check --write --no-errors-on-unmatched"
+    ]
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@axe-core/playwright": "^4.13.0",
+    "@clack/prompts": "^1.7.0",
+    "@playwright/browser-chromium": "^1.62.0",
+    "commander": "^15.0.0",
+    "jscpd": "^5.0.16",
+    "node-html-parser": "^9.0.1",
+    "picocolors": "^1.1.1",
+    "playwright": "^1.62.1",
+    "tinyglobby": "^0.2.17"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.12",
+    "@types/node": "^26.2.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^17.5.0",
+    "tsup": "^8.5.1",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11"
+  }
+}