@rankture/cli 0.1.1 → 0.1.3

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
 /**
  * Check result from an SEO check
  */
@@ -37,6 +39,8 @@ interface CheckSummary {
     warning: number;
     /** Total info messages */
     info: number;
+    /** Percentage of all checks that passed */
+    score?: number;
 }
 /**
  * Full report from a check run
@@ -52,6 +56,49 @@ interface CheckReport {
     summary: CheckSummary;
     /** All check results */
     results: CheckResult[];
+    /** Git/CI context, when detectable */
+    ci?: CiMetadata;
+    /** Baseline suppression info, when a baseline was applied */
+    baseline?: {
+        /** Baseline file path */
+        file: string;
+        /** Number of known issues suppressed by the baseline */
+        suppressed: number;
+        /** Issues not covered by the baseline */
+        fresh: number;
+    };
+    /** Hosted run created by --sync */
+    sync?: {
+        runId: string;
+        websiteId?: string;
+    };
+}
+/**
+ * Git/CI context detected from standard environment variables
+ */
+interface CiMetadata {
+    /** CI provider slug, e.g. github-actions, gitlab-ci, vercel, or 'git' for local */
+    provider: string;
+    /** Commit SHA */
+    commit?: string;
+    /** Branch or ref name */
+    branch?: string;
+    /** Pull/merge request number */
+    pullRequest?: number;
+    /** Link to the CI build, when the provider exposes one */
+    buildUrl?: string;
+}
+interface CheckThresholds {
+    titleLength?: {
+        min: number;
+        max: number;
+    };
+    descriptionLength?: {
+        min: number;
+        max: number;
+    };
+    maxImageSize?: number;
+    maxPageSize?: number;
 }
 /**
  * Options for running checks
@@ -60,11 +107,11 @@ interface CheckOptions {
     /** Path to check (directory or file) */
     path: string;
     /** Output format */
-    format: 'terminal' | 'json' | 'html';
+    format: 'terminal' | 'json' | 'html' | 'sarif' | 'markdown';
     /** Output file path (optional) */
     output?: string;
-    /** Fail threshold */
-    failOn: 'none' | 'critical' | 'warning' | 'any';
+    /** Fail threshold ('new' requires --baseline) */
+    failOn: 'none' | 'critical' | 'warning' | 'any' | 'new';
     /** Glob patterns to ignore */
     ignore: string[];
     /** Config file path */
@@ -75,6 +122,36 @@ interface CheckOptions {
     changed?: boolean;
     /** Only check git staged files */
     staged?: boolean;
+    /** Suppress non-essential output (spinner, passed counts, info results) */
+    quiet?: boolean;
+    /** Baseline file: known issues in it are suppressed */
+    baseline?: string;
+    /** Write/refresh the baseline file from this run's failures */
+    updateBaseline?: boolean;
+    /** Fail when warning count exceeds this (after baseline filtering) */
+    maxWarnings?: number;
+    /** Fail when critical count exceeds this (after baseline filtering) */
+    maxCritical?: number;
+    /** Fail when the overall score is below this percentage */
+    minScore?: number;
+    /** Emit GitHub Actions workflow-command annotations */
+    annotations?: boolean;
+    /** Disable ANSI colors */
+    noColor?: boolean;
+    /** Validate built-site links through an ephemeral local HTTP server */
+    serve?: boolean;
+    /** Preferred local server port (0 selects an available port) */
+    servePort?: number;
+    /** Open a generated HTML report in the system browser */
+    open?: boolean;
+    /** Upload this local report to Rankture */
+    sync?: boolean;
+    /** Website receiving the synced run */
+    websiteId?: string;
+    /** One-run API key override */
+    apiKey?: string;
+    /** Rankture API origin override */
+    apiUrl?: string;
 }
 /**
  * Configuration file structure
@@ -87,22 +164,15 @@ interface RanktureConfig {
     /** Severity overrides for specific checks */
     rules?: Record<string, 'critical' | 'warning' | 'info'>;
     /** Threshold settings */
-    thresholds?: {
-        titleLength?: {
-            min: number;
-            max: number;
-        };
-        descriptionLength?: {
-            min: number;
-            max: number;
-        };
-        maxImageSize?: number;
-        maxPageSize?: number;
-    };
+    thresholds?: CheckThresholds;
     /** API key for Pro features */
     apiKey?: string;
     /** Whether to sync results to dashboard */
     sync?: boolean;
+    /** Default website association for synced runs */
+    websiteId?: string;
+    /** Rankture API origin override */
+    apiUrl?: string;
 }
 /**
  * Parsed HTML page data for checks
@@ -112,6 +182,8 @@ interface ParsedPage {
     filePath: string;
     /** Raw HTML content */
     html: string;
+    /** Original untransformed file contents used for source provenance */
+    sourceContent?: string;
     /** Page title */
     title?: string;
     /** Meta description */
@@ -179,7 +251,7 @@ interface CheckRegistry {
     name: string;
     description: string;
     severity: 'critical' | 'warning' | 'info';
-    run: (page: ParsedPage, allPages: ParsedPage[], basePath: string) => CheckResult[];
+    run: (page: ParsedPage, allPages: ParsedPage[], basePath: string, thresholds?: CheckThresholds) => CheckResult[];
 }
 /**
  * All available checks
@@ -188,7 +260,7 @@ declare const checks: CheckRegistry[];
 /**
  * Run all enabled checks on a page
  */
-declare function runChecks(page: ParsedPage, allPages: ParsedPage[], basePath: string, enabledChecks?: Set<string>): CheckResult[];
+declare function runChecks(page: ParsedPage, allPages: ParsedPage[], basePath: string, enabledChecks?: Set<string>, thresholds?: CheckThresholds): CheckResult[];
 /**
  * Get list of all available check IDs
  */
@@ -197,11 +269,11 @@ declare function getAvailableChecks(): string[];
 /**
  * Check for missing or problematic title tags
  */
-declare function checkMetaTitle(page: ParsedPage, allPages: ParsedPage[]): CheckResult[];
+declare function checkMetaTitle(page: ParsedPage, allPages: ParsedPage[], thresholds?: CheckThresholds): CheckResult[];
 /**
  * Check for missing or problematic meta descriptions
  */
-declare function checkMetaDescription(page: ParsedPage, allPages: ParsedPage[]): CheckResult[];
+declare function checkMetaDescription(page: ParsedPage, allPages: ParsedPage[], thresholds?: CheckThresholds): CheckResult[];
 /**
  * Check for missing viewport meta tag
  * Note: Skipped for source files since viewport is typically in layouts
@@ -281,15 +353,146 @@ declare const defaultConfig: RanktureConfig;
  * Find and load config file from directory
  */
 declare function loadConfig(basePath: string, configPath?: string): Promise<RanktureConfig>;
+/**
+ * Validate config structure
+ */
+declare function validateConfig(config: unknown): config is RanktureConfig;
+/** Return every configuration problem so users can fix a file in one pass. */
+declare function getConfigErrors(config: unknown): string[];
 /**
  * Get enabled checks from config
  */
 declare function getEnabledChecks(config: RanktureConfig, allChecks: string[]): Set<string>;
 
+/**
+ * Baseline file: a committed snapshot of known issues so CI can fail only on
+ * newly introduced problems (`--baseline seo-baseline.json --fail-on new`).
+ *
+ * Issues are keyed by `checkId|relative-file-path` with an occurrence count.
+ * Counts matter: a file with 2 known image-alt issues fails again when a 3rd
+ * appears. Line numbers and messages are deliberately excluded from the key —
+ * they shift with unrelated edits and would make the baseline churn.
+ */
+interface BaselineFile {
+    version: 1;
+    createdAt: string;
+    issues: Record<string, number>;
+}
+interface BaselineResult {
+    /** Failures not covered by the baseline (still fail CI) */
+    fresh: CheckResult[];
+    /** Number of failures suppressed as already-known */
+    suppressed: number;
+}
+declare function buildBaseline(failures: CheckResult[], basePath: string, timestamp: string): BaselineFile;
+declare function loadBaseline(filePath: string): BaselineFile;
+declare function saveBaseline(filePath: string, baseline: BaselineFile): void;
+/**
+ * Split failures into fresh (not in baseline, or exceeding the known count)
+ * and suppressed. Deterministic: the first N occurrences of a key are
+ * suppressed, where N is the baseline count.
+ */
+declare function applyBaseline(failures: CheckResult[], baseline: BaselineFile, basePath: string): BaselineResult;
+
+type Env = Record<string, string | undefined>;
+/**
+ * Detect git/CI context from standard environment variables so reports and
+ * sync payloads can be tied to a commit, branch, and PR. Falls back to local
+ * git when no CI provider is detected. Returns undefined when nothing is
+ * detectable (e.g. a plain directory outside a repo).
+ */
+declare function collectCiMetadata(env?: Env, cwd?: string): CiMetadata | undefined;
+
+/** Attach exact locations only to findings that refer to syntax that exists. */
+declare function locateFinding(page: ParsedPage, result: CheckResult): CheckResult;
+
+interface StaticServer {
+    origin: string;
+    close: () => Promise<void>;
+}
+declare function startStaticServer(rootPath: string, port?: number): Promise<StaticServer>;
+declare function pageUrlForFile(filePath: string, rootPath: string, origin: string): string;
+
+interface StoredCredentials {
+    apiKey: string;
+    apiUrl: string;
+}
+declare function credentialFile(env?: NodeJS.ProcessEnv): string;
+declare function saveCredentials(credentials: StoredCredentials, env?: NodeJS.ProcessEnv): string;
+declare function loadCredentials(env?: NodeJS.ProcessEnv): StoredCredentials | undefined;
+declare function clearCredentials(env?: NodeJS.ProcessEnv): boolean;
+
+interface CliIdentity {
+    user: {
+        id: string;
+        email: string;
+        name?: string | null;
+    };
+    scopes: string[];
+}
+declare function cliApiRequest<T>(pathname: string, init?: RequestInit, override?: Partial<StoredCredentials>): Promise<T>;
+declare const getIdentity: (override?: Partial<StoredCredentials>) => Promise<CliIdentity>;
+declare const getWebsites: (override?: Partial<StoredCredentials>) => Promise<{
+    websites: Array<{
+        id: string;
+        name?: string;
+        url: string;
+    }>;
+}>;
+declare const syncCheckReport: (report: CheckReport, websiteId?: string, override?: Partial<StoredCredentials>) => Promise<{
+    success: true;
+    runId: string;
+}>;
+declare const startRemoteAudit: (url: string, options?: {
+    pages?: number;
+}, override?: Partial<StoredCredentials>) => Promise<{
+    success: true;
+    auditId: string;
+}>;
+declare const getRemoteAudit: (auditId: string, override?: Partial<StoredCredentials>, full?: boolean) => Promise<Record<string, unknown>>;
+
+declare function createMcpServer(rootPath?: string, cliEntry?: string): McpServer;
+declare function startMcpServer(rootPath?: string): Promise<void>;
+
+interface IntegrationOptions {
+    path?: string;
+    config?: string;
+    failOn?: CheckOptions['failOn'];
+    format?: CheckOptions['format'];
+    serve?: boolean;
+    quiet?: boolean;
+    runner?: (options: CheckOptions) => Promise<number>;
+}
+/** Astro integration: run after static build output has been written. */
+declare function ranktureAstro(options?: IntegrationOptions): {
+    name: string;
+    hooks: {
+        'astro:build:done': ({ dir }: {
+            dir: URL;
+        }) => Promise<void>;
+    };
+};
+/** Vite/Rollup plugin: run after the configured output directory is built. */
+declare function ranktureVite(options?: IntegrationOptions): {
+    name: string;
+    apply: "build";
+    enforce: "post";
+    configResolved(config: {
+        root?: string;
+        build?: {
+            outDir?: string;
+        };
+    }): void;
+    closeBundle(): Promise<void>;
+};
+
 /**
  * Format check results for terminal output
  */
-declare function formatTerminal(report: CheckReport): string;
+declare function formatTerminal(report: CheckReport, opts?: {
+    quiet?: boolean;
+    noColor?: boolean;
+}): string;
 
 /**
  * Format check results as JSON
@@ -301,12 +504,24 @@ declare function formatJson(report: CheckReport): string;
  */
 declare function formatHtml(report: CheckReport): string;
 
+/** Compact, actionable output intended for pull requests and coding agents. */
+declare function formatMarkdown(report: CheckReport): string;
+
+/**
+ * SARIF 2.1.0 output for GitHub code scanning and other static-analysis
+ * consumers. Failures only; rule metadata is derived from the results so the
+ * rule list always matches what actually fired.
+ */
+declare function formatSarif(report: CheckReport, basePath: string): string;
+
 interface ValidateResult {
     valid: boolean;
     errors: string[];
     warnings: string[];
     info: string[];
 }
+/** Validate a JSON-LD document or JSON-LD scripts embedded in HTML/source. */
+declare function validateSchema(filePath: string): Promise<ValidateResult>;
 /**
  * Validate a robots.txt file
  */
@@ -336,4 +551,4 @@ interface PageCheckResult {
  */
 declare function checkPage(html: string, url?: string, basePath?: string): PageCheckResult;
 
-export { type CheckOptions, type CheckReport, type CheckResult, type CheckSummary, type PageCheckResult, type ParsedPage, type RanktureConfig, SUPPORTED_EXTENSIONS, type ValidateResult, checkAccessibility, checkCanonical, checkColorContrast, checkFocusIndicators, checkH1, checkHeadingHierarchy, checkImageAlt, checkInternalLinks, checkLang, checkMetaDescription, checkMetaTitle, checkOpenGraph, checkPage, checkRobotsMeta, checkSchema, checkSchemaJsonValidity, checkTwitterCards, checkViewport, checks, defaultConfig, formatHtml, formatJson, formatTerminal, getAvailableChecks, getEnabledChecks, loadConfig, parseHtml, parseSourceFile, runChecks, validateRobotsTxt, validateSitemap };
+export { type BaselineFile, type BaselineResult, type CheckOptions, type CheckReport, type CheckResult, type CheckSummary, type CheckThresholds, type CiMetadata, type IntegrationOptions, type PageCheckResult, type ParsedPage, type RanktureConfig, SUPPORTED_EXTENSIONS, type ValidateResult, applyBaseline, buildBaseline, checkAccessibility, checkCanonical, checkColorContrast, checkFocusIndicators, checkH1, checkHeadingHierarchy, checkImageAlt, checkInternalLinks, checkLang, checkMetaDescription, checkMetaTitle, checkOpenGraph, checkPage, checkRobotsMeta, checkSchema, checkSchemaJsonValidity, checkTwitterCards, checkViewport, checks, clearCredentials, cliApiRequest, collectCiMetadata, createMcpServer, credentialFile, defaultConfig, formatHtml, formatJson, formatMarkdown, formatSarif, formatTerminal, getAvailableChecks, getConfigErrors, getEnabledChecks, getIdentity, getRemoteAudit, getWebsites, loadBaseline, loadConfig, loadCredentials, locateFinding, pageUrlForFile, parseHtml, parseSourceFile, ranktureAstro, ranktureVite, runChecks, saveBaseline, saveCredentials, startMcpServer, startRemoteAudit, startStaticServer, syncCheckReport, validateConfig, validateRobotsTxt, validateSchema, validateSitemap };